@agent-cards/commerce-sdk 0.0.0-stage → 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,250 @@
+/** The fetch the client calls: Node 18 and later have one built in. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    ok: boolean;
+    text(): Promise<string>;
+}>;
+export declare const DEFAULT_BASE_URL = "https://api.agentcard.sh";
+/** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
+export declare const BUY_TURN_TIMEOUT_MS = 130000;
+/** A company's client credentials, or one shopper's own access token. */
+export type AgentcardClientOptions = {
+    baseUrl?: string;
+    fetch?: FetchLike;
+} & ({
+    clientId: string;
+    clientSecret: string;
+    accessToken?: undefined;
+} | {
+    accessToken: string;
+    clientId?: undefined;
+    clientSecret?: undefined;
+});
+/** Who a call is for. A company names the shopper by its own id or by Agentcard's user id. Under a shopper's own token, leave both out. */
+export interface Shopper {
+    externalUserId?: string;
+    userId?: string;
+}
+/** A delivery address the company already holds for the shopper; the cart is built for it and the shopper is asked for none of it. */
+export interface BuyDeliveryAddress {
+    street: string;
+    city: string;
+    state: string;
+    zip: string;
+    address2?: string;
+    phone?: string;
+    name?: string;
+    country?: string;
+    can_leave_at_door?: boolean;
+}
+/** One `POST /buy`, as sent. */
+export interface BuyRequest {
+    ask?: string;
+    /** A cart hash from an earlier answer, or true for the cart Agentcard last answered with. */
+    confirm?: string | true;
+    /** Continue the shopper's newest open conversation instead of starting one. */
+    resume?: true;
+    /** Drop the cart on the table and start a new order. */
+    new_order?: true;
+    payment_source?: 'vault';
+    delivery_address?: BuyDeliveryAddress;
+    external_user_id?: string;
+    user_id?: string;
+}
+export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
+export interface BuyStore {
+    id: string;
+    name?: string;
+}
+export interface BuyCartLine {
+    name: string;
+    qty: number;
+    priceCents?: number;
+    product_id: string | null;
+    /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
+    url: string | null;
+}
+/**
+ * A cart as Agentcard answers it. `totalCents` is the all-in figure the shopper sees; `hash` is what a confirm names.
+ * Every amount is in the minor unit of `currency`, the store's ISO 4217 code.
+ */
+export interface BuyCart {
+    merchant: string;
+    merchant_name: string;
+    store: BuyStore | null;
+    items: BuyCartLine[];
+    serviceFeesCents: number;
+    tipCents: number;
+    totalCents: number;
+    /** The ISO 4217 code the store prices the cart in, or null when Agentcard sent none. */
+    currency: string | null;
+    approvedCeilingCents: number | null;
+    hash: string;
+}
+/** A product a search found. `priceCents` is in the minor unit of `currency`, the store's ISO 4217 code. */
+export interface BuyCatalogItem {
+    id: string;
+    name: string | null;
+    priceCents: number | null;
+    /** The ISO 4217 code the store prices the product in, or null when Agentcard sent none. */
+    currency: string | null;
+    image_url: string | null;
+    store: BuyStore | null;
+    /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
+    url: string | null;
+}
+/** The products the last search found. */
+export interface BuyCatalog {
+    merchant: string;
+    merchant_name: string;
+    items: BuyCatalogItem[];
+}
+export interface BuyPaymentSource {
+    source: string;
+    brand: string | null;
+    last4: string | null;
+}
+/** One turn's answer, every field read for its type; a field an older API does not send reads as null. */
+export interface BuyTurn {
+    conversation_id: string;
+    /** A status Agentcard adds later reads as `needs_input`. */
+    status: BuyStatus;
+    reply: string;
+    messages: string[];
+    cart: BuyCart | null;
+    carts: BuyCart[];
+    catalog: BuyCatalog | null;
+    order_id: string | null;
+    payment_source: BuyPaymentSource | null;
+    decline_code: string | null;
+    approval_url: string | null;
+    charge_status: string | null;
+    error_code: string | null;
+    authorization_id: string | null;
+    merchant_total_cents: number | null;
+    merchant_currency: string | null;
+    add_card_url: string | null;
+    add_card_expires_at: string | null;
+    placement_announced: boolean | null;
+    approval_expires_at: string | null;
+    approval_in_progress: boolean | null;
+    /** The page where the shopper signs in to a store's own account before Agentcard can buy there. */
+    store_login_url: string | null;
+    store_login_expires_at: string | null;
+    /** The store that page signs in to. */
+    store_login_merchant_name: string | null;
+    /** The answer as Agentcard sent it. */
+    raw: Record<string, unknown>;
+}
+export interface BuyOrder {
+    order_id: string | null;
+    merchant: string;
+    merchant_name: string;
+    status: string;
+    total_cents: number;
+    placed_at: string | null;
+}
+export interface BuyLastCheckout {
+    at: string;
+    merchant: string;
+    merchant_name: string;
+    status: string;
+    code: string | null;
+    message: string | null;
+    order_id: string | null;
+    decline_code: string | null;
+    approval_url: string | null;
+    approval_expires_at: string | null;
+    placement_announced: boolean | null;
+    approval_in_progress: boolean | null;
+    /** The add-card link a checkout that found no card made, and when it stops working. */
+    add_card_url: string | null;
+    add_card_expires_at: string | null;
+    total_cents: number | null;
+}
+/** Where one conversation stands: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
+export interface BuyConversation {
+    conversation_id: string;
+    status: 'open' | 'closed';
+    turn_in_progress: boolean;
+    last_checkout: BuyLastCheckout | null;
+    orders: BuyOrder[];
+    carts: BuyCart[];
+    raw: Record<string, unknown>;
+}
+/** A Vault link: the page where a shopper connects and adds a card. */
+export interface VaultLink {
+    id: string;
+    url: string;
+    /** When the link stops working, as an ISO 8601 timestamp. */
+    expiresAt: string | null;
+    /** True when Agentcard returned a link it had already opened for this shopper. */
+    reused: boolean;
+}
+/**
+ * A refusal, or a failure to reach Agentcard. `code` is the API's own
+ * (`user_not_connected`, `external_user_id_ambiguous`, `turn_in_progress`,
+ * `user_id_mismatch`), one read from the shape of the answer
+ * (`cart_changed`, `nothing_to_confirm`, `conversation_closed`,
+ * `conversation_not_found`), or the client's (`unreachable`, `timeout`,
+ * `oauth_failed`, `unauthorized`, `http_<status>`). `status` is 0 when
+ * Agentcard never answered.
+ */
+export declare class AgentcardApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** The error body as Agentcard sent it. */
+    readonly body: Record<string, unknown>;
+    readonly conversationId: string | null;
+    /** The carts as they stand, when the refusal names them: a changed cart's fresh hash is here. */
+    readonly carts: BuyCart[];
+    constructor(status: number, code: string, message: string, body?: Record<string, unknown>, cause?: unknown);
+}
+/** A turn as Agentcard answers it. */
+export declare function turnOf(body: Record<string, unknown>): BuyTurn;
+/** The client every shopper's buy tool shares. Build one per set of credentials and keep it. */
+export declare class AgentcardClient {
+    readonly baseUrl: string;
+    private readonly fetchFn;
+    private readonly credentials;
+    private readonly shopperToken;
+    private token;
+    private inflight;
+    private learnedSandbox;
+    constructor(options: AgentcardClientOptions);
+    /** True when the client buys for many shoppers with a company's credentials; false under one shopper's own token. */
+    get company(): boolean;
+    /** True for a sandbox client, as the token exchange said; null until the first exchange, and under a shopper's token. */
+    get sandbox(): boolean | null;
+    /** The access token the client sends: the shopper's own, or the company's, exchanged once and renewed a minute before it expires. */
+    bearer(): Promise<string>;
+    /**
+     * One purchase turn, sent once with a 130-second wait. A turn is a model run
+     * against live stores, so a lost answer is never sent again: read the
+     * conversation instead. Only a 401 is sent again, once, with a fresh token,
+     * because Agentcard refused it before anything ran.
+     */
+    buy(body: BuyRequest): Promise<BuyTurn>;
+    /** One read of a conversation: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
+    conversation(conversationId: string, who?: Shopper): Promise<BuyConversation>;
+    /**
+     * The Vault link a shopper opens to connect to your company and add a card.
+     * Agentcard returns the link it already opened for this shopper while that
+     * link has time left, so a shopper who asks twice gets one link. Sent once.
+     */
+    mintVaultLink(input: {
+        externalUserId: string;
+    }): Promise<VaultLink>;
+    /** A company names the shopper exactly once; a shopper's own token already names them. */
+    private checkShopper;
+    private call;
+    private send;
+    /** After a 401: the token another call already renewed, or one new exchange, however many calls were refused at once. */
+    private renewAfter;
+    private exchange;
+}

package/dist/client.js

@@ -0,0 +1,412 @@
+/**
+ * The client the buy tool calls Agentcard with. A company builds one from its
+ * client credentials, and every shopper's tool shares the one access token it
+ * exchanges them for; or a tool runs on one shopper's own access token. The
+ * global fetch is the only transport, so the package keeps no dependencies.
+ *
+ * The answer fields and the error codes follow the buy module of
+ * @agent-cards/sdk (packages/checkout/src/buy.ts: turnOf, buyError), and the
+ * token cache follows its client (packages/checkout/src/client.ts accessToken).
+ */
+import { isRecord } from './verify.js';
+export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
+/** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
+export const BUY_TURN_TIMEOUT_MS = 130_000;
+/** The wait for every other call. */
+const CALL_TIMEOUT_MS = 30_000;
+/** A token is renewed this long before it expires, so it never expires mid-call. */
+const RENEW_EARLY_MS = 60_000;
+/**
+ * A refusal, or a failure to reach Agentcard. `code` is the API's own
+ * (`user_not_connected`, `external_user_id_ambiguous`, `turn_in_progress`,
+ * `user_id_mismatch`), one read from the shape of the answer
+ * (`cart_changed`, `nothing_to_confirm`, `conversation_closed`,
+ * `conversation_not_found`), or the client's (`unreachable`, `timeout`,
+ * `oauth_failed`, `unauthorized`, `http_<status>`). `status` is 0 when
+ * Agentcard never answered.
+ */
+export class AgentcardApiError extends Error {
+    status;
+    code;
+    /** The error body as Agentcard sent it. */
+    body;
+    conversationId;
+    /** The carts as they stand, when the refusal names them: a changed cart's fresh hash is here. */
+    carts;
+    constructor(status, code, message, body = {}, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'AgentcardApiError';
+        this.status = status;
+        this.code = code;
+        this.body = body;
+        this.conversationId = str(body.conversation_id);
+        this.carts = cartsOf(body.carts);
+    }
+}
+const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const bool = (v) => (typeof v === 'boolean' ? v : null);
+/**
+ * A product page's address: an absolute http or https URL, serialized the way
+ * every browser reads it, or null. A value that is no web page, such as a
+ * `javascript:` address, never reaches your code as a store's page, and
+ * neither does one with a user name before its host, which reads as one store
+ * and opens another.
+ */
+function pageUrl(v) {
+    const text = str(v);
+    if (!text)
+        return null;
+    try {
+        const url = new URL(text);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return null;
+        return url.username === '' && url.password === '' ? url.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+function storeOf(v) {
+    if (!isRecord(v) || !str(v.id))
+        return null;
+    return { id: v.id, ...(str(v.name) ? { name: v.name } : {}) };
+}
+function cartOf(v) {
+    if (!isRecord(v) || !str(v.hash) || !str(v.merchant))
+        return null;
+    return {
+        merchant: v.merchant,
+        merchant_name: str(v.merchant_name) ?? v.merchant,
+        store: storeOf(v.store),
+        items: Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => ({
+            name: str(i.name) ?? '',
+            qty: num(i.qty) ?? 1,
+            ...(num(i.priceCents) !== null ? { priceCents: i.priceCents } : {}),
+            product_id: str(i.product_id),
+            url: pageUrl(i.url),
+        })) : [],
+        serviceFeesCents: num(v.serviceFeesCents) ?? 0,
+        tipCents: num(v.tipCents) ?? 0,
+        totalCents: num(v.totalCents) ?? 0,
+        currency: str(v.currency),
+        approvedCeilingCents: num(v.approvedCeilingCents),
+        hash: v.hash,
+    };
+}
+function cartsOf(v) {
+    return Array.isArray(v) ? v.map(cartOf).filter((c) => c !== null) : [];
+}
+function catalogOf(v) {
+    if (!isRecord(v))
+        return null;
+    const items = Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => ({
+        id: str(i.id) ?? '',
+        name: str(i.name),
+        priceCents: num(i.priceCents),
+        currency: str(i.currency),
+        image_url: str(i.image_url),
+        store: storeOf(i.store),
+        url: pageUrl(i.url),
+    })) : [];
+    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items };
+}
+function paymentSourceOf(v) {
+    return isRecord(v) && str(v.source) ? { source: v.source, brand: str(v.brand), last4: str(v.last4) } : null;
+}
+const STATUSES = new Set(['needs_input', 'needs_approval', 'order_placed', 'partially_placed', 'declined']);
+/** A turn as Agentcard answers it. */
+export function turnOf(body) {
+    return {
+        conversation_id: str(body.conversation_id) ?? '',
+        status: typeof body.status === 'string' && STATUSES.has(body.status) ? body.status : 'needs_input',
+        reply: typeof body.reply === 'string' ? body.reply : '',
+        messages: Array.isArray(body.messages) ? body.messages.filter((m) => typeof m === 'string') : [],
+        cart: cartOf(body.cart),
+        carts: cartsOf(body.carts),
+        catalog: catalogOf(body.catalog),
+        order_id: str(body.order_id),
+        payment_source: paymentSourceOf(body.payment_source),
+        decline_code: str(body.decline_code),
+        approval_url: str(body.approval_url),
+        charge_status: str(body.charge_status),
+        error_code: str(body.error_code),
+        authorization_id: str(body.authorization_id),
+        merchant_total_cents: num(body.merchant_total_cents),
+        merchant_currency: str(body.merchant_currency),
+        add_card_url: str(body.add_card_url),
+        add_card_expires_at: str(body.add_card_expires_at),
+        placement_announced: bool(body.placement_announced),
+        approval_expires_at: str(body.approval_expires_at),
+        approval_in_progress: bool(body.approval_in_progress),
+        store_login_url: str(body.store_login_url),
+        store_login_expires_at: str(body.store_login_expires_at),
+        store_login_merchant_name: str(body.store_login_merchant_name),
+        raw: body,
+    };
+}
+function conversationOf(body) {
+    const last = isRecord(body.last_checkout) ? body.last_checkout : null;
+    return {
+        conversation_id: str(body.conversation_id) ?? '',
+        status: body.status === 'closed' ? 'closed' : 'open',
+        turn_in_progress: body.turn_in_progress === true,
+        last_checkout: last ? {
+            at: str(last.at) ?? '',
+            merchant: str(last.merchant) ?? '',
+            merchant_name: str(last.merchant_name) ?? str(last.merchant) ?? '',
+            status: str(last.status) ?? '',
+            code: str(last.code),
+            message: str(last.message),
+            order_id: str(last.order_id),
+            decline_code: str(last.decline_code),
+            approval_url: str(last.approval_url),
+            approval_expires_at: str(last.approval_expires_at),
+            placement_announced: bool(last.placement_announced),
+            approval_in_progress: bool(last.approval_in_progress),
+            add_card_url: str(last.add_card_url),
+            add_card_expires_at: str(last.add_card_expires_at),
+            total_cents: num(last.total_cents),
+        } : null,
+        orders: Array.isArray(body.orders) ? body.orders.filter(isRecord).map((o) => ({
+            order_id: str(o.order_id),
+            merchant: str(o.merchant) ?? '',
+            merchant_name: str(o.merchant_name) ?? str(o.merchant) ?? '',
+            status: str(o.status) ?? '',
+            total_cents: num(o.total_cents) ?? 0,
+            placed_at: str(o.placed_at),
+        })) : [],
+        carts: cartsOf(body.carts),
+        raw: body,
+    };
+}
+/** An error code as the API spells one: lower-case words joined by underscores. */
+const CODE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
+/**
+ * The refusal as the client reports it. Most refusals name their code; the
+ * ones the API names in prose only (a changed cart, nothing to confirm, a
+ * closed conversation) and a conversation not found get a code from the shape
+ * of the answer, so a caller branches on `code` and never on the message.
+ */
+function errorOf(status, body) {
+    let code;
+    let message;
+    if (isRecord(body.error)) {
+        code = str(body.error.code);
+        message = str(body.error.message);
+    }
+    else {
+        const named = str(body.error);
+        code = str(body.code) ?? (named && CODE.test(named) ? named : null);
+        message = str(body.message) ?? (named && named !== code ? named : null) ?? str(body.error_description);
+    }
+    if (!code) {
+        const text = message ?? '';
+        if (status === 404)
+            code = 'conversation_not_found';
+        else if (status === 409 && Array.isArray(body.carts))
+            code = 'cart_changed';
+        else if (status === 409 && /nothing to confirm/i.test(text))
+            code = 'nothing_to_confirm';
+        else if (status === 409 && /closed/i.test(text))
+            code = 'conversation_closed';
+        else if (status === 401)
+            code = 'unauthorized';
+        else
+            code = `http_${status}`;
+    }
+    return new AgentcardApiError(status, code, message ?? `Agentcard answered ${status} (${code}).`, body);
+}
+function failureOf(error, timeoutMs) {
+    const name = typeof error === 'object' && error !== null ? error.name : undefined;
+    if (name === 'TimeoutError' || name === 'AbortError') {
+        return new AgentcardApiError(0, 'timeout', `Agentcard did not answer within ${Math.round(timeoutMs / 1000)} seconds.`, {}, error);
+    }
+    return new AgentcardApiError(0, 'unreachable', 'Agentcard could not be reached.', {}, error);
+}
+/** The answer's JSON object, or null when the text is not JSON or not an object. */
+function parseJson(text) {
+    try {
+        const value = JSON.parse(text);
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The client every shopper's buy tool shares. Build one per set of credentials and keep it. */
+export class AgentcardClient {
+    baseUrl;
+    fetchFn;
+    credentials;
+    shopperToken;
+    token = null;
+    inflight = null;
+    learnedSandbox = null;
+    constructor(options) {
+        const o = (options ?? {});
+        const hasCredentials = o.clientId !== undefined || o.clientSecret !== undefined;
+        if (hasCredentials === (o.accessToken !== undefined)) {
+            throw new TypeError('Pass your company client credentials (clientId and clientSecret), or one shopper\'s accessToken, and not both.');
+        }
+        if (hasCredentials && (!str(o.clientId) || !str(o.clientSecret))) {
+            throw new TypeError('Pass clientId and clientSecret: the client credentials of your Agentcard app.');
+        }
+        if (!hasCredentials && !str(o.accessToken))
+            throw new TypeError('Pass accessToken: the shopper\'s own Agentcard access token.');
+        const fetchFn = o.fetch ?? globalThis.fetch;
+        if (typeof fetchFn !== 'function')
+            throw new TypeError('Pass fetch: this runtime has no global fetch. Node 18 and later have one.');
+        this.fetchFn = fetchFn;
+        this.baseUrl = (str(o.baseUrl) ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.credentials = hasCredentials ? { clientId: o.clientId, clientSecret: o.clientSecret } : null;
+        this.shopperToken = hasCredentials ? null : o.accessToken;
+    }
+    /** True when the client buys for many shoppers with a company's credentials; false under one shopper's own token. */
+    get company() {
+        return this.credentials !== null;
+    }
+    /** True for a sandbox client, as the token exchange said; null until the first exchange, and under a shopper's token. */
+    get sandbox() {
+        return this.learnedSandbox;
+    }
+    /** The access token the client sends: the shopper's own, or the company's, exchanged once and renewed a minute before it expires. */
+    async bearer() {
+        if (this.shopperToken !== null)
+            return this.shopperToken;
+        if (this.token && Date.now() < this.token.expiresAt)
+            return this.token.value;
+        if (!this.inflight)
+            this.inflight = this.exchange().finally(() => { this.inflight = null; });
+        return this.inflight;
+    }
+    /**
+     * One purchase turn, sent once with a 130-second wait. A turn is a model run
+     * against live stores, so a lost answer is never sent again: read the
+     * conversation instead. Only a 401 is sent again, once, with a fresh token,
+     * because Agentcard refused it before anything ran.
+     */
+    async buy(body) {
+        if (!isRecord(body))
+            throw new TypeError('Pass the purchase request as an object, such as { ask: "two AA battery packs" }.');
+        this.checkShopper({ externalUserId: body.external_user_id, userId: body.user_id });
+        return turnOf(await this.call('POST', '/buy', body, BUY_TURN_TIMEOUT_MS));
+    }
+    /** One read of a conversation: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
+    async conversation(conversationId, who = {}) {
+        if (!str(conversationId))
+            throw new TypeError('Pass the conversation_id a purchase answer named.');
+        this.checkShopper(who);
+        const query = who.externalUserId ? `?external_user_id=${encodeURIComponent(who.externalUserId)}`
+            : who.userId ? `?user_id=${encodeURIComponent(who.userId)}` : '';
+        return conversationOf(await this.call('GET', `/buy/conversations/${encodeURIComponent(conversationId)}${query}`, undefined, CALL_TIMEOUT_MS));
+    }
+    /**
+     * The Vault link a shopper opens to connect to your company and add a card.
+     * Agentcard returns the link it already opened for this shopper while that
+     * link has time left, so a shopper who asks twice gets one link. Sent once.
+     */
+    async mintVaultLink(input) {
+        if (!this.credentials)
+            throw new TypeError('A Vault link is made with your company credentials: build the client with clientId and clientSecret.');
+        const externalUserId = input?.externalUserId;
+        if (!str(externalUserId))
+            throw new TypeError('Pass externalUserId: your own id for the shopper.');
+        const answer = await this.call('POST', '/api/v2/vault_sessions', { external_user_id: externalUserId, reuse: true }, CALL_TIMEOUT_MS);
+        const url = str(answer.url);
+        if (!url)
+            throw new AgentcardApiError(200, 'invalid_answer', 'Agentcard answered the Vault link request without a link.', answer);
+        return { id: str(answer.id) ?? '', url, expiresAt: str(answer.expires_at), reused: answer.reused === true };
+    }
+    /** A company names the shopper exactly once; a shopper's own token already names them. */
+    checkShopper(who) {
+        const named = [who.externalUserId, who.userId].filter((v) => v !== undefined);
+        if (this.shopperToken !== null) {
+            if (named.length > 0)
+                throw new TypeError('A shopper\'s own access token already names the shopper. Leave externalUserId and userId out.');
+            return;
+        }
+        if (named.length !== 1 || !str(named[0])) {
+            throw new TypeError('Name the shopper once: externalUserId, your own id for them, or userId, the Agentcard user id.');
+        }
+    }
+    async call(method, path, body, timeoutMs) {
+        let token = await this.bearer();
+        for (let attempt = 0;; attempt++) {
+            const answer = await this.send(method, path, token, body, timeoutMs);
+            if (answer.status === 401 && attempt === 0 && this.credentials) {
+                token = await this.renewAfter(token);
+                continue;
+            }
+            if (answer.ok) {
+                // An answer the client cannot read is not an empty purchase. It is refused, and never sent again.
+                if (!answer.readable) {
+                    throw new AgentcardApiError(answer.status, 'invalid_answer', `Agentcard answered ${answer.status} with a body that is not a JSON object.`);
+                }
+                return answer.body;
+            }
+            if (answer.status === 401 && !this.credentials) {
+                throw new AgentcardApiError(401, 'unauthorized', 'Agentcard refused the shopper\'s access token. Sign the shopper in again.', answer.body);
+            }
+            throw errorOf(answer.status, answer.body);
+        }
+    }
+    async send(method, path, token, body, timeoutMs) {
+        try {
+            const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    accept: 'application/json',
+                    ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+                },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const parsed = parseJson(await res.text());
+            return { status: res.status, ok: res.ok, readable: parsed !== null, body: parsed ?? {} };
+        }
+        catch (error) {
+            throw failureOf(error, timeoutMs);
+        }
+    }
+    /** After a 401: the token another call already renewed, or one new exchange, however many calls were refused at once. */
+    async renewAfter(refused) {
+        if (this.inflight)
+            return this.inflight;
+        if (this.token && this.token.value !== refused && Date.now() < this.token.expiresAt)
+            return this.token.value;
+        this.token = null;
+        return this.bearer();
+    }
+    async exchange() {
+        const { clientId, clientSecret } = this.credentials;
+        const form = new URLSearchParams({ grant_type: 'client_credentials', client_id: clientId, client_secret: clientSecret });
+        let status;
+        let body;
+        try {
+            const res = await this.fetchFn(`${this.baseUrl}/api/v2/oauth/token`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+                body: form.toString(),
+                signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+            });
+            status = res.status;
+            body = parseJson(await res.text()) ?? {};
+            if (!res.ok || !str(body.access_token)) {
+                const reason = str(body.error);
+                throw new AgentcardApiError(status, 'oauth_failed', `Agentcard refused the client credentials (${status}${reason ? `, ${reason}` : ''}). Check the clientId and clientSecret you passed.`, body);
+            }
+        }
+        catch (error) {
+            throw error instanceof AgentcardApiError ? error : failureOf(error, CALL_TIMEOUT_MS);
+        }
+        if (body.sandbox === true || body.livemode === false)
+            this.learnedSandbox = true;
+        else if (body.sandbox === false || body.livemode === true)
+            this.learnedSandbox = false;
+        const ttlMs = Math.max(60_000, (num(body.expires_in) ?? 3600) * 1000 - RENEW_EARLY_MS);
+        this.token = { value: body.access_token, expiresAt: Date.now() + ttlMs };
+        return this.token.value;
+    }
+}