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

package/dist/core/meta.js

@@ -0,0 +1,79 @@
+/**
+ * The `_meta` keys Assay reads and writes on MCP messages (spec section 3), and pure helpers.
+ */
+export const IDEMPOTENCY_META = "assay/idempotency-key";
+export const RAIL_META = "assay/rail";
+export const VOUCHER_META = "assay/voucher";
+export const PAYMENT_REQUIRED_META = "x402/paymentRequired";
+export const ERROR_META = "assay/error";
+export const RECEIPT_META = "assay/receipt";
+export const REPLAYED_META = "assay/replayed";
+export const PRICE_META = "assay/price";
+export const PAYMENT_REQUIRED_CODE = "PAYMENT_REQUIRED";
+export const DELEGATE_INACTIVE_CODE = "PAYMENT_VOUCHER_DELEGATE_INACTIVE";
+export const IN_PROGRESS_CODE = "IDEMPOTENCY_IN_PROGRESS";
+/** The meta tools every Assay MCP URL serves. */
+export const SEARCH_TOOLS = "search_tools";
+export const GET_TOOL = "get_tool";
+export const CALL_TOOL = "call_tool";
+const IDEMPOTENCY_KEY = /^[\x20-\x7e]{1,128}$/;
+const UINT = /^(0|[1-9][0-9]*)$/;
+const TOOL_NAME = /^[A-Za-z0-9_-]{1,128}$/;
+export function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** 1 to 128 printable ASCII characters (spec section 8). */
+export function isIdempotencyKey(value) {
+    return typeof value === "string" && IDEMPOTENCY_KEY.test(value);
+}
+/**
+ * A tool name as sent to the server, unchanged: a standard `verb_noun`, or a provider tool's
+ * `{handle}__{tool}` (for example `acme__get_quote`). The server decides what it serves.
+ */
+export function isToolName(value) {
+    return typeof value === "string" && TOOL_NAME.test(value);
+}
+export function quoteOf(price) {
+    if (!isObject(price))
+        return null;
+    const { maxAmount, asset } = price;
+    if (typeof maxAmount !== "string" || !UINT.test(maxAmount) || maxAmount.length > 30)
+        return null;
+    if (typeof asset !== "string" || asset.length === 0 || asset.length > 200)
+        return null;
+    return { maxAmount, asset };
+}
+/** The structured output of a meta tool result (`structuredContent`, else the JSON text block). */
+export function structuredOf(result) {
+    if (!isObject(result) || result.isError === true)
+        return null;
+    if (isObject(result.structuredContent))
+        return result.structuredContent;
+    const first = Array.isArray(result.content) ? result.content[0] : undefined;
+    if (isObject(first) && first.type === "text" && typeof first.text === "string" && first.text.length <= 1_000_000) {
+        try {
+            const parsed = JSON.parse(first.text);
+            return isObject(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/** The voucher envelope of the signed retry (spec section 6.4). */
+export function voucherEnvelope(voucher, signature, providerId, contractVersion) {
+    return {
+        voucher,
+        signature,
+        providerId,
+        ...(typeof contractVersion === "number" && Number.isSafeInteger(contractVersion) && contractVersion >= 1
+            ? { contractVersion }
+            : {}),
+    };
+}
+/** The payment key as people compare it: the last 8 hex digits, upper case, in two groups. */
+export function fingerprint(address) {
+    const tail = address.slice(-8).toUpperCase();
+    return `${tail.slice(0, 4)} ${tail.slice(4)}`;
+}

package/dist/core/voucher.d.ts

@@ -0,0 +1,116 @@
+import { type Address, type Hex } from "./hex.js";
+/** The escrow's EIP-712 domain name and version (spec section 6.1). */
+export declare const VOUCHER_DOMAIN_NAME = "Assay Settlement";
+export declare const VOUCHER_DOMAIN_VERSION = "2";
+/** The lifetime a client asks for: well inside the server's 300 s ceiling. */
+export declare const VOUCHER_LIFETIME_SECONDS = 240;
+/** The eight signed fields. The order is the type hash. */
+export declare const VOUCHER_TYPES: {
+    readonly Voucher: readonly [{
+        readonly name: "payer";
+        readonly type: "address";
+    }, {
+        readonly name: "provider";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint64";
+    }, {
+        readonly name: "resourceHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "requestHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "seq";
+        readonly type: "uint64";
+    }, {
+        readonly name: "issuedAt";
+        readonly type: "uint64";
+    }, {
+        readonly name: "expiresAt";
+        readonly type: "uint64";
+    }];
+};
+export interface Money {
+    amount: string;
+    asset: string;
+    decimals: number;
+}
+/** `_meta["x402/paymentRequired"]` on rail B (spec section 4). */
+export interface VoucherRequirement {
+    rail: "B";
+    scheme: "voucher";
+    network: string;
+    payer: string;
+    payTo: string;
+    provider: string;
+    providerId: string;
+    amount: Money;
+    contractVersion?: number;
+    resource: string;
+    requestHash: string;
+    seq: string;
+    maxTimeoutSeconds: number;
+    signers?: string[];
+    delegate?: string | null;
+}
+/** The voucher as it goes on the wire in `_meta["assay/voucher"].voucher` (spec section 6.3). */
+export interface WireVoucher {
+    payer: string;
+    payTo: string;
+    provider: string;
+    amount: Money;
+    resource: string;
+    requestHash: string;
+    seq: string;
+    issuedAt: number;
+    expiresAt: number;
+}
+export interface VoucherTypedData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: Address;
+    };
+    types: typeof VOUCHER_TYPES;
+    primaryType: "Voucher";
+    message: {
+        payer: Address;
+        provider: Address;
+        amount: bigint;
+        resourceHash: Hex;
+        requestHash: Hex;
+        seq: bigint;
+        issuedAt: bigint;
+        expiresAt: bigint;
+    };
+}
+/** A network entry of the client's own built-in table. Never taken from the server. */
+export interface NetworkEntry {
+    /** CAIP-2, `eip155:<chainId>`. */
+    caip2: string;
+    /** CAIP-10 escrow account. */
+    escrow: string;
+    /** CAIP-19 erc20 asset. */
+    asset: string;
+    decimals: number;
+}
+/**
+ * Builds the wire voucher and the EIP-712 typed data the payment key signs (spec section 6),
+ * from a rail-B requirement, a corrected `issuedAt` and the client's own network entry.
+ *
+ * - `resourceHash = keccak256(utf8(resource))`; `requestHash` is the requirement's 32 bytes
+ *   without `sha256:`;
+ * - `expiresAt = issuedAt + min(240, maxTimeoutSeconds)`;
+ * - the domain is `{name: "Assay Settlement", version: "2", chainId, verifyingContract}`, from
+ *   `net` only.
+ *
+ * Throws `SignerRefusal` for a requirement on another network, a `payTo` other than the escrow,
+ * an amount in another asset or scale, and anything that cannot be encoded.
+ */
+export declare function buildVoucher(requirement: VoucherRequirement, issuedAtSeconds: number, net: NetworkEntry): {
+    wire: WireVoucher;
+    typedData: VoucherTypedData;
+};

package/dist/core/voucher.js

@@ -0,0 +1,137 @@
+import { parseCaip10, parseCaip19Erc20 } from "./caip.js";
+import { getAddress, keccakUtf8 } from "./hex.js";
+import { SignerRefusal } from "./errors.js";
+/** The escrow's EIP-712 domain name and version (spec section 6.1). */
+export const VOUCHER_DOMAIN_NAME = "Assay Settlement";
+export const VOUCHER_DOMAIN_VERSION = "2";
+/** The lifetime a client asks for: well inside the server's 300 s ceiling. */
+export const VOUCHER_LIFETIME_SECONDS = 240;
+/** The eight signed fields. The order is the type hash. */
+export const VOUCHER_TYPES = {
+    Voucher: [
+        { name: "payer", type: "address" },
+        { name: "provider", type: "address" },
+        { name: "amount", type: "uint64" },
+        { name: "resourceHash", type: "bytes32" },
+        { name: "requestHash", type: "bytes32" },
+        { name: "seq", type: "uint64" },
+        { name: "issuedAt", type: "uint64" },
+        { name: "expiresAt", type: "uint64" },
+    ],
+};
+const MAX_UINT64 = 2n ** 64n - 1n;
+const CAIP2 = /^eip155:([1-9][0-9]*)$/;
+function refuse(field, reason) {
+    throw new SignerRefusal("the voucher", field, reason);
+}
+function uint64(field, value) {
+    const ok = (typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value)) ||
+        (typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
+    if (!ok)
+        refuse(field, "is not a non-negative integer");
+    const n = BigInt(value);
+    if (n > MAX_UINT64)
+        refuse(field, "does not fit uint64");
+    return n;
+}
+function account(field, value, chainId) {
+    const parsed = typeof value === "string" ? parseCaip10(value) : null;
+    if (!parsed)
+        refuse(field, "is not a checksummed CAIP-10 account");
+    if (parsed.chainId !== chainId)
+        refuse(field, "is not on the requirement's network");
+    return getAddress(parsed.address);
+}
+/** `sha256:<64 hex>` or bare 64 hex, as 32 bytes. */
+function requestHashBytes(value) {
+    const hex = typeof value === "string" ? value.replace(/^sha256:/, "") : "";
+    if (!/^[0-9a-fA-F]{64}$/.test(hex))
+        refuse("requestHash", "is not 32 bytes of hex");
+    return `0x${hex.toLowerCase()}`;
+}
+function resolve(net) {
+    const chain = typeof net?.caip2 === "string" ? CAIP2.exec(net.caip2) : null;
+    if (!chain)
+        refuse("network", "is not an eip155 CAIP-2 chain id");
+    const chainId = Number(chain[1]);
+    const escrow = typeof net.escrow === "string" ? parseCaip10(net.escrow) : null;
+    if (!escrow || escrow.chainId !== chainId)
+        refuse("network.escrow", "is not a CAIP-10 account on the network's chain");
+    const asset = typeof net.asset === "string" ? parseCaip19Erc20(net.asset) : null;
+    if (!asset || asset.chainId !== chainId)
+        refuse("network.asset", "is not a CAIP-19 erc20 asset on the network's chain");
+    if (!Number.isInteger(net.decimals) || net.decimals < 0 || net.decimals > 36)
+        refuse("network.decimals", "is invalid");
+    return { chainId, escrow: getAddress(escrow.address) };
+}
+/**
+ * Builds the wire voucher and the EIP-712 typed data the payment key signs (spec section 6),
+ * from a rail-B requirement, a corrected `issuedAt` and the client's own network entry.
+ *
+ * - `resourceHash = keccak256(utf8(resource))`; `requestHash` is the requirement's 32 bytes
+ *   without `sha256:`;
+ * - `expiresAt = issuedAt + min(240, maxTimeoutSeconds)`;
+ * - the domain is `{name: "Assay Settlement", version: "2", chainId, verifyingContract}`, from
+ *   `net` only.
+ *
+ * Throws `SignerRefusal` for a requirement on another network, a `payTo` other than the escrow,
+ * an amount in another asset or scale, and anything that cannot be encoded.
+ */
+export function buildVoucher(requirement, issuedAtSeconds, net) {
+    const { chainId, escrow: verifyingContract } = resolve(net);
+    if (requirement.network !== net.caip2)
+        refuse("network", "is not the client's network");
+    const payTo = account("payTo", requirement.payTo, chainId);
+    if (payTo !== verifyingContract)
+        refuse("payTo", "is not the built-in escrow");
+    const payer = account("payer", requirement.payer, chainId);
+    const provider = account("provider", requirement.provider, chainId);
+    const money = requirement.amount;
+    if (typeof money !== "object" || money === null)
+        refuse("amount", "is missing");
+    const amount = uint64("amount", requirement.amount.amount);
+    if (requirement.amount.asset !== net.asset)
+        refuse("amount.asset", "is not the built-in asset");
+    if (requirement.amount.decimals !== net.decimals)
+        refuse("amount.decimals", "are not the built-in decimals");
+    const seq = uint64("seq", requirement.seq);
+    if (typeof requirement.resource !== "string" || requirement.resource.length === 0)
+        refuse("resource", "is empty");
+    const requestHash = requestHashBytes(requirement.requestHash);
+    const maxTimeout = requirement.maxTimeoutSeconds;
+    if (!Number.isSafeInteger(maxTimeout) || maxTimeout < 1)
+        refuse("maxTimeoutSeconds", "is not a positive integer");
+    if (!Number.isSafeInteger(issuedAtSeconds) || issuedAtSeconds <= 0)
+        refuse("issuedAt", "is not a positive integer");
+    const issuedAt = issuedAtSeconds;
+    const expiresAt = issuedAt + Math.min(VOUCHER_LIFETIME_SECONDS, maxTimeout);
+    // Built fresh: nothing the server sent beyond the checked fields reaches the wire.
+    const wire = {
+        payer: requirement.payer,
+        payTo: requirement.payTo,
+        provider: requirement.provider,
+        amount: { amount: amount.toString(), asset: net.asset, decimals: net.decimals },
+        resource: requirement.resource,
+        requestHash: requirement.requestHash,
+        seq: seq.toString(),
+        issuedAt,
+        expiresAt,
+    };
+    const typedData = {
+        domain: { name: VOUCHER_DOMAIN_NAME, version: VOUCHER_DOMAIN_VERSION, chainId, verifyingContract },
+        types: VOUCHER_TYPES,
+        primaryType: "Voucher",
+        message: {
+            payer,
+            provider,
+            amount,
+            // The UTF-8 bytes: a resource starting with `0x` is still a string.
+            resourceHash: keccakUtf8(requirement.resource),
+            requestHash,
+            seq,
+            issuedAt: BigInt(issuedAt),
+            expiresAt: BigInt(expiresAt),
+        },
+    };
+    return { wire, typedData };
+}

package/dist/errors.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The SDK's errors. Every error the SDK raises is an {@link AssayError} with a stable `code`;
+ * branch on the class or on `code`, never on the message. A server code this release does not
+ * know still arrives, as the nearest class (or `AssayError` itself).
+ *
+ * ```text
+ * AssayError
+ * ├─ ConfigError                      local setup (missing API key, bad option)
+ * ├─ AuthError                        401, or an AUTH_* refusal
+ * │   ├─ ScopeMissingError            403 AUTH_SCOPE_MISSING (.requiredScope)
+ * │   └─ HumanSessionRequiredError    403 AUTH_HUMAN_SESSION_REQUIRED: only a signed-in person may do this
+ * ├─ McpUrlNotFoundError              404 MCP_URL_NOT_FOUND: the MCP host serves no such URL for this key
+ * ├─ DelegateAlreadyBoundError        409 ACCOUNT_DELEGATE_ALREADY_BOUND: the key is bound to another API key
+ * ├─ DelegateBindConflictError        409 ACCOUNT_DELEGATE_BIND_CONFLICT: another key won a first bind; retry once
+ * ├─ PaymentError                     a PAYMENT_* refusal from the server
+ * │   ├─ PaymentRequiredError         the tool is paid and no signer was given (.requirement)
+ * │   ├─ PaymentSchemeUnsupportedError no signer for the requirement's network (.network)
+ * │   └─ PaymentRefusedError          refused locally before signing (.guard); nothing signed
+ * │       └─ PaymentNetworkUnknownError the network is not in the SDK's network table (.network)
+ * ├─ RateLimitError                   429, RATE_LIMITED, quota or velocity limits (.retryAfterMs)
+ * ├─ NetworkError                     no answer: connection failure
+ * │   └─ TimeoutError
+ * └─ ServerError                      5xx or an answer the SDK cannot read
+ * ```
+ */
+export interface AssayErrorInit {
+    retryable?: boolean;
+    status?: number;
+    fixUrl?: string;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+export declare class AssayError extends Error {
+    name: string;
+    /** A stable code, from the server (`assay/error.code`, REST `error.code`) or the SDK. */
+    readonly code: string;
+    /** Whether the same call can succeed later. */
+    readonly retryable: boolean;
+    /** The HTTP status, when the error came with one. */
+    readonly status: number | undefined;
+    /** A page that fixes the cause, when the server named one. */
+    readonly fixUrl: string | undefined;
+    /** Extra structured data the server sent (never a key or a signature). */
+    readonly details: Record<string, unknown> | undefined;
+    /**
+     * On an error out of `tools.call`: the idempotency key of that logical call. Call again with
+     * `{ idempotencyKey: err.idempotencyKey }` to retry safely: Assay replays a served call instead
+     * of charging it twice.
+     */
+    idempotencyKey: string | undefined;
+    constructor(code: string, message: string, init?: AssayErrorInit);
+}
+export declare class ConfigError extends AssayError {
+    name: string;
+    constructor(message: string);
+}
+export declare class AuthError extends AssayError {
+    name: string;
+}
+export declare class ScopeMissingError extends AuthError {
+    name: string;
+    /** The scope the API key lacks, for example `payments`, when the server named it. */
+    readonly requiredScope: string | undefined;
+    constructor(message: string, init?: AssayErrorInit & {
+        requiredScope?: string;
+    });
+}
+export declare class HumanSessionRequiredError extends AuthError {
+    name: string;
+    constructor(message: string, init?: AssayErrorInit);
+}
+export declare const MCP_URL_NOT_FOUND = "MCP_URL_NOT_FOUND";
+/**
+ * The MCP host serves no such URL for this API key (`MCP_URL_NOT_FOUND`, or any 404 from it): the
+ * tool set, version, topic or maker does not exist, is not shared with you, or no longer serves.
+ * Not retried.
+ */
+export declare class McpUrlNotFoundError extends AssayError {
+    name: string;
+    constructor(message?: string, init?: AssayErrorInit);
+}
+/**
+ * The payment key is already bound (or waiting for approval) on another live API key; nothing was
+ * bound. Use a key of this agent's own, or revoke the other API key first.
+ */
+export declare class DelegateAlreadyBoundError extends AssayError {
+    name: string;
+    constructor(message: string, init?: AssayErrorInit);
+}
+/**
+ * Another payment key was bound to this API key at the same moment (two first binds raced);
+ * nothing was bound. Retryable once: a second `bind()` asks for a new challenge and parks this key
+ * as `pendingDelegate` (`bindStatus: "PENDING_APPROVAL"`) until a person approves it.
+ */
+export declare class DelegateBindConflictError extends AssayError {
+    name: string;
+    constructor(message: string, init?: AssayErrorInit);
+}
+export declare class PaymentError extends AssayError {
+    name: string;
+}
+export declare class PaymentRequiredError extends PaymentError {
+    name: string;
+    /** `_meta["x402/paymentRequired"]` as the server sent it. Untrusted. */
+    readonly requirement: unknown;
+    constructor(message: string, requirement: unknown, init?: AssayErrorInit);
+}
+export declare class PaymentSchemeUnsupportedError extends PaymentError {
+    name: string;
+    /** The CAIP-2 network the requirement is for. */
+    readonly network: string;
+    constructor(network: string);
+}
+export declare class PaymentRefusedError extends PaymentError {
+    name: string;
+    /** The local guard that refused (`G1`..`G12`), or `onPayment` for the caller's hook. */
+    readonly guard: string;
+    constructor(guard: string, code: string, reason: string, init?: AssayErrorInit);
+}
+export declare class PaymentNetworkUnknownError extends PaymentRefusedError {
+    name: string;
+    /** The CAIP-2 network asked for. */
+    readonly network: string;
+    constructor(network: string, message?: string);
+}
+export declare class RateLimitError extends AssayError {
+    name: string;
+    /** How long to wait before trying again, when the server said. */
+    readonly retryAfterMs: number | undefined;
+    constructor(code: string, message: string, init?: AssayErrorInit & {
+        retryAfterMs?: number;
+    });
+}
+export declare class NetworkError extends AssayError {
+    name: string;
+    constructor(message: string, cause?: unknown, code?: string);
+}
+export declare class TimeoutError extends NetworkError {
+    name: string;
+    constructor(message?: string, cause?: unknown);
+}
+export declare class ServerError extends AssayError {
+    name: string;
+}
+export interface ServerErrorFields extends AssayErrorInit {
+    retryAfterMs?: number;
+}
+/** The typed error for a server refusal, chosen by code first, then by HTTP status. */
+export declare function errorFromServer(code: string | undefined, message: string, f?: ServerErrorFields): AssayError;

package/dist/errors.js

@@ -0,0 +1,205 @@
+/**
+ * The SDK's errors. Every error the SDK raises is an {@link AssayError} with a stable `code`;
+ * branch on the class or on `code`, never on the message. A server code this release does not
+ * know still arrives, as the nearest class (or `AssayError` itself).
+ *
+ * ```text
+ * AssayError
+ * ├─ ConfigError                      local setup (missing API key, bad option)
+ * ├─ AuthError                        401, or an AUTH_* refusal
+ * │   ├─ ScopeMissingError            403 AUTH_SCOPE_MISSING (.requiredScope)
+ * │   └─ HumanSessionRequiredError    403 AUTH_HUMAN_SESSION_REQUIRED: only a signed-in person may do this
+ * ├─ McpUrlNotFoundError              404 MCP_URL_NOT_FOUND: the MCP host serves no such URL for this key
+ * ├─ DelegateAlreadyBoundError        409 ACCOUNT_DELEGATE_ALREADY_BOUND: the key is bound to another API key
+ * ├─ DelegateBindConflictError        409 ACCOUNT_DELEGATE_BIND_CONFLICT: another key won a first bind; retry once
+ * ├─ PaymentError                     a PAYMENT_* refusal from the server
+ * │   ├─ PaymentRequiredError         the tool is paid and no signer was given (.requirement)
+ * │   ├─ PaymentSchemeUnsupportedError no signer for the requirement's network (.network)
+ * │   └─ PaymentRefusedError          refused locally before signing (.guard); nothing signed
+ * │       └─ PaymentNetworkUnknownError the network is not in the SDK's network table (.network)
+ * ├─ RateLimitError                   429, RATE_LIMITED, quota or velocity limits (.retryAfterMs)
+ * ├─ NetworkError                     no answer: connection failure
+ * │   └─ TimeoutError
+ * └─ ServerError                      5xx or an answer the SDK cannot read
+ * ```
+ */
+export class AssayError extends Error {
+    name = "AssayError";
+    /** A stable code, from the server (`assay/error.code`, REST `error.code`) or the SDK. */
+    code;
+    /** Whether the same call can succeed later. */
+    retryable;
+    /** The HTTP status, when the error came with one. */
+    status;
+    /** A page that fixes the cause, when the server named one. */
+    fixUrl;
+    /** Extra structured data the server sent (never a key or a signature). */
+    details;
+    /**
+     * On an error out of `tools.call`: the idempotency key of that logical call. Call again with
+     * `{ idempotencyKey: err.idempotencyKey }` to retry safely: Assay replays a served call instead
+     * of charging it twice.
+     */
+    idempotencyKey;
+    constructor(code, message, init = {}) {
+        super(message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.code = code;
+        this.retryable = init.retryable ?? false;
+        this.status = init.status;
+        this.fixUrl = init.fixUrl;
+        this.details = init.details;
+        this.idempotencyKey = undefined;
+    }
+}
+export class ConfigError extends AssayError {
+    name = "ConfigError";
+    constructor(message) {
+        super("CONFIG_INVALID", message);
+    }
+}
+export class AuthError extends AssayError {
+    name = "AuthError";
+}
+export class ScopeMissingError extends AuthError {
+    name = "ScopeMissingError";
+    /** The scope the API key lacks, for example `payments`, when the server named it. */
+    requiredScope;
+    constructor(message, init = {}) {
+        super("AUTH_SCOPE_MISSING", message, { ...init, status: init.status ?? 403 });
+        this.requiredScope = init.requiredScope;
+    }
+}
+export class HumanSessionRequiredError extends AuthError {
+    name = "HumanSessionRequiredError";
+    constructor(message, init = {}) {
+        super("AUTH_HUMAN_SESSION_REQUIRED", message, { ...init, status: init.status ?? 403 });
+    }
+}
+export const MCP_URL_NOT_FOUND = "MCP_URL_NOT_FOUND";
+/**
+ * The MCP host serves no such URL for this API key (`MCP_URL_NOT_FOUND`, or any 404 from it): the
+ * tool set, version, topic or maker does not exist, is not shared with you, or no longer serves.
+ * Not retried.
+ */
+export class McpUrlNotFoundError extends AssayError {
+    name = "McpUrlNotFoundError";
+    constructor(message = "the MCP host serves no such URL for this API key", init = {}) {
+        super(MCP_URL_NOT_FOUND, message, { ...init, status: init.status ?? 404 });
+    }
+}
+/**
+ * The payment key is already bound (or waiting for approval) on another live API key; nothing was
+ * bound. Use a key of this agent's own, or revoke the other API key first.
+ */
+export class DelegateAlreadyBoundError extends AssayError {
+    name = "DelegateAlreadyBoundError";
+    constructor(message, init = {}) {
+        super("ACCOUNT_DELEGATE_ALREADY_BOUND", message, { ...init, status: init.status ?? 409 });
+    }
+}
+/**
+ * Another payment key was bound to this API key at the same moment (two first binds raced);
+ * nothing was bound. Retryable once: a second `bind()` asks for a new challenge and parks this key
+ * as `pendingDelegate` (`bindStatus: "PENDING_APPROVAL"`) until a person approves it.
+ */
+export class DelegateBindConflictError extends AssayError {
+    name = "DelegateBindConflictError";
+    constructor(message, init = {}) {
+        super("ACCOUNT_DELEGATE_BIND_CONFLICT", message, { ...init, retryable: true, status: init.status ?? 409 });
+    }
+}
+export class PaymentError extends AssayError {
+    name = "PaymentError";
+}
+export class PaymentRequiredError extends PaymentError {
+    name = "PaymentRequiredError";
+    /** `_meta["x402/paymentRequired"]` as the server sent it. Untrusted. */
+    requirement;
+    constructor(message, requirement, init = {}) {
+        super("PAYMENT_REQUIRED", message, init);
+        this.requirement = requirement;
+    }
+}
+export class PaymentSchemeUnsupportedError extends PaymentError {
+    name = "PaymentSchemeUnsupportedError";
+    /** The CAIP-2 network the requirement is for. */
+    network;
+    constructor(network) {
+        super("PAYMENT_SCHEME_UNSUPPORTED", `no signer for network ${network}; pass a signer for this network`);
+        this.network = network;
+    }
+}
+export class PaymentRefusedError extends PaymentError {
+    name = "PaymentRefusedError";
+    /** The local guard that refused (`G1`..`G12`), or `onPayment` for the caller's hook. */
+    guard;
+    constructor(guard, code, reason, init = {}) {
+        super(code, `payment refused before signing: ${reason}`, init);
+        this.guard = guard;
+    }
+}
+export class PaymentNetworkUnknownError extends PaymentRefusedError {
+    name = "PaymentNetworkUnknownError";
+    /** The CAIP-2 network asked for. */
+    network;
+    constructor(network, message) {
+        super("G2", "G2_NETWORK", message ??
+            `the network ${network} is not in this SDK's network table (pass networks for another environment or chain)`);
+        this.network = network;
+    }
+}
+export class RateLimitError extends AssayError {
+    name = "RateLimitError";
+    /** How long to wait before trying again, when the server said. */
+    retryAfterMs;
+    constructor(code, message, init = {}) {
+        super(code, message, { retryable: true, ...init });
+        this.retryAfterMs = init.retryAfterMs;
+    }
+}
+export class NetworkError extends AssayError {
+    name = "NetworkError";
+    constructor(message, cause, code = "NETWORK_ERROR") {
+        super(code, message, { retryable: true, cause });
+    }
+}
+export class TimeoutError extends NetworkError {
+    name = "TimeoutError";
+    constructor(message = "the request timed out", cause) {
+        super(message, cause, "TIMEOUT");
+    }
+}
+export class ServerError extends AssayError {
+    name = "ServerError";
+}
+const RATE_LIMIT_CODES = new Set([
+    "RATE_LIMITED",
+    "TOO_MANY_REQUESTS",
+    "MCP_QUOTA_EXCEEDED",
+    "MCP_VELOCITY_LIMIT_EXCEEDED",
+]);
+/** The typed error for a server refusal, chosen by code first, then by HTTP status. */
+export function errorFromServer(code, message, f = {}) {
+    const c = code ?? (f.status !== undefined ? `HTTP_${f.status}` : "UNKNOWN");
+    if (c === "AUTH_SCOPE_MISSING") {
+        const scope = f.details?.requiredScope;
+        return new ScopeMissingError(message, { ...f, ...(typeof scope === "string" ? { requiredScope: scope } : {}) });
+    }
+    if (c === MCP_URL_NOT_FOUND)
+        return new McpUrlNotFoundError(message, f);
+    if (c === "AUTH_HUMAN_SESSION_REQUIRED")
+        return new HumanSessionRequiredError(message, f);
+    if (c === "ACCOUNT_DELEGATE_ALREADY_BOUND")
+        return new DelegateAlreadyBoundError(message, f);
+    if (c === "ACCOUNT_DELEGATE_BIND_CONFLICT")
+        return new DelegateBindConflictError(message, f);
+    if (RATE_LIMIT_CODES.has(c) || f.status === 429)
+        return new RateLimitError(c, message, f);
+    if (c.startsWith("AUTH_") || f.status === 401)
+        return new AuthError(c, message, f);
+    if (c.startsWith("PAYMENT_"))
+        return new PaymentError(c, message, f);
+    if (f.status !== undefined && f.status >= 500)
+        return new ServerError(c, message, { retryable: true, ...f });
+    return new AssayError(c, message, f);
+}