@agent-cards/commerce-sdk 0.8.0 → 0.10.0

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

@@ -4,10 +4,11 @@
  * model that holds a link writes it into the chat. So a link never enters
  * this view: `sendLink` delivers it, and the model reads `link_sent` for the
  * Vault and approval links, and `link_sent` on each product and
- * `product_links_sent` for the products' store pages.
+ * `product_links_sent` for the products' store pages, and `link_sent` on each
+ * store and `store_links_sent` for the pages of the stores to pick from.
  */
 import type { BuyNextAction } from './client.js';
-import type { BuyToolProduct, BuyToolResult, BuyToolStatus } from './buy-tool.js';
+import type { BuyToolProduct, BuyToolResult, BuyToolStatus, BuyToolStore } from './buy-tool.js';
 export interface BuyToolModelCart {
     store: string;
     items: Array<{
@@ -16,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. */
@@ -29,6 +39,15 @@ export interface BuyToolModelProduct {
     /** True when the shopper holds this product's store page, which `sendLink` delivered beside the reply. */
     link_sent: boolean;
 }
+export interface BuyToolModelStore {
+    /** What the model passes as `store_id` when the shopper picks this store: Agentcard's id, never a link. */
+    store_id: string;
+    name: string;
+    /** The delivery estimate in minutes, or null when the store showed none. */
+    eta_minutes: number | null;
+    /** True when the shopper holds this store's page, which `sendLink` delivered beside the reply. */
+    link_sent: boolean;
+}
 /** The buy tool's answer as the model reads it. */
 export interface BuyToolModelView {
     status: BuyToolStatus;
@@ -47,13 +66,22 @@ 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. */
+    /** 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: {
         product_id: string | null;
         in_cart: boolean;
     } | null;
+    /** The stores the reply presents to choose from, in the order it names them. */
+    stores: BuyToolModelStore[];
+    /** How many store pages of the stores above the shopper holds, 0 when none went out. */
+    store_links_sent: number;
+    /** The store this call's `store_id` (or an answer such as `the second one`) picked, and whether Agentcard selected it; null when none was picked. */
+    store_pick: {
+        store_id: string;
+        selected: boolean;
+    } | null;
 }
 /**
  * The text with every link taken out: a Markdown link keeps its label, an address with a path or a scheme goes
@@ -73,11 +101,28 @@ export declare function money(minor: number | null | undefined, currency: string
  * shopper never holds a product link the model cannot name.
  */
 export declare function shownProducts(products: readonly BuyToolProduct[] | null | undefined): BuyToolProduct[];
+/**
+ * The stores the model reads: each one whose id and name hold no link, so the model never reads a
+ * link and never offers a store without its name. The tool sends pages for these same stores.
+ */
+export declare function shownStores(stores: readonly BuyToolStore[] | null | undefined): BuyToolStore[];
 /**
  * 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;
+/**
+ * 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

package/dist/model-view.js

@@ -93,6 +93,13 @@ export function money(minor, currency) {
 export function shownProducts(products) {
     return (products ?? []).filter((product) => stripLinks(product.name) !== '' && stripLinks(product.store ?? '') !== '').slice(0, MAX_PRODUCTS);
 }
+/**
+ * The stores the model reads: each one whose id and name hold no link, so the model never reads a
+ * link and never offers a store without its name. The tool sends pages for these same stores.
+ */
+export function shownStores(stores) {
+    return (stores ?? []).filter((store) => store.id !== '' && stripLinks(store.id) === store.id && stripLinks(store.name) !== '');
+}
 /**
  * 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.
@@ -102,13 +109,35 @@ export function pickId(product) {
         return product.ref;
     return typeof product.id === 'string' && product.id !== '' && stripLinks(product.id) === product.id ? product.id : 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 function cardKey(product) {
+    return pickId(product) ?? (typeof product.url === 'string' && product.url !== '' ? product.url : 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 function productCardKey(product) {
+    if (typeof product.url === 'string' && product.url !== '')
+        return cardKey(product);
+    return product.flight ? pickId(product) : null;
+}
 function cartView(cart) {
     return {
         store: stripLinks(cart.store?.name ?? cart.merchant_name) || stripLinks(cart.merchant),
         items: cart.items.map((line) => ({ name: stripLinks(line.name), qty: line.qty, price: money(line.priceCents, cart.currency) })),
         fees: cart.serviceFeesCents > 0 ? money(cart.serviceFeesCents, cart.currency) : null,
+        fee_lines: (cart.merchantFeeLines ?? []).map((line) => ({ label: stripLinks(line.label), amount: money(line.amountCents, cart.currency) })),
         tip: cart.tipCents > 0 ? money(cart.tipCents, cart.currency) : null,
         total: money(cart.totalCents, cart.currency) ?? money(0, cart.currency),
+        total_is_estimate: cart.totalIsEstimate === true,
+        // Agentcard names a ceiling equal to the total only for a hold of exactly the total, as a flight's.
+        max_charge: typeof cart.approvedCeilingCents === 'number' && cart.approvedCeilingCents > 0 && cart.approvedCeilingCents >= cart.totalCents ? money(cart.approvedCeilingCents, cart.currency) : null,
     };
 }
 /**
@@ -120,7 +149,9 @@ function cartView(cart) {
 export function forModel(result) {
     const status = typeof result.status === 'string' && MODEL_STATUSES.has(result.status) ? result.status : 'needs_input';
     const products = shownProducts(result.products);
-    const held = (product) => product.linkSent === true && typeof product.url === 'string' && product.url !== '';
+    const held = (product) => product.linkSent === true && productCardKey(product) !== null;
+    const stores = shownStores(result.stores);
+    const heldStore = (store) => store.linkSent === true && typeof store.url === 'string' && store.url !== '';
     return {
         status,
         next_action: result.next_action ?? null,
@@ -132,10 +163,16 @@ export function forModel(result) {
         shopper_need_not_reply: result.shopper_need_not_reply === true,
         shopper_already_told_looking: result.shopper_already_told_looking === 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,
+        // A card per product, so two dishes on a restaurant's one page are two cards.
+        product_links_sent: new Set(products.filter(held).map(productCardKey)).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,
+        stores: stores.map((store) => ({ store_id: store.id, name: stripLinks(store.name), eta_minutes: store.etaMinutes, link_sent: heldStore(store) })),
+        store_links_sent: new Set(stores.filter(heldStore).map((store) => store.url)).size,
+        // A store id with a link in it is never read back to the model.
+        store_pick: result.store_pick && stripLinks(result.store_pick.store_id) === result.store_pick.store_id
+            ? { store_id: result.store_pick.store_id, selected: result.store_pick.selected === true }
+            : null,
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Give your agent one tool that buys for your shoppers at real stores, and post each purchase update Agentcard sends into the shopper's chat, over a connection your server opens or a webhook endpoint.",
   "type": "module",
   "main": "dist/index.js",