@agent-cards/commerce-sdk 0.9.0 → 0.11.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;
@@ -125,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;
@@ -184,13 +199,15 @@ export interface BuyPick {
 /**
  * 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.
+ * 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 {
@@ -213,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;
@@ -333,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;
@@ -365,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,
@@ -140,7 +155,7 @@ function storesOf(v) {
         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 }] : [];
+        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;
 }
@@ -380,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;
@@ -470,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.js

@@ -10,24 +10,34 @@ 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.',
-    "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.",
+    '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 already knows you are working on their request, from a reply or a 👀 on their message, 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, beside your reply, as product links do: `store_links_sent` says how many.',
+    '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.',
+    "Talk to the shopper only about their order, in their terms: what is in the cart, what was found and what they can do next. Leave out how it was done, even when `reply` says it: never mention this tool, `reply`, a field, a system, \"my end\" or what you can or can't see, the searches run, the stores checked or not, a timeout, account setup, or a link that did not go out. When parts of the result disagree, say what you are sure of and ask, never which part said what.",
+    'Say as fact only what the result shows: never promise what a store will do later, such as confirm a size when the order goes through.',
+    'Never tell the shopper to remove, delete or replace a card or to change a setting, even when `reply` says to.',
+    'Name each link by what it is for, from `next_action`: the link to add a card, to sign in to the store, or to approve the payment.',
+    'Within a step, ask for one detail per message, such as the delivery address before the name for the label.',
+    'Write every sentence in your own style, casing included, even where `reply` is written another way.',
 ].join(' ');
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
 export function buyToolDefinition() {
@@ -40,7 +50,7 @@ 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: {

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,11 +2,11 @@ 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, type BuyStoreChoice, type BuyStorePick, type BuyStores, } 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, type BuyToolStore, } from './buy-tool.js';
-export { instantAck, ackFor, type AckForOptions } from './ack.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, type BuyAckMode, } from './buy-tool.js';
+export { instantAck, instantReaction, ackFor, ACK_REACTION, type AckForOptions } from './ack.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';

package/dist/index.js

@@ -4,9 +4,9 @@ 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 { instantAck, instantReaction, ackFor, ACK_REACTION } from './ack.js';
 export { forModel, forModelError, stripLinks, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
 export { listenToAgentcard, } from './listen.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/message.d.ts

@@ -12,12 +12,17 @@ import { type AgentcardEvent } from './verify.js';
  * - `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.
+ * - `approval_declined`: the shopper declined the approval, and nothing was charged.
+ * - `payment_declined`: the shopper approved, and the payment was refused before the order went in; `facts.reason` says why. 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.
+ * - `store_connected`: the shopper signed in to their own account at the store from the sign-in link your app sent, so the order can go through on it.
+ * - `store_connect_failed`: the shopper's sign-in to the store did not go through, and the link no longer works.
+ * - `store_connect_expired`: the sign-in link expired before the shopper finished signing in.
  */
-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';
+export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'approval_expiring' | 'approval_expired' | 'approval_declined' | 'payment_declined' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle' | 'card_added' | 'store_connected' | 'store_connect_failed' | 'store_connect_expired';
 /** 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;
@@ -28,7 +33,7 @@ export interface PurchaseFacts {
     cardBrand?: string;
     cardLast4?: string;
     orderId?: string;
-    /** Why an order failed or was not placed, in words. */
+    /** Why an order failed or was not placed, or a payment was declined, in words. */
     reason?: string;
     approvalUrl?: string;
     /** When the approval link stops working, as an ISO 8601 timestamp. */

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.
  *

package/dist/messages.js

@@ -116,9 +116,60 @@ export function toMessages(text) {
     scanner.end();
     return messages;
 }
+/** The pause before a message, as someone texting takes it: 300 ms, plus 12 ms a character, at most 1.5 seconds. */
+const TYPING_BASE_MS = 300;
+const TYPING_MS_PER_CHARACTER = 12;
+const TYPING_MAX_MS = 1_500;
 /**
- * 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
+ * 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 function typingDelay(message) {
+    return Math.min(TYPING_MAX_MS, TYPING_BASE_MS + TYPING_MS_PER_CHARACTER * [...String(message ?? '')].length);
+}
+/** The pause for each message `pace` asks for, or null for none. Throws a TypeError for a pace that cannot work. */
+export function paceOf(pace) {
+    if (pace === undefined || pace === true)
+        return typingDelay;
+    if (pace === false)
+        return null;
+    if (typeof pace !== 'function')
+        throw new TypeError('Pass pace as true, false, or a function that returns the pause before a message in milliseconds.');
+    return (message) => {
+        let ms;
+        try {
+            ms = Number(pace(message));
+        }
+        catch {
+            // A pace function that fails costs only the pause.
+            return 0;
+        }
+        return Number.isFinite(ms) && ms > 0 ? ms : 0;
+    };
+}
+/** A typing hook that never throws: one that fails costs nothing but the indicator. */
+export function typingHook(onTyping) {
+    if (onTyping !== undefined && typeof onTyping !== 'function')
+        throw new TypeError('Pass onTyping as a function that takes true when a pause starts and false when its message goes out.');
+    return (typing) => {
+        try {
+            onTyping?.(typing);
+        }
+        catch {
+            // The app's indicator failing never stops a message.
+        }
+    };
+}
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * 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.
  *
@@ -133,16 +184,38 @@ export function messageStream(options) {
     const onMessage = options?.onMessage;
     if (typeof onMessage !== 'function')
         throw new TypeError('Pass onMessage as a function that takes each message.');
+    const pauseOf = paceOf(options.pace);
+    const typing = typingHook(options.onTyping);
     // The line still being written. A trailing \r waits here too, in case its \n is in the next piece.
     let open = '';
     let ended = false;
     let failure = null;
-    // Messages waiting for the send before them. A send that returns no promise goes out at once.
+    // Messages waiting for the send before them, or for their pause. A send that returns no promise goes out at once.
     const queue = [];
     let running = null;
+    // When the last message went out, and whether the app was told a pause started.
+    let lastAt = null;
+    let paused = false;
+    // The pause chosen for the message at the head of the queue: chosen once, so a pace that varies never makes it wait twice.
+    let headPause = null;
     const drain = () => {
         while (queue.length > 0 && !failure) {
-            const message = queue.shift();
+            const message = queue[0];
+            if (pauseOf && lastAt !== null) {
+                headPause ??= pauseOf(message);
+                const wait = lastAt + headPause - Date.now();
+                if (wait > 0) {
+                    if (!paused)
+                        typing(true);
+                    paused = true;
+                    return sleep(wait).then(() => drain() ?? undefined);
+                }
+            }
+            queue.shift();
+            headPause = null;
+            if (paused)
+                typing(false);
+            paused = false;
             let sent;
             try {
                 sent = onMessage(message);
@@ -152,10 +225,14 @@ export function messageStream(options) {
                 break;
             }
             if (sent && typeof sent.then === 'function') {
-                return Promise.resolve(sent).then(() => drain() ?? undefined, (error) => {
+                return Promise.resolve(sent).then(() => {
+                    lastAt = Date.now();
+                    return drain() ?? undefined;
+                }, (error) => {
                     failure = { error };
                 });
             }
+            lastAt = Date.now();
         }
         return null;
     };

package/dist/model-view.d.ts

@@ -17,8 +17,17 @@ export interface BuyToolModelCart {
         price: string | null;
     }>;
     fees: string | null;
+    /** The store's own fee and tax lines inside `fees`, by the store's labels. Empty when it itemized none. */
+    fee_lines: Array<{
+        label: string;
+        amount: string;
+    }>;
     tip: string | null;
     total: string;
+    /** True when the store has not priced its fees and tax yet: `total` is an estimate, never the final amount. */
+    total_is_estimate: boolean;
+    /** The most the shopper's card can be held for this cart: above `total` at a store that prices its final at checkout, `total` itself for a flight, which holds exactly that; else null. */
+    max_charge: string | null;
 }
 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. */
@@ -57,7 +66,13 @@ export interface BuyToolModelView {
     shopper_already_told_looking: boolean;
     /** True when the shopper already has the link this answer needed. */
     link_sent: boolean;
-    /** How many store pages of the products above the shopper holds, 0 when none went out. */
+    /**
+     * Which links went out with this answer: `store_login` is the store's own login page (the shopper
+     * logs in to their account there), `vault` is the page where they add a card, `approval` the page
+     * where they approve the payment. Name the link by what it is: a store login is never a card link.
+     */
+    links_sent: Array<'vault' | 'approval' | 'store_login'>;
+    /** How many of the products above the shopper holds as cards, each with its name, price and picture; 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: {
@@ -102,6 +117,18 @@ export declare function shownStores(stores: readonly BuyToolStore[] | null | und
  * 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;
+/**
+ * What tells one product card from another: the product's link-free id, else its page. A restaurant gives
+ * every menu item the store's one page, so a card per page sent one card for a reply that offered three
+ * dishes (2026-10-20, Suavecito Birria & Tacos on DoorDash). Each product the model reads gets its own card.
+ */
+export declare function cardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'url'>): string | null;
+/**
+ * The key of the card a product gets, or null when it gets none: a product with a page at its store,
+ * or a flight option, which has no page, with an id a pick takes. A flight's card is how the shopper
+ * taps the flight they want (2026-10-20: three flights listed in text, and no card to tap).
+ */
+export declare function productCardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'url' | 'flight'>): 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 id, name and price, and