@agent-cards/commerce-sdk 0.15.0 → 0.17.0

package/dist/client.d.ts

@@ -127,6 +127,12 @@ export interface BuyStreamHandlers {
     onCatalog?: (update: BuyCatalogUpdate) => void | Promise<void>;
     /** Each message Agentcard writes, the moment it is written. */
     onSegment?: (update: BuySegmentUpdate) => void | Promise<void>;
+    /**
+     * The line that says what Agentcard is looking for, such as `one sec, checking target for la croix`, written while the
+     * search runs on an ask for something new. It comes before the turn's cards and messages, or not at all, and the
+     * answer's `messages` never hold it.
+     */
+    onAck?: (update: BuySegmentUpdate) => void | Promise<void>;
     /** The carts, each time the turn builds or changes one. */
     onCart?: (update: BuyCartUpdate) => void | Promise<void>;
     /** Each piece of a message as Agentcard writes it. Passing it asks Agentcard for the pieces (`?stream=deltas`). */
@@ -234,6 +240,8 @@ export interface BuyRequest {
     delivery_address?: BuyDeliveryAddress;
     external_user_id?: string;
     user_id?: string;
+    /** `false` asks for no line that says what Agentcard is looking for (`onAck`): the shopper already read one. */
+    ack?: false;
 }
 export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
 export interface BuyStore {
@@ -373,6 +381,32 @@ export interface BuyStorePick {
     name: string | null;
     selected: boolean;
 }
+/** One value the shopper picks from. `id` is the option id the cart takes, null when the shopper's words answer it. */
+export interface BuyChoiceOption {
+    id: string | null;
+    label: string;
+    /** What choosing it adds to the price, in cents: 0 when free, null when the store does not say. */
+    price_delta_cents: number | null;
+}
+/** One group of values, such as a sandwich's bread or a shirt's size. `min` and `max` count the values picked; `max` null for no limit. */
+export interface BuyChoiceGroup {
+    name: string;
+    required: boolean;
+    min: number;
+    max: number | null;
+    options: BuyChoiceOption[];
+}
+/**
+ * The choice an answer's reply asks the shopper to make, as data: the question, the item it is about, where the values come
+ * from (`menu_item`: a restaurant item's options, `store_checkout`: a store's own size or colour question, `catalog_variant`:
+ * a product's sizes or colours in stock), and every group with its values.
+ */
+export interface BuyChoice {
+    question: string | null;
+    item: string | null;
+    source: string;
+    groups: BuyChoiceGroup[];
+}
 export interface BuyPaymentSource {
     source: string;
     brand: string | null;
@@ -435,6 +469,8 @@ export interface BuyTurn {
     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 choice the reply asks the shopper to make, each group with every value; null when it asks none, and on an older API. */
+    choice: BuyChoice | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -506,6 +542,8 @@ export declare class AgentcardApiError extends Error {
 }
 /** A turn as Agentcard answers it. */
 export declare function turnOf(body: Record<string, unknown>): BuyTurn;
+/** An answer's `choice`, its groups with at least one value each, or null when it carries none. */
+export declare function choiceOf(value: unknown): BuyChoice | null;
 /** 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. */

package/dist/client.js

@@ -11,7 +11,7 @@
 import { isRecord } from './verify.js';
 import { listenToAgentcard } from './listen.js';
 /** The handlers that ask Agentcard to stream a turn. */
-const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onCart', 'onDelta', 'onAvailability'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability'];
 const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -299,9 +299,20 @@ export function turnOf(body) {
         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),
+        choice: choiceOf(body.choice),
         raw: body,
     };
 }
+/** An answer's `choice`, its groups with at least one value each, or null when it carries none. */
+export function choiceOf(value) {
+    if (!isRecord(value) || !Array.isArray(value.groups))
+        return null;
+    const groups = value.groups.filter(isRecord).flatMap((g) => {
+        const options = (Array.isArray(g.options) ? g.options : []).filter(isRecord).flatMap((o) => str(o.label) ? [{ id: str(o.id), label: o.label.trim(), price_delta_cents: num(o.price_delta_cents) }] : []);
+        return options.length ? [{ name: str(g.name) ?? '', required: g.required === true, min: num(g.min) ?? 0, max: num(g.max), options }] : [];
+    });
+    return groups.length ? { question: str(value.question), item: str(value.item), source: str(value.source) ?? '', groups } : null;
+}
 /** 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;
@@ -524,6 +535,9 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             else if (event === 'segment' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onSegment) {
                 deliver(() => stream.onSegment({ conversationId: named, text: data.text }));
             }
+            else if (event === 'ack' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onAck) {
+                deliver(() => stream.onAck({ conversationId: named, text: data.text }));
+            }
             else if (event === 'venue_availability' && stream.onAvailability && str(data.conversation_id) && Array.isArray(data.items)) {
                 const items = data.items.filter(isRecord).flatMap((i) => {
                     const id = str(i.id);

package/dist/definition.js

@@ -13,6 +13,7 @@ export const BUY_TOOL_DESCRIPTION = [
     '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 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.",
+    'When the shopper asks you to find, buy, book or order something new, such as a product, a gift idea, a meal, a table, a flight or a store page they pasted a link to, first write one short line that says what you are about to look for, then call this tool in the same reply: only what they asked for, and the store or place they named, in their own words, such as "on it, looking for la croix at target", "one sec, checking nopa for a table for 2 at 7pm" or, for a pasted link, "one sec, checking that link", never a price, a total, stock, a result, a question or that anything was found, added or ordered. A store named by its site, such as "the polishing cloth from myrqvist.com", is a store, not a link. For a yes, a pick, a size, an address, a code, a change to a cart or a question about an order, write no line first, and after this tool answers, never say again that you are looking.',
     'When `shopper_already_read_reply` is true, the shopper already read `reply` as Agentcard wrote it, so never say it again in any words: answer with only what `reply` leaves out, in one short line, or with nothing.',
     '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.',
@@ -42,6 +43,7 @@ export const BUY_TOOL_DESCRIPTION = [
     "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 `yes_carried` is set, the shopper already said yes to this cart, or picked it (`yes_carried.picked`), and Agentcard went ahead on it once they finished the step outside the chat, so never ask for their yes again: ask only for the step `next_action` names. When `yes_carried.total_changed` is true, that one short line opens with the new total, the one price it names beside `max_charge`, such as "it\'s $17.89 with fees and tax now. approve the payment to place your order (up to $19.02)".',
     '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.',
@@ -52,6 +54,7 @@ export const BUY_TOOL_DESCRIPTION = [
     "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".',
+    'When you list options or choices for the shopper, such as sizes, breads, times, or stores no card shows, write one per line, each starting with "• ", in the same paragraph as the line that asks which one, so the question and its choices reach the shopper as one message. When the result has `choice`, list every value it holds that way, with its extra price, such as "• Gluten-free bread (+$2.46)", even when `reply` names them inside a sentence. The products and stores the cards show are still never listed again.',
     '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.',

package/dist/direct.d.ts

@@ -1,7 +1,10 @@
 import type { BuyNextAction } from './client.js';
 import type { BuyToolInput } from './definition.js';
-/** Why a message goes straight to Agentcard. */
-export type DirectReason = 'product_ask' | 'pick' | 'answer' | 'confirm';
+/**
+ * Why a message goes straight to Agentcard. `next_step` is a turn `buy.nextStep` opened: its call reads where the
+ * purchase stands and goes on from there whatever the model would write, so it never needs the model to decide it.
+ */
+export type DirectReason = 'product_ask' | 'pick' | 'answer' | 'confirm' | 'next_step';
 /** The buy call for a message that goes straight to Agentcard, and why it does. */
 export interface DirectCall {
     input: BuyToolInput;
@@ -18,11 +21,21 @@ export interface DirectContext {
     nextAction?: BuyNextAction | null;
     /** Agentcard's last reply, the question a short answer answers. */
     asked?: string | null;
-    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends. */
+    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends. A place (`the second one`) reads these. */
     products?: ReadonlyArray<{
         productId: string | null;
         name: string;
     }>;
+    /**
+     * Every product card the shopper can tap by its name, each once: the answer's and the ones its searches sent as they answered,
+     * which an answer about one item can leave out (a menu turn that answered with the Burrito beside eight menu cards). A pick by
+     * name (a card's tap, a product's whole name, a word only one name holds) reads these; a place never does, so `the last one` is
+     * the last of `products`. Left out, `products` stands for both.
+     */
+    tappable?: ReadonlyArray<{
+        productId: string | null;
+        name: string;
+    }>;
     /** The stores Agentcard's last answer showed, with the `store_id` a pick sends. */
     stores?: ReadonlyArray<{
         storeId: string;

package/dist/direct.js

@@ -9,7 +9,10 @@
  * - a pick of what Agentcard just showed, by a card's tap (`I'll take the KODAK AA (24 Pack) ($13.49)`,
  *   `Order from Shake Shack`), its place (`the first one`, `#2`, `1 and 3`) or a reference (`that one`);
  * - the answer to the question Agentcard just asked: the address, name or code it asked for, a short
- *   answer such as `medium` or `size 9`, or a plain yes to the total it asked the shopper to confirm.
+ *   answer such as `medium` or `size 9`, or a plain yes to the total it asked the shopper to confirm;
+ * - a price limit for the products Agentcard just showed: `only options under $20`, `under 20`, `cheaper ones`.
+ *   Agentcard holds its cards to the limit and shows the ones inside it again as cards; your model, answering
+ *   from the list it saw, named two products with no card to tap (2026-10-27).
  *
  * Everything else goes to the model: a question, small talk, a change of mind (`no`, `wait`, `cancel`),
  * a command to the cart, and anything about the account, an order or how the chat works. A pick or an
@@ -21,6 +24,11 @@
  * the 188 labelled messages in `test/fixtures/direct-messages.json`, it sends none it should not.
  */
 import { ABOUT, ACKNOWLEDGED, CAPABILITY, CART_COMMAND, CHECKOUT, CHITCHAT, FILLER, asksForDetails, isNewRequest, isPickText, namesStore, plain } from './ack.js';
+/**
+ * A price limit put on what was just shown: `under $20`, `under 20`, `less than 15 bucks`, `between 10 and 20`, `$20 or
+ * less`, `over $50`, `cheaper ones`, `menos de 20`. Only whether the message states one: Agentcard reads the limit itself.
+ */
+const PRICE_REFINE = /(?:\b(?:under|below|less than|cheaper than|up to|at most|no more than|max(?:imum)?|between|over|above|more than|at least|menos de|hasta|entre)\s+\$?\s?\d)|\$\s?\d+(?:\.\d{1,2})?\s*(?:or (?:less|under|below|more)|and (?:under|below|up)|max|tops|\+)|\b\d+\s*(?:dollars|bucks)\b|\b(?:cheaper|less expensive|more affordable|lower[- ]priced)\b(?!\s+than\b)|\bm[aá]s barat/;
 /** The longest message that goes straight: a long one is read by the model. */
 const MAX_CHARS = 500;
 /** The steps a shopper answers with their own details or a code. */
@@ -143,9 +151,17 @@ function placesOf(bare, count) {
 function nameWords(text) {
     return String(text ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
 }
+/** A card's tap as an app writes it, `I'll take the <name> (<price>)`: the name in it, or null for any other message. */
+const TAP = /^(?:i'?ll (?:take|have|get)|i want|add)\s+(?:the\s+)?(.+?)\s*\(\s*(?:[$€£]\s?\d[\d,]*(?:\.\d{1,2})?|from [$€£]\s?\d[\d,]*(?:\.\d{1,2})?)\s*\)\s*[.!]?$/i;
+function tappedName(raw) {
+    const name = TAP.exec(raw.trim())?.[1]?.trim();
+    return name ? name : null;
+}
 /** The pick a message makes of what Agentcard just showed, null when it picks nothing, or false when it counts past the list. */
 function pickOf(raw, bare, context) {
     const products = context.products ?? [];
+    // A pick by name reads every card the shopper can tap; a place reads `products`, in the order the answer showed them.
+    const byName = context.tappable?.length ? context.tappable : products;
     const stores = context.stores ?? [];
     const call = (fields) => ({ input: { ask: raw, confirm: false, new_order: false, product_id: null, store_id: null, ...fields }, reason: 'pick' });
     if (stores.length > 0) {
@@ -159,18 +175,26 @@ function pickOf(raw, bare, context) {
         if (named.length > 1)
             return call({});
     }
-    if (products.length > 0) {
-        // A card's tap names the product whole: `I'll take the KODAK AA Alkaline Batteries (24 Pack) ($13.49)`.
+    if (byName.length > 0) {
+        // A card's tap names the product whole, `I'll take the Burrito Bowl ($15.15)`: the product of exactly that name is the pick,
+        // never the Burrito whose one word it shares, and a tap that names no product here (a card this list does not hold), or two
+        // alike, sends none, so Agentcard reads the words against every card it showed.
+        const tap = tappedName(raw);
+        if (tap !== null) {
+            const exact = byName.filter((product) => [nameWords(tap), nameWords(`the ${tap}`)].includes(nameWords(product.name)));
+            return call(exact.length === 1 ? { product_id: exact[0].productId } : {});
+        }
+        // A product's whole name inside the message: `I want the KODAK AA Alkaline Batteries (24 Pack)`.
         const said = nameWords(raw);
-        const named = products.filter((product) => nameWords(product.name).length >= 12 && said.includes(nameWords(product.name)));
+        const named = byName.filter((product) => nameWords(product.name).length >= 12 && said.includes(nameWords(product.name)));
         if (named.length === 1)
             return call({ product_id: named[0].productId });
         if (named.length > 1)
             return call({});
         // A word only one product's name holds, such as its brand: `lets do the coppertop ones`, `duracell 24 count is fine`.
         const words = new Set(said.split(' '));
-        const owners = (word) => products.filter((product) => nameWords(product.name).split(' ').includes(word));
-        const marked = products.filter((product) => nameWords(product.name).split(' ').some((word) => word.length >= 4 && !/^\d/.test(word) && words.has(word) && owners(word).length === 1));
+        const owners = (word) => byName.filter((product) => nameWords(product.name).split(' ').includes(word));
+        const marked = byName.filter((product) => nameWords(product.name).split(' ').some((word) => word.length >= 4 && !/^\d/.test(word) && words.has(word) && owners(word).length === 1));
         if (marked.length === 1 && said.split(' ').length <= 10 && !QUESTION_START.test(bare) && !DOUBT.test(said))
             return call({ product_id: marked[0].productId });
         const places = placesOf(bare, products.length);
@@ -182,7 +206,7 @@ function pickOf(raw, bare, context) {
         if (/^(?:both|all|all of them|both of them|all three|all 3)$/.test(bare))
             return call({});
     }
-    if ((products.length > 0 || stores.length > 0) && isPickText(raw))
+    if ((byName.length > 0 || stores.length > 0) && isPickText(raw))
         return call({});
     return null;
 }
@@ -220,6 +244,9 @@ export function directCall(shopperText, context = {}) {
                 return null;
             if (pick)
                 return pick;
+            // A price limit on the products just shown: Agentcard shows the ones inside it again, as cards.
+            if ((ctx.products ?? []).length > 0 && PRICE_REFINE.test(words) && words.split(' ').length <= 15)
+                return plainCall('product_ask');
             // The address, name or code Agentcard asked for: what the shopper sends is the answer, unless it objects.
             const details = (typeof ctx.nextAction === 'string' && DETAIL_STEPS.has(ctx.nextAction)) || asksForDetails(ctx.asked);
             if (details && !OBJECTION.test(words) && !REQUEST_START.test(bare) && !QUESTION_START.test(bare) && !PAST.test(words) && !/\b(?:same as|on file|you have|the usual|ur|your)\b/.test(words) && !/^(?:resend|send|again|still)\b/.test(bare) && !NOT_SHOPPING.test(words) && words.split(' ').length <= 40)

package/dist/index.d.ts

@@ -1,14 +1,16 @@
 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, NEXT_STEP_KINDS, type NextStepKind, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
+export { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderStep, type OrderPathStep, type OrderStepState, type ArrivalTextOptions, } from './order.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 AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, 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 { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, 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, type BuyChoice, type BuyChoiceGroup, type BuyChoiceOption, } 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, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolAvailability, 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 { directCall, isProductAsk, type DirectCall, type DirectContext, type DirectReason } from './direct.js';
-export { forModel, forModelError, replyAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } from './model-view.js';
+export { forModel, forModelError, stepAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
+export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice, type ReplyAsWrittenOptions } from './texting.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';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, } from './verify.js';
 export { readPurchaseMessage, } from './message.js';
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, } from './shopper-message.js';
+export { ORDER_STEPS, updateOrder, arrivalText, } from './order.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';
@@ -8,7 +9,8 @@ export { toMessages, messageStream, typingDelay, } from './messages.js';
 export { buyTool, nextStepPrompt, productAction, } from './buy-tool.js';
 export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION } from './ack.js';
 export { directCall, isProductAsk } from './direct.js';
-export { forModel, forModelError, replyAsWritten, withoutCardList, stripLinks, } from './model-view.js';
+export { forModel, forModelError, stepAsWritten, withoutCardList, stripLinks, } from './model-view.js';
+export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice } from './texting.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';

package/dist/messages.d.ts

@@ -1,19 +1,39 @@
 /**
- * Text cut into the messages a shopper reads one at a time. A chat app sends each paragraph as its
- * own message, so a reply written as three paragraphs arrives as three texts. A blank line ends a
- * paragraph, with two exceptions that keep a block whole: a fenced code block, and a list whose
- * items a blank line separates.
+ * Joins each message that leads in with a colon (`two options came in under $20:`) to the message after it, so a shopper
+ * never reads a bubble that ends on a colon: the lead-in and its first item or list arrive as one message, a line apart.
+ * `add` returns the message to send, or null while it holds a lead-in for the next one. `end` returns what a held lead-in
+ * leaves once nothing followed it, such as when every item it led into went because the cards show them: the text less
+ * its colon sentence (withoutLeadIn), or null when nothing is left. On 2026-10-27 a chat showed "two options came in
+ * under $20:" as a bubble of its own, above the item it led into.
  */
+export declare function leadInJoiner(): {
+    add(message: string): string | null;
+    end(): string | null;
+};
 /**
  * The text as separate messages, in order: one per paragraph, each trimmed, with empty ones left
  * out. One or more blank lines end a paragraph. A fenced code block stays one message whatever blank
- * lines it holds, and so does a list whose items blank lines separate.
+ * lines it holds, and so does a list whose items blank lines separate. A paragraph that ends with a
+ * colon goes with the paragraph after it, one line apart, and loses its colon sentence when nothing
+ * follows it, so no message ends on a colon.
  *
  * ```ts
  * toMessages('Found two.\n\nWant the first one?'); // ['Found two.', 'Want the first one?']
+ * toMessages('two came in under $20:\n\n• Everydaze, $8.99'); // ['two came in under $20:\n• Everydaze, $8.99']
  * ```
  */
 export declare function toMessages(text: string): string[];
+/**
+ * The text's paragraphs as `toMessages` cuts them, before any lead-in joins the paragraph after it: the units Agentcard
+ * and a model write, and what a count of the messages a shopper read is checked against, paragraph for paragraph.
+ */
+export declare function paragraphsOf(text: string): string[];
+/**
+ * Messages in order, each one that leads in with a colon joined to the ones after it by one joiner across them all
+ * (leadInJoiner), so a lead-in that is a whole message of its own, as one of Agentcard's `messages` can be, still goes
+ * with the message after it, and a lead-in nothing follows at the very end loses its colon sentences.
+ */
+export declare function joinLeadIns(messages: readonly string[]): string[];
 /**
  * How long someone texting takes to type `message`, in milliseconds: 300, plus 12 a character, at most
  * 1,500. With `pace: true`, `messageStream` and `buy.turn` wait this long between two messages, so a
@@ -67,7 +87,8 @@ export interface MessageStreamOptions {
  * 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.
+ * whether the list goes on, and a paragraph that ends with a colon waits for the paragraph after it,
+ * so the two go out as one message. `end` hands over the last message and waits for every send.
  *
  * ```ts
  * const paragraphs = messageStream({ onMessage: (text) => sendToShopper(text) });

package/dist/messages.js

@@ -2,18 +2,20 @@
  * Text cut into the messages a shopper reads one at a time. A chat app sends each paragraph as its
  * own message, so a reply written as three paragraphs arrives as three texts. A blank line ends a
  * paragraph, with two exceptions that keep a block whole: a fenced code block, and a list whose
- * items a blank line separates.
+ * items a blank line separates. A paragraph that leads in with a colon never stands alone: it goes out
+ * with the one after it (leadInJoiner).
  */
+import { leadsIn, withoutLeadIn } from './sentences.js';
 /** A line holding nothing but spaces or tabs. */
 const BLANK = /^[ \t]*$/;
-/** A list item: `-`, `*` or `+`, or a number followed by `.` or `)`, then a space or the line's end. */
-const LIST_ITEM = /^ {0,3}(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)/;
+/** A list item: `-`, `*`, `+` or the bullet `•`, or a number followed by `.` or `)`, then a space or the line's end. */
+const LIST_ITEM = /^ {0,3}(?:[-*+•]|\d{1,9}[.)])(?:[ \t]|$)/;
 /** A list item whose marker a space already follows, the only kind a line still being written is sure to stay. */
-const LIST_ITEM_SPACED = /^ {0,3}(?:[-*+]|\d{1,9}[.)])[ \t]/;
+const LIST_ITEM_SPACED = /^ {0,3}(?:[-*+•]|\d{1,9}[.)])[ \t]/;
 /** A line indented under a list item: two spaces or a tab, then text. */
 const INDENTED = /^(?: {2,}|\t)\S/;
 /** The start of a line that can still grow into a list item or an indented line once more text arrives. */
-const MAYBE_ITEM = /^ {0,3}(?:[-*+]|\d{1,9}[.)]?)?$|^[ \t]*$/;
+const MAYBE_ITEM = /^ {0,3}(?:[-*+•]|\d{1,9}[.)]?)?$|^[ \t]*$/;
 /** A code fence: three or more backticks or tildes, indented by at most three spaces. */
 const FENCE = /^ {0,3}(`{3,}|~{3,})/;
 /** How the line after a blank line inside a list reads: it continues the list, it ends it, or it is too short to tell. */
@@ -30,6 +32,29 @@ function closesFence(line, open) {
     const match = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
     return !!match && match[1][0] === open[0] && match[1].length >= open.length;
 }
+/**
+ * Joins each message that leads in with a colon (`two options came in under $20:`) to the message after it, so a shopper
+ * never reads a bubble that ends on a colon: the lead-in and its first item or list arrive as one message, a line apart.
+ * `add` returns the message to send, or null while it holds a lead-in for the next one. `end` returns what a held lead-in
+ * leaves once nothing followed it, such as when every item it led into went because the cards show them: the text less
+ * its colon sentence (withoutLeadIn), or null when nothing is left. On 2026-10-27 a chat showed "two options came in
+ * under $20:" as a bubble of its own, above the item it led into.
+ */
+export function leadInJoiner() {
+    let held = null;
+    return {
+        add(message) {
+            const whole = held === null ? message : `${held}\n${message}`;
+            held = leadsIn(whole) ? whole : null;
+            return held === null ? whole : null;
+        },
+        end() {
+            const rest = held === null ? '' : withoutLeadIn(held);
+            held = null;
+            return rest || null;
+        },
+    };
+}
 /**
  * Reads text line by line and closes each message once nothing later can change it. It keeps only
  * the message being built, so text fed in pieces costs what the text costs once.
@@ -102,19 +127,47 @@ class Scanner {
 /**
  * The text as separate messages, in order: one per paragraph, each trimmed, with empty ones left
  * out. One or more blank lines end a paragraph. A fenced code block stays one message whatever blank
- * lines it holds, and so does a list whose items blank lines separate.
+ * lines it holds, and so does a list whose items blank lines separate. A paragraph that ends with a
+ * colon goes with the paragraph after it, one line apart, and loses its colon sentence when nothing
+ * follows it, so no message ends on a colon.
  *
  * ```ts
  * toMessages('Found two.\n\nWant the first one?'); // ['Found two.', 'Want the first one?']
+ * toMessages('two came in under $20:\n\n• Everydaze, $8.99'); // ['two came in under $20:\n• Everydaze, $8.99']
  * ```
  */
 export function toMessages(text) {
-    const messages = [];
-    const scanner = new Scanner((message) => messages.push(message));
+    return joinLeadIns(paragraphsOf(text));
+}
+/**
+ * The text's paragraphs as `toMessages` cuts them, before any lead-in joins the paragraph after it: the units Agentcard
+ * and a model write, and what a count of the messages a shopper read is checked against, paragraph for paragraph.
+ */
+export function paragraphsOf(text) {
+    const paragraphs = [];
+    const scanner = new Scanner((paragraph) => paragraphs.push(paragraph));
     for (const line of String(text ?? '').replace(/\r\n?/g, '\n').split('\n'))
         scanner.line(line);
     scanner.end();
-    return messages;
+    return paragraphs;
+}
+/**
+ * Messages in order, each one that leads in with a colon joined to the ones after it by one joiner across them all
+ * (leadInJoiner), so a lead-in that is a whole message of its own, as one of Agentcard's `messages` can be, still goes
+ * with the message after it, and a lead-in nothing follows at the very end loses its colon sentences.
+ */
+export function joinLeadIns(messages) {
+    const leads = leadInJoiner();
+    const out = [];
+    for (const message of messages) {
+        const ready = leads.add(message);
+        if (ready)
+            out.push(ready);
+    }
+    const rest = leads.end();
+    if (rest)
+        out.push(rest);
+    return out;
 }
 /** 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;
@@ -171,7 +224,8 @@ export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * 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.
+ * whether the list goes on, and a paragraph that ends with a colon waits for the paragraph after it,
+ * so the two go out as one message. `end` hands over the last message and waits for every send.
  *
  * ```ts
  * const paragraphs = messageStream({ onMessage: (text) => sendToShopper(text) });
@@ -247,10 +301,15 @@ export function messageStream(options) {
             });
         }
     };
-    const scanner = new Scanner((message) => {
+    // A paragraph that leads in with a colon waits for the one after it, so the two go out as one message.
+    const leads = leadInJoiner();
+    const send = (message) => {
+        if (!message)
+            return;
         queue.push(message);
         kick();
-    });
+    };
+    const scanner = new Scanner((paragraph) => send(leads.add(paragraph)));
     return {
         push(delta) {
             if (ended)
@@ -273,6 +332,7 @@ export function messageStream(options) {
                     scanner.line(line);
                 open = '';
                 scanner.end();
+                send(leads.end());
             }
             while (running)
                 await running;

package/dist/model-view.d.ts

@@ -107,6 +107,18 @@ export interface BuyToolModelView {
         product_id: string | null;
         in_cart: boolean;
     } | null;
+    /**
+     * The choice the reply asks the shopper to make, absent when it asks none: each group's name and its values with their
+     * extra price, such as `Gluten-free bread (+$2.46)`. List them one per line, each starting with `• `, under the question.
+     */
+    choice?: {
+        question: string | null;
+        groups: Array<{
+            name: string;
+            required: boolean;
+            options: string[];
+        }>;
+    };
     /** 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. */
@@ -116,6 +128,17 @@ export interface BuyToolModelView {
         store_id: string;
         selected: boolean;
     } | null;
+    /**
+     * Present when this answer went ahead on the yes the shopper already gave in the chat, after a step they finished
+     * outside it, or on their pick of what is in the cart (`picked`): the total they said yes to, or the chat last showed
+     * them, the cart's total now, and whether it changed. Never ask for their yes again.
+     */
+    yes_carried?: {
+        said_yes_to: string;
+        total: string;
+        total_changed: boolean;
+        picked?: true;
+    };
 }
 /**
  * The text with every link taken out: a Markdown link keeps its label, an address with a path or a scheme goes
@@ -183,6 +206,16 @@ export declare function expiresIn(iso: string | null | undefined, now?: number):
  * reads as `needs_input`.
  */
 export declare function forModel(result: BuyToolResult): BuyToolModelView;
+/**
+ * The fixed short line for an answer whose next step is a link the shopper already holds: `add your card to place the
+ * order`, `sign in to DoorDash to place your order`, or `approve the payment to place your order (up to $19.02)`, with
+ * the most the shopper can be charged in the parentheses when the cart names it. After the shopper's own words put the
+ * cart together, a line about the cart comes first, as its own message. After a yes the turn carried past a step outside
+ * the chat, a total that changed opens the ask: `it's $17.89 with fees and tax now. approve the payment ...`. Null for any
+ * other answer, when the link did not go out, when the shopper already read Agentcard's own ask through `onText`, when a
+ * card or approval step has no cart to place, and when the answer also showed products.
+ */
+export declare function stepAsWritten(result: BuyToolResult): string | null;
 /**
  * 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
@@ -191,25 +224,39 @@ export declare function forModel(result: BuyToolResult): BuyToolModelView;
  * 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.
  * Null as well once the shopper read the reply through `onText` (`shopper_already_read_reply`).
+ * An answer whose next step is a link the call handed over reads as that step's fixed short line
+ * instead (`stepAsWritten`), whoever wrote the reply.
  *
  * ```ts
  * replyAsWritten(result); // 'found two at Amazon. want the first one?'
  * ```
  */
 export declare function replyAsWritten(result: BuyToolResult): string | null;
+/** A card the shopper holds: a product's or a store's name and, for a product, its price as the model reads it (`$22.89`, `from $10.69`). */
+export interface ShownCard {
+    name: string;
+    price?: string | null;
+}
 /**
  * Agentcard's reply without the list its cards already show the shopper: each list line that names a product or
  * store whose card went out, the line that led into that list (`here are a few:`, `other choices:`), a sentence that
- * points at a number the list gave (`the dishwand in #8`), and, past the one or two products a reply recommends in
- * words, each further sentence that names another card. What is left is the reply around the list, such as `found
- * these at amazon.` and `which one do you want?`. A reply whose cards went out names none of them twice over.
+ * points at a number the list gave (`the dishwand in #8`), a sentence that goes on to more of the list (`other 6-packs
+ * are ...`, `there's also ...`) and names a card, and, past the one or two products a reply recommends in words, each
+ * further sentence that names another card. A list written on one line goes the same way, item by item (inlineList),
+ * and so does a list line written without a bullet, whole, up to the question on it. What is left is the reply around
+ * the list, such as `found these at amazon.` and `which one do you want?`. A reply whose cards went out names none of
+ * them twice over. A list that keeps an item for a product no card shows keeps its lead-in, and the two read as one
+ * message (toMessages), so the shopper never reads `two options came in under $20:` on its own.
+ *
+ * Each card is its name, or its name and its price as the model reads it (`{ name, price: '$22.89' }`): with the price,
+ * a reply's short name for the product, such as `Planet Oat Extra Creamy ($22.89)`, reads as its card (cardsNamed).
  *
  * ```ts
  * withoutCardList('Two I'd suggest:\n- Duracell AA, 24 pack, $20.78\n\nWhich one?', ['Duracell AA Batteries, 24 Count']);
  * // 'Which one?'
  * ```
  */
-export declare function withoutCardList(reply: string, cardNames: readonly string[]): string;
+export declare function withoutCardList(reply: string, cardNames: readonly (string | ShownCard)[]): string;
 /**
  * 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