@superclerk/sdk 0.0.0-stage → 0.1.1

package/core/api-promise.js

@@ -0,0 +1,52 @@
+import { APIConnectionError } from "./errors.js";
+/**
+ * What every method returns: a promise of the parsed answer that also hands over the raw response. The request starts
+ * when the method is called, like fetch; the body is parsed once, when the promise is first awaited.
+ */
+export class APIPromise extends Promise {
+    response;
+    parse;
+    #parsed;
+    constructor(response, parse) {
+        // The executor's value is never read: then, catch and finally all go through the parsed answer.
+        super((resolve) => resolve(undefined));
+        this.response = response;
+        this.parse = parse;
+    }
+    /** The raw response, its body unread. Await the promise or call withResponse instead to read the body. */
+    asResponse() {
+        return this.response;
+    }
+    /** The parsed answer with the response it came in and the request's ID. */
+    async withResponse() {
+        const [response, data] = await Promise.all([this.response, this.parsed()]);
+        return { data, response, requestID: response.headers.get("x-superclerk-request-id") };
+    }
+    parsed() {
+        this.#parsed ??= this.response.then(this.parse);
+        return this.#parsed;
+    }
+    then(onfulfilled, onrejected) {
+        return this.parsed().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.parsed().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.parsed().finally(onfinally);
+    }
+}
+/**
+ * Reads the body of an answer the SDK parses. Your abort rejects with its reason; any other failure means the answer
+ * never arrived whole.
+ */
+export async function readBody(read, signal) {
+    try {
+        return await read;
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw signal.reason;
+        throw new APIConnectionError("connection_failed", "The answer couldn't be read whole", { cause: error });
+    }
+}

package/core/client.d.ts

@@ -0,0 +1,72 @@
+import { APIPromise } from "./api-promise.js";
+import { PagePromise, type PageBody } from "./pagination.js";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** One API operation, as a generated method describes it. */
+export interface Operation {
+    method: HttpMethod;
+    /** The path with its parameters already in place, such as `/v1/contacts/cct_123`. */
+    path: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    /** The operation takes an Idempotency-Key: the SDK sends one, and every retry of the call repeats it. */
+    idempotent?: boolean;
+    /** A 2xx answer's body: JSON, or a response handed back as it came, such as a provider's through the proxy. */
+    response: "json" | "raw";
+}
+export interface ClientOptions {
+    /** Defaults to the `SUPERCLERK_API_KEY` environment variable. */
+    apiKey?: string;
+    /** Defaults to the `SUPERCLERK_BASE_URL` environment variable, then `https://api.superclerk.com`. */
+    baseURL?: string;
+    /** A client workspace of the key's agency to act in, as `workspaces.list` returns it. */
+    workspace?: string;
+    /** How long one attempt may wait for its answer to start, in milliseconds. Defaults to 60 seconds. */
+    timeout?: number;
+    /** How many times a failed attempt is retried when retrying is safe. Defaults to 2. */
+    maxRetries?: number;
+    /** The secret `webhooks.unwrap` verifies with. Defaults to the `SUPERCLERK_WEBHOOK_SECRET` environment variable. */
+    webhookSecret?: string;
+    /** The fetch every request goes through. Defaults to the runtime's own. */
+    fetch?: (input: Request) => Promise<Response>;
+    /** Headers sent with every request. */
+    defaultHeaders?: Record<string, string>;
+}
+export interface RequestOptions {
+    /** A UUIDv4 to send as Idempotency-Key, for retrying a call across processes. The SDK makes one when it's left out. */
+    idempotencyKey?: string;
+    /** The client workspace this request acts in, instead of the client's. */
+    workspace?: string;
+    timeout?: number;
+    maxRetries?: number;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+export declare class Core {
+    #private;
+    readonly baseURL: string;
+    readonly workspace: string | undefined;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly webhookSecret: string | undefined;
+    /** What this client resolved, its environment included, so a copy keeps its key and address. */
+    protected readonly clientOptions: ClientOptions;
+    constructor(options?: ClientOptions);
+    /** Sends an operation and answers its parsed body. */
+    request<T>(operation: Operation, options?: RequestOptions): APIPromise<T>;
+    /** Sends a list operation; await it for the first page, or iterate it for every item across pages. */
+    list<Body extends PageBody>(operation: Operation, options?: RequestOptions): PagePromise<Body>;
+    /**
+     * Sends an operation, retrying what is safe to retry, and answers its response. A non-2xx answer throws APIError,
+     * except a raw operation's answer from the provider itself, which is handed back whatever its status.
+     */
+    send(operation: Operation, options?: RequestOptions): Promise<Response>;
+    private log;
+    private headers;
+}
+/** The base of every resource: it calls the API through the client it belongs to. */
+export declare class APIResource {
+    protected readonly _client: Core;
+    constructor(_client: Core);
+}
+/** A path parameter, encoded to stay one segment. */
+export declare function pathParam(value: string): string;

package/core/client.js

@@ -0,0 +1,226 @@
+import { API_VERSION, DEFAULT_BASE_URL, SDK_VERSION } from "../generated/version.js";
+import { APIPromise, readBody } from "./api-promise.js";
+import { APIConnectionError, APIError, SuperclerkError } from "./errors.js";
+import { PagePromise } from "./pagination.js";
+import { answeredByProvider, retryAfterMs, sleep } from "./timing.js";
+// An attempt the API refused before doing any work is safe to repeat; a timeout or 5xx is safe only for a call that
+// repeats harmlessly: a read, a PUT or DELETE, or a write the server deduplicates by its Idempotency-Key.
+const REFUSED = new Set([429, 503]);
+const UNFINISHED = new Set([408, 500, 502, 504]);
+export class Core {
+    baseURL;
+    workspace;
+    timeout;
+    maxRetries;
+    webhookSecret;
+    /** What this client resolved, its environment included, so a copy keeps its key and address. */
+    clientOptions;
+    #apiKey;
+    #fetch;
+    #defaultHeaders;
+    #userAgent = userAgent();
+    // SUPERCLERK_LOG=debug writes each attempt and retry to stderr, for you or the agent debugging an integration.
+    #debug = readEnv("SUPERCLERK_LOG") === "debug";
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? readEnv("SUPERCLERK_API_KEY");
+        if (!apiKey)
+            throw new SuperclerkError("missing_api_key", "Pass apiKey, or set the SUPERCLERK_API_KEY environment variable. To create a key: https://docs.superclerk.com/authentication");
+        this.#apiKey = apiKey;
+        this.baseURL = (options.baseURL ?? readEnv("SUPERCLERK_BASE_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.workspace = options.workspace;
+        this.timeout = options.timeout ?? 60_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.webhookSecret = options.webhookSecret ?? readEnv("SUPERCLERK_WEBHOOK_SECRET");
+        this.#fetch = options.fetch ?? ((request) => fetch(request));
+        this.#defaultHeaders = options.defaultHeaders ?? {};
+        this.clientOptions = { ...options, apiKey, baseURL: this.baseURL, webhookSecret: this.webhookSecret };
+    }
+    /** Sends an operation and answers its parsed body. */
+    request(operation, options = {}) {
+        return new APIPromise(this.send(operation, options), async (response) => operation.response === "raw" ? response : readBody(response.json(), options.signal));
+    }
+    /** Sends a list operation; await it for the first page, or iterate it for every item across pages. */
+    list(operation, options = {}) {
+        return new PagePromise(this, operation, options);
+    }
+    /**
+     * Sends an operation, retrying what is safe to retry, and answers its response. A non-2xx answer throws APIError,
+     * except a raw operation's answer from the provider itself, which is handed back whatever its status.
+     */
+    async send(operation, options = {}) {
+        const headers = this.headers(operation, options);
+        const body = encodeBody(operation.body, headers);
+        // Serialized once, so every attempt sends the same bytes under the same key, a multipart boundary included.
+        const prepared = new Request(`${this.baseURL}${operation.path}${query(operation.query)}`, {
+            method: operation.method,
+            headers,
+            body,
+        });
+        const init = {
+            method: prepared.method,
+            headers: prepared.headers,
+            body: prepared.body === null ? undefined : await prepared.arrayBuffer(),
+        };
+        const maxRetries = options.maxRetries ?? this.maxRetries;
+        for (let retries = 0;; retries++) {
+            let response;
+            try {
+                response = await this.attempt(prepared.url, init, options);
+            }
+            catch (error) {
+                if (!(error instanceof APIConnectionError) || retries >= maxRetries || !repeatable(operation))
+                    throw error;
+                const wait = backoffMs(retries);
+                this.log(`retrying in ${Math.round(wait)} ms after ${error.code}`);
+                await sleep(wait, options.signal);
+                continue;
+            }
+            if (response.ok || (operation.response === "raw" && answeredByProvider(response)))
+                return response;
+            if (retries >= maxRetries || !retryable(operation, response)) {
+                throw APIError.from(response, await readBody(response.text(), options.signal));
+            }
+            await response.body?.cancel();
+            const wait = retryAfterMs(response) ?? backoffMs(retries);
+            this.log(`retrying in ${Math.round(wait)} ms after ${response.status}`);
+            await sleep(wait, options.signal);
+        }
+    }
+    /**
+     * @internal One attempt at a request through the client's fetch, with your signal, and the timeout running until
+     * the answer's headers arrive. No answer throws APIConnectionError; your abort rejects with its reason.
+     */
+    async attempt(url, init, options) {
+        const timeout = options.timeout ?? this.timeout;
+        const timer = new AbortController();
+        const stop = setTimeout(() => timer.abort(), timeout);
+        const signal = options.signal ? AbortSignal.any([options.signal, timer.signal]) : timer.signal;
+        // Host and path only: a signed upload URL's query is a credential.
+        const { host, pathname } = new URL(url);
+        const startedAt = Date.now();
+        try {
+            const response = await this.#fetch(new Request(url, { ...init, signal }));
+            // An upload URL's storage answers too, without a Superclerk request ID.
+            const requestID = response.headers.get("x-superclerk-request-id");
+            this.log(`${init.method} ${host}${pathname} → ${response.status} in ${Date.now() - startedAt} ms${requestID ? ` (${requestID})` : ""}`);
+            return response;
+        }
+        catch (error) {
+            this.log(`${init.method} ${host}${pathname} → no answer after ${Date.now() - startedAt} ms`);
+            if (options.signal?.aborted)
+                throw options.signal.reason;
+            if (timer.signal.aborted) {
+                throw new APIConnectionError("timeout", `No answer started within ${timeout} ms`, { cause: error });
+            }
+            throw new APIConnectionError("connection_failed", `${host} could not be reached`, { cause: error });
+        }
+        finally {
+            clearTimeout(stop);
+        }
+    }
+    log(message) {
+        if (this.#debug)
+            console.error(`[superclerk] ${message}`);
+    }
+    headers(operation, options) {
+        const headers = new Headers(this.#defaultHeaders);
+        headers.set("Authorization", `Bearer ${this.#apiKey}`);
+        headers.set("Accept", "application/json");
+        headers.set("Superclerk-Version", API_VERSION);
+        headers.set("User-Agent", this.#userAgent);
+        const workspace = options.workspace ?? this.workspace;
+        if (workspace !== undefined)
+            headers.set("Superclerk-Workspace", workspace);
+        if (operation.idempotent)
+            headers.set("Idempotency-Key", options.idempotencyKey ?? crypto.randomUUID());
+        for (const [name, value] of Object.entries(options.headers ?? {}))
+            headers.set(name, value);
+        return headers;
+    }
+}
+/** The base of every resource: it calls the API through the client it belongs to. */
+export class APIResource {
+    _client;
+    constructor(_client) {
+        this._client = _client;
+    }
+}
+/** A path parameter, encoded to stay one segment. */
+export function pathParam(value) {
+    return encodeURIComponent(value);
+}
+// An answer that names its run is the run's recorded ending, or the provider's answer: repeating the request would
+// replay it, not redo it.
+function retryable(operation, response) {
+    if (response.headers.has("x-superclerk-run-id"))
+        return false;
+    if (REFUSED.has(response.status))
+        return true;
+    return UNFINISHED.has(response.status) && repeatable(operation);
+}
+function repeatable(operation) {
+    return (operation.idempotent || operation.method === "GET" || operation.method === "PUT" || operation.method === "DELETE");
+}
+function backoffMs(retries) {
+    // 0.5 s doubling to 8 s, less up to a quarter at random, so clients that failed together retry apart.
+    return Math.min(500 * 2 ** retries, 8_000) * (1 - Math.random() * 0.25);
+}
+// A body fetch already sends goes as it is, such as a proxied form or file; anything else is JSON.
+function encodeBody(body, headers) {
+    if (body === undefined ||
+        typeof body === "string" ||
+        body instanceof Blob ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        body instanceof FormData ||
+        body instanceof URLSearchParams) {
+        return body;
+    }
+    headers.set("Content-Type", "application/json");
+    return JSON.stringify(body);
+}
+// Arrays repeat their key, and an object's entries become keys of their own (OpenAPI's exploded form style).
+function query(values = {}) {
+    const params = new URLSearchParams();
+    const add = (key, value) => {
+        if (Array.isArray(value))
+            return value.forEach((item) => add(key, item));
+        if (value !== null && typeof value === "object")
+            return Object.entries(value).forEach((entry) => add(...entry));
+        if (value !== undefined && value !== null)
+            params.append(key, String(value));
+    };
+    Object.entries(values).forEach((entry) => add(...entry));
+    return params.size > 0 ? `?${params}` : "";
+}
+// Node and Bun have a process; Workers and browsers don't, and the SDK names none of their types.
+const runtimeProcess = globalThis.process;
+function readEnv(name) {
+    const value = runtimeProcess?.env?.[name];
+    return value === "" ? undefined : value;
+}
+// The variable each coding agent sets in the processes it runs, as Stripe's SDK reads them.
+const CODING_AGENTS = [
+    ["CLAUDECODE", "claude_code"],
+    ["CURSOR_AGENT", "cursor"],
+    ["CODEX_SANDBOX", "codex"],
+    ["CODEX_THREAD_ID", "codex"],
+    ["GEMINI_CLI", "gemini_cli"],
+    ["CLINE_ACTIVE", "cline"],
+    ["OPENCODE", "opencode"],
+];
+/** `superclerk-js/0.1.0 node/22.12.0 darwin-arm64`, ending `agent/claude_code` when a coding agent runs the process. */
+function userAgent() {
+    const versions = runtimeProcess?.versions ?? {};
+    // Bun and Deno report a Node version too, so they're asked first.
+    const runtime = versions.bun
+        ? `bun/${versions.bun}`
+        : versions.deno
+            ? `deno/${versions.deno}`
+            : versions.node
+                ? `node/${versions.node}`
+                : "runtime/unknown";
+    const platform = runtimeProcess?.platform && `${runtimeProcess.platform}-${runtimeProcess.arch}`;
+    const agent = CODING_AGENTS.find(([variable]) => readEnv(variable))?.[1];
+    return [`superclerk-js/${SDK_VERSION}`, runtime, platform, agent && `agent/${agent}`].filter(Boolean).join(" ");
+}

package/core/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Everything the SDK throws. Branch on `code`, which names the failure the same way the API does (`not_found`,
+ * `revision_conflict`, `rate_limited`, …); `instanceof` against a subclass tells only where it came from.
+ */
+export declare class SuperclerkError extends Error {
+    readonly code: string;
+    readonly name: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** One field the request got wrong, by its path in the request. */
+export interface FieldError {
+    path: string[];
+    message: string;
+}
+/** The API answered with a status that isn't 2xx. */
+export declare class APIError extends SuperclerkError {
+    /** The answer's body: the error object, or its text when it wasn't JSON. */
+    readonly body: unknown;
+    readonly name: string;
+    readonly status: number;
+    readonly headers: Headers;
+    /** The request's ID, for support: the `x-superclerk-request-id` header. */
+    readonly requestID: string | null;
+    readonly fields: FieldError[] | undefined;
+    private constructor();
+    /** The error an answer makes of its status and body: the API's error object, or the text when it isn't JSON. */
+    static from(response: Response, text: string): APIError;
+}
+/** No whole answer came: the network failed, or no answer started within the attempt's timeout. */
+export declare class APIConnectionError extends SuperclerkError {
+    readonly name: string;
+    constructor(code: "connection_failed" | "timeout", message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A webhook's signature didn't verify, so its body must not be trusted. */
+export declare class WebhookVerificationError extends SuperclerkError {
+    readonly name: string;
+    constructor(message: string);
+}
+/** A tool run that `tools.run` started ended failed or cancelled. `code` is the run's `error.kind`. */
+export declare class ToolRunError extends SuperclerkError {
+    readonly run: {
+        id: string;
+        status: string;
+        error: {
+            kind: string;
+            message?: string;
+        };
+    };
+    readonly name: string;
+    constructor(run: {
+        id: string;
+        status: string;
+        error: {
+            kind: string;
+            message?: string;
+        };
+    });
+}

package/core/errors.js

@@ -0,0 +1,72 @@
+/**
+ * Everything the SDK throws. Branch on `code`, which names the failure the same way the API does (`not_found`,
+ * `revision_conflict`, `rate_limited`, …); `instanceof` against a subclass tells only where it came from.
+ */
+export class SuperclerkError extends Error {
+    code;
+    name = "SuperclerkError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/** The API answered with a status that isn't 2xx. */
+export class APIError extends SuperclerkError {
+    body;
+    name = "APIError";
+    status;
+    headers;
+    /** The request's ID, for support: the `x-superclerk-request-id` header. */
+    requestID;
+    fields;
+    constructor(response, 
+    /** The answer's body: the error object, or its text when it wasn't JSON. */
+    body) {
+        const error = body?.error;
+        // An answer that isn't the API's, such as a proxy's HTML page, still says what happened by its status.
+        const message = error?.message ?? `${response.status} ${response.statusText}`.trim();
+        // The wrong fields go in the message too: an uncaught error prints its message, but a field's path only as [Array].
+        const wrong = error?.fields?.map((field) => (field.path.length ? `${field.path.join(".")}: ` : "") + field.message);
+        super(error?.code ?? error?.kind ?? `http_${response.status}`, wrong?.length ? `${message} (${wrong.join("; ")})` : message);
+        this.body = body;
+        this.status = response.status;
+        this.headers = response.headers;
+        this.requestID = response.headers.get("x-superclerk-request-id");
+        this.fields = error?.fields;
+    }
+    /** The error an answer makes of its status and body: the API's error object, or the text when it isn't JSON. */
+    static from(response, text) {
+        return new APIError(response, parseJSON(text) ?? text);
+    }
+}
+/** No whole answer came: the network failed, or no answer started within the attempt's timeout. */
+export class APIConnectionError extends SuperclerkError {
+    name = "APIConnectionError";
+    constructor(code, message, options) {
+        super(code, message, options);
+    }
+}
+/** A webhook's signature didn't verify, so its body must not be trusted. */
+export class WebhookVerificationError extends SuperclerkError {
+    name = "WebhookVerificationError";
+    constructor(message) {
+        super("invalid_webhook_signature", message);
+    }
+}
+/** A tool run that `tools.run` started ended failed or cancelled. `code` is the run's `error.kind`. */
+export class ToolRunError extends SuperclerkError {
+    run;
+    name = "ToolRunError";
+    constructor(run) {
+        super(run.error.kind, run.error.message ?? `Tool run ${run.id} ended ${run.status}`);
+        this.run = run;
+    }
+}
+function parseJSON(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/core/pagination.d.ts

@@ -0,0 +1,29 @@
+import { APIPromise } from "./api-promise.js";
+import type { Core, Operation, RequestOptions } from "./client.js";
+/** A list's answer: its items, where the next page starts, and any fields beside them. */
+export type PageBody = {
+    items: unknown[];
+    nextCursor: string | null;
+};
+/** One page of a list. Iterate it for its items and every later page's. */
+export declare class Page<Body extends PageBody> implements AsyncIterable<Body["items"][number]> {
+    private readonly client;
+    private readonly operation;
+    private readonly options;
+    /** The page's whole answer, with any fields beside its items, such as an opportunity list's `stageCounts`. */
+    readonly body: Body;
+    constructor(client: Core, operation: Operation, options: RequestOptions, 
+    /** The page's whole answer, with any fields beside its items, such as an opportunity list's `stageCounts`. */
+    body: Body);
+    get items(): Body["items"][number][];
+    /** Where the next page starts; null on the last page. */
+    get nextCursor(): string | null;
+    hasNextPage(): boolean;
+    getNextPage(): PagePromise<Body>;
+    [Symbol.asyncIterator](): AsyncGenerator<Body["items"][number]>;
+}
+/** A list call: await it for the first page, or iterate it for every item across pages. */
+export declare class PagePromise<Body extends PageBody> extends APIPromise<Page<Body>> implements AsyncIterable<Body["items"][number]> {
+    constructor(client: Core, operation: Operation, options: RequestOptions);
+    [Symbol.asyncIterator](): AsyncGenerator<Body["items"][number]>;
+}

package/core/pagination.js

@@ -0,0 +1,50 @@
+import { APIPromise, readBody } from "./api-promise.js";
+import { SuperclerkError } from "./errors.js";
+/** One page of a list. Iterate it for its items and every later page's. */
+export class Page {
+    client;
+    operation;
+    options;
+    body;
+    constructor(client, operation, options, 
+    /** The page's whole answer, with any fields beside its items, such as an opportunity list's `stageCounts`. */
+    body) {
+        this.client = client;
+        this.operation = operation;
+        this.options = options;
+        this.body = body;
+    }
+    get items() {
+        return this.body.items;
+    }
+    /** Where the next page starts; null on the last page. */
+    get nextCursor() {
+        return this.body.nextCursor;
+    }
+    hasNextPage() {
+        return this.body.nextCursor !== null;
+    }
+    getNextPage() {
+        if (this.body.nextCursor === null)
+            throw new SuperclerkError("no_next_page", "This is the last page");
+        return this.client.list({ ...this.operation, query: { ...this.operation.query, cursor: this.body.nextCursor } }, this.options);
+    }
+    async *[Symbol.asyncIterator]() {
+        let page = this;
+        for (;;) {
+            yield* page.items;
+            if (!page.hasNextPage())
+                return;
+            page = await page.getNextPage();
+        }
+    }
+}
+/** A list call: await it for the first page, or iterate it for every item across pages. */
+export class PagePromise extends APIPromise {
+    constructor(client, operation, options) {
+        super(client.send(operation, options), async (response) => new Page(client, operation, options, await readBody(response.json(), options.signal)));
+    }
+    async *[Symbol.asyncIterator]() {
+        yield* await this;
+    }
+}

package/core/timing.d.ts

@@ -0,0 +1,20 @@
+import type { APIPromise } from "./api-promise.js";
+import type { Core, RequestOptions } from "./client.js";
+/** Waits, unless the signal aborts first. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/** How long a response asks to be waited for: `Retry-After` in seconds or as a date, at most a minute. */
+export declare function retryAfterMs(response: Response): number | undefined;
+/** Whether a proxy answer is the provider's own response, fresh or stored, rather than one of Superclerk's. */
+export declare function answeredByProvider(response: Response): boolean;
+/** Whether an answer says the work goes on: Superclerk's 202, not a provider's own through the proxy. */
+export declare function isPending(response: Response): boolean;
+/**
+ * Asks the API to hold a read until the work settles, for as long as one attempt may last, less five seconds for the
+ * answer to come back. The API holds at most 30 seconds whatever it's asked, and your own `Prefer` header wins.
+ */
+export declare function holding(client: Core, options: RequestOptions): RequestOptions;
+/**
+ * Reads something that settles later, such as a tool run or a connect link, until it does. The API holds each read,
+ * and an answer that says the work goes on is let go unread. Aborting the signal stops the waiting, not the work.
+ */
+export declare function settle<T>(client: Core, read: (options: RequestOptions) => APIPromise<T>, options: RequestOptions): Promise<T>;

package/core/timing.js

@@ -0,0 +1,54 @@
+/** Waits, unless the signal aborts first. */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        signal?.throwIfAborted();
+        const stop = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", stop, { once: true });
+    });
+}
+/** How long a response asks to be waited for: `Retry-After` in seconds or as a date, at most a minute. */
+export function retryAfterMs(response) {
+    const header = response.headers.get("retry-after") ?? "";
+    const ms = /^\d+$/.test(header) ? Number(header) * 1_000 : Date.parse(header) - Date.now();
+    // NaN, a missing or unreadable header, is never at least 0.
+    return ms >= 0 ? Math.min(ms, 60_000) : undefined;
+}
+/** Whether a proxy answer is the provider's own response, fresh or stored, rather than one of Superclerk's. */
+export function answeredByProvider(response) {
+    const source = response.headers.get("x-superclerk-response-source");
+    return source === "upstream" || source === "replay";
+}
+/** Whether an answer says the work goes on: Superclerk's 202, not a provider's own through the proxy. */
+export function isPending(response) {
+    return response.status === 202 && !answeredByProvider(response);
+}
+/**
+ * Asks the API to hold a read until the work settles, for as long as one attempt may last, less five seconds for the
+ * answer to come back. The API holds at most 30 seconds whatever it's asked, and your own `Prefer` header wins.
+ */
+export function holding(client, options) {
+    const seconds = Math.max(Math.floor((options.timeout ?? client.timeout) / 1_000) - 5, 0);
+    return { ...options, headers: { Prefer: `wait=${seconds}`, ...options.headers } };
+}
+/**
+ * Reads something that settles later, such as a tool run or a connect link, until it does. The API holds each read,
+ * and an answer that says the work goes on is let go unread. Aborting the signal stops the waiting, not the work.
+ */
+export async function settle(client, read, options) {
+    const held = holding(client, options);
+    for (;;) {
+        const answer = read(held);
+        const response = await answer.asResponse();
+        if (!isPending(response))
+            return answer;
+        await response.body?.cancel();
+        await sleep(retryAfterMs(response) ?? 1_000, options.signal);
+    }
+}