@planqk/planqk-service-sdk 2.7.0 → 2.8.0

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/openapi/openapi.yml

@@ -57,11 +57,22 @@ components:
       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
@@ -97,9 +108,9 @@ components:
       flows:
         clientCredentials:
           tokenUrl: https://gateway.platform.planqk.de/token
-          scopes: {}
+          scopes: { }
 security:
-  - ApplicationCredentials: []
+  - 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.7.0",
+  "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.7.0"
+__version__ = "2.8.0"

package/planqk/service/sdk/__init__.py

@@ -9,6 +9,7 @@ if typing.TYPE_CHECKING:
     from .types import (
         HalLink,
         LogEntry,
+        LogEntrySeverity,
         RequestBody,
         ResultResponse,
         ResultResponseEmbedded,
@@ -23,6 +24,7 @@ _dynamic_imports: typing.Dict[str, str] = {
     "AsyncPlanqkServiceApi": ".client",
     "HalLink": ".types",
     "LogEntry": ".types",
+    "LogEntrySeverity": ".types",
     "PlanqkServiceApi": ".client",
     "PlanqkServiceApiEnvironment": ".environment",
     "RequestBody": ".types",
@@ -60,6 +62,7 @@ __all__ = [
     "AsyncPlanqkServiceApi",
     "HalLink",
     "LogEntry",
+    "LogEntrySeverity",
     "PlanqkServiceApi",
     "PlanqkServiceApiEnvironment",
     "RequestBody",

package/planqk/service/sdk/types/__init__.py

@@ -8,6 +8,7 @@ from importlib import import_module
 if typing.TYPE_CHECKING:
     from .hal_link import HalLink
     from .log_entry import LogEntry
+    from .log_entry_severity import LogEntrySeverity
     from .request_body import RequestBody
     from .result_response import ResultResponse
     from .result_response_embedded import ResultResponseEmbedded
@@ -17,6 +18,7 @@ if typing.TYPE_CHECKING:
 _dynamic_imports: typing.Dict[str, str] = {
     "HalLink": ".hal_link",
     "LogEntry": ".log_entry",
+    "LogEntrySeverity": ".log_entry_severity",
     "RequestBody": ".request_body",
     "ResultResponse": ".result_response",
     "ResultResponseEmbedded": ".result_response_embedded",
@@ -50,6 +52,7 @@ def __dir__():
 __all__ = [
     "HalLink",
     "LogEntry",
+    "LogEntrySeverity",
     "RequestBody",
     "ResultResponse",
     "ResultResponseEmbedded",

package/planqk/service/sdk/types/log_entry.py

@@ -6,12 +6,24 @@ import typing
 import pydantic
 from ..core.pydantic_utilities import IS_PYDANTIC_V2
 from ..core.unchecked_base_model import UncheckedBaseModel
+from .log_entry_severity import LogEntrySeverity
 
 
 class LogEntry(UncheckedBaseModel):
-    message: typing.Optional[str] = None
-    severity: typing.Optional[str] = None
-    timestamp: typing.Optional[dt.datetime] = None
+    message: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Log message content.
+    """
+
+    severity: typing.Optional[LogEntrySeverity] = pydantic.Field(default=None)
+    """
+    Severity of the log entry.
+    """
+
+    timestamp: typing.Optional[dt.datetime] = pydantic.Field(default=None)
+    """
+    Timestamp when the entry was logged.
+    """
 
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2

package/planqk/service/sdk/types/log_entry_severity.py

@@ -0,0 +1,5 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+LogEntrySeverity = typing.Union[typing.Literal["DEBUG", "NOTICE", "INFO", "WARNING", "ERROR"], typing.Any]

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "planqk-service-sdk"
-version = "2.7.0"
+version = "2.8.0"
 description = "SDK to interact with PLANQK Managed Services."
 authors = [
     { name = "Kipu Quantum GmbH", email = "info@kipu-quantum.com" },

package/src/index.test.ts

@@ -14,6 +14,16 @@ console.log(`Service endpoint: ${serviceEndpoint}`)
 console.log(`Consumer key: ${consumerKey}`)
 console.log(`Consumer secret: ${consumerSecret}`)
 
+test.skip('integration test: retrieve logs', {timeout: 5 * 60 * 1000}, async () => {
+  const client = new PlanqkServiceClient(serviceEndpoint!, consumerKey, consumerSecret, tokenEndpoint);
+
+  const serviceExecutions = await client.api().getServiceExecutions()
+  console.log(serviceExecutions)
+
+  const logs = await client.api().getLogs(serviceExecutions[0].id!)
+  console.log(logs)
+})
+
 test.skip('integration test: coin toss', {timeout: 5 * 60 * 1000}, async () => {
   const client = new PlanqkServiceClient(serviceEndpoint!, consumerKey, consumerSecret, tokenEndpoint);
 

package/src/sdk/BaseClient.ts

@@ -0,0 +1,30 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import * as environments from "./environments.js";
+import * as core from "./core/index.js";
+
+export interface BaseClientOptions {
+    environment?: core.Supplier<environments.PlanqkServiceApiEnvironment | string>;
+    /** Specify a custom URL to connect the client to. */
+    baseUrl?: core.Supplier<string>;
+    token?: core.Supplier<core.BearerToken | undefined>;
+    /** Additional headers to include in requests. */
+    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
+    /** The default maximum time to wait for a response in seconds. */
+    timeoutInSeconds?: number;
+    /** The default number of times to retry the request. Defaults to 2. */
+    maxRetries?: number;
+}
+
+export interface BaseRequestOptions {
+    /** The maximum time to wait for a response in seconds. */
+    timeoutInSeconds?: number;
+    /** The number of times to retry the request. Defaults to 2. */
+    maxRetries?: number;
+    /** A hook to abort the request. */
+    abortSignal?: AbortSignal;
+    /** Additional query string parameters to include in the request. */
+    queryParams?: Record<string, unknown>;
+    /** Additional headers to include in the request. */
+    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
+}

package/src/sdk/Client.ts

@@ -1,32 +1,15 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
+// This file was auto-generated by Fern from our API Definition.
 
-import * as environments from "./environments.js";
+import type { BaseClientOptions, BaseRequestOptions } from "./BaseClient.js";
 import * as core from "./core/index.js";
 import { mergeHeaders } from "./core/headers.js";
+import * as environments from "./environments.js";
 import { ServiceApi } from "./api/resources/serviceApi/client/Client.js";
 
 export declare namespace PlanqkServiceApiClient {
-    export interface Options {
-        environment?: core.Supplier<environments.PlanqkServiceApiEnvironment | string>;
-        /** Specify a custom URL to connect the client to. */
-        baseUrl?: core.Supplier<string>;
-        token?: core.Supplier<core.BearerToken | undefined>;
-        /** Additional headers to include in requests. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
-    }
+    export interface Options extends BaseClientOptions {}
 
-    export interface RequestOptions {
-        /** The maximum time to wait for a response in seconds. */
-        timeoutInSeconds?: number;
-        /** The number of times to retry the request. Defaults to 2. */
-        maxRetries?: number;
-        /** A hook to abort the request. */
-        abortSignal?: AbortSignal;
-        /** Additional headers to include in the request. */
-        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
-    }
+    export interface RequestOptions extends BaseRequestOptions {}
 }
 
 export class PlanqkServiceApiClient {

package/src/sdk/api/index.ts

@@ -1,2 +1,2 @@
-export * from "./resources/index.js";
 export * from "./types/index.js";
+export * from "./resources/index.js";

package/src/sdk/api/resources/index.ts

@@ -1,2 +1 @@
 export * as serviceApi from "./serviceApi/index.js";
-export * from "./serviceApi/types/index.js";