@agent-cards/commerce-sdk 0.8.0 → 0.10.0

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { type AgentcardListener, type ListenOptions } from './listen.js';
+import type { ShopperMessage } from './shopper-message.js';
 /** The fetch the client calls: Node 18 and later have one built in. */
 export type FetchLike = (url: string, init: {
     method: string;
@@ -94,10 +95,14 @@ export interface BuyRequest {
     new_order?: true;
     /**
      * The product the shopper picked from the last search's `catalog.items`, by its `id` or its `ref`:
-     * Agentcard adds exactly that item, with no new search. Goes with an `ask`, never with `confirm` or `new_order`.
+     * Agentcard adds exactly that item, with no new search. Or the store the shopper picked from the last
+     * answer's `stores.items`, by its `id`: Agentcard selects exactly that store before the turn runs.
+     * Goes with an `ask`, never with `confirm` or `new_order`.
      */
     pick?: {
         product_id: string;
+    } | {
+        store_id: string;
     };
     payment_source?: 'vault';
     delivery_address?: BuyDeliveryAddress;
@@ -121,14 +126,28 @@ export interface BuyCartLine {
  * 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.
  */
+/** One of the store's own fee or tax lines, as the store labels it: `Delivery Fee`, `Service Fee`, `Estimated Tax`. */
+export interface BuyCartFeeLine {
+    label: string;
+    amountCents: number;
+}
 export interface BuyCart {
     merchant: string;
     merchant_name: string;
     store: BuyStore | null;
     items: BuyCartLine[];
+    /** The items alone, or null from an older API. */
+    subtotalCents: number | null;
     serviceFeesCents: number;
+    /** The store's own fee and tax lines inside `serviceFeesCents`, or null when the store itemized none. */
+    merchantFeeLines: BuyCartFeeLine[] | null;
     tipCents: number;
     totalCents: number;
+    /**
+     * True when the store has not priced the cart's fees and tax yet, so `totalCents` covers the items and
+     * known fees only: show it as an estimate. DoorDash prices a cart once the shopper's own account holds it.
+     */
+    totalIsEstimate: boolean;
     /** The ISO 4217 code the store prices the cart in, or null when Agentcard sent none. */
     currency: string | null;
     approvedCeilingCents: number | null;
@@ -177,6 +196,32 @@ export interface BuyPick {
     ref: string | null;
     in_cart: boolean;
 }
+/**
+ * One store a delivery store search found that the answer's reply names. `id` holds no link and is what
+ * `pick.store_id` takes; `store_page_url` is the store's page at the merchant. `eta_minutes` is the
+ * merchant's delivery estimate, or null when it showed none. `image_url` is the picture the store's
+ * card shows at the merchant, or null when it shows none.
+ */
+export interface BuyStoreChoice {
+    id: string;
+    name: string;
+    store_page_url: string | null;
+    eta_minutes: number | null;
+    image_url: string | null;
+}
+/** The stores an answer's reply presents to choose from, at most three, in the order the reply names them. */
+export interface BuyStores {
+    merchant: string;
+    merchant_name: string;
+    items: BuyStoreChoice[];
+    as_of: string | null;
+}
+/** The store a store pick named, and whether Agentcard selected it before the turn ran. */
+export interface BuyStorePick {
+    store_id: string;
+    name: string | null;
+    selected: boolean;
+}
 export interface BuyPaymentSource {
     source: string;
     brand: string | null;
@@ -185,11 +230,12 @@ export interface BuyPaymentSource {
 /**
  * The one thing the shopper does next, as Agentcard names it, in the order a purchase asks for them:
  * `shipping_details` (a shipping address and phone), `guest_details` (a name, email and phone for a
- * booking), `add_card` (a card in their Vault), `confirm` (their yes to the cart), `verification_code`
+ * booking), `store_login` (a login to their own account at a store that checks out only on it, with
+ * the `store_login` link), `add_card` (a card in their Vault), `confirm` (their yes to the cart), `verification_code`
  * (the code a booking texted them), then `approve` (the approval link). A value this version does
  * not know reads as null.
  */
-export type BuyNextAction = 'shipping_details' | 'guest_details' | 'add_card' | 'confirm' | 'verification_code' | 'approve';
+export type BuyNextAction = 'shipping_details' | 'guest_details' | 'store_login' | 'add_card' | 'confirm' | 'verification_code' | 'approve';
 /** 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;
@@ -223,6 +269,10 @@ export interface BuyTurn {
     store_login_merchant_name: string | null;
     /** The product this turn's `pick` named, and whether the cart holds it; null for a turn without one. */
     pick: BuyPick | null;
+    /** The stores this answer's reply presents to choose from; null when it presents none, and on an older API. */
+    stores: BuyStores | null;
+    /** The store this turn's `pick.store_id` named, or an answer such as `the second one` picked; null without one. */
+    store_pick: BuyStorePick | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -301,6 +351,9 @@ export declare class AgentcardClient {
     private token;
     private inflight;
     private learnedSandbox;
+    /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
+    private readonly inbox;
+    private readonly deliveredIds;
     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;
@@ -333,6 +386,21 @@ export declare class AgentcardClient {
      * webhook endpoint: `listenToAgentcard(this, opts)`. Takes your company credentials.
      */
     listen(opts: ListenOptions): AgentcardListener;
+    /**
+     * Notes that `message` reached the chat of the shopper you call `externalUserId`, so that shopper's
+     * next `buy.turn` hands it to your model (`turn.messages`), until a history the model ran with holds it. `listen` and `agentcardWebhook({ agentcard })`
+     * call it once `onMessage` returns, so call it yourself only for a message you delivered another way.
+     * A message is kept once per event id. The messages live in this process's memory, at most 20 per
+     * shopper: the listener and the buy tool share one client in one process.
+     */
+    delivered(externalUserId: string, message: ShopperMessage): void;
+    /**
+     * The messages kept for this shopper, oldest first: each one that reached their chat and that no
+     * history `turn.messages` read has held yet. `buy.turn` reads them when it opens.
+     */
+    keptMessages(externalUserId: string): ShopperMessage[];
+    /** Forgets these messages for this shopper: `turn.messages` calls it once the history it reads holds them. */
+    forgetMessages(externalUserId: string, messages: readonly ShopperMessage[]): void;
     /** A company names the shopper exactly once; a shopper's own token already names them. */
     private checkShopper;
     private call;

package/dist/client.js

@@ -18,7 +18,13 @@ export const BUY_TURN_TIMEOUT_MS = 130_000;
 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']);
+/** The messages a shopper's chat got that the client keeps for that shopper's next turn, the oldest dropped first. */
+const DELIVERED_PER_SHOPPER = 20;
+/** The shoppers the client keeps such messages for, the one written to longest ago dropped first. */
+const DELIVERED_SHOPPERS = 10_000;
+/** The event ids the client remembers taking in, so a message delivered twice reaches the model once. */
+const DELIVERED_IDS_KEPT = 10_000;
+const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'store_login', '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`,
@@ -75,6 +81,12 @@ function storeOf(v) {
         return null;
     return { id: v.id, ...(str(v.name) ? { name: v.name } : {}) };
 }
+function feeLinesOf(v) {
+    if (!Array.isArray(v))
+        return null;
+    const lines = v.filter(isRecord).flatMap((f) => (str(f.label) && num(f.amountCents) !== null ? [{ label: f.label, amountCents: f.amountCents }] : []));
+    return lines.length ? lines : null;
+}
 function cartOf(v) {
     if (!isRecord(v) || !str(v.hash) || !str(v.merchant))
         return null;
@@ -89,9 +101,12 @@ function cartOf(v) {
             product_id: str(i.product_id),
             url: pageUrl(i.url),
         })) : [],
+        subtotalCents: num(v.subtotalCents),
         serviceFeesCents: num(v.serviceFeesCents) ?? 0,
+        merchantFeeLines: feeLinesOf(v.merchantFeeLines),
         tipCents: num(v.tipCents) ?? 0,
         totalCents: num(v.totalCents) ?? 0,
+        totalIsEstimate: v.totalIsEstimate === true,
         currency: str(v.currency),
         approvedCeilingCents: num(v.approvedCeilingCents),
         hash: v.hash,
@@ -132,6 +147,18 @@ function catalogOf(v) {
     }) : [];
     return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
 }
+/** The stores an answer presents: each one with an id and a name, and no block when none has both. */
+function storesOf(v) {
+    if (!isRecord(v) || !Array.isArray(v.items))
+        return null;
+    const items = v.items.filter(isRecord).flatMap((i) => {
+        const id = str(i.id);
+        const name = str(i.name);
+        const eta = num(i.eta_minutes);
+        return id && name ? [{ id, name, store_page_url: pageUrl(i.store_page_url), eta_minutes: eta, image_url: str(i.image_url) }] : [];
+    });
+    return items.length ? { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, as_of: str(v.as_of) } : null;
+}
 function paymentSourceOf(v) {
     return isRecord(v) && str(v.source) ? { source: v.source, brand: str(v.brand), last4: str(v.last4) } : null;
 }
@@ -165,6 +192,8 @@ export function turnOf(body) {
         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,
         pick: isRecord(body.pick) && str(body.pick.product_id) ? { product_id: body.pick.product_id, ref: str(body.pick.ref), in_cart: body.pick.in_cart === true } : null,
+        stores: storesOf(body.stores),
+        store_pick: isRecord(body.store_pick) && str(body.store_pick.store_id) ? { store_id: body.store_pick.store_id, name: str(body.store_pick.name), selected: body.store_pick.selected === true } : null,
         raw: body,
     };
 }
@@ -366,6 +395,9 @@ export class AgentcardClient {
     token = null;
     inflight = null;
     learnedSandbox = null;
+    /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
+    inbox = new Map();
+    deliveredIds = new Set();
     constructor(options) {
         const o = (options ?? {});
         const hasCredentials = o.clientId !== undefined || o.clientSecret !== undefined;
@@ -456,6 +488,52 @@ export class AgentcardClient {
     listen(opts) {
         return listenToAgentcard(this, opts);
     }
+    /**
+     * Notes that `message` reached the chat of the shopper you call `externalUserId`, so that shopper's
+     * next `buy.turn` hands it to your model (`turn.messages`), until a history the model ran with holds it. `listen` and `agentcardWebhook({ agentcard })`
+     * call it once `onMessage` returns, so call it yourself only for a message you delivered another way.
+     * A message is kept once per event id. The messages live in this process's memory, at most 20 per
+     * shopper: the listener and the buy tool share one client in one process.
+     */
+    delivered(externalUserId, message) {
+        if (!str(externalUserId))
+            throw new TypeError('Pass externalUserId: your own id for the shopper whose chat got the message.');
+        if (!isRecord(message) || typeof message.text !== 'string')
+            throw new TypeError('Pass the message onMessage got, with its text.');
+        if (message.text.trim() === '')
+            return;
+        if (str(message.eventId)) {
+            if (this.deliveredIds.has(message.eventId))
+                return;
+            this.deliveredIds.add(message.eventId);
+            if (this.deliveredIds.size > DELIVERED_IDS_KEPT)
+                this.deliveredIds.delete(this.deliveredIds.values().next().value);
+        }
+        const kept = this.inbox.get(externalUserId) ?? [];
+        // The shopper written to last moves to the end, so the one dropped first is the one written to longest ago.
+        this.inbox.delete(externalUserId);
+        this.inbox.set(externalUserId, [...kept, message].slice(-DELIVERED_PER_SHOPPER));
+        if (this.inbox.size > DELIVERED_SHOPPERS)
+            this.inbox.delete(this.inbox.keys().next().value);
+    }
+    /**
+     * The messages kept for this shopper, oldest first: each one that reached their chat and that no
+     * history `turn.messages` read has held yet. `buy.turn` reads them when it opens.
+     */
+    keptMessages(externalUserId) {
+        return [...(this.inbox.get(externalUserId) ?? [])];
+    }
+    /** Forgets these messages for this shopper: `turn.messages` calls it once the history it reads holds them. */
+    forgetMessages(externalUserId, messages) {
+        const kept = this.inbox.get(externalUserId);
+        if (!kept)
+            return;
+        const left = kept.filter((m) => !messages.includes(m));
+        if (left.length > 0)
+            this.inbox.set(externalUserId, left);
+        else
+            this.inbox.delete(externalUserId);
+    }
     /** 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);

package/dist/definition.d.ts

@@ -1,7 +1,7 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with four required fields, `product_id` null unless the shopper
- * picks a product they were shown. The delivery address and the
+ * JSON Schema with five required fields, `product_id` null unless the shopper
+ * picks a product they were shown and `store_id` null unless they pick a store. 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.
  */
@@ -9,8 +9,9 @@ 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: `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.
+ * What the model sends: `ask`, `confirm` and `new_order` every time, `product_id`, null unless the
+ * shopper picks a product from the last result, and `store_id`, null unless they pick a store from it.
+ * Your own code may leave `product_id` and `store_id` out.
  */
 export interface BuyToolInput {
     ask: string;
@@ -18,6 +19,8 @@ export interface BuyToolInput {
     new_order: boolean;
     /** The `product_id` of the product the shopper picked from the last result's `products`, or null. */
     product_id?: string | null;
+    /** The `store_id` of the store the shopper picked from the last result's `stores`, or null. */
+    store_id?: string | null;
 }
 /** A type, not an interface, so it fits the SDKs' own input schema types, which take any key. */
 export type BuyToolInputSchema = {
@@ -39,6 +42,10 @@ export type BuyToolInputSchema = {
             type: ['string', 'null'];
             description: string;
         };
+        store_id: {
+            type: ['string', 'null'];
+            description: string;
+        };
     };
     required: Array<keyof BuyToolInput>;
     additionalProperties: false;
@@ -52,8 +59,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, `confirm` and `new_order` booleans, `product_id` a
- * string, null or left out, and nothing else. Throws a TypeError whose message
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` and
+ * `store_id` each a string, null or left out, at most one of them set, and
+ * nothing else. Throws a TypeError whose message
  * tells the model what to send.
  */
 export declare function parseBuyToolInput(value: unknown): BuyToolInput;

package/dist/definition.js

@@ -1,7 +1,7 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with four required fields, `product_id` null unless the shopper
- * picks a product they were shown. The delivery address and the
+ * JSON Schema with five required fields, `product_id` null unless the shopper
+ * picks a product they were shown and `store_id` null unless they pick a store. 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.
  */
@@ -10,21 +10,27 @@ export const BUY_TOOL_NAME = 'buy';
 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.',
+    'Tell the shopper what `reply` says, in your own voice, except the products and stores it lists that reach the shopper as cards.',
     "When `shopper_already_told_looking` is true, the shopper was already told you are working on their request, so never acknowledge it again: open with the answer or the question.",
     '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.',
+    'When `next_action` is null and `reply` is about something other than a cart, ask for no checkout step: a cart from an earlier request gets one short line at most, after the answer to what the shopper just asked, and never a question about confirming or placing it.',
+    'Set `confirm` to true only when the shopper just said yes to the cart in your last result, asks to check out or pay for a cart that waits, says they added the card for a cart that waits, says they approved, or asks for the approval link again.',
+    'When the shopper asks to check out, pay or place the order, call this tool: Agentcard knows whether their card is saved, so never ask the shopper whether they added it.',
     '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.',
+    'Product links reach the shopper on their own, as cards that show each product\'s name, price and picture. When `product_links_sent` is above zero, the shopper already sees those products, so never list them again, by name, price or number, even when `reply` lists them: write one short line, such as which one they want, plus only what the cards do not show, such as why one is the pick. When 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.',
+    "Never tell the shopper that you or Agentcard can't see their name, phone number or address: Agentcard may use the ones saved on their Agentcard account for an order, and `reply` says when it does.",
     "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 the shopper picks one of the `stores` in your last result, by its name, its place in the list or a tap that names it, set `store_id` to that store's `store_id`, so Agentcard orders from exactly that store; otherwise set it to null. Never set both `product_id` and `store_id`.",
+    'Store links reach the shopper on their own, as cards that show each store\'s name and delivery time. When `store_links_sent` is above zero, never list those stores again: ask which one in one short line.',
+    'When `store_links_sent` is 0 and you offer the `stores`, name each one by its `name`, never only "their links are there".',
     '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. */
@@ -38,24 +44,29 @@ export function buyToolDefinition() {
                 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.',
+                    description: 'True only when the shopper just said yes to the cart in your last result, asks to check out or pay for a cart that waits, 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.",
                 },
+                store_id: {
+                    type: ['string', 'null'],
+                    description: 'The `store_id` of the store the shopper picked from the `stores` in your last result. Null when they picked none.',
+                },
             },
-            required: ['ask', 'confirm', 'new_order', 'product_id'],
+            required: ['ask', 'confirm', 'new_order', 'product_id', 'store_id'],
             additionalProperties: false,
         },
     };
 }
-const FIELDS = new Set(['ask', 'confirm', 'new_order', 'product_id']);
+const FIELDS = new Set(['ask', 'confirm', 'new_order', 'product_id', 'store_id']);
 /**
  * The model's input, checked against the schema: an object, or its JSON text,
- * 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
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` and
+ * `store_id` each a string, null or left out, at most one of them set, and
+ * nothing else. Throws a TypeError whose message
  * tells the model what to send.
  */
 export function parseBuyToolInput(value) {
@@ -74,7 +85,7 @@ 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, new_order and product_id, and ${extra} is not one of them.`);
+        throw new TypeError(`The buy tool takes only ask, confirm, new_order, product_id and store_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')
@@ -85,7 +96,15 @@ export function parseBuyToolInput(value) {
     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 };
+    const storeId = fields.store_id;
+    if (storeId !== undefined && storeId !== null && typeof storeId !== 'string') {
+        throw new TypeError("Set store_id to the picked store's store_id, as a string, or to null.");
+    }
+    const product = typeof productId === 'string' && productId.trim() !== '' ? productId.trim() : null;
+    const store = typeof storeId === 'string' && storeId.trim() !== '' ? storeId.trim() : null;
+    if (product && store)
+        throw new TypeError('Set product_id or store_id for the one thing the shopper picked, and the other to null.');
+    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order, product_id: product, store_id: store };
 }
 /** 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

@@ -7,6 +7,7 @@
  */
 import { type AgentcardEvent, type VerifyOptions } from './verify.js';
 import { type PurchaseMessage } from './message.js';
+import type { AgentcardClient } from './client.js';
 import { type ShopperMessage } from './shopper-message.js';
 /** The parts of a Node or Express request the handler reads. */
 export interface WebhookRequest {
@@ -80,6 +81,11 @@ export interface AgentcardWebhookOptions extends PurchaseAgentWebhookOptions {
      * 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 client your buy tools share. Once `onMessage` returns, the client keeps the message for that
+     * shopper's next `buy.turn`, which hands it to your model, as `agentcard.listen` does.
+     */
+    agentcard?: AgentcardClient;
 }
 /** The handler `agentcardWebhook` returns: a Node or Express `(req, res)` handler, with `fetch` for a web `Request`. */
 export interface AgentcardWebhookHandler {

package/dist/handler.js

@@ -284,6 +284,9 @@ export function agentcardWebhook(opts) {
     if (typeof opts.onMessage !== 'function') {
         throw new TypeError('Pass onMessage, the function that receives each message for a shopper.');
     }
+    if (opts.agentcard !== undefined && typeof opts.agentcard?.delivered !== 'function') {
+        throw new TypeError('Pass agentcard as the AgentcardClient your buy tools share, or leave it out.');
+    }
     const secret = opts.secret;
     const verifyOpts = { toleranceSeconds: toleranceOf(opts) };
     const report = reporter(opts.onError);
@@ -316,6 +319,7 @@ export function agentcardWebhook(opts) {
         try {
             if (message?.externalUserId) {
                 await opts.onMessage(message.externalUserId, message, event);
+                opts.agentcard?.delivered(message.externalUserId, message);
             }
             else if (opts.onEvent) {
                 await opts.onEvent(event);

package/dist/index.d.ts

@@ -2,12 +2,12 @@ export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatur
 export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.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 FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyStreamHandlers, 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 { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, } 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 { toMessages, messageStream, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
+export { buyTool, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, } from './buy-tool.js';
 export { instantAck, ackFor, type AckForOptions } from './ack.js';
-export { forModel, forModelError, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, } from './model-view.js';
+export { forModel, forModelError, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';
 export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';
 export { AGENTCARD_EVENT_TYPES, type AgentcardEventType, } from './events.js';

package/dist/index.js

@@ -4,7 +4,7 @@ export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, } from './shopper-mes
 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 { toMessages, messageStream, typingDelay, } from './messages.js';
 export { buyTool, } from './buy-tool.js';
 export { instantAck, ackFor } from './ack.js';
 export { forModel, forModelError, stripLinks, } from './model-view.js';

package/dist/listen.d.ts

@@ -47,6 +47,8 @@ export interface ListenOptions {
      * Receives each event for one of your shoppers, under your own id for them, with the message
      * ready to post into that shopper's chat: the same as `agentcardWebhook`'s `onMessage`. A message
      * whose link or window closed before it arrived reaches no shopper: its event goes to `onEvent`.
+     * Once it returns, the client keeps the message for that shopper's next `buy.turn`, which hands it
+     * to your model, so the model knows what the shopper read between turns.
      */
     onMessage?: (externalUserId: string, message: ShopperMessage, event: AgentcardEvent<AgentcardEventType>) => void | Promise<void>;
     /** Receives every event `onMessage` does not take: every event, when you pass no `onMessage`. */

package/dist/listen.js

@@ -198,8 +198,11 @@ export function listenToAgentcard(agentcard, opts) {
         const forShopper = message && message.externalUserId !== null && !isStale(message) ? message : null;
         for (let attempt = 1;; attempt++) {
             try {
-                if (opts.onMessage && forShopper?.externalUserId)
+                if (opts.onMessage && forShopper?.externalUserId) {
                     await opts.onMessage(forShopper.externalUserId, forShopper, event);
+                    // The shopper's chat holds the message now, so their next `buy.turn` tells the model.
+                    agentcard.delivered(forShopper.externalUserId, forShopper);
+                }
                 else if (opts.onEvent)
                     await opts.onEvent(event);
                 return finish(event.id);

package/dist/messages.d.ts

@@ -14,6 +14,23 @@
  * ```
  */
 export declare function toMessages(text: string): string[];
+/**
+ * How long someone texting takes to type `message`, in milliseconds: 300, plus 12 a character, at most
+ * 1,500. `messageStream` and `buy.turn` wait this long between two messages by default, so a model that
+ * writes three paragraphs in 100 ms still delivers them one at a time.
+ *
+ * ```ts
+ * typingDelay('which one do you want?'); // 564
+ * ```
+ */
+export declare function typingDelay(message: string): number;
+/** How messages are spaced: `true` by `typingDelay`, `false` not at all, or a function that returns the pause for a message. */
+export type MessagePace = boolean | ((message: string) => number);
+/** The pause for each message `pace` asks for, or null for none. Throws a TypeError for a pace that cannot work. */
+export declare function paceOf(pace: unknown): ((message: string) => number) | null;
+/** A typing hook that never throws: one that fails costs nothing but the indicator. */
+export declare function typingHook(onTyping: unknown): (typing: boolean) => void;
+export declare const sleep: (ms: number) => Promise<void>;
 /** What `messageStream` hands back: push each piece of text as it arrives, then end once it stops. */
 export interface MessageStream {
     /** Adds the next piece of text. Each message the piece completes goes to `onMessage` in order, after the one before it settled. */
@@ -31,10 +48,24 @@ export interface MessageStreamOptions {
      * After a send fails, no later message is sent, and `end` rejects with the failure.
      */
     onMessage: (message: string) => void | Promise<void>;
+    /**
+     * Spaces the messages like someone texting. Each message after the first waits until `typingDelay`
+     * of it has passed since the one before it went out, so a model that writes three paragraphs in
+     * 100 ms still delivers them one at a time. Time the model spent writing counts toward the pause, so
+     * a slow model gets no added wait. Default `true`. `false` hands each message over the moment it is
+     * written, and a function returns the pause in milliseconds for a message.
+     */
+    pace?: MessagePace;
+    /**
+     * Hears `true` when the pause before a message starts and `false` the moment that message goes out,
+     * so your app can show a typing indicator between messages. One that throws costs nothing.
+     */
+    onTyping?: (typing: boolean) => void;
 }
 /**
- * Cuts streamed text into the messages `toMessages` finds, as it arrives. Each paragraph goes to
- * `onMessage` the moment the blank line that ends it arrives, whatever the pieces split it into. A
+ * Cuts streamed text into the messages `toMessages` finds, as it arrives. Each paragraph is ready the
+ * moment the blank line that ends it arrives, whatever the pieces split it into, and goes to
+ * `onMessage` then, or, after the first, once its typing pause since the last one passed (`pace`). A
  * paragraph inside a list waits for the first characters of the line after the blank, which say
  * whether the list goes on. `end` hands over the last message and waits for every send.
  *