@goassay-ai/sdk 0.0.0-bootstrap.0 → 0.1.0

package/dist/resources/paid-calls.d.ts

@@ -0,0 +1,82 @@
+import type { ClientContext } from "./context.js";
+export type PaidCallsState = "unbound" | "pending_approval" | "active" | "expired" | "bound_to_other_key" | "unknown";
+export interface PaidCallsStatus {
+    /**
+     * - `unbound`: no payment key is bound to this API key;
+     * - `pending_approval`: this key is bound (or waits) and a person has not approved it yet;
+     * - `active`: paid calls are on for this key;
+     * - `expired`: the approval lapsed; approve it again;
+     * - `bound_to_other_key`: another key is bound; `bind()` this one;
+     * - `unknown`: Assay could not read the key's grant from the chain just now; ask again.
+     */
+    state: PaidCallsState;
+    credentialId: string;
+    /** The bound key's `0x` address, or null. While a new key waits for approval, still the old key. */
+    delegate: string | null;
+    /** When `delegate` was bound (ISO 8601), or null. */
+    boundAt: string | null;
+    /** A key waiting for approval to replace `delegate`, or null. */
+    pendingDelegate: string | null;
+    /** When `pendingDelegate` was proved (ISO 8601), or null. */
+    pendingSince: string | null;
+    /** The on-chain caps of the bound key, in atomic units, when the server read them. */
+    caps: {
+        maxVoucherAmount: string | null;
+        maxPerWindow: string | null;
+        spentInWindow: string | null;
+        validUntil: string | null;
+    } | null;
+    /**
+     * Where a person approves this client's key: `{webUrl}/agents/enable-paid?credential=...#key=...`.
+     * The key travels only in the fragment. Null without a signer.
+     */
+    approvalUrl: string | null;
+    /** This client's key as the approval page shows it (`1A2B 9F3C`); null without a signer. */
+    fingerprint: string | null;
+}
+export interface BindResult extends PaidCallsStatus {
+    /** The key was already bound (or already waiting for approval): nothing was signed. */
+    alreadyBound: boolean;
+    /**
+     * - `ACTIVE`: this key is the bound key (`delegate`); a person still approves its caps on chain;
+     * - `PENDING_APPROVAL`: another key stays bound and keeps signing; this key is `pendingDelegate`
+     *   and replaces it once a person approves it at `approvalUrl`.
+     */
+    bindStatus: "ACTIVE" | "PENDING_APPROVAL";
+}
+export interface WaitOptions {
+    /** Default 15 minutes. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * The approval link, with this key only in the fragment (browsers never send it to a server). A
+ * link the server sent is used only when it is on the configured web origin and names this
+ * credential; otherwise the link is built from the web origin.
+ */
+export declare function approvalLink(webOrigin: string, server: unknown, credentialId: string, address: string | null): string | null;
+/** Binding a payment key for server-side integrators (spec section 5). */
+export declare class PaidCalls {
+    #private;
+    constructor(context: ClientContext);
+    /** Where paid calls stand for this API key and this client's signer. */
+    status(): Promise<PaidCallsStatus>;
+    /**
+     * Binds this client's EVM signer to the API key: challenge, field check, sign, bind. A no-op
+     * when the key is already bound or already waiting. When another key is bound, this key waits as
+     * `pendingDelegate` (`bindStatus: "PENDING_APPROVAL"`) and the old key keeps signing until a
+     * person approves the new one at `approvalUrl`, comparing the fingerprint. Needs the `payments`
+     * scope. A key bound to another API key is refused with `DelegateAlreadyBoundError` (409).
+     * When another key wins a first bind at the same moment, this is `DelegateBindConflictError`
+     * (409, retryable): nothing was bound, and calling `bind()` once more parks this key as pending.
+     */
+    bind(options?: {
+        network?: string;
+    }): Promise<BindResult>;
+    /**
+     * Polls until a person approved this client's key: `delegate` is this key and its paid calls are
+     * on. A key waiting to replace another one becomes `delegate` only when the approval lands.
+     * Every 5 s for 2 minutes, then every 15 s.
+     */
+    waitUntilActive(options?: WaitOptions): Promise<PaidCallsStatus>;
+}

package/dist/resources/paid-calls.js

@@ -0,0 +1,156 @@
+import { eip155ChainId, parseCaip10 } from "../core/caip.js";
+import { getAddress } from "../core/hex.js";
+import { fingerprint, isObject } from "../core/meta.js";
+import { AssayError, ConfigError, PaymentNetworkUnknownError, ServerError } from "../errors.js";
+import { bindEvmKey } from "../schemes/eip155/bind.js";
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function addressOf(caip10) {
+    const p = typeof caip10 === "string" ? parseCaip10(caip10) : null;
+    return p ? p.address : null;
+}
+/**
+ * The approval link, with this key only in the fragment (browsers never send it to a server). A
+ * link the server sent is used only when it is on the configured web origin and names this
+ * credential; otherwise the link is built from the web origin.
+ */
+export function approvalLink(webOrigin, server, credentialId, address) {
+    if (address === null)
+        return null;
+    let url = null;
+    if (typeof server === "string") {
+        try {
+            const u = new URL(server);
+            if (u.origin === webOrigin && !u.username && !u.password && u.searchParams.get("credential") === credentialId)
+                url = u;
+        }
+        catch {
+            url = null;
+        }
+    }
+    url ??= new URL(`${webOrigin}/agents/enable-paid?credential=${encodeURIComponent(credentialId)}`);
+    url.hash = `key=${address}`;
+    return url.toString();
+}
+/** Binding a payment key for server-side integrators (spec section 5). */
+export class PaidCalls {
+    #c;
+    constructor(context) {
+        this.#c = context;
+    }
+    #signer() {
+        return this.#c.signers.find((s) => s.namespace === "eip155") ?? null;
+    }
+    /** Where paid calls stand for this API key and this client's signer. */
+    async status() {
+        const { data } = await this.#c.api.get("/agents/me/delegate");
+        if (!isObject(data) || typeof data.credentialId !== "string" || !UUID.test(data.credentialId)) {
+            throw new ServerError("API_BAD_ANSWER", "the paid-call status is not readable");
+        }
+        const signer = this.#signer();
+        const mine = signer ? getAddress(signer.address) : null;
+        const delegate = addressOf(data.delegate);
+        const pending = addressOf(data.pendingDelegate);
+        const paid = isObject(data.paidCalls) ? data.paidCalls : null;
+        let state;
+        if (data.paidCallsUnknown === true && delegate !== null && (mine === null || delegate === mine))
+            state = "unknown";
+        else if (mine !== null && pending === mine)
+            state = "pending_approval";
+        else if (delegate === null)
+            state = "unbound";
+        else if (mine !== null && delegate !== mine)
+            state = "bound_to_other_key";
+        else if (paid?.status === "ACTIVE")
+            state = "active";
+        else if (paid?.status === "EXPIRED")
+            state = "expired";
+        else
+            state = "pending_approval";
+        const str = (v) => (typeof v === "string" ? v : null);
+        return {
+            state,
+            credentialId: data.credentialId,
+            delegate,
+            boundAt: str(data.boundAt),
+            pendingDelegate: pending,
+            pendingSince: str(data.pendingSince),
+            caps: paid
+                ? {
+                    maxVoucherAmount: str(paid.maxVoucherAmount),
+                    maxPerWindow: str(paid.maxPerWindow),
+                    spentInWindow: str(paid.spentInWindow),
+                    validUntil: str(paid.validUntil),
+                }
+                : null,
+            approvalUrl: approvalLink(this.#c.webOrigin, data.approvalUrl, data.credentialId, mine),
+            fingerprint: mine ? fingerprint(mine) : null,
+        };
+    }
+    /**
+     * Binds this client's EVM signer to the API key: challenge, field check, sign, bind. A no-op
+     * when the key is already bound or already waiting. When another key is bound, this key waits as
+     * `pendingDelegate` (`bindStatus: "PENDING_APPROVAL"`) and the old key keeps signing until a
+     * person approves the new one at `approvalUrl`, comparing the fingerprint. Needs the `payments`
+     * scope. A key bound to another API key is refused with `DelegateAlreadyBoundError` (409).
+     * When another key wins a first bind at the same moment, this is `DelegateBindConflictError`
+     * (409, retryable): nothing was bound, and calling `bind()` once more parks this key as pending.
+     */
+    async bind(options = {}) {
+        const signer = this.#signer();
+        if (signer === null)
+            throw new ConfigError("bind() needs an eip155 signer");
+        const mine = getAddress(signer.address);
+        const current = await this.status();
+        if (current.delegate === mine)
+            return { ...current, alreadyBound: true, bindStatus: "ACTIVE" };
+        if (current.pendingDelegate === mine)
+            return { ...current, alreadyBound: true, bindStatus: "PENDING_APPROVAL" };
+        const evm = [...this.#c.networks.keys()].filter((n) => n.startsWith("eip155:"));
+        const network = options.network ?? (evm.length === 1 ? evm[0] : undefined);
+        const chainId = network === undefined || !this.#c.networks.has(network) ? null : eip155ChainId(network);
+        if (chainId === null) {
+            if (network === undefined && evm.length > 1)
+                throw new ConfigError("bind() needs `network` naming one of the eip155 networks");
+            if (network === undefined)
+                throw new PaymentNetworkUnknownError("eip155", "no network is configured for this signer's namespace (eip155); pass `networks` to the Assay constructor with an entry for your chain");
+            throw new PaymentNetworkUnknownError(network);
+        }
+        const answer = await bindEvmKey({
+            signer,
+            chainId,
+            credentialId: current.credentialId,
+            api: this.#c.api,
+            now: this.#c.now,
+        });
+        const bindStatus = answer.status === "PENDING_APPROVAL" ? "PENDING_APPROVAL" : "ACTIVE";
+        return { ...(await this.status()), alreadyBound: false, bindStatus };
+    }
+    /**
+     * Polls until a person approved this client's key: `delegate` is this key and its paid calls are
+     * on. A key waiting to replace another one becomes `delegate` only when the approval lands.
+     * Every 5 s for 2 minutes, then every 15 s.
+     */
+    async waitUntilActive(options = {}) {
+        const signer = this.#signer();
+        const mine = signer ? getAddress(signer.address) : null;
+        const started = this.#c.now();
+        const until = started + (options.timeoutMs ?? 15 * 60_000);
+        for (;;) {
+            if (options.signal?.aborted)
+                throw new AssayError("ABORTED", "the wait was aborted");
+            try {
+                const s = await this.status();
+                if (s.state === "active" && (mine === null || s.delegate === mine))
+                    return s;
+            }
+            catch (err) {
+                if (!(err instanceof AssayError) || !err.retryable)
+                    throw err;
+            }
+            const now = this.#c.now();
+            if (now >= until)
+                throw new AssayError("WAIT_TIMEOUT", "paid calls were not approved in time", { retryable: true });
+            await this.#c.sleep(Math.min(until - now, now - started < 120_000 ? 5_000 : 15_000));
+        }
+    }
+}

package/dist/resources/receipts.d.ts

@@ -0,0 +1,25 @@
+import type { Money } from "../core/voucher.js";
+import type { ClientContext } from "./context.js";
+/** `GET /receipts/{intentId}`: one call, with what it cost. Dates are ISO 8601 strings. */
+export interface Receipt {
+    intentId: string;
+    toolId: string;
+    providerId: string | null;
+    status: string;
+    classification: string | null;
+    listedPrice: Money;
+    chargedPrice: Money;
+    withheld: Money;
+    createdAt: string;
+    settledAt: string | null;
+    [key: string]: unknown;
+}
+export declare class Receipts {
+    #private;
+    constructor(context: ClientContext);
+    /**
+     * The receipt of a call, by its intent id (`result.receipt.intentId`). Needs the
+     * `activity:read` scope.
+     */
+    get(intentId: string): Promise<Receipt>;
+}

package/dist/resources/receipts.js

@@ -0,0 +1,21 @@
+import { ConfigError, ServerError } from "../errors.js";
+import { isObject } from "../core/meta.js";
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+export class Receipts {
+    #c;
+    constructor(context) {
+        this.#c = context;
+    }
+    /**
+     * The receipt of a call, by its intent id (`result.receipt.intentId`). Needs the
+     * `activity:read` scope.
+     */
+    async get(intentId) {
+        if (typeof intentId !== "string" || !UUID.test(intentId))
+            throw new ConfigError("intentId must be a UUID");
+        const { data } = await this.#c.api.get(`/receipts/${intentId}`);
+        if (!isObject(data) || typeof data.intentId !== "string")
+            throw new ServerError("API_BAD_ANSWER", "the receipt answer is not readable");
+        return data;
+    }
+}

package/dist/resources/tools.d.ts

@@ -0,0 +1,96 @@
+import { type PriceQuote } from "../core/meta.js";
+import type { Money } from "../core/voucher.js";
+import type { ClientContext } from "./context.js";
+/** `_meta["assay/receipt"]`: what a call cost (spec section 10.1). */
+export interface CallReceipt {
+    /** The payment intent; `null` for a free call, which has no intent and no receipt to fetch. */
+    intentId: string | null;
+    charged?: Money & {
+        display?: string;
+    };
+    held?: Money & {
+        display?: string;
+    };
+    status?: string;
+    toolId?: string;
+    providerId?: string;
+    classification?: string;
+    attempts?: number;
+    fellBack?: boolean;
+    [key: string]: unknown;
+}
+export interface ToolResult {
+    content: unknown[];
+    structuredContent?: Record<string, unknown>;
+    /** The provider's own tool error. Assay refusals are thrown, never returned. */
+    isError: boolean;
+    receipt: CallReceipt | null;
+    /** The stored result of an earlier attempt with the same idempotency key; not charged again. */
+    replayed: boolean;
+    /** The key this logical call used; pass it again to retry the same call safely. */
+    idempotencyKey: string;
+}
+export interface CallOptions {
+    /** Names one logical call. A UUID is created when it is not given. 1-128 printable ASCII. */
+    idempotencyKey?: string;
+}
+export interface SearchOptions {
+    limit?: number;
+    category?: string;
+    detail?: "names" | "summary" | "full";
+    cursor?: string;
+}
+export interface ToolSummary {
+    name: string;
+    [key: string]: unknown;
+}
+export interface SearchResult {
+    results: ToolSummary[];
+    nextCursor: string | null;
+}
+export interface ListOptions {
+    cursor?: string;
+}
+export interface ListResult {
+    /** The tools this URL lists, as MCP describes them (`name`, `description`, `inputSchema`, `_meta` ...). */
+    tools: ToolInfo[];
+    nextCursor: string | null;
+    /**
+     * The list's `_meta`, as sent: `assay/toolsetVersion` (a tool set URL without `@n`),
+     * `assay/sharingEnds`, `assay/renamed` (an old handle) and `assay/ignoredTools` (`?tools=` names
+     * this URL does not serve).
+     */
+    meta: Record<string, unknown>;
+}
+export interface ToolInfo {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    price?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Tools over MCP: search, describe and call, with paid calls signed by the caller's signer. */
+export declare class Tools {
+    #private;
+    constructor(context: ClientContext);
+    /** `search_tools`: tools this URL can run, by what they do. Free. */
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * `tools/list`: the tools this URL lists. A tool set, topic, maker or `?tools=` URL lists its
+     * tools; Everything (`/`) lists only a few, plus `search_tools`, `get_tool` and `call_tool`.
+     * Free. Each tool's `_meta["assay/price"]` is kept as its quote for paid calls (G3).
+     */
+    list(options?: ListOptions): Promise<ListResult>;
+    /** `get_tool`: one tool's description, schemas, price and version. Free. */
+    get(name: string): Promise<ToolInfo>;
+    /**
+     * Calls a tool. A paid tool's `PAYMENT_REQUIRED` is checked by every local guard, offered to
+     * `onPayment`, signed once, and the same call is sent again with the voucher and the same
+     * idempotency key. Network retries resend the same request; nothing is ever signed twice for
+     * one attempt. Assay refusals are thrown as typed errors.
+     */
+    call(name: string, args?: Record<string, unknown>, options?: CallOptions): Promise<ToolResult>;
+    /** G3: the cached quote, or a fresh `get_tool` just before signing. */
+    quoteFor(tool: string): Promise<PriceQuote | null>;
+}

package/dist/resources/tools.js

@@ -0,0 +1,241 @@
+import { randomUUID } from "node:crypto";
+import { namespaceOf } from "../core/caip.js";
+import { CALL_TOOL, ERROR_META, GET_TOOL, IDEMPOTENCY_META, IN_PROGRESS_CODE, isIdempotencyKey, isObject, isToolName, PAYMENT_REQUIRED_CODE, PAYMENT_REQUIRED_META, PRICE_META, quoteOf, RECEIPT_META, REPLAYED_META, SEARCH_TOOLS, structuredOf, VOUCHER_META, } from "../core/meta.js";
+import { AssayError, ConfigError, errorFromServer, PaymentError, PaymentNetworkUnknownError, PaymentRefusedError, PaymentRequiredError, PaymentSchemeUnsupportedError, ServerError, } from "../errors.js";
+import { MAX_RETRY_AFTER_MS } from "../http.js";
+function assayErrorOf(result) {
+    const meta = isObject(result._meta) ? result._meta : null;
+    return meta && isObject(meta[ERROR_META]) && typeof meta[ERROR_META].code === "string" ? meta[ERROR_META] : null;
+}
+function textOf(result) {
+    const c = Array.isArray(result.content) ? result.content : [];
+    const t = c.find((x) => isObject(x) && x.type === "text" && typeof x.text === "string");
+    return t?.text;
+}
+/** The typed error for `_meta["assay/error"]`. */
+function toolError(e, result) {
+    const code = e.code;
+    const message = typeof e.message === "string" ? e.message : (textOf(result) ?? code);
+    const secs = typeof e.retryAfter === "number" ? e.retryAfter * 1000 : undefined;
+    const wait = typeof e.retryAfterMs === "number" ? e.retryAfterMs : secs;
+    const details = isObject(e.details) ? { ...e.details } : {};
+    if (typeof e.intentId === "string")
+        details.intentId = e.intentId;
+    // A scope refusal on a tool call names the scope on `assay/error` itself, not under `details`.
+    if (typeof e.requiredScope === "string" && details.requiredScope === undefined)
+        details.requiredScope = e.requiredScope;
+    return errorFromServer(code, message, {
+        retryable: e.retryable === true,
+        ...(typeof e.fixUrl === "string" ? { fixUrl: e.fixUrl } : {}),
+        ...(Object.keys(details).length > 0 ? { details } : {}),
+        ...(wait !== undefined ? { retryAfterMs: wait } : {}),
+    });
+}
+function withKey(err, key) {
+    err.idempotencyKey ??= key;
+    return err;
+}
+function toResult(result, idempotencyKey) {
+    const meta = isObject(result._meta) ? result._meta : {};
+    const receipt = isObject(meta[RECEIPT_META]) ? meta[RECEIPT_META] : null;
+    return {
+        content: Array.isArray(result.content) ? result.content : [],
+        ...(isObject(result.structuredContent) ? { structuredContent: result.structuredContent } : {}),
+        isError: result.isError === true,
+        receipt,
+        replayed: meta[REPLAYED_META] === true,
+        idempotencyKey,
+    };
+}
+/** Tools over MCP: search, describe and call, with paid calls signed by the caller's signer. */
+export class Tools {
+    #c;
+    constructor(context) {
+        this.#c = context;
+    }
+    /** `search_tools`: tools this URL can run, by what they do. Free. */
+    async search(query, options = {}) {
+        const out = await this.#meta(SEARCH_TOOLS, { query, ...options });
+        const results = Array.isArray(out.results)
+            ? out.results.filter((r) => isObject(r) && isToolName(r.name))
+            : [];
+        for (const r of results)
+            this.#remember(r.name, quoteOf(r.assayPrice));
+        return { results, nextCursor: typeof out.nextCursor === "string" ? out.nextCursor : null };
+    }
+    /**
+     * `tools/list`: the tools this URL lists. A tool set, topic, maker or `?tools=` URL lists its
+     * tools; Everything (`/`) lists only a few, plus `search_tools`, `get_tool` and `call_tool`.
+     * Free. Each tool's `_meta["assay/price"]` is kept as its quote for paid calls (G3).
+     */
+    async list(options = {}) {
+        const out = await this.#c.mcp.request("tools/list", options.cursor !== undefined ? { cursor: options.cursor } : {});
+        const tools = Array.isArray(out.tools)
+            ? out.tools.filter((t) => isObject(t) && isToolName(t.name))
+            : [];
+        for (const t of tools)
+            this.#remember(t.name, quoteOf(isObject(t._meta) ? t._meta[PRICE_META] : undefined));
+        return {
+            tools,
+            nextCursor: typeof out.nextCursor === "string" ? out.nextCursor : null,
+            meta: isObject(out._meta) ? { ...out._meta } : {},
+        };
+    }
+    /** `get_tool`: one tool's description, schemas, price and version. Free. */
+    async get(name) {
+        const out = await this.#meta(GET_TOOL, { name });
+        if (typeof out.name !== "string")
+            throw new ServerError("MCP_BAD_ANSWER", "get_tool answered without a tool name");
+        this.#remember(out.name, quoteOf(out.price));
+        return out;
+    }
+    /**
+     * Calls a tool. A paid tool's `PAYMENT_REQUIRED` is checked by every local guard, offered to
+     * `onPayment`, signed once, and the same call is sent again with the voucher and the same
+     * idempotency key. Network retries resend the same request; nothing is ever signed twice for
+     * one attempt. Assay refusals are thrown as typed errors.
+     */
+    async call(name, args = {}, options = {}) {
+        if (!isToolName(name))
+            throw new ConfigError("name is not a tool name");
+        if (!isObject(args))
+            throw new ConfigError("arguments must be an object");
+        const key = options.idempotencyKey ?? randomUUID();
+        if (!isIdempotencyKey(key))
+            throw new ConfigError("idempotencyKey must be 1 to 128 printable ASCII characters");
+        // One logical call per key in this client: a second call with the key while the first runs
+        // waits for it, so at most one voucher is ever signed for it.
+        const fingerprint = JSON.stringify([name, args]);
+        const running = this.#c.inFlight.get(key);
+        if (running) {
+            if (running.fingerprint !== fingerprint) {
+                throw withKey(new AssayError("IDEMPOTENCY_KEY_REUSED", "this idempotency key is in use for another call"), key);
+            }
+            return running.promise;
+        }
+        const promise = this.#call(name, args, key).catch((err) => {
+            throw err instanceof AssayError ? withKey(err, key) : err;
+        });
+        this.#c.inFlight.set(key, { fingerprint, promise });
+        try {
+            return await promise;
+        }
+        finally {
+            this.#c.inFlight.delete(key);
+        }
+    }
+    async #call(name, args, key) {
+        const params = { name, arguments: args, _meta: { [IDEMPOTENCY_META]: key } };
+        const calledAt = Math.floor(this.#c.now() / 1000);
+        const first = await this.#send(params);
+        const refusal = assayErrorOf(first);
+        if (refusal === null)
+            return toResult(first, key);
+        const meta = first._meta;
+        const requirement = meta[PAYMENT_REQUIRED_META];
+        if (refusal.code !== PAYMENT_REQUIRED_CODE || requirement === undefined || requirement === null)
+            throw toolError(refusal, first);
+        const fixUrl = typeof refusal.fixUrl === "string" ? { fixUrl: refusal.fixUrl } : {};
+        if (this.#c.signers.length === 0) {
+            throw new PaymentRequiredError(`${name} is a paid tool and this client has no signer`, requirement, fixUrl);
+        }
+        const network = isObject(requirement) && typeof requirement.network === "string" ? requirement.network : "unknown";
+        const ns = namespaceOf(network);
+        const signer = this.#c.signers.find((s) => s.namespace === ns);
+        const scheme = ns === null ? undefined : this.#c.schemes.get(ns);
+        if (!signer || !scheme)
+            throw new PaymentSchemeUnsupportedError(network);
+        const tool = name === CALL_TOOL ? args.name : name;
+        if (!isToolName(tool))
+            throw new PaymentRefusedError("G1", "G1_NOT_FORWARDED", "the paid tool's name is not readable");
+        const input = {
+            requirement,
+            tool,
+            calledAt,
+            signer,
+            idempotencyKey: key,
+            quote: (t) => this.quoteFor(t),
+        };
+        const prepared = await scheme.prepare(input);
+        if (!prepared.ok) {
+            if (prepared.code === "G2_NETWORK")
+                throw new PaymentNetworkUnknownError(network);
+            throw new PaymentRefusedError(prepared.guard, prepared.code, prepared.reason, fixUrl);
+        }
+        if (this.#c.onPayment) {
+            let verdict;
+            try {
+                verdict = await this.#c.onPayment(Object.freeze({ ...prepared.details }));
+            }
+            catch (err) {
+                prepared.release();
+                throw err;
+            }
+            if (verdict === false) {
+                prepared.release();
+                throw new PaymentRefusedError("onPayment", "PAYMENT_REFUSED_BY_CALLER", "the onPayment hook refused it");
+            }
+        }
+        let envelope;
+        try {
+            envelope = await prepared.sign();
+        }
+        catch (err) {
+            prepared.release();
+            if (err instanceof AssayError)
+                throw err;
+            throw new PaymentError("SIGNER_FAILED", "the signer did not sign the voucher", { cause: err });
+        }
+        const paid = await this.#send({ ...params, _meta: { ...params._meta, [VOUCHER_META]: envelope } });
+        const after = assayErrorOf(paid);
+        if (after === null)
+            return toResult(paid, key);
+        await scheme.onRefused(after.code, input);
+        throw toolError(after, paid);
+    }
+    /** One `tools/call`; an `IDEMPOTENCY_IN_PROGRESS` answer waits and sends the same request again. */
+    async #send(params) {
+        for (let attempt = 0;; attempt++) {
+            const result = await this.#c.mcp.request("tools/call", params);
+            const e = assayErrorOf(result);
+            // The first attempt still runs, or a refusal-rate limit: wait and send the same bytes again.
+            if ((e?.code !== IN_PROGRESS_CODE && e?.code !== "RATE_LIMITED") || attempt >= this.#c.maxRetries)
+                return result;
+            const wait = typeof e.retryAfterMs === "number"
+                ? e.retryAfterMs
+                : typeof e.retryAfter === "number"
+                    ? e.retryAfter * 1000
+                    : 1000;
+            if (wait > MAX_RETRY_AFTER_MS)
+                return result;
+            await this.#c.sleep(wait);
+        }
+    }
+    async #meta(tool, args) {
+        const result = await this.#send({ name: tool, arguments: args });
+        const e = assayErrorOf(result);
+        if (e)
+            throw toolError(e, result);
+        const out = structuredOf(result);
+        if (out === null)
+            throw new AssayError("TOOL_ERROR", textOf(result) ?? `${tool} failed`);
+        return out;
+    }
+    #remember(name, quote) {
+        if (quote)
+            this.#c.quotes.set(name, quote);
+    }
+    /** G3: the cached quote, or a fresh `get_tool` just before signing. */
+    async quoteFor(tool) {
+        const cached = this.#c.quotes.get(tool);
+        if (cached)
+            return cached;
+        try {
+            const info = await this.get(tool);
+            return info.name === tool ? this.#c.quotes.get(tool) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/rest.d.ts

@@ -0,0 +1,17 @@
+import type { Http } from "./http.js";
+/** A REST answer's `data` and its `Date` header. */
+export interface RestAnswer {
+    data: unknown;
+    date: string | null;
+}
+/** The REST API (spec section 2.2): `{data}` on success, a typed error from `{error}` otherwise. */
+export declare class RestClient {
+    #private;
+    private readonly http;
+    private readonly base;
+    private readonly now;
+    constructor(http: Http, base: string, now?: () => number);
+    /** GETs are retried; POSTs are not (a challenge or a bind is not resent blindly). */
+    get(path: string): Promise<RestAnswer>;
+    post(path: string, body: unknown): Promise<RestAnswer>;
+}