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

package/dist/client.js

@@ -0,0 +1,431 @@
+/**
+ * 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;
+const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'add_card', 'confirm', 'verification_code', 'approve']);
+/**
+ * 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 flightOf(value) {
+    if (!isRecord(value) || !Array.isArray(value.legs))
+        return undefined;
+    return {
+        ...(Object.hasOwn(value, 'fareCabinClass') ? { fareCabinClass: str(value.fareCabinClass) } : {}),
+        legs: value.legs.map(value => {
+            const leg = isRecord(value) ? value : {};
+            return { origin: str(leg.origin), destination: str(leg.destination),
+                departureAt: str(leg.departureAt), arrivalAt: str(leg.arrivalAt),
+                cabinClasses: Array.isArray(leg.cabinClasses) ? leg.cabinClasses.map(str) : [] };
+        }),
+    };
+}
+function catalogOf(v) {
+    if (!isRecord(v))
+        return null;
+    const items = Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => {
+        const flight = flightOf(i.flight);
+        return {
+            id: str(i.id) ?? '',
+            name: str(i.name),
+            priceCents: num(i.priceCents),
+            currency: str(i.currency),
+            image_url: str(i.image_url),
+            ...(flight ? { flight } : {}),
+            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),
+        next_action: typeof body.next_action === 'string' && NEXT_ACTIONS.has(body.next_action) ? body.next_action : null,
+        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;
+    }
+}

package/dist/definition.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The buy tool as a model sees it: one name, one description, and a strict
+ * JSON Schema with three required fields. The delivery address and the
+ * shopper's id are construction options, never model inputs, so a model can
+ * neither change where an order goes nor buy for someone else.
+ */
+export declare const BUY_TOOL_NAME = "buy";
+/** What the model reads before it calls the tool. Every sentence is a rule the model follows. */
+export declare const BUY_TOOL_DESCRIPTION: string;
+/** What the model sends: all three fields, every time. */
+export interface BuyToolInput {
+    ask: string;
+    confirm: boolean;
+    new_order: boolean;
+}
+/** A type, not an interface, so it fits the SDKs' own input schema types, which take any key. */
+export type BuyToolInputSchema = {
+    type: 'object';
+    properties: {
+        ask: {
+            type: 'string';
+            description: string;
+        };
+        confirm: {
+            type: 'boolean';
+            description: string;
+        };
+        new_order: {
+            type: 'boolean';
+            description: string;
+        };
+    };
+    required: Array<keyof BuyToolInput>;
+    additionalProperties: false;
+};
+export interface BuyToolDefinition {
+    name: string;
+    description: string;
+    input_schema: BuyToolInputSchema;
+}
+/** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
+export declare function buyToolDefinition(): BuyToolDefinition;
+/**
+ * The model's input, checked against the schema: an object, or its JSON text,
+ * with `ask` a string and `confirm` and `new_order` booleans, and nothing
+ * else. Throws a TypeError whose message tells the model what to send.
+ */
+export declare function parseBuyToolInput(value: unknown): BuyToolInput;
+/** The buy tool in OpenAI's function-calling format, which the OpenAI SDK, OpenRouter's chat API and most other model APIs take. */
+export interface OpenAIBuyTool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: BuyToolInputSchema;
+        strict: true;
+    };
+}
+/** A fresh copy of the tool in OpenAI's function-calling format: plain JSON, so an SDK that sends it as is sends exactly this. */
+export declare function openAIBuyTool(): OpenAIBuyTool;
+/** What a Standard Schema check returns: the model's input, checked, or why it does not fit. */
+export type BuyToolInputCheck = {
+    readonly value: BuyToolInput;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+    }>;
+};
+/**
+ * The input schema as a Standard Schema that also hands over its JSON Schema,
+ * the form the Vercel AI SDK reads from a tool's `inputSchema`. The shape is
+ * the published Standard Schema one, so the package names no schema library.
+ */
+export interface BuyToolStandardSchema {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => BuyToolInputCheck;
+        readonly jsonSchema: {
+            readonly input: (options: {
+                readonly target: string;
+            }) => BuyToolInputSchema;
+            readonly output: (options: {
+                readonly target: string;
+            }) => BuyToolInputSchema;
+        };
+        /** Read by type inference only, never set. */
+        readonly types?: {
+            readonly input: BuyToolInput;
+            readonly output: BuyToolInput;
+        } | undefined;
+    };
+}
+/**
+ * The Standard Schema of the tool's input. `validate` checks the model's
+ * input as `parseBuyToolInput` does, and reports a refusal in the words
+ * `refusal` gives it, so the model reads what to send.
+ */
+export declare function buyToolStandardSchema(refusal: (error: unknown) => string): BuyToolStandardSchema;

package/dist/definition.js

@@ -0,0 +1,104 @@
+/**
+ * The buy tool as a model sees it: one name, one description, and a strict
+ * JSON Schema with three required fields. The delivery address and the
+ * shopper's id are construction options, never model inputs, so a model can
+ * neither change where an order goes nor buy for someone else.
+ */
+export const BUY_TOOL_NAME = 'buy';
+/** What the model reads before it calls the tool. Every sentence is a rule the model follows. */
+export const BUY_TOOL_DESCRIPTION = [
+    'Buy what this shopper asks for at real stores.',
+    "Put the shopper's own words in `ask`.",
+    'Tell the shopper what `reply` says, in your own voice.',
+    'Show the shopper the cart before you confirm it.',
+    'Ask the shopper for exactly one thing per message: the step `next_action` names, even when `reply` lists more. Never mention a later step, and never ask for the next one until the shopper has done this one.',
+    'Set `confirm` to true only when the shopper just said yes to the cart in your last result, says they added the card for a cart that waits, says they approved, or asks for the approval link again.',
+    'Never write a link.',
+    'Each link reaches the shopper on its own.',
+    'When `link_sent` is true, tell the shopper a link is waiting for them.',
+    'Product links reach the shopper on their own, beside your reply: when `product_links_sent` is above zero and the shopper asks for links, tell them the links are there; never write or invent a URL.',
+    'A `placing` status means the order is going through, so never ask for another approval.',
+    'Tell the shopper they need not reply only when `shopper_need_not_reply` is true.',
+    'After `needs_card` with a cart, Agentcard keeps the cart, so set `confirm` to true once the shopper says they added the card.',
+    "After `needs_card` with no cart, call this tool again with the shopper's request once they say they added a card.",
+    'Set `new_order` to true only when the shopper drops the cart.',
+].join(' ');
+/** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
+export function buyToolDefinition() {
+    return {
+        name: BUY_TOOL_NAME,
+        description: BUY_TOOL_DESCRIPTION,
+        input_schema: {
+            type: 'object',
+            properties: {
+                ask: { type: 'string', description: 'What the shopper said, in their own words.' },
+                confirm: {
+                    type: 'boolean',
+                    description: 'True only when the shopper just said yes to the cart in your last result, says they added the card for a cart that waits, says they approved, or asks for the approval link again. False otherwise.',
+                },
+                new_order: { type: 'boolean', description: 'True only when the shopper drops the cart to start a new order. False otherwise.' },
+            },
+            required: ['ask', 'confirm', 'new_order'],
+            additionalProperties: false,
+        },
+    };
+}
+const FIELDS = new Set(['ask', 'confirm', 'new_order']);
+/**
+ * The model's input, checked against the schema: an object, or its JSON text,
+ * with `ask` a string and `confirm` and `new_order` booleans, and nothing
+ * else. Throws a TypeError whose message tells the model what to send.
+ */
+export function parseBuyToolInput(value) {
+    let input = value;
+    if (typeof input === 'string') {
+        try {
+            input = JSON.parse(input);
+        }
+        catch {
+            throw new TypeError('The buy tool takes a JSON object with ask, confirm and new_order.');
+        }
+    }
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new TypeError('The buy tool takes an object with ask, confirm and new_order.');
+    }
+    const fields = input;
+    const extra = Object.keys(fields).find((key) => !FIELDS.has(key));
+    if (extra !== undefined)
+        throw new TypeError(`The buy tool takes only ask, confirm and new_order, and ${extra} is not one of them.`);
+    if (typeof fields.ask !== 'string')
+        throw new TypeError("Set ask to the shopper's words, as a string.");
+    if (typeof fields.confirm !== 'boolean')
+        throw new TypeError('Set confirm to true or false.');
+    if (typeof fields.new_order !== 'boolean')
+        throw new TypeError('Set new_order to true or false.');
+    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order };
+}
+/** A fresh copy of the tool in OpenAI's function-calling format: plain JSON, so an SDK that sends it as is sends exactly this. */
+export function openAIBuyTool() {
+    const { name, description, input_schema } = buyToolDefinition();
+    return { type: 'function', function: { name, description, parameters: input_schema, strict: true } };
+}
+/**
+ * The Standard Schema of the tool's input. `validate` checks the model's
+ * input as `parseBuyToolInput` does, and reports a refusal in the words
+ * `refusal` gives it, so the model reads what to send.
+ */
+export function buyToolStandardSchema(refusal) {
+    const schema = () => buyToolDefinition().input_schema;
+    return {
+        '~standard': {
+            version: 1,
+            vendor: 'agentcard',
+            validate: (value) => {
+                try {
+                    return { value: parseBuyToolInput(value) };
+                }
+                catch (error) {
+                    return { issues: [{ message: refusal(error) }] };
+                }
+            },
+            jsonSchema: { input: schema, output: schema },
+        },
+    };
+}