@planqk/planqk-service-sdk 2.7.0 → 2.9.0

package/src/sdk/api/resources/serviceApi/client/Client.ts

@@ -1,7 +1,6 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
+// This file was auto-generated by Fern from our API Definition.
 
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient.js";
 import * as environments from "../../../../environments.js";
 import * as core from "../../../../core/index.js";
 import * as PlanqkServiceApi from "../../../index.js";
@@ -9,25 +8,9 @@ import { mergeHeaders, mergeOnlyDefinedHeaders } from "../../../../core/headers.
 import * as errors from "../../../../errors/index.js";
 
 export declare namespace ServiceApi {
-    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 ServiceApi {
@@ -55,19 +38,21 @@ export class ServiceApi {
     private async __getServiceExecutions(
         requestOptions?: ServiceApi.RequestOptions,
     ): Promise<core.WithRawResponse<PlanqkServiceApi.ServiceExecution[]>> {
+        let _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+            this._options?.headers,
+            mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
+            requestOptions?.headers,
+        );
         const _response = await core.fetcher({
             url:
                 (await core.Supplier.get(this._options.baseUrl)) ??
                 (await core.Supplier.get(this._options.environment)) ??
                 environments.PlanqkServiceApiEnvironment.Default,
             method: "GET",
-            headers: mergeHeaders(
-                this._options?.headers,
-                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
-                requestOptions?.headers,
-            ),
-            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
-            maxRetries: requestOptions?.maxRetries,
+            headers: _headers,
+            queryParameters: requestOptions?.queryParams,
+            timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+            maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,
             abortSignal: requestOptions?.abortSignal,
         });
@@ -104,7 +89,7 @@ export class ServiceApi {
      * Starts a service execution, which in turn is processed asynchronously.
      * The location header of the response contains the URL which can be used to query the status and the result of the service execution.
      *
-     * @param {Record<string, any>} request
+     * @param {PlanqkServiceApi.RequestBody} request
      * @param {ServiceApi.RequestOptions} requestOptions - Request-specific configuration.
      *
      * @example
@@ -113,32 +98,34 @@ export class ServiceApi {
      *     })
      */
     public startExecution(
-        request: Record<string, any>,
+        request: PlanqkServiceApi.RequestBody,
         requestOptions?: ServiceApi.RequestOptions,
     ): core.HttpResponsePromise<PlanqkServiceApi.ServiceExecution> {
         return core.HttpResponsePromise.fromPromise(this.__startExecution(request, requestOptions));
     }
 
     private async __startExecution(
-        request: Record<string, any>,
+        request: PlanqkServiceApi.RequestBody,
         requestOptions?: ServiceApi.RequestOptions,
     ): Promise<core.WithRawResponse<PlanqkServiceApi.ServiceExecution>> {
+        let _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+            this._options?.headers,
+            mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
+            requestOptions?.headers,
+        );
         const _response = await core.fetcher({
             url:
                 (await core.Supplier.get(this._options.baseUrl)) ??
                 (await core.Supplier.get(this._options.environment)) ??
                 environments.PlanqkServiceApiEnvironment.Default,
             method: "POST",
-            headers: mergeHeaders(
-                this._options?.headers,
-                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
-                requestOptions?.headers,
-            ),
+            headers: _headers,
             contentType: "application/json",
+            queryParameters: requestOptions?.queryParams,
             requestType: "json",
             body: request,
-            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
-            maxRetries: requestOptions?.maxRetries,
+            timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+            maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,
             abortSignal: requestOptions?.abortSignal,
         });
@@ -192,6 +179,11 @@ export class ServiceApi {
         id: string,
         requestOptions?: ServiceApi.RequestOptions,
     ): Promise<core.WithRawResponse<PlanqkServiceApi.ServiceExecution>> {
+        let _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+            this._options?.headers,
+            mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
+            requestOptions?.headers,
+        );
         const _response = await core.fetcher({
             url: core.url.join(
                 (await core.Supplier.get(this._options.baseUrl)) ??
@@ -200,13 +192,10 @@ export class ServiceApi {
                 `${encodeURIComponent(id)}`,
             ),
             method: "GET",
-            headers: mergeHeaders(
-                this._options?.headers,
-                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
-                requestOptions?.headers,
-            ),
-            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
-            maxRetries: requestOptions?.maxRetries,
+            headers: _headers,
+            queryParameters: requestOptions?.queryParams,
+            timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+            maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,
             abortSignal: requestOptions?.abortSignal,
         });
@@ -253,14 +242,19 @@ export class ServiceApi {
     public getResult(
         id: string,
         requestOptions?: ServiceApi.RequestOptions,
-    ): core.HttpResponsePromise<PlanqkServiceApi.GetResultResponse> {
+    ): core.HttpResponsePromise<PlanqkServiceApi.ResultResponse> {
         return core.HttpResponsePromise.fromPromise(this.__getResult(id, requestOptions));
     }
 
     private async __getResult(
         id: string,
         requestOptions?: ServiceApi.RequestOptions,
-    ): Promise<core.WithRawResponse<PlanqkServiceApi.GetResultResponse>> {
+    ): Promise<core.WithRawResponse<PlanqkServiceApi.ResultResponse>> {
+        let _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+            this._options?.headers,
+            mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
+            requestOptions?.headers,
+        );
         const _response = await core.fetcher({
             url: core.url.join(
                 (await core.Supplier.get(this._options.baseUrl)) ??
@@ -269,18 +263,15 @@ export class ServiceApi {
                 `${encodeURIComponent(id)}/result`,
             ),
             method: "GET",
-            headers: mergeHeaders(
-                this._options?.headers,
-                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
-                requestOptions?.headers,
-            ),
-            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
-            maxRetries: requestOptions?.maxRetries,
+            headers: _headers,
+            queryParameters: requestOptions?.queryParams,
+            timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+            maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,
             abortSignal: requestOptions?.abortSignal,
         });
         if (_response.ok) {
-            return { data: _response.body as PlanqkServiceApi.GetResultResponse, rawResponse: _response.rawResponse };
+            return { data: _response.body as PlanqkServiceApi.ResultResponse, rawResponse: _response.rawResponse };
         }
 
         if (_response.error.reason === "status-code") {
@@ -326,6 +317,11 @@ export class ServiceApi {
         file: string,
         requestOptions?: ServiceApi.RequestOptions,
     ): Promise<core.WithRawResponse<core.BinaryResponse>> {
+        let _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+            this._options?.headers,
+            mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
+            requestOptions?.headers,
+        );
         const _response = await core.fetcher<core.BinaryResponse>({
             url: core.url.join(
                 (await core.Supplier.get(this._options.baseUrl)) ??
@@ -334,14 +330,11 @@ export class ServiceApi {
                 `${encodeURIComponent(id)}/result/${encodeURIComponent(file)}`,
             ),
             method: "GET",
-            headers: mergeHeaders(
-                this._options?.headers,
-                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
-                requestOptions?.headers,
-            ),
+            headers: _headers,
+            queryParameters: requestOptions?.queryParams,
             responseType: "binary-response",
-            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
-            maxRetries: requestOptions?.maxRetries,
+            timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+            maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,
             abortSignal: requestOptions?.abortSignal,
         });
@@ -394,6 +387,11 @@ export class ServiceApi {
         id: string,
         requestOptions?: ServiceApi.RequestOptions,
     ): Promise<core.WithRawResponse<PlanqkServiceApi.LogEntry[]>> {
+        let _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+            this._options?.headers,
+            mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
+            requestOptions?.headers,
+        );
         const _response = await core.fetcher({
             url: core.url.join(
                 (await core.Supplier.get(this._options.baseUrl)) ??
@@ -402,13 +400,10 @@ export class ServiceApi {
                 `${encodeURIComponent(id)}/log`,
             ),
             method: "GET",
-            headers: mergeHeaders(
-                this._options?.headers,
-                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
-                requestOptions?.headers,
-            ),
-            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
-            maxRetries: requestOptions?.maxRetries,
+            headers: _headers,
+            queryParameters: requestOptions?.queryParams,
+            timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+            maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,
             abortSignal: requestOptions?.abortSignal,
         });
@@ -461,6 +456,11 @@ export class ServiceApi {
         id: string,
         requestOptions?: ServiceApi.RequestOptions,
     ): Promise<core.WithRawResponse<PlanqkServiceApi.ServiceExecution>> {
+        let _headers: core.Fetcher.Args["headers"] = mergeHeaders(
+            this._options?.headers,
+            mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
+            requestOptions?.headers,
+        );
         const _response = await core.fetcher({
             url: core.url.join(
                 (await core.Supplier.get(this._options.baseUrl)) ??
@@ -469,13 +469,10 @@ export class ServiceApi {
                 `${encodeURIComponent(id)}/cancel`,
             ),
             method: "PUT",
-            headers: mergeHeaders(
-                this._options?.headers,
-                mergeOnlyDefinedHeaders({ Authorization: await this._getAuthorizationHeader() }),
-                requestOptions?.headers,
-            ),
-            timeoutMs: requestOptions?.timeoutInSeconds != null ? requestOptions.timeoutInSeconds * 1000 : 60000,
-            maxRetries: requestOptions?.maxRetries,
+            headers: _headers,
+            queryParameters: requestOptions?.queryParams,
+            timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+            maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
             withCredentials: true,
             abortSignal: requestOptions?.abortSignal,
         });

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

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

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

@@ -1,6 +1,4 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
+// This file was auto-generated by Fern from our API Definition.
 
 export interface HalLink {
     /** The URL of the link */

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

@@ -1,9 +1,22 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
+// This file was auto-generated by Fern from our API Definition.
 
 export interface LogEntry {
+    /** Log message content. */
     message?: string;
-    severity?: string;
+    /** Severity of the log entry. */
+    severity?: LogEntry.Severity;
+    /** Timestamp when the entry was logged. */
     timestamp?: string;
 }
+
+export namespace LogEntry {
+    /** Severity of the log entry. */
+    export const Severity = {
+        Debug: "DEBUG",
+        Notice: "NOTICE",
+        Info: "INFO",
+        Warning: "WARNING",
+        Error: "ERROR",
+    } as const;
+    export type Severity = (typeof Severity)[keyof typeof Severity];
+}

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

@@ -0,0 +1,3 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export type RequestBody = Record<string, any>;

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

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

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

@@ -1,17 +1,28 @@
-/**
- * This file was auto-generated by Fern from our API Definition.
- */
+// This file was auto-generated by Fern from our API Definition.
 
 export interface ServiceExecution {
+    /** Unique identifier of the service execution. */
     id?: string;
-    status?: ServiceExecution.Status;
+    /** Timestamp when the service execution was created. */
     createdAt?: string;
+    /** Timestamp when the service execution started. */
     startedAt?: string;
+    /** Timestamp when the service execution ended. */
     endedAt?: string;
+    /** Status of the service execution. */
+    status?: ServiceExecution.Status;
+    /** Type identifier indicating whether the underlying service is a 'managed' or 'workflow' service. */
+    type?: ServiceExecution.Type;
+    /** The ID of the service for which this service execution was created. */
+    serviceId?: string;
+    /** The ID of the service definition for which this service execution was created. */
+    serviceDefinitionId?: string;
+    /** The ID of the application for which this service execution was created. */
+    applicationId?: string;
 }
 
 export namespace ServiceExecution {
-    export type Status = "UNKNOWN" | "PENDING" | "RUNNING" | "SUCCEEDED" | "CANCELLED" | "FAILED";
+    /** Status of the service execution. */
     export const Status = {
         Unknown: "UNKNOWN",
         Pending: "PENDING",
@@ -20,4 +31,11 @@ export namespace ServiceExecution {
         Cancelled: "CANCELLED",
         Failed: "FAILED",
     } as const;
+    export type Status = (typeof Status)[keyof typeof Status];
+    /** Type identifier indicating whether the underlying service is a 'managed' or 'workflow' service. */
+    export const Type = {
+        Managed: "MANAGED",
+        Workflow: "WORKFLOW",
+    } as const;
+    export type Type = (typeof Type)[keyof typeof Type];
 }

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

@@ -1,3 +1,5 @@
+export * from "./RequestBody.js";
+export * from "./ResultResponse.js";
 export * from "./ServiceExecution.js";
 export * from "./LogEntry.js";
 export * from "./HalLink.js";

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

@@ -0,0 +1,5 @@
+import type { AuthRequest } from "./AuthRequest.js";
+
+export interface AuthProvider {
+    getAuthRequest(): Promise<AuthRequest>;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Request parameters for authentication requests.
+ */
+export interface AuthRequest {
+    /**
+     * The headers to be included in the request.
+     */
+    headers: Record<string, string>;
+}

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

@@ -18,7 +18,8 @@ export const BasicAuth = {
     fromAuthorizationHeader: (header: string): BasicAuth => {
         const credentials = header.replace(BASIC_AUTH_HEADER_PREFIX, "");
         const decoded = base64Decode(credentials);
-        const [username, password] = decoded.split(":", 2);
+        const [username, ...passwordParts] = decoded.split(":");
+        const password = passwordParts.length > 0 ? passwordParts.join(":") : undefined;
 
         if (username == null || password == null) {
             throw new Error("Invalid basic auth");

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

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

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

@@ -1,4 +1,4 @@
-import { RawResponse } from "./RawResponse.js";
+import type { RawResponse } from "./RawResponse.js";
 
 /**
  * The response of an API call.

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

@@ -1,4 +1,4 @@
-import { ResponseWithBody } from "./ResponseWithBody.js";
+import type { ResponseWithBody } from "./ResponseWithBody.js";
 
 export type BinaryResponse = {
     /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bodyUsed) */

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

@@ -0,0 +1,13 @@
+export type SecuritySchemeKey = string;
+/**
+ * A collection of security schemes, where the key is the name of the security scheme and the value is the list of scopes required for that scheme.
+ * All schemes in the collection must be satisfied for authentication to be successful.
+ */
+export type SecuritySchemeCollection = Record<SecuritySchemeKey, AuthScope[]>;
+export type AuthScope = string;
+export type EndpointMetadata = {
+    /**
+     * An array of security scheme collections. Each collection represents an alternative way to authenticate.
+     */
+    security?: SecuritySchemeCollection[];
+};

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

@@ -0,0 +1,14 @@
+import type { EndpointMetadata } from "./EndpointMetadata.js";
+import { Supplier } from "./Supplier.js";
+
+type EndpointSupplierFn<T> = (arg: { endpointMetadata: EndpointMetadata }) => T | Promise<T>;
+export type EndpointSupplier<T> = Supplier<T> | EndpointSupplierFn<T>;
+export const EndpointSupplier = {
+    get: async <T>(supplier: EndpointSupplier<T>, arg: { endpointMetadata: EndpointMetadata }): Promise<T> => {
+        if (typeof supplier === "function") {
+            return (supplier as EndpointSupplierFn<T>)(arg);
+        } else {
+            return supplier;
+        }
+    },
+};

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

@@ -1,13 +1,14 @@
 import { toJson } from "../json.js";
-import { APIResponse } from "./APIResponse.js";
-import { abortRawResponse, toRawResponse, unknownRawResponse } from "./RawResponse.js";
-import { Supplier } from "./Supplier.js";
+import type { APIResponse } from "./APIResponse.js";
 import { createRequestUrl } from "./createRequestUrl.js";
+import type { EndpointMetadata } from "./EndpointMetadata.js";
+import { EndpointSupplier } from "./EndpointSupplier.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 { abortRawResponse, toRawResponse, unknownRawResponse } from "./RawResponse.js";
 import { requestWithRetries } from "./requestWithRetries.js";
 
 export type FetchFunction = <R = unknown>(args: Fetcher.Args) => Promise<APIResponse<R, Fetcher.Error>>;
@@ -17,8 +18,8 @@ export declare namespace Fetcher {
         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;
@@ -27,6 +28,7 @@ export declare namespace Fetcher {
         requestType?: "json" | "file" | "bytes";
         responseType?: "json" | "blob" | "sse" | "streaming" | "text" | "arrayBuffer" | "binary-response";
         duplex?: "half";
+        endpointMetadata?: EndpointMetadata;
     }
 
     export type Error = FailedStatusCodeError | NonJsonError | TimeoutError | UnknownError;
@@ -64,7 +66,7 @@ async function getHeaders(args: Fetcher.Args): Promise<Record<string, string>> {
     }
 
     for (const [key, value] of Object.entries(args.headers)) {
-        const result = await Supplier.get(value);
+        const result = await EndpointSupplier.get(value, { endpointMetadata: args.endpointMetadata ?? {} });
         if (typeof result === "string") {
             newHeaders[key] = result;
             continue;

package/src/sdk/core/fetcher/HttpResponsePromise.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/src/sdk/core/fetcher/index.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/src/sdk/core/fetcher/requestWithRetries.ts

@@ -3,12 +3,55 @@ 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;
+function addPositiveJitter(delay: number): number {
+    // Generate a random value between 0 and +JITTER_FACTOR
+    const jitterMultiplier = 1 + Math.random() * JITTER_FACTOR;
     return delay * jitterMultiplier;
 }
 
+function addSymmetricJitter(delay: number): number {
+    // 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: Response, retryAttempt: number): number {
+    // 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));
+}
+
 export async function requestWithRetries(
     requestFn: () => Promise<Response>,
     maxRetries: number = DEFAULT_MAX_RETRIES,
@@ -17,13 +60,10 @@ export async function requestWithRetries(
 
     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);
+            // Get delay with appropriate jitter applied
+            const delay = getRetryDelayFromHeaders(response, i);
 
-            await new Promise((resolve) => setTimeout(resolve, delayWithJitter));
+            await new Promise((resolve) => setTimeout(resolve, delay));
             response = await requestFn();
         } else {
             break;