@planqk/planqk-api-sdk 1.0.0

package/src/core/fetcher/getHeader.ts

@@ -0,0 +1,8 @@
+export function getHeader(headers: Record<string, any>, header: string): string | undefined {
+    for (const [headerKey, headerValue] of Object.entries(headers)) {
+        if (headerKey.toLowerCase() === header.toLowerCase()) {
+            return headerValue;
+        }
+    }
+    return undefined;
+}

package/src/core/fetcher/getRequestBody.ts

@@ -0,0 +1,16 @@
+import { toJson } from "../json.js";
+
+export declare namespace GetRequestBody {
+    interface Args {
+        body: unknown;
+        type: "json" | "file" | "bytes" | "other";
+    }
+}
+
+export async function getRequestBody({ body, type }: GetRequestBody.Args): Promise<BodyInit | undefined> {
+    if (type.includes("json")) {
+        return toJson(body);
+    } else {
+        return body as BodyInit;
+    }
+}

package/src/core/fetcher/getResponseBody.ts

@@ -0,0 +1,43 @@
+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 (!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/core/fetcher/index.ts

@@ -0,0 +1,9 @@
+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/core/fetcher/makeRequest.ts

@@ -0,0 +1,44 @@
+import { anySignal, getTimeoutSignal } from "./signals.js";
+
+export const makeRequest = async (
+    fetchFn: (url: string, init: RequestInit) => Promise<Response>,
+    url: string,
+    method: string,
+    headers: Record<string, string>,
+    requestBody: BodyInit | undefined,
+    timeoutMs?: number,
+    abortSignal?: AbortSignal,
+    withCredentials?: boolean,
+    duplex?: "half",
+): Promise<Response> => {
+    const signals: AbortSignal[] = [];
+
+    // Add timeout signal
+    let timeoutAbortId: NodeJS.Timeout | undefined = undefined;
+    if (timeoutMs != null) {
+        const { signal, abortId } = getTimeoutSignal(timeoutMs);
+        timeoutAbortId = abortId;
+        signals.push(signal);
+    }
+
+    // Add arbitrary signal
+    if (abortSignal != null) {
+        signals.push(abortSignal);
+    }
+    let newSignals = anySignal(signals);
+    const response = await fetchFn(url, {
+        method: method,
+        headers,
+        body: requestBody,
+        signal: newSignals,
+        credentials: withCredentials ? "include" : undefined,
+        // @ts-ignore
+        duplex,
+    });
+
+    if (timeoutAbortId != null) {
+        clearTimeout(timeoutAbortId);
+    }
+
+    return response;
+};

package/src/core/fetcher/requestWithRetries.ts

@@ -0,0 +1,33 @@
+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,
+): Promise<Response> {
+    let response: 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));
+            response = await requestFn();
+        } else {
+            break;
+        }
+    }
+    return response!;
+}

package/src/core/fetcher/signals.ts

@@ -0,0 +1,38 @@
+const TIMEOUT = "timeout";
+
+export function getTimeoutSignal(timeoutMs: number): { signal: AbortSignal; abortId: NodeJS.Timeout } {
+    const controller = new AbortController();
+    const abortId = setTimeout(() => controller.abort(TIMEOUT), timeoutMs);
+    return { signal: controller.signal, abortId };
+}
+
+/**
+ * Returns an abort signal that is getting aborted when
+ * at least one of the specified abort signals is aborted.
+ *
+ * Requires at least node.js 18.
+ */
+export function anySignal(...args: AbortSignal[] | [AbortSignal[]]): AbortSignal {
+    // Allowing signals to be passed either as array
+    // of signals or as multiple arguments.
+    const signals = (args.length === 1 && Array.isArray(args[0]) ? args[0] : args) as AbortSignal[];
+
+    const controller = new AbortController();
+
+    for (const signal of signals) {
+        if (signal.aborted) {
+            // Exiting early if one of the signals
+            // is already aborted.
+            controller.abort((signal as any)?.reason);
+            break;
+        }
+
+        // Listening for signals and removing the listeners
+        // when at least one symbol is aborted.
+        signal.addEventListener("abort", () => controller.abort((signal as any)?.reason), {
+            signal: controller.signal,
+        });
+    }
+
+    return controller.signal;
+}

package/src/core/file.ts

@@ -0,0 +1,11 @@
+export type FileLike =
+    | ArrayBuffer
+    | Uint8Array
+    | import("buffer").Buffer
+    | import("buffer").Blob
+    | import("buffer").File
+    | import("stream").Readable
+    | import("stream/web").ReadableStream
+    | globalThis.Blob
+    | globalThis.File
+    | ReadableStream;

package/src/core/form-data-utils/FormDataWrapper.ts

@@ -0,0 +1,176 @@
+import { toJson } from "../../core/json.js";
+import { RUNTIME } from "../runtime/index.js";
+
+type NamedValue = {
+    name: string;
+} & unknown;
+
+type PathedValue = {
+    path: string | { toString(): string };
+} & unknown;
+
+type StreamLike = {
+    read?: () => unknown;
+    pipe?: (dest: unknown) => unknown;
+} & unknown;
+
+function isNamedValue(value: unknown): value is NamedValue {
+    return typeof value === "object" && value != null && "name" in value;
+}
+
+function isPathedValue(value: unknown): value is PathedValue {
+    return typeof value === "object" && value != null && "path" in value;
+}
+
+function isStreamLike(value: unknown): value is StreamLike {
+    return typeof value === "object" && value != null && ("read" in value || "pipe" in value);
+}
+
+function isReadableStream(value: unknown): value is ReadableStream {
+    return typeof value === "object" && value != null && "getReader" in value;
+}
+
+function isBuffer(value: unknown): value is Buffer {
+    return typeof Buffer !== "undefined" && Buffer.isBuffer && Buffer.isBuffer(value);
+}
+
+function isArrayBufferView(value: unknown): value is ArrayBufferView {
+    return ArrayBuffer.isView(value);
+}
+
+interface FormDataRequest<Body> {
+    body: Body;
+    headers: Record<string, string>;
+    duplex?: "half";
+}
+
+function getLastPathSegment(pathStr: string): string {
+    const lastForwardSlash = pathStr.lastIndexOf("/");
+    const lastBackSlash = pathStr.lastIndexOf("\\");
+    const lastSlashIndex = Math.max(lastForwardSlash, lastBackSlash);
+    return lastSlashIndex >= 0 ? pathStr.substring(lastSlashIndex + 1) : pathStr;
+}
+
+async function streamToBuffer(stream: unknown): Promise<Buffer> {
+    if (RUNTIME.type === "node") {
+        const { Readable } = await import("stream");
+
+        if (stream instanceof Readable) {
+            const chunks: Buffer[] = [];
+            for await (const chunk of stream) {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            }
+            return Buffer.concat(chunks);
+        }
+    }
+
+    if (isReadableStream(stream)) {
+        const reader = stream.getReader();
+        const chunks: Uint8Array[] = [];
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                chunks.push(value);
+            }
+        } finally {
+            reader.releaseLock();
+        }
+
+        const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+        const result = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+
+        return Buffer.from(result);
+    }
+
+    throw new Error(
+        "Unsupported stream type: " + typeof stream + ". Expected Node.js Readable stream or Web ReadableStream.",
+    );
+}
+
+export async function newFormData(): Promise<FormDataWrapper> {
+    return new FormDataWrapper();
+}
+
+export class FormDataWrapper {
+    private fd: FormData = new FormData();
+
+    public async setup(): Promise<void> {
+        // noop
+    }
+
+    public append(key: string, value: unknown): void {
+        this.fd.append(key, String(value));
+    }
+
+    private getFileName(value: unknown, filename?: string): string | undefined {
+        if (filename != null) {
+            return filename;
+        }
+        if (isNamedValue(value)) {
+            return value.name;
+        }
+        if (isPathedValue(value) && value.path) {
+            return getLastPathSegment(value.path.toString());
+        }
+        return undefined;
+    }
+
+    private async convertToBlob(value: unknown): Promise<Blob> {
+        if (isStreamLike(value) || isReadableStream(value)) {
+            const buffer = await streamToBuffer(value);
+            return new Blob([buffer]);
+        }
+
+        if (value instanceof Blob) {
+            return value;
+        }
+
+        if (isBuffer(value)) {
+            return new Blob([value]);
+        }
+
+        if (value instanceof ArrayBuffer) {
+            return new Blob([value]);
+        }
+
+        if (isArrayBufferView(value)) {
+            return new Blob([value]);
+        }
+
+        if (typeof value === "string") {
+            return new Blob([value]);
+        }
+
+        if (typeof value === "object" && value !== null) {
+            return new Blob([toJson(value)], { type: "application/json" });
+        }
+
+        return new Blob([String(value)]);
+    }
+
+    public async appendFile(key: string, value: unknown, fileName?: string): Promise<void> {
+        fileName = this.getFileName(value, fileName);
+        const blob = await this.convertToBlob(value);
+
+        if (fileName) {
+            this.fd.append(key, blob, fileName);
+        } else {
+            this.fd.append(key, blob);
+        }
+    }
+
+    public getRequest(): FormDataRequest<FormData> {
+        return {
+            body: this.fd,
+            headers: {},
+            duplex: "half" as const,
+        };
+    }
+}

package/src/core/form-data-utils/encodeAsFormParameter.ts

@@ -0,0 +1,12 @@
+import { toQueryString } from "../url/qs.js";
+
+export function encodeAsFormParameter(value: unknown): Record<string, string> {
+    const stringified = toQueryString(value, { encode: false });
+
+    const keyValuePairs = stringified.split("&").map((pair) => {
+        const [key, value] = pair.split("=");
+        return [key, value] as const;
+    });
+
+    return Object.fromEntries(keyValuePairs);
+}

package/src/core/form-data-utils/index.ts

@@ -0,0 +1,2 @@
+export { encodeAsFormParameter } from "./encodeAsFormParameter.js";
+export * from "./FormDataWrapper.js";

package/src/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/core/index.ts

@@ -0,0 +1,5 @@
+export * from "./fetcher/index.js";
+export * from "./runtime/index.js";
+export * as url from "./url/index.js";
+export * from "./form-data-utils/index.js";
+export * from "./file.js";

package/src/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/core/runtime/index.ts

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

package/src/core/runtime/runtime.ts

@@ -0,0 +1,133 @@
+interface DenoGlobal {
+    version: {
+        deno: string;
+    };
+}
+
+interface BunGlobal {
+    version: string;
+}
+
+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.
+ */
+export const RUNTIME: Runtime = evaluateRuntime();
+
+export interface Runtime {
+    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",
+            version: window.navigator.userAgent,
+        };
+    }
+
+    /**
+     * 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",
+            version: Deno.version.deno,
+        };
+    }
+
+    /**
+     * 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",
+            version: Bun.version,
+        };
+    }
+
+    /**
+     * 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",
+            version: process.versions.node,
+            parsedVersion: Number(process.versions.node.split(".")[0]),
+        };
+    }
+
+    /**
+     * 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",
+        };
+    }
+
+    return {
+        type: "unknown",
+    };
+}

package/src/core/url/index.ts

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

package/src/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);
+}