@planqk/planqk-service-sdk 2.1.1 → 2.2.0

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

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

package/src/sdk/api/resources/serviceApi/types/GetResultResponse.ts

@@ -2,9 +2,21 @@
  * This file was auto-generated by Fern from our API Definition.
  */
 
-import * as PlanqkServiceApi from "../../../index";
+import * as PlanqkServiceApi from "../../../index.js";
 
 export interface GetResultResponse {
-    _links?: PlanqkServiceApi.GetResultResponseLinks;
-    _embedded?: PlanqkServiceApi.GetResultResponseEmbedded;
+    _links?: GetResultResponse.Links;
+    _embedded?: GetResultResponse.Embedded;
+    /** Accepts any additional properties */
+    [key: string]: any;
+}
+
+export namespace GetResultResponse {
+    export interface Links {
+        status?: PlanqkServiceApi.HalLink;
+    }
+
+    export interface Embedded {
+        status?: PlanqkServiceApi.ServiceExecution;
+    }
 }

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

@@ -1,4 +1 @@
-export * from "./HealthCheckResponse";
-export * from "./GetResultResponseLinks";
-export * from "./GetResultResponseEmbedded";
-export * from "./GetResultResponse";
+export * from "./GetResultResponse.js";

package/src/sdk/api/types/ServiceExecution.ts

@@ -2,12 +2,22 @@
  * This file was auto-generated by Fern from our API Definition.
  */
 
-import * as PlanqkServiceApi from "../index";
-
 export interface ServiceExecution {
     id?: string;
-    status?: PlanqkServiceApi.ServiceExecutionStatus;
+    status?: ServiceExecution.Status;
     createdAt?: string;
     startedAt?: string;
     endedAt?: string;
 }
+
+export namespace ServiceExecution {
+    export type Status = "UNKNOWN" | "PENDING" | "RUNNING" | "SUCCEEDED" | "CANCELLED" | "FAILED";
+    export const Status = {
+        Unknown: "UNKNOWN",
+        Pending: "PENDING",
+        Running: "RUNNING",
+        Succeeded: "SUCCEEDED",
+        Cancelled: "CANCELLED",
+        Failed: "FAILED",
+    } as const;
+}

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

@@ -1,6 +1,2 @@
-export * from "./InputData";
-export * from "./InputParams";
-export * from "./InputDataRef";
-export * from "./ServiceExecutionStatus";
-export * from "./ServiceExecution";
-export * from "./HalLink";
+export * from "./ServiceExecution.js";
+export * from "./HalLink.js";

package/src/sdk/core/auth/BasicAuth.ts

@@ -1,4 +1,4 @@
-import { Base64 } from "js-base64";
+import { base64Decode, base64Encode } from "../base64.js";
 
 export interface BasicAuth {
     username: string;
@@ -12,12 +12,12 @@ export const BasicAuth = {
         if (basicAuth == null) {
             return undefined;
         }
-        const token = Base64.encode(`${basicAuth.username}:${basicAuth.password}`);
+        const token = base64Encode(`${basicAuth.username}:${basicAuth.password}`);
         return `Basic ${token}`;
     },
     fromAuthorizationHeader: (header: string): BasicAuth => {
         const credentials = header.replace(BASIC_AUTH_HEADER_PREFIX, "");
-        const decoded = Base64.decode(credentials);
+        const decoded = base64Decode(credentials);
         const [username, password] = decoded.split(":", 2);
 
         if (username == null || password == null) {

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

@@ -1,2 +1,2 @@
-export { BasicAuth } from "./BasicAuth";
-export { BearerToken } from "./BearerToken";
+export { BasicAuth } from "./BasicAuth.js";
+export { BearerToken } from "./BearerToken.js";

package/src/sdk/core/base64.ts

@@ -0,0 +1,27 @@
+function base64ToBytes(base64: string): Uint8Array {
+    const binString = atob(base64);
+    return Uint8Array.from(binString, (m) => m.codePointAt(0)!);
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+    const binString = String.fromCodePoint(...bytes);
+    return btoa(binString);
+}
+
+export function base64Encode(input: string): string {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(input, "utf8").toString("base64");
+    }
+
+    const bytes = new TextEncoder().encode(input);
+    return bytesToBase64(bytes);
+}
+
+export function base64Decode(input: string): string {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(input, "base64").toString("utf8");
+    }
+
+    const bytes = base64ToBytes(input);
+    return new TextDecoder().decode(bytes);
+}

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

@@ -1,12 +1,23 @@
+import { RawResponse } from "./RawResponse.js";
+
+/**
+ * The response of an API call.
+ * It is a successful response or a failed response.
+ */
 export type APIResponse<Success, Failure> = SuccessfulResponse<Success> | FailedResponse<Failure>;
 
 export interface SuccessfulResponse<T> {
     ok: true;
     body: T;
+    /**
+     * @deprecated Use `rawResponse` instead
+     */
     headers?: Record<string, any>;
+    rawResponse: RawResponse;
 }
 
 export interface FailedResponse<T> {
     ok: false;
     error: T;
+    rawResponse: RawResponse;
 }

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

@@ -0,0 +1,36 @@
+import { ResponseWithBody } from "./ResponseWithBody.js";
+
+export type BinaryResponse = {
+    /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bodyUsed) */
+    bodyUsed: boolean;
+    /**
+     * Returns a ReadableStream of the response body.
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/body)
+     */
+    stream: () => ReadableStream<Uint8Array>;
+    /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/arrayBuffer) */
+    arrayBuffer: () => Promise<ArrayBuffer>;
+    /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/blob) */
+    blob: () => Promise<Blob>;
+    /**
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bytes)
+     * Some versions of the Fetch API may not support this method.
+     */
+    bytes?(): Promise<Uint8Array>;
+};
+
+export function getBinaryResponse(response: ResponseWithBody): BinaryResponse {
+    const binaryResponse: BinaryResponse = {
+        get bodyUsed() {
+            return response.bodyUsed;
+        },
+        stream: () => response.body,
+        arrayBuffer: response.arrayBuffer.bind(response),
+        blob: response.blob.bind(response),
+    };
+    if ("bytes" in response && typeof response.bytes === "function") {
+        binaryResponse.bytes = response.bytes.bind(response);
+    }
+
+    return binaryResponse;
+}

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

@@ -1,10 +1,14 @@
-import { APIResponse } from "./APIResponse";
-import { createRequestUrl } from "./createRequestUrl";
-import { getFetchFn } from "./getFetchFn";
-import { getRequestBody } from "./getRequestBody";
-import { getResponseBody } from "./getResponseBody";
-import { makeRequest } from "./makeRequest";
-import { requestWithRetries } from "./requestWithRetries";
+import { toJson } from "../json.js";
+import { APIResponse } from "./APIResponse.js";
+import { abortRawResponse, toRawResponse, unknownRawResponse } from "./RawResponse.js";
+import { Supplier } from "./Supplier.js";
+import { createRequestUrl } from "./createRequestUrl.js";
+import { getErrorResponseBody } from "./getErrorResponseBody.js";
+import { getFetchFn } from "./getFetchFn.js";
+import { getRequestBody } from "./getRequestBody.js";
+import { getResponseBody } from "./getResponseBody.js";
+import { makeRequest } from "./makeRequest.js";
+import { requestWithRetries } from "./requestWithRetries.js";
 
 export type FetchFunction = <R = unknown>(args: Fetcher.Args) => Promise<APIResponse<R, Fetcher.Error>>;
 
@@ -13,15 +17,15 @@ export declare namespace Fetcher {
         url: string;
         method: string;
         contentType?: string;
-        headers?: Record<string, string | undefined>;
-        queryParameters?: Record<string, string | string[] | object | object[]>;
+        headers?: Record<string, string | Supplier<string | undefined> | undefined>;
+        queryParameters?: Record<string, string | string[] | object | object[] | null>;
         body?: unknown;
         timeoutMs?: number;
         maxRetries?: number;
         withCredentials?: boolean;
         abortSignal?: AbortSignal;
         requestType?: "json" | "file" | "bytes";
-        responseType?: "json" | "blob" | "sse" | "streaming" | "text";
+        responseType?: "json" | "blob" | "sse" | "streaming" | "text" | "arrayBuffer" | "binary-response";
         duplex?: "half";
     }
 
@@ -49,22 +53,33 @@ export declare namespace Fetcher {
     }
 }
 
-export async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIResponse<R, Fetcher.Error>> {
-    const headers: Record<string, string> = {};
+async function getHeaders(args: Fetcher.Args): Promise<Record<string, string>> {
+    const newHeaders: Record<string, string> = {};
     if (args.body !== undefined && args.contentType != null) {
-        headers["Content-Type"] = args.contentType;
+        newHeaders["Content-Type"] = args.contentType;
+    }
+
+    if (args.headers == null) {
+        return newHeaders;
     }
 
-    if (args.headers != null) {
-        for (const [key, value] of Object.entries(args.headers)) {
-            if (value != null) {
-                headers[key] = value;
-            }
+    for (const [key, value] of Object.entries(args.headers)) {
+        const result = await Supplier.get(value);
+        if (typeof result === "string") {
+            newHeaders[key] = result;
+            continue;
         }
+        if (result == null) {
+            continue;
+        }
+        newHeaders[key] = `${result}`;
     }
+    return newHeaders;
+}
 
+export async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIResponse<R, Fetcher.Error>> {
     const url = createRequestUrl(args.url, args.queryParameters);
-    let requestBody: BodyInit | undefined = await getRequestBody({
+    const requestBody: BodyInit | undefined = await getRequestBody({
         body: args.body,
         type: args.requestType === "json" ? "json" : "other",
     });
@@ -77,22 +92,22 @@ export async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIR
                     fetchFn,
                     url,
                     args.method,
-                    headers,
+                    await getHeaders(args),
                     requestBody,
                     args.timeoutMs,
                     args.abortSignal,
                     args.withCredentials,
-                    args.duplex
+                    args.duplex,
                 ),
-            args.maxRetries
+            args.maxRetries,
         );
-        let responseBody = await getResponseBody(response, args.responseType);
 
         if (response.status >= 200 && response.status < 400) {
             return {
                 ok: true,
-                body: responseBody as R,
+                body: (await getResponseBody(response, args.responseType)) as R,
                 headers: response.headers,
+                rawResponse: toRawResponse(response),
             };
         } else {
             return {
@@ -100,8 +115,9 @@ export async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIR
                 error: {
                     reason: "status-code",
                     statusCode: response.status,
-                    body: responseBody,
+                    body: await getErrorResponseBody(response),
                 },
+                rawResponse: toRawResponse(response),
             };
         }
     } catch (error) {
@@ -112,6 +128,7 @@ export async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIR
                     reason: "unknown",
                     errorMessage: "The user aborted a request",
                 },
+                rawResponse: abortRawResponse,
             };
         } else if (error instanceof Error && error.name === "AbortError") {
             return {
@@ -119,6 +136,7 @@ export async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIR
                 error: {
                     reason: "timeout",
                 },
+                rawResponse: abortRawResponse,
             };
         } else if (error instanceof Error) {
             return {
@@ -127,6 +145,7 @@ export async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIR
                     reason: "unknown",
                     errorMessage: error.message,
                 },
+                rawResponse: unknownRawResponse,
             };
         }
 
@@ -134,8 +153,9 @@ export async function fetcherImpl<R = unknown>(args: Fetcher.Args): Promise<APIR
             ok: false,
             error: {
                 reason: "unknown",
-                errorMessage: JSON.stringify(error),
+                errorMessage: toJson(error),
             },
+            rawResponse: unknownRawResponse,
         };
     }
 }

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

@@ -0,0 +1,93 @@
+let Headers: typeof globalThis.Headers;
+
+if (typeof globalThis.Headers !== "undefined") {
+    Headers = globalThis.Headers;
+} else {
+    Headers = class Headers implements Headers {
+        private headers: Map<string, string[]>;
+
+        constructor(init?: HeadersInit) {
+            this.headers = new Map();
+
+            if (init) {
+                if (init instanceof Headers) {
+                    init.forEach((value, key) => this.append(key, value));
+                } else if (Array.isArray(init)) {
+                    for (const [key, value] of init) {
+                        if (typeof key === "string" && typeof value === "string") {
+                            this.append(key, value);
+                        } else {
+                            throw new TypeError("Each header entry must be a [string, string] tuple");
+                        }
+                    }
+                } else {
+                    for (const [key, value] of Object.entries(init)) {
+                        if (typeof value === "string") {
+                            this.append(key, value);
+                        } else {
+                            throw new TypeError("Header values must be strings");
+                        }
+                    }
+                }
+            }
+        }
+
+        append(name: string, value: string): void {
+            const key = name.toLowerCase();
+            const existing = this.headers.get(key) || [];
+            this.headers.set(key, [...existing, value]);
+        }
+
+        delete(name: string): void {
+            const key = name.toLowerCase();
+            this.headers.delete(key);
+        }
+
+        get(name: string): string | null {
+            const key = name.toLowerCase();
+            const values = this.headers.get(key);
+            return values ? values.join(", ") : null;
+        }
+
+        has(name: string): boolean {
+            const key = name.toLowerCase();
+            return this.headers.has(key);
+        }
+
+        set(name: string, value: string): void {
+            const key = name.toLowerCase();
+            this.headers.set(key, [value]);
+        }
+
+        forEach(callbackfn: (value: string, key: string, parent: Headers) => void, thisArg?: unknown): void {
+            const boundCallback = thisArg ? callbackfn.bind(thisArg) : callbackfn;
+            this.headers.forEach((values, key) => boundCallback(values.join(", "), key, this));
+        }
+
+        getSetCookie(): string[] {
+            return this.headers.get("set-cookie") || [];
+        }
+
+        *entries(): HeadersIterator<[string, string]> {
+            for (const [key, values] of this.headers.entries()) {
+                yield [key, values.join(", ")];
+            }
+        }
+
+        *keys(): HeadersIterator<string> {
+            yield* this.headers.keys();
+        }
+
+        *values(): HeadersIterator<string> {
+            for (const values of this.headers.values()) {
+                yield values.join(", ");
+            }
+        }
+
+        [Symbol.iterator](): HeadersIterator<[string, string]> {
+            return this.entries();
+        }
+    };
+}
+
+export { Headers };

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

@@ -0,0 +1,116 @@
+import { WithRawResponse } from "./RawResponse.js";
+
+/**
+ * A promise that returns the parsed response and lets you retrieve the raw response too.
+ */
+export class HttpResponsePromise<T> extends Promise<T> {
+    private innerPromise: Promise<WithRawResponse<T>>;
+    private unwrappedPromise: Promise<T> | undefined;
+
+    private constructor(promise: Promise<WithRawResponse<T>>) {
+        // Initialize with a no-op to avoid premature parsing
+        super((resolve) => {
+            resolve(undefined as unknown as T);
+        });
+        this.innerPromise = promise;
+    }
+
+    /**
+     * Creates an `HttpResponsePromise` from a function that returns a promise.
+     *
+     * @param fn - A function that returns a promise resolving to a `WithRawResponse` object.
+     * @param args - Arguments to pass to the function.
+     * @returns An `HttpResponsePromise` instance.
+     */
+    public static fromFunction<F extends (...args: never[]) => Promise<WithRawResponse<T>>, T>(
+        fn: F,
+        ...args: Parameters<F>
+    ): HttpResponsePromise<T> {
+        return new HttpResponsePromise<T>(fn(...args));
+    }
+
+    /**
+     * Creates a function that returns an `HttpResponsePromise` from a function that returns a promise.
+     *
+     * @param fn - A function that returns a promise resolving to a `WithRawResponse` object.
+     * @returns A function that returns an `HttpResponsePromise` instance.
+     */
+    public static interceptFunction<
+        F extends (...args: never[]) => Promise<WithRawResponse<T>>,
+        T = Awaited<ReturnType<F>>["data"],
+    >(fn: F): (...args: Parameters<F>) => HttpResponsePromise<T> {
+        return (...args: Parameters<F>): HttpResponsePromise<T> => {
+            return HttpResponsePromise.fromPromise<T>(fn(...args));
+        };
+    }
+
+    /**
+     * Creates an `HttpResponsePromise` from an existing promise.
+     *
+     * @param promise - A promise resolving to a `WithRawResponse` object.
+     * @returns An `HttpResponsePromise` instance.
+     */
+    public static fromPromise<T>(promise: Promise<WithRawResponse<T>>): HttpResponsePromise<T> {
+        return new HttpResponsePromise<T>(promise);
+    }
+
+    /**
+     * Creates an `HttpResponsePromise` from an executor function.
+     *
+     * @param executor - A function that takes resolve and reject callbacks to create a promise.
+     * @returns An `HttpResponsePromise` instance.
+     */
+    public static fromExecutor<T>(
+        executor: (resolve: (value: WithRawResponse<T>) => void, reject: (reason?: unknown) => void) => void,
+    ): HttpResponsePromise<T> {
+        const promise = new Promise<WithRawResponse<T>>(executor);
+        return new HttpResponsePromise<T>(promise);
+    }
+
+    /**
+     * Creates an `HttpResponsePromise` from a resolved result.
+     *
+     * @param result - A `WithRawResponse` object to resolve immediately.
+     * @returns An `HttpResponsePromise` instance.
+     */
+    public static fromResult<T>(result: WithRawResponse<T>): HttpResponsePromise<T> {
+        const promise = Promise.resolve(result);
+        return new HttpResponsePromise<T>(promise);
+    }
+
+    private unwrap(): Promise<T> {
+        if (!this.unwrappedPromise) {
+            this.unwrappedPromise = this.innerPromise.then(({ data }) => data);
+        }
+        return this.unwrappedPromise;
+    }
+
+    /** @inheritdoc */
+    public override then<TResult1 = T, TResult2 = never>(
+        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+    ): Promise<TResult1 | TResult2> {
+        return this.unwrap().then(onfulfilled, onrejected);
+    }
+
+    /** @inheritdoc */
+    public override catch<TResult = never>(
+        onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null,
+    ): Promise<T | TResult> {
+        return this.unwrap().catch(onrejected);
+    }
+
+    /** @inheritdoc */
+    public override finally(onfinally?: (() => void) | null): Promise<T> {
+        return this.unwrap().finally(onfinally);
+    }
+
+    /**
+     * Retrieves the data and raw response.
+     *
+     * @returns A promise resolving to a `WithRawResponse` object.
+     */
+    public async withRawResponse(): Promise<WithRawResponse<T>> {
+        return await this.innerPromise;
+    }
+}

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

@@ -0,0 +1,61 @@
+import { Headers } from "./Headers.js";
+
+/**
+ * The raw response from the fetch call excluding the body.
+ */
+export type RawResponse = Omit<
+    {
+        [K in keyof Response as Response[K] extends Function ? never : K]: Response[K]; // strips out functions
+    },
+    "ok" | "body" | "bodyUsed"
+>; // strips out body and bodyUsed
+
+/**
+ * A raw response indicating that the request was aborted.
+ */
+export const abortRawResponse: RawResponse = {
+    headers: new Headers(),
+    redirected: false,
+    status: 499,
+    statusText: "Client Closed Request",
+    type: "error",
+    url: "",
+} as const;
+
+/**
+ * A raw response indicating an unknown error.
+ */
+export const unknownRawResponse: RawResponse = {
+    headers: new Headers(),
+    redirected: false,
+    status: 0,
+    statusText: "Unknown Error",
+    type: "error",
+    url: "",
+} as const;
+
+/**
+ * Converts a `RawResponse` object into a `RawResponse` by extracting its properties,
+ * excluding the `body` and `bodyUsed` fields.
+ *
+ * @param response - The `RawResponse` object to convert.
+ * @returns A `RawResponse` object containing the extracted properties of the input response.
+ */
+export function toRawResponse(response: Response): RawResponse {
+    return {
+        headers: response.headers,
+        redirected: response.redirected,
+        status: response.status,
+        statusText: response.statusText,
+        type: response.type,
+        url: response.url,
+    };
+}
+
+/**
+ * Creates a `RawResponse` from a standard `Response` object.
+ */
+export interface WithRawResponse<T> {
+    readonly data: T;
+    readonly rawResponse: RawResponse;
+}

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

@@ -0,0 +1,7 @@
+export type ResponseWithBody = Response & {
+    body: ReadableStream<Uint8Array>;
+};
+
+export function isResponseWithBody(response: Response): response is ResponseWithBody {
+    return (response as ResponseWithBody).body != null;
+}

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

@@ -1,10 +1,6 @@
-import qs from "qs";
+import { toQueryString } from "../url/qs.js";
 
-export function createRequestUrl(
-    baseUrl: string,
-    queryParameters?: Record<string, string | string[] | object | object[]>
-): string {
-    return Object.keys(queryParameters ?? {}).length > 0
-        ? `${baseUrl}?${qs.stringify(queryParameters, { arrayFormat: "repeat" })}`
-        : baseUrl;
+export function createRequestUrl(baseUrl: string, queryParameters?: Record<string, unknown>): string {
+    const queryString = toQueryString(queryParameters, { arrayFormat: "repeat" });
+    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
 }