@planqk/planqk-service-sdk 2.6.2 → 2.8.0

package/dist/sdk/core/fetcher/Fetcher.d.ts

@@ -1,13 +1,14 @@
-import { APIResponse } from "./APIResponse.js";
-import { Supplier } from "./Supplier.js";
+import type { APIResponse } from "./APIResponse.js";
+import type { EndpointMetadata } from "./EndpointMetadata.js";
+import { EndpointSupplier } from "./EndpointSupplier.js";
 export type FetchFunction = <R = unknown>(args: Fetcher.Args) => Promise<APIResponse<R, Fetcher.Error>>;
 export declare namespace Fetcher {
     interface Args {
         url: string;
         method: string;
         contentType?: string;
-        headers?: Record<string, string | Supplier<string | undefined> | undefined>;
-        queryParameters?: Record<string, string | string[] | object | object[] | null>;
+        headers?: Record<string, string | EndpointSupplier<string | null | undefined> | null | undefined>;
+        queryParameters?: Record<string, unknown>;
         body?: unknown;
         timeoutMs?: number;
         maxRetries?: number;
@@ -16,6 +17,7 @@ export declare namespace Fetcher {
         requestType?: "json" | "file" | "bytes";
         responseType?: "json" | "blob" | "sse" | "streaming" | "text" | "arrayBuffer" | "binary-response";
         duplex?: "half";
+        endpointMetadata?: EndpointMetadata;
     }
     type Error = FailedStatusCodeError | NonJsonError | TimeoutError | UnknownError;
     interface FailedStatusCodeError {

package/dist/sdk/core/fetcher/Fetcher.js

@@ -3,14 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetcher = void 0;
 exports.fetcherImpl = fetcherImpl;
 const json_js_1 = require("../json.js");
-const RawResponse_js_1 = require("./RawResponse.js");
-const Supplier_js_1 = require("./Supplier.js");
 const createRequestUrl_js_1 = require("./createRequestUrl.js");
+const EndpointSupplier_js_1 = require("./EndpointSupplier.js");
 const getErrorResponseBody_js_1 = require("./getErrorResponseBody.js");
 const getFetchFn_js_1 = require("./getFetchFn.js");
 const getRequestBody_js_1 = require("./getRequestBody.js");
 const getResponseBody_js_1 = require("./getResponseBody.js");
 const makeRequest_js_1 = require("./makeRequest.js");
+const RawResponse_js_1 = require("./RawResponse.js");
 const requestWithRetries_js_1 = require("./requestWithRetries.js");
 async function getHeaders(args) {
     const newHeaders = {};
@@ -21,7 +21,7 @@ async function getHeaders(args) {
         return newHeaders;
     }
     for (const [key, value] of Object.entries(args.headers)) {
-        const result = await Supplier_js_1.Supplier.get(value);
+        const result = await EndpointSupplier_js_1.EndpointSupplier.get(value, { endpointMetadata: args.endpointMetadata ?? {} });
         if (typeof result === "string") {
             newHeaders[key] = result;
             continue;

package/dist/sdk/core/fetcher/HttpResponsePromise.d.ts

@@ -1,4 +1,4 @@
-import { WithRawResponse } from "./RawResponse.js";
+import type { WithRawResponse } from "./RawResponse.js";
 /**
  * A promise that returns the parsed response and lets you retrieve the raw response too.
  */

package/dist/sdk/core/fetcher/index.d.ts

@@ -1,9 +1,11 @@
 export type { APIResponse } from "./APIResponse.js";
-export { fetcher } from "./Fetcher.js";
+export type { BinaryResponse } from "./BinaryResponse.js";
+export type { EndpointMetadata } from "./EndpointMetadata.js";
+export { EndpointSupplier } from "./EndpointSupplier.js";
 export type { Fetcher, FetchFunction } from "./Fetcher.js";
+export { fetcher } from "./Fetcher.js";
 export { getHeader } from "./getHeader.js";
-export { Supplier } from "./Supplier.js";
-export { abortRawResponse, toRawResponse, unknownRawResponse } from "./RawResponse.js";
-export type { RawResponse, WithRawResponse } from "./RawResponse.js";
 export { HttpResponsePromise } from "./HttpResponsePromise.js";
-export { BinaryResponse } from "./BinaryResponse.js";
+export type { RawResponse, WithRawResponse } from "./RawResponse.js";
+export { abortRawResponse, toRawResponse, unknownRawResponse } from "./RawResponse.js";
+export { Supplier } from "./Supplier.js";

package/dist/sdk/core/fetcher/index.js

@@ -1,15 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpResponsePromise = exports.unknownRawResponse = exports.toRawResponse = exports.abortRawResponse = exports.Supplier = exports.getHeader = exports.fetcher = void 0;
+exports.Supplier = exports.unknownRawResponse = exports.toRawResponse = exports.abortRawResponse = exports.HttpResponsePromise = exports.getHeader = exports.fetcher = exports.EndpointSupplier = void 0;
+var EndpointSupplier_js_1 = require("./EndpointSupplier.js");
+Object.defineProperty(exports, "EndpointSupplier", { enumerable: true, get: function () { return EndpointSupplier_js_1.EndpointSupplier; } });
 var Fetcher_js_1 = require("./Fetcher.js");
 Object.defineProperty(exports, "fetcher", { enumerable: true, get: function () { return Fetcher_js_1.fetcher; } });
 var getHeader_js_1 = require("./getHeader.js");
 Object.defineProperty(exports, "getHeader", { enumerable: true, get: function () { return getHeader_js_1.getHeader; } });
-var Supplier_js_1 = require("./Supplier.js");
-Object.defineProperty(exports, "Supplier", { enumerable: true, get: function () { return Supplier_js_1.Supplier; } });
+var HttpResponsePromise_js_1 = require("./HttpResponsePromise.js");
+Object.defineProperty(exports, "HttpResponsePromise", { enumerable: true, get: function () { return HttpResponsePromise_js_1.HttpResponsePromise; } });
 var RawResponse_js_1 = require("./RawResponse.js");
 Object.defineProperty(exports, "abortRawResponse", { enumerable: true, get: function () { return RawResponse_js_1.abortRawResponse; } });
 Object.defineProperty(exports, "toRawResponse", { enumerable: true, get: function () { return RawResponse_js_1.toRawResponse; } });
 Object.defineProperty(exports, "unknownRawResponse", { enumerable: true, get: function () { return RawResponse_js_1.unknownRawResponse; } });
-var HttpResponsePromise_js_1 = require("./HttpResponsePromise.js");
-Object.defineProperty(exports, "HttpResponsePromise", { enumerable: true, get: function () { return HttpResponsePromise_js_1.HttpResponsePromise; } });
+var Supplier_js_1 = require("./Supplier.js");
+Object.defineProperty(exports, "Supplier", { enumerable: true, get: function () { return Supplier_js_1.Supplier; } });

package/dist/sdk/core/fetcher/requestWithRetries.js

@@ -5,20 +5,56 @@ const INITIAL_RETRY_DELAY = 1000; // in milliseconds
 const MAX_RETRY_DELAY = 60000; // in milliseconds
 const DEFAULT_MAX_RETRIES = 2;
 const JITTER_FACTOR = 0.2; // 20% random jitter
-function addJitter(delay) {
-    // Generate a random value between -JITTER_FACTOR and +JITTER_FACTOR
-    const jitterMultiplier = 1 + (Math.random() * 2 - 1) * JITTER_FACTOR;
+function addPositiveJitter(delay) {
+    // Generate a random value between 0 and +JITTER_FACTOR
+    const jitterMultiplier = 1 + Math.random() * JITTER_FACTOR;
     return delay * jitterMultiplier;
 }
+function addSymmetricJitter(delay) {
+    // Generate a random value in a JITTER_FACTOR-sized percentage range around delay
+    const jitterMultiplier = 1 + (Math.random() - 0.5) * JITTER_FACTOR;
+    return delay * jitterMultiplier;
+}
+function getRetryDelayFromHeaders(response, retryAttempt) {
+    // Check for Retry-After header first (RFC 7231), with no jitter
+    const retryAfter = response.headers.get("Retry-After");
+    if (retryAfter) {
+        // Parse as number of seconds...
+        const retryAfterSeconds = parseInt(retryAfter, 10);
+        if (!isNaN(retryAfterSeconds) && retryAfterSeconds > 0) {
+            return Math.min(retryAfterSeconds * 1000, MAX_RETRY_DELAY);
+        }
+        // ...or as an HTTP date; both are valid
+        const retryAfterDate = new Date(retryAfter);
+        if (!isNaN(retryAfterDate.getTime())) {
+            const delay = retryAfterDate.getTime() - Date.now();
+            if (delay > 0) {
+                return Math.min(Math.max(delay, 0), MAX_RETRY_DELAY);
+            }
+        }
+    }
+    // Then check for industry-standard X-RateLimit-Reset header, with positive jitter
+    const rateLimitReset = response.headers.get("X-RateLimit-Reset");
+    if (rateLimitReset) {
+        const resetTime = parseInt(rateLimitReset, 10);
+        if (!isNaN(resetTime)) {
+            // Assume Unix timestamp in epoch seconds
+            const delay = resetTime * 1000 - Date.now();
+            if (delay > 0) {
+                return addPositiveJitter(Math.min(delay, MAX_RETRY_DELAY));
+            }
+        }
+    }
+    // Fall back to exponential backoff, with symmetric jitter
+    return addSymmetricJitter(Math.min(INITIAL_RETRY_DELAY * Math.pow(2, retryAttempt), MAX_RETRY_DELAY));
+}
 async function requestWithRetries(requestFn, maxRetries = DEFAULT_MAX_RETRIES) {
     let response = await requestFn();
     for (let i = 0; i < maxRetries; ++i) {
         if ([408, 429].includes(response.status) || response.status >= 500) {
-            // Calculate base delay using exponential backoff (in milliseconds)
-            const baseDelay = Math.min(INITIAL_RETRY_DELAY * Math.pow(2, i), MAX_RETRY_DELAY);
-            // Add jitter to the delay
-            const delayWithJitter = addJitter(baseDelay);
-            await new Promise((resolve) => setTimeout(resolve, delayWithJitter));
+            // Get delay with appropriate jitter applied
+            const delay = getRetryDelayFromHeaders(response, i);
+            await new Promise((resolve) => setTimeout(resolve, delay));
             response = await requestFn();
         }
         else {

package/dist/sdk/core/headers.d.ts

@@ -1,3 +1,2 @@
-import * as core from "./index.js";
-export declare function mergeHeaders(...headersArray: (Record<string, string | core.Supplier<string | undefined> | undefined> | undefined)[]): Record<string, string | core.Supplier<string | undefined>>;
-export declare function mergeOnlyDefinedHeaders(...headersArray: (Record<string, string | core.Supplier<string | undefined> | undefined> | undefined)[]): Record<string, string | core.Supplier<string | undefined>>;
+export declare function mergeHeaders<THeaderValue>(...headersArray: (Record<string, THeaderValue> | null | undefined)[]): Record<string, string | THeaderValue>;
+export declare function mergeOnlyDefinedHeaders<THeaderValue>(...headersArray: (Record<string, THeaderValue> | null | undefined)[]): Record<string, THeaderValue>;

package/dist/sdk/core/url/join.js

@@ -5,6 +5,9 @@ function join(base, ...segments) {
     if (!base) {
         return "";
     }
+    if (segments.length === 0) {
+        return base;
+    }
     if (base.includes("://")) {
         let url;
         try {
@@ -14,24 +17,37 @@ function join(base, ...segments) {
             // Fallback to path joining if URL is malformed
             return joinPath(base, ...segments);
         }
+        const lastSegment = segments[segments.length - 1];
+        const shouldPreserveTrailingSlash = lastSegment && lastSegment.endsWith("/");
         for (const segment of segments) {
             const cleanSegment = trimSlashes(segment);
             if (cleanSegment) {
                 url.pathname = joinPathSegments(url.pathname, cleanSegment);
             }
         }
+        if (shouldPreserveTrailingSlash && !url.pathname.endsWith("/")) {
+            url.pathname += "/";
+        }
         return url.toString();
     }
     return joinPath(base, ...segments);
 }
 function joinPath(base, ...segments) {
+    if (segments.length === 0) {
+        return base;
+    }
     let result = base;
+    const lastSegment = segments[segments.length - 1];
+    const shouldPreserveTrailingSlash = lastSegment && lastSegment.endsWith("/");
     for (const segment of segments) {
         const cleanSegment = trimSlashes(segment);
         if (cleanSegment) {
             result = joinPathSegments(result, cleanSegment);
         }
     }
+    if (shouldPreserveTrailingSlash && !result.endsWith("/")) {
+        result += "/";
+    }
     return result;
 }
 function joinPathSegments(left, right) {
@@ -43,7 +59,11 @@ function joinPathSegments(left, right) {
 function trimSlashes(str) {
     if (!str)
         return str;
-    let start = str.startsWith("/") ? 1 : 0;
-    let end = str.endsWith("/") ? str.length - 1 : str.length;
-    return str.slice(start, end);
+    let start = 0;
+    let end = str.length;
+    if (str.startsWith("/"))
+        start = 1;
+    if (str.endsWith("/"))
+        end = str.length - 1;
+    return start === 0 && end === str.length ? str : str.slice(start, end);
 }

package/dist/sdk/environments.d.ts

@@ -1,6 +1,3 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
 export declare const PlanqkServiceApiEnvironment: {
     readonly Default: "https://gateway.platform.planqk.de/<context>/<service>/<version>";
 };

package/dist/sdk/environments.js

@@ -1,7 +1,5 @@
 "use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
+// This file was auto-generated by Fern from our API Definition.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlanqkServiceApiEnvironment = void 0;
 exports.PlanqkServiceApiEnvironment = {

package/dist/sdk/errors/PlanqkServiceApiError.d.ts

@@ -1,6 +1,3 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
 import * as core from "../core/index.js";
 export declare class PlanqkServiceApiError extends Error {
     readonly statusCode?: number;

package/dist/sdk/errors/PlanqkServiceApiError.js

@@ -1,7 +1,5 @@
 "use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
+// This file was auto-generated by Fern from our API Definition.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlanqkServiceApiError = void 0;
 const json_js_1 = require("../core/json.js");

package/dist/sdk/errors/PlanqkServiceApiTimeoutError.d.ts

@@ -1,6 +1,3 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
 export declare class PlanqkServiceApiTimeoutError extends Error {
     constructor(message: string);
 }

package/dist/sdk/errors/PlanqkServiceApiTimeoutError.js

@@ -1,7 +1,5 @@
 "use strict";
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
+// This file was auto-generated by Fern from our API Definition.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlanqkServiceApiTimeoutError = void 0;
 class PlanqkServiceApiTimeoutError extends Error {

package/dist/sdk/index.d.ts

@@ -1,4 +1,5 @@
 export * as PlanqkServiceApi from "./api/index.js";
 export { PlanqkServiceApiError, PlanqkServiceApiTimeoutError } from "./errors/index.js";
+export { type BaseClientOptions, type BaseRequestOptions } from "./BaseClient.js";
 export { PlanqkServiceApiClient } from "./Client.js";
 export { PlanqkServiceApiEnvironment } from "./environments.js";

package/fern/fern.config.json

@@ -1,4 +1,4 @@
 {
   "organization": "planqk-service",
-  "version": "0.65.35"
+  "version": "0.86.2"
 }

package/fern/generators.yml

@@ -6,8 +6,8 @@ default-group: local
 groups:
   local:
     generators:
-      - name: fernapi/fern-typescript-node-sdk
-        version: 2.4.6
+      - name: fernapi/fern-typescript-sdk
+        version: 3.7.1
         output:
           location: local-file-system
           path: ../generated/typescript
@@ -18,8 +18,10 @@ groups:
           skipResponseValidation: true
           noSerdeLayer: true
       - name: fernapi/fern-python-sdk
-        version: 4.25.0
+        version: 4.31.0
         output:
           location: local-file-system
           path: ../generated/python
-        config: {}
+        config:
+          pydantic_config:
+            skip_validation: true

package/fern/openapi/openapi.yml

@@ -4,6 +4,116 @@ info:
   title: PLANQK Service API
   description: |
     API description for a managed PLANQK Service.
+components:
+  schemas:
+    RequestBody:
+      type: object
+      additionalProperties: true
+      #
+      # Define the schema of your service execution input here
+      #
+    ResultResponse:
+      type: object
+      additionalProperties: true
+      properties:
+        #
+        # Add the schema of your result response here
+        #
+
+        # DO NOT REMOVE THE FOLLOWING LINES
+        _links:
+          type: object
+          properties:
+            status:
+              $ref: '#/components/schemas/HALLink'
+          additionalProperties:
+            $ref: '#/components/schemas/HALLink'
+        _embedded:
+          type: object
+          properties:
+            status:
+              $ref: '#/components/schemas/ServiceExecution'
+    ServiceExecution:
+      type: object
+      properties:
+        id:
+          type: string
+          examples: [ 87cb778e-ac43-11ec-b909-0242ac120002 ]
+        status:
+          type: string
+          enum: [ UNKNOWN, PENDING, RUNNING, SUCCEEDED, CANCELLED, FAILED ]
+          examples: [ SUCCEEDED ]
+        createdAt:
+          type: string
+          examples: [ "2022-01-01 22:38:08" ]
+        startedAt:
+          type: string
+          examples: [ "2022-01-01 22:39:08" ]
+        endedAt:
+          type: string
+          examples: [ "2022-01-01 22:40:08" ]
+    LogEntry:
+      type: object
+      properties:
+        message:
+          type: string
+          description: Log message content.
+        severity:
+          type: string
+          description: Severity of the log entry.
+          enum:
+            - DEBUG
+            - NOTICE
+            - INFO
+            - WARNING
+            - ERROR
+          examples: [ "INFO" ]
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the entry was logged.
+          examples: [ "2025-10-10T08:23:26.452335419Z" ]
+    # Representation of link as defined in HAL: https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-11
+    HALLink:
+      type: object
+      properties:
+        href:
+          type: string
+          description: The URL of the link
+        templated:
+          type: boolean
+          description: Whether the link is templated (optional)
+          default: false
+        type:
+          type: string
+          description: The media type of the link (optional)
+        deprecation:
+          type: string
+          description: A URL that provides further information about the deprecation of the link (optional)
+        name:
+          type: string
+          description: The name of the link (optional)
+        profile:
+          type: string
+          description: A URL that provides further information about the profile of the link (optional)
+        title:
+          type: string
+          description: The title of the link (optional)
+        hreflang:
+          type: string
+          description: The language of the link's target resource (optional)
+  securitySchemes:
+    ApplicationCredentials:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://gateway.platform.planqk.de/token
+          scopes: { }
+security:
+  - ApplicationCredentials: [ ]
+servers:
+  - url: https://gateway.platform.planqk.de/<context>/<service>/<version>
+    description: The service endpoint
 paths:
   /:
     get:
@@ -36,8 +146,7 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              additionalProperties: true
+              $ref: "#/components/schemas/RequestBody"
       responses:
         "201":
           description: Service execution is submitted
@@ -96,21 +205,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                additionalProperties: true
-                properties:
-                  _links:
-                    type: object
-                    properties:
-                      status:
-                        $ref: '#/components/schemas/HALLink'
-                    additionalProperties:
-                      $ref: '#/components/schemas/HALLink'
-                  _embedded:
-                    type: object
-                    properties:
-                      status:
-                        $ref: '#/components/schemas/ServiceExecution'
+                $ref: "#/components/schemas/ResultResponse"
   /{id}/result/{file}:
     get:
       tags:
@@ -165,7 +260,9 @@ paths:
               schema:
                 type: array
                 items:
-                  type: string
+                  $ref: "#/components/schemas/LogEntry"
+        "204":
+          description: No log entries available
   /{id}/cancel:
     put:
       tags:
@@ -188,65 +285,3 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ServiceExecution"
-components:
-  schemas:
-    ServiceExecution:
-      type: object
-      properties:
-        id:
-          type: string
-          examples: [ 87cb778e-ac43-11ec-b909-0242ac120002 ]
-        status:
-          type: string
-          enum: [ UNKNOWN, PENDING, RUNNING, SUCCEEDED, CANCELLED, FAILED ]
-          examples: [ SUCCEEDED ]
-        createdAt:
-          type: string
-          examples: [ "2022-01-01 22:38:08" ]
-        startedAt:
-          type: string
-          examples: [ "2022-01-01 22:39:08" ]
-        endedAt:
-          type: string
-          examples: [ "2022-01-01 22:40:08" ]
-    # Representation of link as defined in HAL: https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-11
-    HALLink:
-      type: object
-      properties:
-        href:
-          type: string
-          description: The URL of the link
-        templated:
-          type: boolean
-          description: Whether the link is templated (optional)
-          default: false
-        type:
-          type: string
-          description: The media type of the link (optional)
-        deprecation:
-          type: string
-          description: A URL that provides further information about the deprecation of the link (optional)
-        name:
-          type: string
-          description: The name of the link (optional)
-        profile:
-          type: string
-          description: A URL that provides further information about the profile of the link (optional)
-        title:
-          type: string
-          description: The title of the link (optional)
-        hreflang:
-          type: string
-          description: The language of the link's target resource (optional)
-  securitySchemes:
-    ApplicationCredentials:
-      type: oauth2
-      flows:
-        clientCredentials:
-          tokenUrl: https://gateway.platform.planqk.de/token
-          scopes: {}
-security:
-  - ApplicationCredentials: []
-servers:
-  - url: https://gateway.platform.planqk.de/<context>/<service>/<version>
-    description: The service endpoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planqk/planqk-service-sdk",
-  "version": "2.6.2",
+  "version": "2.8.0",
   "description": "SDK to interact with PLANQK Managed Services.",
   "author": "Kipu Quantum GmbH",
   "contributors": [

package/planqk/service/_version.py

@@ -1 +1 @@
-__version__ = "2.6.2"
+__version__ = "2.8.0"

package/planqk/service/client.py

@@ -5,7 +5,7 @@ import time
 import typing
 
 from planqk.service.auth import DEFAULT_TOKEN_ENDPOINT, PlanqkServiceAuth
-from planqk.service.sdk import PlanqkServiceApi, ServiceExecution, GetResultResponse
+from planqk.service.sdk import PlanqkServiceApi, ServiceExecution, LogEntry, ResultResponse
 from planqk.service.sdk.service_api.client import ServiceApiClient
 from planqk.service.sdk.types.service_execution_status import ServiceExecutionStatus
 
@@ -61,7 +61,7 @@ class PlanqkServiceExecution:
     def refresh(self):
         self._service_execution = self._client.api.get_status(id=self.id)
 
-    def result(self) -> GetResultResponse:
+    def result(self) -> ResultResponse:
         self.wait_for_final_state()
         delay = 1  # Start with a small delay
         max_delay = 16  # Maximum delay
@@ -105,7 +105,7 @@ class PlanqkServiceExecution:
     def cancel(self) -> None:
         self._client.api.cancel_execution(id=self.id)
 
-    def logs(self) -> typing.List[str]:
+    def logs(self) -> typing.List[LogEntry]:
         return self._client.api.get_logs(id=self.id)