@planqk/planqk-service-sdk 2.1.1 → 2.2.0

package/src/sdk/core/fetcher/getErrorResponseBody.ts

@@ -0,0 +1,32 @@
+import { fromJson } from "../json.js";
+import { getResponseBody } from "./getResponseBody.js";
+
+export async function getErrorResponseBody(response: Response): Promise<unknown> {
+    let contentType = response.headers.get("Content-Type")?.toLowerCase();
+    if (contentType == null || contentType.length === 0) {
+        return getResponseBody(response);
+    }
+
+    if (contentType.indexOf(";") !== -1) {
+        contentType = contentType.split(";")[0]?.trim() ?? "";
+    }
+    switch (contentType) {
+        case "application/hal+json":
+        case "application/json":
+        case "application/ld+json":
+        case "application/problem+json":
+        case "application/vnd.api+json":
+        case "text/json":
+            const text = await response.text();
+            return text.length > 0 ? fromJson(text) : undefined;
+        default:
+            if (contentType.startsWith("application/vnd.") && contentType.endsWith("+json")) {
+                const text = await response.text();
+                return text.length > 0 ? fromJson(text) : undefined;
+            }
+
+            // Fallback to plain text if content type is not recognized
+            // Even if no body is present, the response will be an empty string
+            return await response.text();
+    }
+}

package/src/sdk/core/fetcher/getFetchFn.ts

@@ -1,25 +1,3 @@
-import { RUNTIME } from "../runtime";
-
-/**
- * Returns a fetch function based on the runtime
- */
-export async function getFetchFn(): Promise<any> {
-    // In Node.js 18+ environments, use native fetch
-    if (RUNTIME.type === "node" && RUNTIME.parsedVersion != null && RUNTIME.parsedVersion >= 18) {
-        return fetch;
-    }
-
-    // In Node.js 18 or lower environments, the SDK always uses`node-fetch`.
-    if (RUNTIME.type === "node") {
-        return (await import("node-fetch")).default as any;
-    }
-
-    // Otherwise the SDK uses global fetch if available,
-    // and falls back to node-fetch.
-    if (typeof fetch == "function") {
-        return fetch;
-    }
-
-    // Defaults to node `node-fetch` if global fetch isn't available
-    return (await import("node-fetch")).default as any;
+export async function getFetchFn(): Promise<typeof fetch> {
+    return fetch;
 }

package/src/sdk/core/fetcher/getRequestBody.ts

@@ -1,3 +1,5 @@
+import { toJson } from "../json.js";
+
 export declare namespace GetRequestBody {
     interface Args {
         body: unknown;
@@ -7,7 +9,7 @@ export declare namespace GetRequestBody {
 
 export async function getRequestBody({ body, type }: GetRequestBody.Args): Promise<BodyInit | undefined> {
     if (type.includes("json")) {
-        return JSON.stringify(body);
+        return toJson(body);
     } else {
         return body as BodyInit;
     }

package/src/sdk/core/fetcher/getResponseBody.ts

@@ -1,32 +1,43 @@
-import { chooseStreamWrapper } from "./stream-wrappers/chooseStreamWrapper";
+import { getBinaryResponse } from "./BinaryResponse.js";
+import { isResponseWithBody } from "./ResponseWithBody.js";
+import { fromJson } from "../json.js";
 
 export async function getResponseBody(response: Response, responseType?: string): Promise<unknown> {
-    if (response.body != null && responseType === "blob") {
-        return await response.blob();
-    } else if (response.body != null && responseType === "sse") {
-        return response.body;
-    } else if (response.body != null && responseType === "streaming") {
-        return chooseStreamWrapper(response.body);
-    } else if (response.body != null && responseType === "text") {
-        return await response.text();
-    } else {
-        const text = await response.text();
-        if (text.length > 0) {
-            try {
-                let responseBody = JSON.parse(text);
-                return responseBody;
-            } catch (err) {
-                return {
-                    ok: false,
-                    error: {
-                        reason: "non-json",
-                        statusCode: response.status,
-                        rawBody: text,
-                    },
-                };
-            }
-        } else {
-            return undefined;
+    if (!isResponseWithBody(response)) {
+        return undefined;
+    }
+    switch (responseType) {
+        case "binary-response":
+            return getBinaryResponse(response);
+        case "blob":
+            return await response.blob();
+        case "arrayBuffer":
+            return await response.arrayBuffer();
+        case "sse":
+            return response.body;
+        case "streaming":
+            return response.body;
+
+        case "text":
+            return await response.text();
+    }
+
+    // if responseType is "json" or not specified, try to parse as JSON
+    const text = await response.text();
+    if (text.length > 0) {
+        try {
+            let responseBody = fromJson(text);
+            return responseBody;
+        } catch (err) {
+            return {
+                ok: false,
+                error: {
+                    reason: "non-json",
+                    statusCode: response.status,
+                    rawBody: text,
+                },
+            };
         }
     }
+    return undefined;
 }

package/src/sdk/core/fetcher/index.ts

@@ -1,5 +1,9 @@
-export type { APIResponse } from "./APIResponse";
-export { fetcher } from "./Fetcher";
-export type { Fetcher, FetchFunction } from "./Fetcher";
-export { getHeader } from "./getHeader";
-export { Supplier } from "./Supplier";
+export type { APIResponse } from "./APIResponse.js";
+export { fetcher } from "./Fetcher.js";
+export type { Fetcher, FetchFunction } 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";

package/src/sdk/core/fetcher/makeRequest.ts

@@ -1,4 +1,4 @@
-import { anySignal, getTimeoutSignal } from "./signals";
+import { anySignal, getTimeoutSignal } from "./signals.js";
 
 export const makeRequest = async (
     fetchFn: (url: string, init: RequestInit) => Promise<Response>,
@@ -9,7 +9,7 @@ export const makeRequest = async (
     timeoutMs?: number,
     abortSignal?: AbortSignal,
     withCredentials?: boolean,
-    duplex?: "half"
+    duplex?: "half",
 ): Promise<Response> => {
     const signals: AbortSignal[] = [];
 

package/src/sdk/core/fetcher/requestWithRetries.ts

@@ -1,17 +1,29 @@
-const INITIAL_RETRY_DELAY = 1;
-const MAX_RETRY_DELAY = 60;
+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: number): number {
+    // Generate a random value between -JITTER_FACTOR and +JITTER_FACTOR
+    const jitterMultiplier = 1 + (Math.random() * 2 - 1) * JITTER_FACTOR;
+    return delay * jitterMultiplier;
+}
 
 export async function requestWithRetries(
     requestFn: () => Promise<Response>,
-    maxRetries: number = DEFAULT_MAX_RETRIES
+    maxRetries: number = DEFAULT_MAX_RETRIES,
 ): Promise<Response> {
     let response: Response = await requestFn();
 
     for (let i = 0; i < maxRetries; ++i) {
-        if ([408, 409, 429].includes(response.status) || response.status >= 500) {
-            const delay = Math.min(INITIAL_RETRY_DELAY * Math.pow(2, i), MAX_RETRY_DELAY);
-            await new Promise((resolve) => setTimeout(resolve, delay));
+        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));
             response = await requestFn();
         } else {
             break;

package/src/sdk/core/fetcher/signals.ts

@@ -15,7 +15,7 @@ export function getTimeoutSignal(timeoutMs: number): { signal: AbortSignal; abor
 export function anySignal(...args: AbortSignal[] | [AbortSignal[]]): AbortSignal {
     // Allowing signals to be passed either as array
     // of signals or as multiple arguments.
-    const signals = <AbortSignal[]>(args.length === 1 && Array.isArray(args[0]) ? args[0] : args);
+    const signals = (args.length === 1 && Array.isArray(args[0]) ? args[0] : args) as AbortSignal[];
 
     const controller = new AbortController();
 

package/src/sdk/core/headers.ts

@@ -0,0 +1,35 @@
+import * as core from "./index.js";
+
+export function mergeHeaders(
+    ...headersArray: (Record<string, string | core.Supplier<string | undefined> | undefined> | undefined)[]
+): Record<string, string | core.Supplier<string | undefined>> {
+    const result: Record<string, string | core.Supplier<string | undefined>> = {};
+
+    for (const [key, value] of headersArray
+        .filter((headers) => headers != null)
+        .flatMap((headers) => Object.entries(headers))) {
+        if (value != null) {
+            result[key] = value;
+        } else if (key in result) {
+            delete result[key];
+        }
+    }
+
+    return result;
+}
+
+export function mergeOnlyDefinedHeaders(
+    ...headersArray: (Record<string, string | core.Supplier<string | undefined> | undefined> | undefined)[]
+): Record<string, string | core.Supplier<string | undefined>> {
+    const result: Record<string, string | core.Supplier<string | undefined>> = {};
+
+    for (const [key, value] of headersArray
+        .filter((headers) => headers != null)
+        .flatMap((headers) => Object.entries(headers))) {
+        if (value != null) {
+            result[key] = value;
+        }
+    }
+
+    return result;
+}

package/src/sdk/core/index.ts

@@ -1,3 +1,5 @@
-export * from "./fetcher";
-export * from "./auth";
-export * from "./runtime";
+export * from "./fetcher/index.js";
+export * from "./runtime/index.js";
+export * as url from "./url/index.js";
+export * from "./auth/index.js";
+export * from "./base64.js";

package/src/sdk/core/json.ts

@@ -0,0 +1,27 @@
+/**
+ * Serialize a value to JSON
+ * @param value A JavaScript value, usually an object or array, to be converted.
+ * @param replacer A function that transforms the results.
+ * @param space Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
+ * @returns JSON string
+ */
+export const toJson = (
+    value: unknown,
+    replacer?: (this: unknown, key: string, value: unknown) => unknown,
+    space?: string | number,
+): string => {
+    return JSON.stringify(value, replacer, space);
+};
+
+/**
+ * Parse JSON string to object, array, or other type
+ * @param text A valid JSON string.
+ * @param reviver A function that transforms the results. This function is called for each member of the object. If a member contains nested objects, the nested objects are transformed before the parent object is.
+ * @returns Parsed object, array, or other type
+ */
+export function fromJson<T = unknown>(
+    text: string,
+    reviver?: (this: unknown, key: string, value: unknown) => unknown,
+): T {
+    return JSON.parse(text, reviver);
+}

package/src/sdk/core/runtime/index.ts

@@ -1 +1 @@
-export { RUNTIME } from "./runtime";
+export { RUNTIME } from "./runtime.js";

package/src/sdk/core/runtime/runtime.ts

@@ -8,58 +8,12 @@ interface BunGlobal {
     version: string;
 }
 
-declare const Deno: DenoGlobal;
-declare const Bun: BunGlobal;
-
-/**
- * A constant that indicates whether the environment the code is running is a Web Browser.
- */
-const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
-
-/**
- * A constant that indicates whether the environment the code is running is a Web Worker.
- */
-const isWebWorker =
-    typeof self === "object" &&
-    // @ts-ignore
-    typeof self?.importScripts === "function" &&
-    (self.constructor?.name === "DedicatedWorkerGlobalScope" ||
-        self.constructor?.name === "ServiceWorkerGlobalScope" ||
-        self.constructor?.name === "SharedWorkerGlobalScope");
-
-/**
- * A constant that indicates whether the environment the code is running is Deno.
- */
-const isDeno =
-    typeof Deno !== "undefined" && typeof Deno.version !== "undefined" && typeof Deno.version.deno !== "undefined";
-
-/**
- * A constant that indicates whether the environment the code is running is Bun.sh.
- */
-const isBun = typeof Bun !== "undefined" && typeof Bun.version !== "undefined";
-
-/**
- * A constant that indicates whether the environment the code is running is Node.JS.
- */
-const isNode =
-    typeof process !== "undefined" &&
-    Boolean(process.version) &&
-    Boolean(process.versions?.node) &&
-    // Deno spoofs process.versions.node, see https://deno.land/std@0.177.0/node/process.ts?s=versions
-    !isDeno &&
-    !isBun;
-
-/**
- * A constant that indicates whether the environment the code is running is in React-Native.
- * https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Core/setUpNavigator.js
- */
-const isReactNative = typeof navigator !== "undefined" && navigator?.product === "ReactNative";
-
-/**
- * A constant that indicates whether the environment the code is running is Cloudflare.
- * https://developers.cloudflare.com/workers/runtime-apis/web-standards/#navigatoruseragent
- */
-const isCloudflare = typeof globalThis !== "undefined" && globalThis?.navigator?.userAgent === "Cloudflare-Workers";
+declare const Deno: DenoGlobal | undefined;
+declare const Bun: BunGlobal | undefined;
+declare const EdgeRuntime: string | undefined;
+declare const self: typeof globalThis.self & {
+    importScripts?: unknown;
+};
 
 /**
  * A constant that indicates which environment and version the SDK is running in.
@@ -67,12 +21,16 @@ const isCloudflare = typeof globalThis !== "undefined" && globalThis?.navigator?
 export const RUNTIME: Runtime = evaluateRuntime();
 
 export interface Runtime {
-    type: "browser" | "web-worker" | "deno" | "bun" | "node" | "react-native" | "unknown" | "workerd";
+    type: "browser" | "web-worker" | "deno" | "bun" | "node" | "react-native" | "unknown" | "workerd" | "edge-runtime";
     version?: string;
     parsedVersion?: number;
 }
 
 function evaluateRuntime(): Runtime {
+    /**
+     * A constant that indicates whether the environment the code is running is a Web Browser.
+     */
+    const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
     if (isBrowser) {
         return {
             type: "browser",
@@ -80,18 +38,49 @@ function evaluateRuntime(): Runtime {
         };
     }
 
+    /**
+     * A constant that indicates whether the environment the code is running is Cloudflare.
+     * https://developers.cloudflare.com/workers/runtime-apis/web-standards/#navigatoruseragent
+     */
+    const isCloudflare = typeof globalThis !== "undefined" && globalThis?.navigator?.userAgent === "Cloudflare-Workers";
     if (isCloudflare) {
         return {
             type: "workerd",
         };
     }
 
+    /**
+     * A constant that indicates whether the environment the code is running is Edge Runtime.
+     * https://vercel.com/docs/functions/runtimes/edge-runtime#check-if-you're-running-on-the-edge-runtime
+     */
+    const isEdgeRuntime = typeof EdgeRuntime === "string";
+    if (isEdgeRuntime) {
+        return {
+            type: "edge-runtime",
+        };
+    }
+
+    /**
+     * A constant that indicates whether the environment the code is running is a Web Worker.
+     */
+    const isWebWorker =
+        typeof self === "object" &&
+        typeof self?.importScripts === "function" &&
+        (self.constructor?.name === "DedicatedWorkerGlobalScope" ||
+            self.constructor?.name === "ServiceWorkerGlobalScope" ||
+            self.constructor?.name === "SharedWorkerGlobalScope");
     if (isWebWorker) {
         return {
             type: "web-worker",
         };
     }
 
+    /**
+     * A constant that indicates whether the environment the code is running is Deno.
+     * FYI Deno spoofs process.versions.node, see https://deno.land/std@0.177.0/node/process.ts?s=versions
+     */
+    const isDeno =
+        typeof Deno !== "undefined" && typeof Deno.version !== "undefined" && typeof Deno.version.deno !== "undefined";
     if (isDeno) {
         return {
             type: "deno",
@@ -99,6 +88,10 @@ function evaluateRuntime(): Runtime {
         };
     }
 
+    /**
+     * A constant that indicates whether the environment the code is running is Bun.sh.
+     */
+    const isBun = typeof Bun !== "undefined" && typeof Bun.version !== "undefined";
     if (isBun) {
         return {
             type: "bun",
@@ -106,6 +99,15 @@ function evaluateRuntime(): Runtime {
         };
     }
 
+    /**
+     * A constant that indicates whether the environment the code is running is Node.JS.
+     */
+    const isNode =
+        typeof process !== "undefined" &&
+        "version" in process &&
+        !!process.version &&
+        "versions" in process &&
+        !!process.versions?.node;
     if (isNode) {
         return {
             type: "node",
@@ -114,6 +116,11 @@ function evaluateRuntime(): Runtime {
         };
     }
 
+    /**
+     * A constant that indicates whether the environment the code is running is in React-Native.
+     * https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Core/setUpNavigator.js
+     */
+    const isReactNative = typeof navigator !== "undefined" && navigator?.product === "ReactNative";
     if (isReactNative) {
         return {
             type: "react-native",

package/src/sdk/core/url/index.ts

@@ -0,0 +1,2 @@
+export { join } from "./join.js";
+export { toQueryString } from "./qs.js";

package/src/sdk/core/url/join.ts

@@ -0,0 +1,55 @@
+export function join(base: string, ...segments: string[]): string {
+    if (!base) {
+        return "";
+    }
+
+    if (base.includes("://")) {
+        let url: URL;
+        try {
+            url = new URL(base);
+        } catch {
+            // Fallback to path joining if URL is malformed
+            return joinPath(base, ...segments);
+        }
+
+        for (const segment of segments) {
+            const cleanSegment = trimSlashes(segment);
+            if (cleanSegment) {
+                url.pathname = joinPathSegments(url.pathname, cleanSegment);
+            }
+        }
+
+        return url.toString();
+    }
+
+    return joinPath(base, ...segments);
+}
+
+function joinPath(base: string, ...segments: string[]): string {
+    let result = base;
+
+    for (const segment of segments) {
+        const cleanSegment = trimSlashes(segment);
+        if (cleanSegment) {
+            result = joinPathSegments(result, cleanSegment);
+        }
+    }
+
+    return result;
+}
+
+function joinPathSegments(left: string, right: string): string {
+    if (left.endsWith("/")) {
+        return left + right;
+    }
+    return left + "/" + right;
+}
+
+function trimSlashes(str: string): string {
+    if (!str) return str;
+
+    let start = str.startsWith("/") ? 1 : 0;
+    let end = str.endsWith("/") ? str.length - 1 : str.length;
+
+    return str.slice(start, end);
+}

package/src/sdk/core/url/qs.ts

@@ -0,0 +1,74 @@
+interface QueryStringOptions {
+    arrayFormat?: "indices" | "repeat";
+    encode?: boolean;
+}
+
+const defaultQsOptions: Required<QueryStringOptions> = {
+    arrayFormat: "indices",
+    encode: true,
+} as const;
+
+function encodeValue(value: unknown, shouldEncode: boolean): string {
+    if (value === undefined) {
+        return "";
+    }
+    if (value === null) {
+        return "";
+    }
+    const stringValue = String(value);
+    return shouldEncode ? encodeURIComponent(stringValue) : stringValue;
+}
+
+function stringifyObject(obj: Record<string, unknown>, prefix = "", options: Required<QueryStringOptions>): string[] {
+    const parts: string[] = [];
+
+    for (const [key, value] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}[${key}]` : key;
+
+        if (value === undefined) {
+            continue;
+        }
+
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                continue;
+            }
+            for (let i = 0; i < value.length; i++) {
+                const item = value[i];
+                if (item === undefined) {
+                    continue;
+                }
+                if (typeof item === "object" && !Array.isArray(item) && item !== null) {
+                    const arrayKey = options.arrayFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
+                    parts.push(...stringifyObject(item as Record<string, unknown>, arrayKey, options));
+                } else {
+                    const arrayKey = options.arrayFormat === "indices" ? `${fullKey}[${i}]` : fullKey;
+                    const encodedKey = options.encode ? encodeURIComponent(arrayKey) : arrayKey;
+                    parts.push(`${encodedKey}=${encodeValue(item, options.encode)}`);
+                }
+            }
+        } else if (typeof value === "object" && value !== null) {
+            if (Object.keys(value as Record<string, unknown>).length === 0) {
+                continue;
+            }
+            parts.push(...stringifyObject(value as Record<string, unknown>, fullKey, options));
+        } else {
+            const encodedKey = options.encode ? encodeURIComponent(fullKey) : fullKey;
+            parts.push(`${encodedKey}=${encodeValue(value, options.encode)}`);
+        }
+    }
+
+    return parts;
+}
+
+export function toQueryString(obj: unknown, options?: QueryStringOptions): string {
+    if (obj == null || typeof obj !== "object") {
+        return "";
+    }
+
+    const parts = stringifyObject(obj as Record<string, unknown>, "", {
+        ...defaultQsOptions,
+        ...options,
+    });
+    return parts.join("&");
+}

package/src/sdk/errors/PlanqkServiceApiError.ts

@@ -2,20 +2,30 @@
  * This file was auto-generated by Fern from our API Definition.
  */
 
+import * as core from "../core/index.js";
+import { toJson } from "../core/json.js";
+
 export class PlanqkServiceApiError extends Error {
-    readonly statusCode?: number;
-    readonly body?: unknown;
+    public readonly statusCode?: number;
+    public readonly body?: unknown;
+    public readonly rawResponse?: core.RawResponse;
 
-    constructor({ message, statusCode, body }: { message?: string; statusCode?: number; body?: unknown }) {
+    constructor({
+        message,
+        statusCode,
+        body,
+        rawResponse,
+    }: {
+        message?: string;
+        statusCode?: number;
+        body?: unknown;
+        rawResponse?: core.RawResponse;
+    }) {
         super(buildMessage({ message, statusCode, body }));
         Object.setPrototypeOf(this, PlanqkServiceApiError.prototype);
-        if (statusCode != null) {
-            this.statusCode = statusCode;
-        }
-
-        if (body !== undefined) {
-            this.body = body;
-        }
+        this.statusCode = statusCode;
+        this.body = body;
+        this.rawResponse = rawResponse;
     }
 }
 
@@ -38,7 +48,7 @@ function buildMessage({
     }
 
     if (body != null) {
-        lines.push(`Body: ${JSON.stringify(body, undefined, 2)}`);
+        lines.push(`Body: ${toJson(body, undefined, 2)}`);
     }
 
     return lines.join("\n");