@agent-cards/commerce-sdk 0.2.0 → 0.5.0

package/dist/definition.d.ts

@@ -1,17 +1,23 @@
 /**
  * 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
+ * JSON Schema with four required fields, `product_id` null unless the shopper
+ * picks a product they were shown. 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. */
+/**
+ * What the model sends: `ask`, `confirm` and `new_order` every time, and `product_id`, null unless the
+ * shopper picks a product from the last result. Your own code may leave `product_id` out.
+ */
 export interface BuyToolInput {
     ask: string;
     confirm: boolean;
     new_order: boolean;
+    /** The `product_id` of the product the shopper picked from the last result's `products`, or null. */
+    product_id?: string | null;
 }
 /** A type, not an interface, so it fits the SDKs' own input schema types, which take any key. */
 export type BuyToolInputSchema = {
@@ -29,6 +35,10 @@ export type BuyToolInputSchema = {
             type: 'boolean';
             description: string;
         };
+        product_id: {
+            type: ['string', 'null'];
+            description: string;
+        };
     };
     required: Array<keyof BuyToolInput>;
     additionalProperties: false;
@@ -42,8 +52,9 @@ export interface BuyToolDefinition {
 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.
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` a
+ * string, null or left out, 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. */

package/dist/definition.js

@@ -1,6 +1,7 @@
 /**
  * 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
+ * JSON Schema with four required fields, `product_id` null unless the shopper
+ * picks a product they were shown. 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.
  */
@@ -22,6 +23,8 @@ export const BUY_TOOL_DESCRIPTION = [
     '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.',
+    "When the shopper picks one of the `products` in your last result, by its name, its place in the list or a tap that names it, set `product_id` to that product's `product_id`, so Agentcard adds exactly that product; otherwise set it to null.",
+    'When `pick.in_cart` is false, the product the shopper picked is not in the cart: tell the shopper what `reply` says, and never ask them to confirm the cart.',
 ].join(' ');
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
 export function buyToolDefinition() {
@@ -37,17 +40,22 @@ export function buyToolDefinition() {
                     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.' },
+                product_id: {
+                    type: ['string', 'null'],
+                    description: "The `product_id` of the product the shopper picked from the `products` in your last result. Null when they picked none.",
+                },
             },
-            required: ['ask', 'confirm', 'new_order'],
+            required: ['ask', 'confirm', 'new_order', 'product_id'],
             additionalProperties: false,
         },
     };
 }
-const FIELDS = new Set(['ask', 'confirm', 'new_order']);
+const FIELDS = new Set(['ask', 'confirm', 'new_order', 'product_id']);
 /**
  * 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.
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` a
+ * string, null or left out, and nothing else. Throws a TypeError whose message
+ * tells the model what to send.
  */
 export function parseBuyToolInput(value) {
     let input = value;
@@ -65,14 +73,18 @@ export function parseBuyToolInput(value) {
     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.`);
+        throw new TypeError(`The buy tool takes only ask, confirm, new_order and product_id, 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 };
+    const productId = fields.product_id;
+    if (productId !== undefined && productId !== null && typeof productId !== 'string') {
+        throw new TypeError("Set product_id to the picked product's product_id, as a string, or to null.");
+    }
+    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order, product_id: typeof productId === 'string' && productId.trim() !== '' ? productId.trim() : null };
 }
 /** 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() {

package/dist/handler.d.ts

@@ -1,11 +1,13 @@
 /**
- * A Node or Express `(req, res)` handler for an Agentcard webhook endpoint. It
- * reads the raw bytes, checks the signature, hands the event to your callback,
- * and answers once the callback is done: 200 when it returns, 500 when it
- * throws, so Agentcard delivers the event again instead of losing it.
+ * Handlers for an Agentcard webhook endpoint, for a Node or Express `(req, res)`
+ * route and for a route that takes a web `Request`, such as a Next.js route
+ * handler. Each reads the raw bytes, checks the signature, hands the event to
+ * your callback, and answers once the callback is done: 200 when it returns,
+ * 500 when it throws, so Agentcard delivers the event again instead of losing it.
  */
 import { type AgentcardEvent, type VerifyOptions } from './verify.js';
 import { type PurchaseMessage } from './message.js';
+import { type ShopperMessage } from './shopper-message.js';
 /** The parts of a Node or Express request the handler reads. */
 export interface WebhookRequest {
     headers: Record<string, string | string[] | undefined>;
@@ -35,6 +37,23 @@ export interface PurchaseAgentWebhookOptions extends Pick<VerifyOptions, 'tolera
      */
     onError?: (error: unknown, event: AgentcardEvent | undefined) => void | Promise<void>;
 }
+/** The parts of a web `Request` the fetch handler reads. */
+export interface WebhookFetchRequest {
+    headers: {
+        get(name: string): string | null;
+    };
+    /** The body as a stream, read chunk by chunk so a body past the size cap is never held whole. */
+    body?: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel(reason?: unknown): Promise<void>;
+        };
+    } | null;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
 /**
  * A `(req, res)` handler for your Agentcard webhook endpoint. A delivery with a
  * missing, malformed, stale or wrong signature gets a 400 and reaches no
@@ -43,6 +62,40 @@ export interface PurchaseAgentWebhookOptions extends Pick<VerifyOptions, 'tolera
  * callback is done: 200 when it returns, and 500 when it throws, so Agentcard
  * delivers the event again. Agentcard waits 10 seconds for an answer, so keep
  * the callback short. Agentcard delivers at least once, and again after a 500,
- * so handle each `message.eventId` once.
+ * so handle each `message.eventId` once. `agentcardWebhook` does that for you.
  */
 export declare function purchaseAgentWebhook(secret: string, onMessage: (message: PurchaseMessage, event: AgentcardEvent) => void | Promise<void>, opts?: PurchaseAgentWebhookOptions): (req: WebhookRequest, res: WebhookResponse) => Promise<void>;
+export interface AgentcardWebhookOptions extends PurchaseAgentWebhookOptions {
+    /** The secret Agentcard returned once, when you created the endpoint. */
+    secret: string;
+    /**
+     * Receives each message for one of your shoppers, under your own id for them: post
+     * `message.text` into that shopper's chat, or hand `message.note` to your agent. Runs once per
+     * event, never for a stale message, and the delivery answers 500 when it throws, so Agentcard
+     * delivers the event again.
+     */
+    onMessage: (externalUserId: string, message: ShopperMessage, event: AgentcardEvent) => void | Promise<void>;
+    /**
+     * Receives every verified event that is no message for one of your shoppers: another event type,
+     * such as `vault.card_stored`, and a shopper message for a shopper you gave Agentcard no id for.
+     */
+    onEvent?: (event: AgentcardEvent) => void | Promise<void>;
+}
+/** The handler `agentcardWebhook` returns: a Node or Express `(req, res)` handler, with `fetch` for a web `Request`. */
+export interface AgentcardWebhookHandler {
+    (req: WebhookRequest, res: WebhookResponse): Promise<void>;
+    /** The same handler for a web `Request`, such as a Next.js route handler's: `export const POST = webhook.fetch`. */
+    fetch(request: WebhookFetchRequest): Promise<Response>;
+}
+/**
+ * One handler for every Agentcard event your shoppers should hear about. It checks each delivery's
+ * signature, skips an event this process already handled, reads the message the event carries for
+ * a shopper
+ * (`readShopperMessage`), drops a message whose link or window has closed (`isStale`), and calls
+ * `onMessage` with your own id for the shopper and the message, Agentcard's own text included.
+ * Every other verified event goes to `onEvent`. The answer waits for the callback: 200 when it
+ * returns, 500 when it throws, and an event whose callback threw runs again on the next delivery.
+ * The handled events live in this process's memory: with more than one server, deduplicate on
+ * `message.eventId` in your own storage too.
+ */
+export declare function agentcardWebhook(opts: AgentcardWebhookOptions): AgentcardWebhookHandler;

package/dist/handler.js

@@ -1,11 +1,13 @@
 /**
- * A Node or Express `(req, res)` handler for an Agentcard webhook endpoint. It
- * reads the raw bytes, checks the signature, hands the event to your callback,
- * and answers once the callback is done: 200 when it returns, 500 when it
- * throws, so Agentcard delivers the event again instead of losing it.
+ * Handlers for an Agentcard webhook endpoint, for a Node or Express `(req, res)`
+ * route and for a route that takes a web `Request`, such as a Next.js route
+ * handler. Each reads the raw bytes, checks the signature, hands the event to
+ * your callback, and answers once the callback is done: 200 when it returns,
+ * 500 when it throws, so Agentcard delivers the event again instead of losing it.
  */
 import { AgentcardSignatureError, InvalidEventBodyError, toleranceOf, verifyAgentcardWebhook, } from './verify.js';
 import { readPurchaseMessage } from './message.js';
+import { isStale, readShopperMessage } from './shopper-message.js';
 /** A signed Agentcard delivery is a few kilobytes; a body past this size did not come from Agentcard. */
 const MAX_BODY_BYTES = 1024 * 1024;
 const RAW_BODY_GONE = 'The webhook request reached the handler with its body already parsed and no raw bytes kept, so the signature cannot be checked. ' +
@@ -95,6 +97,132 @@ async function readRawBody(req) {
         return undefined;
     return readStream(req);
 }
+/** Hands an error to `onError`, or to `console.error`. A reporter that throws or rejects never takes the process down. */
+function reporter(onError) {
+    return (error, event) => {
+        try {
+            const reported = onError ? onError(error, event) : console.error('Agentcard webhook:', error);
+            // A reporter that rejects must not leave an unhandled rejection, which ends a plain Node server's process.
+            if (reported && typeof reported.then === 'function')
+                reported.then(undefined, () => { });
+        }
+        catch {
+            // A failing reporter must never take the process down with it.
+        }
+    };
+}
+function checkSecret(secret) {
+    if (typeof secret !== 'string' || secret === '') {
+        throw new TypeError('Pass the webhook endpoint secret Agentcard returned when you created the endpoint.');
+    }
+}
+/** Verifies one raw delivery and runs its callbacks. The answer waits for them, so a callback that fails gets the event delivered again. */
+async function answer(raw, signature, secret, verifyOpts, dispatch, report) {
+    let event;
+    try {
+        event = verifyAgentcardWebhook(raw, signature, secret, verifyOpts);
+    }
+    catch (error) {
+        if (error instanceof AgentcardSignatureError)
+            return { status: 400, body: { error: 'invalid_signature', reason: error.reason } };
+        if (error instanceof InvalidEventBodyError)
+            return { status: 400, body: { error: 'invalid_body' } };
+        report(error, undefined);
+        return { status: 500, body: { error: 'verification_failed' } };
+    }
+    if (await dispatch(event))
+        return { status: 200, body: { received: true } };
+    return { status: 500, body: { error: 'callback_failed' } };
+}
+/** The `(req, res)` handler around one delivery's answer. It never rejects: an unhandled rejection would end a plain Node server's process. */
+function nodeHandler(handleRaw, report) {
+    const handle = async (req, res) => {
+        let raw;
+        try {
+            raw = await readRawBody(req);
+        }
+        catch (error) {
+            if (error instanceof BodyTooLargeError)
+                return send(res, 413, { error: 'body_too_large' });
+            return send(res, 400, { error: 'unreadable_body' });
+        }
+        if (raw === undefined) {
+            report(new Error(RAW_BODY_GONE), undefined);
+            return send(res, 500, { error: 'raw_body_unavailable' });
+        }
+        const outcome = await handleRaw(raw, headerValue(req.headers['agentcard-signature']));
+        send(res, outcome.status, outcome.body);
+    };
+    return async (req, res) => {
+        try {
+            await handle(req, res);
+        }
+        catch (error) {
+            report(error, undefined);
+        }
+    };
+}
+/**
+ * The body of a web request, read chunk by chunk. Past the size cap it stops reading, cancels the
+ * stream and throws, so a caller with no signature cannot make the server hold a large body.
+ */
+async function readFetchBody(request) {
+    if (!request.body || typeof request.body.getReader !== 'function')
+        return new Uint8Array(await request.arrayBuffer());
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!value)
+            continue;
+        size += value.length;
+        if (size > MAX_BODY_BYTES) {
+            await reader.cancel().catch(() => { });
+            throw new BodyTooLargeError();
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/** A web `Response` with a JSON body, built from the runtime's own `Response`. */
+function webResponse(outcome) {
+    return new Response(JSON.stringify(outcome.body), { status: outcome.status, headers: { 'content-type': 'application/json' } });
+}
+/** The web `Request` handler around one delivery's answer. It never rejects. */
+function fetchHandler(handleRaw, report) {
+    return async (request) => {
+        try {
+            const declared = Number(request.headers.get('content-length'));
+            if (Number.isFinite(declared) && declared > MAX_BODY_BYTES)
+                return webResponse({ status: 413, body: { error: 'body_too_large' } });
+            let raw;
+            try {
+                raw = await readFetchBody(request);
+            }
+            catch (error) {
+                if (error instanceof BodyTooLargeError)
+                    return webResponse({ status: 413, body: { error: 'body_too_large' } });
+                return webResponse({ status: 400, body: { error: 'unreadable_body' } });
+            }
+            if (raw.length > MAX_BODY_BYTES)
+                return webResponse({ status: 413, body: { error: 'body_too_large' } });
+            return webResponse(await handleRaw(raw, request.headers.get('agentcard-signature') ?? undefined));
+        }
+        catch (error) {
+            report(error, undefined);
+            return webResponse({ status: 500, body: { error: 'handler_failed' } });
+        }
+    };
+}
 /**
  * A `(req, res)` handler for your Agentcard webhook endpoint. A delivery with a
  * missing, malformed, stale or wrong signature gets a 400 and reaches no
@@ -103,28 +231,15 @@ async function readRawBody(req) {
  * callback is done: 200 when it returns, and 500 when it throws, so Agentcard
  * delivers the event again. Agentcard waits 10 seconds for an answer, so keep
  * the callback short. Agentcard delivers at least once, and again after a 500,
- * so handle each `message.eventId` once.
+ * so handle each `message.eventId` once. `agentcardWebhook` does that for you.
  */
 export function purchaseAgentWebhook(secret, onMessage, opts = {}) {
-    if (typeof secret !== 'string' || secret === '') {
-        throw new TypeError('Pass the webhook endpoint secret Agentcard returned when you created the endpoint.');
-    }
+    checkSecret(secret);
     if (typeof onMessage !== 'function') {
         throw new TypeError('Pass onMessage, the function that receives each purchase message.');
     }
     const verifyOpts = { toleranceSeconds: toleranceOf(opts) };
-    const report = (error, event) => {
-        try {
-            const reported = opts.onError ? opts.onError(error, event) : console.error('Agentcard webhook:', error);
-            // A reporter that rejects must not leave an unhandled rejection, which ends a plain Node server's process.
-            if (reported && typeof reported.then === 'function')
-                reported.then(undefined, () => { });
-        }
-        catch {
-            // A failing reporter must never take the process down with it.
-        }
-    };
-    /** Runs the callback for one verified event. True when the delivery is done, false when the callback threw. */
+    const report = reporter(opts.onError);
     const dispatch = async (event) => {
         let message;
         try {
@@ -147,44 +262,90 @@ export function purchaseAgentWebhook(secret, onMessage, opts = {}) {
             return false;
         }
     };
-    const handle = async (req, res) => {
-        let raw;
+    return nodeHandler((raw, signature) => answer(raw, signature, secret, verifyOpts, dispatch, report), report);
+}
+/** How many handled event ids the handler remembers, the oldest forgotten first. */
+const HANDLED_EVENTS_KEPT = 10_000;
+/**
+ * One handler for every Agentcard event your shoppers should hear about. It checks each delivery's
+ * signature, skips an event this process already handled, reads the message the event carries for
+ * a shopper
+ * (`readShopperMessage`), drops a message whose link or window has closed (`isStale`), and calls
+ * `onMessage` with your own id for the shopper and the message, Agentcard's own text included.
+ * Every other verified event goes to `onEvent`. The answer waits for the callback: 200 when it
+ * returns, 500 when it throws, and an event whose callback threw runs again on the next delivery.
+ * The handled events live in this process's memory: with more than one server, deduplicate on
+ * `message.eventId` in your own storage too.
+ */
+export function agentcardWebhook(opts) {
+    if (opts === null || typeof opts !== 'object')
+        throw new TypeError('Pass { secret, onMessage }.');
+    checkSecret(opts.secret);
+    if (typeof opts.onMessage !== 'function') {
+        throw new TypeError('Pass onMessage, the function that receives each message for a shopper.');
+    }
+    const secret = opts.secret;
+    const verifyOpts = { toleranceSeconds: toleranceOf(opts) };
+    const report = reporter(opts.onError);
+    // The events this process finished, and the ones it is running. A redelivery of a finished event
+    // runs nothing, and one that lands while the first delivery still runs waits for its answer.
+    const finished = new Set();
+    const running = new Map();
+    const finish = (eventId) => {
+        finished.add(eventId);
+        if (finished.size > HANDLED_EVENTS_KEPT)
+            finished.delete(finished.values().next().value);
+    };
+    /** Runs the callback for one event. True when the delivery is done, false when the callback threw. */
+    const run = async (event) => {
+        let message;
         try {
-            raw = await readRawBody(req);
+            message = readShopperMessage(event);
         }
         catch (error) {
-            if (error instanceof BodyTooLargeError)
-                return send(res, 413, { error: 'body_too_large' });
-            return send(res, 400, { error: 'unreadable_body' });
+            // A message the package cannot read reads the same way on every delivery, so it is not sent again.
+            report(error, event);
+            finish(event.id);
+            return true;
         }
-        if (raw === undefined) {
-            report(new Error(RAW_BODY_GONE), undefined);
-            return send(res, 500, { error: 'raw_body_unavailable' });
+        // A message whose link or window closed before it arrived reaches no callback, whichever one it would reach.
+        if (message && isStale(message)) {
+            finish(event.id);
+            return true;
         }
-        let event;
         try {
-            event = verifyAgentcardWebhook(raw, headerValue(req.headers['agentcard-signature']), secret, verifyOpts);
+            if (message?.externalUserId) {
+                await opts.onMessage(message.externalUserId, message, event);
+            }
+            else if (opts.onEvent) {
+                await opts.onEvent(event);
+            }
         }
         catch (error) {
-            if (error instanceof AgentcardSignatureError)
-                return send(res, 400, { error: 'invalid_signature', reason: error.reason });
-            if (error instanceof InvalidEventBodyError)
-                return send(res, 400, { error: 'invalid_body' });
-            report(error, undefined);
-            return send(res, 500, { error: 'verification_failed' });
+            // Not marked finished, so the next delivery of the event runs the callback again.
+            report(error, event);
+            return false;
         }
-        // The answer waits for the callback, so a callback that fails gets the event delivered again.
-        if (await dispatch(event))
-            return send(res, 200, { received: true });
-        return send(res, 500, { error: 'callback_failed' });
+        finish(event.id);
+        return true;
     };
-    // The handler never rejects: an unhandled rejection would end a plain Node server's process.
-    return async (req, res) => {
+    const dispatch = async (event) => {
+        if (finished.has(event.id))
+            return true;
+        const inFlight = running.get(event.id);
+        if (inFlight)
+            return inFlight;
+        const attempt = run(event);
+        running.set(event.id, attempt);
         try {
-            await handle(req, res);
+            return await attempt;
         }
-        catch (error) {
-            report(error, undefined);
+        finally {
+            running.delete(event.id);
         }
     };
+    const handleRaw = (raw, signature) => answer(raw, signature, secret, verifyOpts, dispatch, report);
+    const handler = nodeHandler(handleRaw, report);
+    handler.fetch = fetchHandler(handleRaw, report);
+    return handler;
 }

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatureReason, type AgentcardEvent, type VerifyOptions, } from './verify.js';
 export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.js';
-export { purchaseAgentWebhook, type PurchaseAgentWebhookOptions, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, } from './client.js';
+export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
+export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, type MessageStream, type MessageStreamOptions, } from './messages.js';
 export { buyTool, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, } from './buy-tool.js';
+export { ackFor, type AckForOptions } from './ack.js';
 export { forModel, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';

package/dist/index.js

@@ -1,9 +1,11 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, } from './verify.js';
 export { readPurchaseMessage, } from './message.js';
-export { purchaseAgentWebhook, } from './handler.js';
+export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, } from './shopper-message.js';
+export { agentcardWebhook, purchaseAgentWebhook, } from './handler.js';
 export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, } from './messages.js';
 export { buyTool, } from './buy-tool.js';
+export { ackFor } from './ack.js';
 export { forModel, stripLinks, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';

package/dist/message.d.ts

@@ -9,13 +9,15 @@ import { type AgentcardEvent } from './verify.js';
  * - `order_placed`: the shopper approved, and Agentcard placed the order.
  * - `order_failed`: the order failed after the approval, and nothing more happens for that approval.
  * - `order_not_placed_yet`: the shopper approved, and the order is not placed yet.
+ * - `order_unconfirmed`: the store's reply to the order was lost, so the order may exist; Agentcard is confirming it.
  * - `approval_expiring`: the approval link expires soon; `text` carries the link.
  * - `approval_expired`: the approval expired before the shopper answered, and nothing was charged.
  * - `card_link_unfinished`: the shopper has not added a card from their card link; `text` carries the link again.
  * - `card_link_expired`: the card link expired before the shopper added a card.
  * - `cart_idle`: a cart sat without being sent for approval; `facts.nudgeNumber` counts the nudges.
+ * - `card_added`: the shopper saved a card from the card link your app sent, and can check out with it.
  */
-export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'approval_expiring' | 'approval_expired' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle';
+export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'approval_expiring' | 'approval_expired' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle' | 'card_added';
 /** The message's values one by one, for a company that writes its own copy. A fact that does not apply is absent. */
 export interface PurchaseFacts {
     merchantName?: string;

package/dist/model-view.d.ts

@@ -20,6 +20,8 @@ export interface BuyToolModelCart {
     total: string;
 }
 export interface BuyToolModelProduct {
+    /** What the model passes as `product_id` when the shopper picks this product: Agentcard's ref, never a link. Null when there is none. */
+    product_id: string | null;
     name: string;
     price: string | null;
     /** True when the shopper holds this product's store page, which `sendLink` delivered beside the reply. */
@@ -43,6 +45,11 @@ export interface BuyToolModelView {
     link_sent: boolean;
     /** How many store pages of the products above the shopper holds, 0 when none went out. */
     product_links_sent: number;
+    /** The product this call's `product_id` picked, and whether the cart now holds it; null when the call picked none. */
+    pick: {
+        product_id: string | null;
+        in_cart: boolean;
+    } | null;
 }
 /** The text with every link taken out: a Markdown link keeps its label, and a bare address goes entirely. */
 export declare function stripLinks(text: string): string;
@@ -58,9 +65,14 @@ export declare function money(minor: number | null | undefined, currency: string
  * never holds a product link the model cannot name.
  */
 export declare function shownProducts(products: readonly BuyToolProduct[] | null | undefined): BuyToolProduct[];
+/**
+ * The id the model passes back for a product: Agentcard's link-free ref, else the product's own id when
+ * it holds no link, else null. A retail product's id is its store page, and a link never reaches the model.
+ */
+export declare function pickId(product: Pick<BuyToolProduct, 'id' | 'ref'>): string | null;
 /**
  * The model's view of one answer: the status, Agentcard's reply, the newest
- * cart and every cart on the table, the products by name and price, and
+ * cart and every cart on the table, the products by id, name and price, and
  * whether the shopper has each link. A status this version does not know
  * reads as `needs_input`.
  */

package/dist/model-view.js

@@ -67,6 +67,15 @@ export function money(minor, currency) {
 export function shownProducts(products) {
     return (products ?? []).filter((product) => stripLinks(product.name) !== '').slice(0, MAX_PRODUCTS);
 }
+/**
+ * The id the model passes back for a product: Agentcard's link-free ref, else the product's own id when
+ * it holds no link, else null. A retail product's id is its store page, and a link never reaches the model.
+ */
+export function pickId(product) {
+    if (typeof product.ref === 'string' && product.ref !== '' && stripLinks(product.ref) === product.ref)
+        return product.ref;
+    return typeof product.id === 'string' && product.id !== '' && stripLinks(product.id) === product.id ? product.id : null;
+}
 function cartView(cart) {
     return {
         store: stripLinks(cart.store?.name ?? cart.merchant_name) || stripLinks(cart.merchant),
@@ -78,7 +87,7 @@ function cartView(cart) {
 }
 /**
  * The model's view of one answer: the status, Agentcard's reply, the newest
- * cart and every cart on the table, the products by name and price, and
+ * cart and every cart on the table, the products by id, name and price, and
  * whether the shopper has each link. A status this version does not know
  * reads as `needs_input`.
  */
@@ -92,12 +101,14 @@ export function forModel(result) {
         reply: stripLinks(result.reply),
         cart: result.cart ? cartView(result.cart) : null,
         carts: (result.carts ?? []).map(cartView),
-        products: products.map((product) => ({ name: stripLinks(product.name), price: money(product.priceCents, product.currency), link_sent: held(product) })),
+        products: products.map((product) => ({ product_id: pickId(product), name: stripLinks(product.name), price: money(product.priceCents, product.currency), link_sent: held(product) })),
         approval_expires_at: typeof result.approval_expires_at === 'string' ? stripLinks(result.approval_expires_at) || null : null,
         shopper_need_not_reply: result.shopper_need_not_reply === true,
         link_sent: result.link_sent === true,
         // Two products on one page share one link, so the count is of pages.
         product_links_sent: new Set(products.filter(held).map((product) => product.url)).size,
+        // The id the model sent, never the catalog id, which is a store page for a retail product.
+        pick: result.pick ? { product_id: pickId({ id: result.pick.product_id, ref: result.pick.ref }), in_cart: result.pick.in_cart === true } : null,
     };
 }
 /**