@agent-cards/commerce-sdk 0.10.0 → 0.13.0

package/dist/client.d.ts

@@ -91,6 +91,8 @@ export interface BuyRequest {
     confirm?: string | true;
     /** Continue the shopper's newest open conversation instead of starting one. */
     resume?: true;
+    /** The conversation a confirm of a cart hash belongs to, in place of `resume`. */
+    conversation_id?: string;
     /** Drop the cart on the table and start a new order. */
     new_order?: true;
     /**
@@ -117,8 +119,23 @@ export interface BuyStore {
 export interface BuyCartLine {
     name: string;
     qty: number;
+    /** One unit's price, as the store lists it. */
     priceCents?: number;
+    /**
+     * What the line costs: its price with every add-on, times its quantity, before the store's own fees.
+     * The lines' totals add up to the cart's `subtotalCents`. Null when its price is unknown.
+     */
+    lineTotalCents: number | null;
+    /** The choices made on the line, by the store's names ("Carnitas", "Extra Guacamole"). Empty when none. */
+    options: string[];
+    /** The variant the line is, by the store's name ("Birthday (Medium)"), or null when the store names none. */
+    variant: string | null;
     product_id: string | null;
+    /**
+     * The id of the product card this line is, as `BuyProduct.ref` names it: a shown product whose `ref`
+     * (else `id`) equals it is in the cart. Null from an older API.
+     */
+    ref: string | null;
     /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
     url: string | null;
 }
@@ -172,9 +189,16 @@ export interface BuyCatalogItem {
     ref: string | null;
     name: string | null;
     priceCents: number | null;
+    /** True when `priceCents` is a "from" price: the lowest price of a product priced by a required choice, such as a burger's patty count or a drink's size. */
+    price_from?: true;
     /** The ISO 4217 code the store prices the product in, or null when Agentcard sent none. */
     currency: string | null;
     image_url: string | null;
+    /**
+     * Every photo of the product Agentcard sent, `image_url` first, each once, at most eight. One entry when the
+     * product has one photo, and none when it has none. An older API sends one photo at most.
+     */
+    image_urls: string[];
     store: BuyStore | null;
     /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
     url: string | null;
@@ -209,7 +233,7 @@ export interface BuyStoreChoice {
     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. */
+/** The stores an answer's reply presents to choose from, at most eight, in the order the reply names them. */
 export interface BuyStores {
     merchant: string;
     merchant_name: string;
@@ -236,6 +260,15 @@ export interface BuyPaymentSource {
  * not know reads as null.
  */
 export type BuyNextAction = 'shipping_details' | 'guest_details' | 'store_login' | 'add_card' | 'confirm' | 'verification_code' | 'approve';
+/**
+ * A cart the store's checkout is still building after an answer went out, at `store`, since `started_at`: its cart and
+ * total reach the shopper as a message of their own (purchase.message `cart_ready`), and only the shopper's yes to that
+ * total confirms it.
+ */
+export interface BuyCartBuilding {
+    store: string;
+    started_at: string;
+}
 /** 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;
@@ -273,6 +306,8 @@ export interface BuyTurn {
     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 cart the store's checkout is still building after this answer; null when none is, and on an older API. */
+    cart_building: BuyCartBuilding | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -307,6 +342,8 @@ export interface BuyConversation {
     conversation_id: string;
     status: 'open' | 'closed';
     turn_in_progress: boolean;
+    /** The cart the store's checkout is still building on this conversation; null when none is, and on an older API. */
+    cart_building: BuyCartBuilding | null;
     last_checkout: BuyLastCheckout | null;
     orders: BuyOrder[];
     carts: BuyCart[];
@@ -342,6 +379,8 @@ export declare class AgentcardApiError extends Error {
 }
 /** A turn as Agentcard answers it. */
 export declare function turnOf(body: Record<string, unknown>): BuyTurn;
+/** A cart being built, as an answer, a refusal or the conversation read names it. */
+export declare function cartBuildingOf(value: unknown): BuyCartBuilding | null;
 /** The client every shopper's buy tool shares. Build one per set of credentials and keep it. */
 export declare class AgentcardClient {
     readonly baseUrl: string;
@@ -394,6 +433,17 @@ export declare class AgentcardClient {
      * shopper: the listener and the buy tool share one client in one process.
      */
     delivered(externalUserId: string, message: ShopperMessage): void;
+    /**
+     * Notes that your agent answers `message` with a turn of its own (`buy.nextStep`) instead of posting
+     * its `text`, so the shopper never reads that text: `delivered` skips it from now on, and no later
+     * `buy.turn` hands it to the model as words the shopper read. `buy.nextStep` calls it.
+     */
+    answered(externalUserId: string, message: ShopperMessage): void;
+    /**
+     * Takes back `answered` for a message your agent's own turn could not answer (`BuyToolTurn.release` calls it): once you
+     * post its text after all, `delivered` keeps it, and a later `buy.turn` hands it to the model as words the shopper read.
+     */
+    unanswered(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.

package/dist/client.js

@@ -76,6 +76,30 @@ function pageUrl(v) {
         return null;
     }
 }
+/** The most photos one product carries. */
+const IMAGES_MAX = 8;
+/**
+ * A product's photos: `main` first, then each https address in `list`, in its order, each once, at most
+ * IMAGES_MAX. A value that is no https address, or that names a user before its host, is left out.
+ */
+function imagesOf(main, list) {
+    // The main photo passes the same check as the others: an https address without credentials. It stays as `imageUrl` spells
+    // it, so the list still starts with that address, and a later copy of it is skipped by its normalized form.
+    const mainPage = pageUrl(main);
+    const ok = !!main && !!mainPage && mainPage.startsWith('https:');
+    const out = ok ? [main] : [];
+    const seen = new Set(ok ? [mainPage] : []);
+    for (const v of Array.isArray(list) ? list : []) {
+        if (out.length >= IMAGES_MAX)
+            break;
+        const page = pageUrl(v);
+        if (page && page.startsWith('https:') && !seen.has(page)) {
+            seen.add(page);
+            out.push(page);
+        }
+    }
+    return out;
+}
 function storeOf(v) {
     if (!isRecord(v) || !str(v.id))
         return null;
@@ -94,13 +118,22 @@ function cartOf(v) {
         merchant: v.merchant,
         merchant_name: str(v.merchant_name) ?? v.merchant,
         store: storeOf(v.store),
-        items: Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => ({
-            name: str(i.name) ?? '',
-            qty: num(i.qty) ?? 1,
-            ...(num(i.priceCents) !== null ? { priceCents: i.priceCents } : {}),
-            product_id: str(i.product_id),
-            url: pageUrl(i.url),
-        })) : [],
+        items: Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => {
+            const qty = num(i.qty) ?? 1;
+            const price = num(i.priceCents);
+            return {
+                name: str(i.name) ?? '',
+                qty,
+                ...(price !== null ? { priceCents: price } : {}),
+                // An older API sends no line total: the line's price times its quantity is it.
+                lineTotalCents: num(i.lineTotalCents) ?? (price !== null ? price * qty : null),
+                options: Array.isArray(i.options) ? i.options.filter((o) => typeof o === 'string' && o.trim() !== '') : [],
+                variant: str(i.variant),
+                product_id: str(i.product_id),
+                ref: str(i.ref),
+                url: pageUrl(i.url),
+            };
+        }) : [],
         subtotalCents: num(v.subtotalCents),
         serviceFeesCents: num(v.serviceFeesCents) ?? 0,
         merchantFeeLines: feeLinesOf(v.merchantFeeLines),
@@ -138,8 +171,10 @@ function catalogOf(v) {
             ref: str(i.ref),
             name: str(i.name),
             priceCents: num(i.priceCents),
+            ...(i.price_from === true && num(i.priceCents) !== null ? { price_from: true } : {}),
             currency: str(i.currency),
             image_url: str(i.image_url),
+            image_urls: imagesOf(str(i.image_url), i.image_urls),
             ...(flight ? { flight } : {}),
             store: storeOf(i.store),
             url: pageUrl(i.url),
@@ -194,15 +229,21 @@ export function turnOf(body) {
         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,
+        cart_building: cartBuildingOf(body.cart_building),
         raw: body,
     };
 }
+/** A cart being built, as an answer, a refusal or the conversation read names it. */
+export function cartBuildingOf(value) {
+    return isRecord(value) && str(value.store) ? { store: value.store, started_at: str(value.started_at) ?? '' } : null;
+}
 function conversationOf(body) {
     const last = isRecord(body.last_checkout) ? body.last_checkout : null;
     return {
         conversation_id: str(body.conversation_id) ?? '',
         status: body.status === 'closed' ? 'closed' : 'open',
         turn_in_progress: body.turn_in_progress === true,
+        cart_building: cartBuildingOf(body.cart_building),
         last_checkout: last ? {
             at: str(last.at) ?? '',
             merchant: str(last.merchant) ?? '',
@@ -516,6 +557,37 @@ export class AgentcardClient {
         if (this.inbox.size > DELIVERED_SHOPPERS)
             this.inbox.delete(this.inbox.keys().next().value);
     }
+    /**
+     * Notes that your agent answers `message` with a turn of its own (`buy.nextStep`) instead of posting
+     * its `text`, so the shopper never reads that text: `delivered` skips it from now on, and no later
+     * `buy.turn` hands it to the model as words the shopper read. `buy.nextStep` calls it.
+     */
+    answered(externalUserId, message) {
+        if (!str(externalUserId))
+            throw new TypeError('Pass externalUserId: your own id for the shopper the message is for.');
+        if (!isRecord(message))
+            throw new TypeError('Pass the message onMessage got.');
+        if (str(message.eventId)) {
+            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);
+        if (kept)
+            this.forgetMessages(externalUserId, kept.filter((m) => m === message || (!!message.eventId && m.eventId === message.eventId)));
+    }
+    /**
+     * Takes back `answered` for a message your agent's own turn could not answer (`BuyToolTurn.release` calls it): once you
+     * post its text after all, `delivered` keeps it, and a later `buy.turn` hands it to the model as words the shopper read.
+     */
+    unanswered(externalUserId, message) {
+        if (!str(externalUserId))
+            throw new TypeError('Pass externalUserId: your own id for the shopper the message is for.');
+        if (!isRecord(message))
+            throw new TypeError('Pass the message onMessage got.');
+        if (str(message.eventId))
+            this.deliveredIds.delete(message.eventId);
+    }
     /**
      * 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.

package/dist/definition.js

@@ -10,9 +10,11 @@ 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`.",
+    'When the shopper sends a link to a product, such as a buy.trychannel3.com link, put the whole link in `ask` exactly as they sent it, query string included, with their words beside it: Agentcard buys that exact product from the link, so never describe the link in words instead.',
     '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.",
+    "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.',
+    'When `cart_building` is set, the store is still building that cart: tell the shopper in one short line that its total is on its way, never ask them to confirm it, and confirm it only after they say yes to the total in the message Agentcard sends next.',
     '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.',
     '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.',
@@ -21,17 +23,43 @@ export const BUY_TOOL_DESCRIPTION = [
     '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, 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 product's `price` that reads `from $10.69` is the lowest price it comes at: a size or another choice the shopper makes sets the rest. Say it as `from $10.69`, and never call a price a placeholder or say it shows $0.",
+    'A fact the cards do not show belongs to one product, such as a table time, a class time or where a place is, so name that product with it, by its `name` ("Delfina has 7:45"), never "one of these", "the other two" or "one of the spots i sent": the shopper cannot tell which card that means.',
     '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.',
+    'Set `new_order` to true only when the shopper drops the cart. When `carts` holds more than one cart and the shopper drops one of them, keep `new_order` false and say in `ask` which cart goes: the other carts stay.',
+    'The shopper can buy from more than one store at once: each store keeps its own cart in `carts`, every cart is its own order, and the shopper confirms each one on its own. Never tell the shopper an order can only come from one store.',
     "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's words fit more than one of the `products`, such as \"both\" or \"add dune\" while you or `reply` still asks which of two editions, set `product_id` to null and pass their words in `ask`: Agentcard adds what they settled and asks about the rest. Never add every product their words could mean.",
     "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.',
+    "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.",
+    'Never tell the shopper what has not happened yet or where things stand inside, such as "nothing\'s been charged yet", "your order isn\'t placed yet" or "the address isn\'t locked in", even when `reply` says it: ask for what is needed instead, such as "should it ship to 1 ferry plz?".',
+    'When `next_action` is `store_login`, `add_card` or `approve`, the message that asks for it is one short line and nothing else, even when `reply` says more, such as "sign in to doordash to place your order", "add your card to place the order" or "approve the payment to place your order (up to $19.02)": no recap of the cart, the address or the price, nothing about tax, delivery, shipping, a hold or what was charged, no word on when the link runs out, and never a request to tell you once it is done. On `approve`, put the cart\'s `max_charge` in the parentheses when it is set, and no other amount. Only when the shopper\'s last message picked what went in the cart does a line about the cart come first, as its own message; after an address, a phone number, a yes or a saved card, the ask is the whole reply.',
+    'When `next_action` is `confirm`, ask in one short message: the items, one total, and to say yes to place it, such as "1 carolina black socks pack from walmart, about $9.57. say yes to place it". Leave out the fees one by one, the hold, and the address unless the shopper just changed it.',
+    'Every line you write reaches the shopper, a line before you call this tool too: write to them as "you", never about "the shopper" or "the user", and never say what you are about to do with this tool, such as "I\'ll add them now".',
+    '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.',
+    "When the shopper asks what you can do or which stores you shop at, answer without calling this tool and with no line saying you are looking: one message that names at most four stores plus the kinds of things you can do, such as food delivery and restaurant reservations, then one that asks what they need. Every shopper can buy from Amazon, Walmart, Target and Best Buy, so name those, and no other store unless a result showed it.",
+    'Each paragraph you write reaches the shopper as its own message: give each one job and keep it under about 20 words. On a cart turn, write the confirmation and the one next step, such as "added a little cheeseburger from five guys, about $12.17 before delivery and tax" and then "next, sign in to doordash with the link so i can place it": one total, never a price breakdown your app\'s cart already shows (an app that shows no cart lists each line with its price) and never a fee by its name, rate or formula, such as an order fee, card processing or 2.9% + $0.30, even when `reply` or `fee_lines` names it, unless the shopper asks what the fees are, no promise to show the final total later, and nothing about passkeys, master passwords or Agentcard not seeing the card number unless the shopper asks.',
+    'Never listing products again is for offering choices: when you confirm what is in the cart, name each line by its item, such as "1 Dawn Ultra dish soap, 38 oz", never "the one you picked, shown in the card".',
+    'Say how long a link works only when the shopper asks, with `link_expires_in`, such as "it works for about 24 hours", never as a raw date and time or in UTC, such as `approval_expires_at` holds; when `link_expires_in` is null, say nothing about when it runs out.',
+    'Never call a product the shopper was sent "the card", in any language ("la tarjeta", "o cartão"): to the shopper a card is how they pay. Call it by its name, or "the one i sent".',
+    'When the cart has `total_leaves_out`, its `total` is before those: say so, such as "about $18.41 before tax and shipping", and never say it is with or includes tax, shipping or delivery.',
+    'When the shopper gave a budget, compare it with the cart\'s estimated `total`, never with `max_charge`: `max_charge` is a temporary hold, and what the order does not use is released. Warn about the budget only when `total`, or a shipping cost the result shows, is above it.',
+    "Never say how or on whose account an order is placed, and never send the shopper to their Agentcard dashboard, settings or account or ask them to link an account there, even when `reply` says to. When they ask for something an order can't do, such as Prime shipping, say plainly that it doesn't apply and what that means for the order, such as \"prime shipping doesn't apply on these orders, so amazon may add shipping on carts under about $35\".",
+    'Say what was found, never how searching works, even when `reply` says it: never how much of a store\'s stock shows, what a page or a link showed, or whether a store picked something. Say the outcome and the next step, such as "i couldn\'t find it at best buy. want me to check amazon?". Only when the shopper asks what the search covers, answer in one plain line.',
+    'Agentcard charges nothing for a reservation, but the restaurant may take a card on its own page: say what it takes only from the cart\'s item line, which names a "card hold", a "deposit" or "prepaid" when there is one, the same way every time, and never give a reservation a most-you-could-be-charged amount.',
+    'Ask the shopper to "let me know", never "text me", unless your app is a text-message chat.',
+    'Name only the stores and products that reach the shopper as cards in this result, never others in passing, such as "five guys and mcdonald\'s deliver there too", even when `reply` names them: to offer more, ask "want other options?". This is for what you suggest: when you show the cart or ask for a yes to it, name what is in it.',
 ].join(' ');
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
 export function buyToolDefinition() {
@@ -46,7 +74,7 @@ export function buyToolDefinition() {
                     type: 'boolean',
                     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.' },
+                new_order: { type: 'boolean', description: 'True only when the shopper drops the cart to start a new order. False when they drop one of several carts, and 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.",

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatureReason, type AgentcardEvent, type VerifyOptions, } from './verify.js';
 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 { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, 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 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 { 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 BuyCartBuilding, 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, 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, type BuyToolModelStore, } from './model-view.js';
+export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
+export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION, type AckForOptions } from './ack.js';
+export { forModel, forModelError, replyAsWritten, 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 { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, type AgentcardEventType, } from './events.js';

package/dist/index.js

@@ -1,13 +1,14 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, } from './verify.js';
 export { readPurchaseMessage, } from './message.js';
-export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, } from './shopper-message.js';
+export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, } from './shopper-message.js';
 export { agentcardWebhook, purchaseAgentWebhook, } from './handler.js';
 export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, typingDelay, } from './messages.js';
-export { buyTool, } from './buy-tool.js';
-export { instantAck, ackFor } from './ack.js';
-export { forModel, forModelError, stripLinks, } from './model-view.js';
+export { buyTool, nextStepPrompt, productAction, } from './buy-tool.js';
+export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION } from './ack.js';
+export { forModel, forModelError, replyAsWritten, stripLinks, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
 export { listenToAgentcard, } from './listen.js';
+export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, } from './events.js';

package/dist/message.d.ts

@@ -12,12 +12,20 @@ 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.
+ * - `cart_ready`: the store's checkout built the cart an answer named as still being built (`cart_building`), at the store's own total. Nothing is paid until the shopper says yes to it.
+ * - `cart_needs_input`: that checkout asks the shopper something first, such as a size, a delivery address, a sign-in to the store or an approval of the most the order can cost.
+ * - `cart_failed`: that checkout built no cart, and nothing was ordered or charged.
  */
-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' | 'cart_ready' | 'cart_needs_input' | 'cart_failed';
 /** 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 +36,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

@@ -16,17 +16,17 @@
 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.
+ * 1,500. With `pace: true`, `messageStream` and `buy.turn` wait this long between two messages, 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. */
+/** How messages are spaced: `false` (the default) not at all, `true` by `typingDelay`, 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. */
+/** The pause for each message `pace` asks for, or null for none, the default. 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;
@@ -49,11 +49,11 @@ export interface MessageStreamOptions {
      */
     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.
+     * How the messages are spaced. Default `false`: each message goes out the moment it is written.
+     * `true` spaces them 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, and time the model spent writing counts toward the pause. A
+     * function returns the pause in milliseconds for a message.
      */
     pace?: MessagePace;
     /**

package/dist/messages.js

@@ -122,8 +122,8 @@ const TYPING_MS_PER_CHARACTER = 12;
 const TYPING_MAX_MS = 1_500;
 /**
  * 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.
+ * 1,500. With `pace: true`, `messageStream` and `buy.turn` wait this long between two messages, 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
@@ -132,12 +132,12 @@ const TYPING_MAX_MS = 1_500;
 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. */
+/** The pause for each message `pace` asks for, or null for none, the default. Throws a TypeError for a pace that cannot work. */
 export function paceOf(pace) {
-    if (pace === undefined || pace === true)
-        return typingDelay;
-    if (pace === false)
+    if (pace === undefined || pace === false)
         return null;
+    if (pace === true)
+        return typingDelay;
     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) => {

package/dist/model-view.d.ts

@@ -11,10 +11,19 @@ import type { BuyNextAction } from './client.js';
 import type { BuyToolProduct, BuyToolResult, BuyToolStatus, BuyToolStore } from './buy-tool.js';
 export interface BuyToolModelCart {
     store: string;
+    /**
+     * `price` is one unit's; `line_total` is what the line costs with its add-ons and quantity, and the
+     * lines' totals add up before `fees`. `options` are the choices made on the line and `variant` the
+     * variant it is. `product_id` is the id the line's product carries in `products`, or null.
+     */
     items: Array<{
+        product_id: string | null;
         name: string;
         qty: number;
         price: string | null;
+        line_total: string | null;
+        options: string[];
+        variant: 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. */
@@ -26,6 +35,8 @@ export interface BuyToolModelCart {
     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;
+    /** What an estimated `total` leaves out, in words the model can repeat; null when the store priced the cart. */
+    total_leaves_out: string | null;
     /** 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;
 }
@@ -53,6 +64,13 @@ export interface BuyToolModelView {
     status: BuyToolStatus;
     /** The one thing to ask the shopper for in this message, or null when nothing waits on them. Never ask for a later step. */
     next_action: BuyNextAction | null;
+    /**
+     * The store whose checkout is still building the cart this answer named, absent when none is: its cart and total reach the
+     * shopper in a message from Agentcard, and only the shopper's yes to that total confirms it.
+     */
+    cart_building?: {
+        store: string;
+    };
     /** Agentcard's answer for the shopper, with every link taken out. */
     reply: string;
     /** The newest cart on the table. */
@@ -61,11 +79,24 @@ export interface BuyToolModelView {
     carts: BuyToolModelCart[];
     products: BuyToolModelProduct[];
     approval_expires_at: string | null;
+    /**
+     * How long the newest link this answer sent (Vault, approval or store login) still works, in words the
+     * shopper reads, such as `about 24 hours` or `about 15 minutes`; `no longer` once it ran out; null when
+     * Agentcard named no expiry. Read when the answer came back, so the model never reckons it from a timestamp.
+     */
+    link_expires_in: string | null;
+    /** True when the shopper need not reply to this answer, as when Agentcard places the order on its own. False beside a step `next_action` names, whose ask is one short line. */
     shopper_need_not_reply: boolean;
     /** True when the shopper already got a message this turn saying their request is being worked on, so the reply opens with no acknowledgement of its own. */
     shopper_already_told_looking: boolean;
     /** True when the shopper already has the link this answer needed. */
     link_sent: boolean;
+    /**
+     * 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. */
@@ -93,6 +124,15 @@ export declare function stripLinks(text: string): string;
  * decimal point, so 1331 is $13.31 in USD, CA$13.31 in CAD and ¥1,331 in JPY. An amount whose currency
  * Agentcard did not name shows with no symbol, because a dollar sign on it could be wrong.
  */
+/**
+ * A product's price as the shopper reads it: `$12.99`, or `from $10.69` for a product priced by a
+ * required choice (a size, a patty count), whose base price is often $0. Null when Agentcard named none.
+ */
+export declare function productPrice(product: {
+    priceCents: number | null;
+    currency: string | null;
+    priceFrom?: true;
+}): string | null;
 export declare function money(minor: number | null | undefined, currency: string | null | undefined): string | null;
 /**
  * The products the model reads: the first twenty that keep a name and a store
@@ -123,6 +163,8 @@ export declare function cardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'ur
  * 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;
+/** How long until `iso`, from `now`, as the shopper reads it: `about 24 hours`, `about 15 minutes`, `no longer`, or null. */
+export declare function expiresIn(iso: string | null | undefined, now?: number): 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
@@ -130,6 +172,19 @@ export declare function productCardKey(product: Pick<BuyToolProduct, 'id' | 'ref
  * reads as `needs_input`.
  */
 export declare function forModel(result: BuyToolResult): BuyToolModelView;
+/**
+ * Agentcard's reply, ready for the shopper as written, when the answer only asks them something: a
+ * `needs_input` answer with a reply, such as a product list, a size or a store to pick, or a cart's
+ * total and the ask for their yes. The reply comes with every link taken out, as the model reads it.
+ * Null for any other answer, which your model puts in its own words, and for a line the tool wrote
+ * itself for your model, such as the note that the cart changed or a `nextStep` turn's ask for the
+ * shopper's yes: only the reply Agentcard sent, as `envelope` holds it, is written for the shopper.
+ *
+ * ```ts
+ * replyAsWritten(result); // 'found two at Amazon. want the first one?'
+ * ```
+ */
+export declare function replyAsWritten(result: BuyToolResult): string | null;
 /**
  * A thrown error as the model may read it: the same message with every link
  * taken out, and the original error on `cause` for your logs. A TypeError