@agent-cards/commerce-sdk 0.14.0 → 0.16.0

package/dist/client.d.ts

@@ -51,6 +51,30 @@ export interface BuyCatalogUpdate {
     /** The products found past the cards, in the order they were found, to show on "show more" with no new search. */
     more: BuyCatalog['items'];
 }
+/**
+ * Whether a place a card shows has room at the time the shopper asked for: `checking` while Agentcard's live search runs,
+ * `available` once it found the place open, with the open times it named in `slots` (empty when it named none),
+ * `unavailable` when it found the place full then, and `unknown` when the search ended without saying either way. Only
+ * `available` is a place to offer as a choice. A product with no such question, such as a retail product, carries none.
+ */
+export type BuyAvailability = {
+    status: 'checking';
+} | {
+    status: 'available';
+    slots: string[];
+} | {
+    status: 'unavailable';
+} | {
+    status: 'unknown';
+};
+/** What Agentcard's live search said of the places a running turn's cards show, matched to each card by its catalog `id`. */
+export interface BuyAvailabilityUpdate {
+    conversationId: string;
+    items: Array<{
+        id: string;
+        availability: BuyAvailability;
+    }>;
+}
 /** How many products a running turn found so far, and how many of them it shows: "8 of 23 shown". */
 export interface BuyFoundUpdate {
     conversationId: string;
@@ -107,6 +131,8 @@ export interface BuyStreamHandlers {
     onCart?: (update: BuyCartUpdate) => void | Promise<void>;
     /** Each piece of a message as Agentcard writes it. Passing it asks Agentcard for the pieces (`?stream=deltas`). */
     onDelta?: (update: BuyDeltaUpdate) => void | Promise<void>;
+    /** Whether the places the turn's cards show have room, once Agentcard's live search says, after the cards it changes. */
+    onAvailability?: (update: BuyAvailabilityUpdate) => void | Promise<void>;
 }
 export declare 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. */
@@ -301,6 +327,8 @@ export interface BuyCatalogItem {
     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;
+    /** Whether a place has room at the asked time (BuyAvailability). Absent on a product with no such question. */
+    availability?: BuyAvailability;
 }
 /**
  * The products the last search found. `presented` is true when this answer's reply presents them: the
@@ -345,6 +373,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;
@@ -407,6 +461,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>;
 }
@@ -478,6 +534,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'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', '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. */
@@ -223,9 +223,30 @@ function catalogItemsOf(v) {
             ...(flight ? { flight } : {}),
             store: storeOf(i.store),
             url: pageUrl(i.url),
+            ...availabilityField(i),
         };
     }) : [];
 }
+/**
+ * A place's availability as Agentcard marks it: `checking`, `open` or `available` with the times in `slots`, `none` or
+ * `unavailable`, and `unknown`. A mark this version does not know reads as `unknown`, so no place is offered on a guess.
+ */
+function availabilityOf(v) {
+    const mark = v.availability;
+    if (mark === 'checking')
+        return { status: 'checking' };
+    if (mark === 'open' || mark === 'available') {
+        const slots = Array.isArray(v.slots) ? v.slots.filter((s) => typeof s === 'string' && s.trim() !== '') : [];
+        return { status: 'available', slots };
+    }
+    if (mark === 'none' || mark === 'unavailable')
+        return { status: 'unavailable' };
+    return typeof mark === 'string' ? { status: 'unknown' } : null;
+}
+function availabilityField(v) {
+    const availability = availabilityOf(v);
+    return availability ? { availability } : {};
+}
 /** A count Agentcard sent: a whole number, never negative. Null otherwise. */
 function countOf(v) {
     return typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : null;
@@ -278,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;
@@ -424,7 +456,7 @@ async function eachEvent(res, onEvent) {
 }
 /**
  * A streamed purchase turn, read to its `envelope`: the same answer a JSON turn returns, with its
- * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment` and `cart` goes to its handler
+ * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment`, `cart` and `venue_availability` goes to its handler
  * on the way, and any other event, such as a `ping` or a `tool`, is read past. A stream that breaks or
  * ends before its envelope, once it named the conversation, reads as a turn past its budget
  * (`turn_timeout`), so the tool reads the conversation for what the turn left instead of losing it.
@@ -503,6 +535,15 @@ 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 === '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);
+                    const availability = availabilityOf(i);
+                    return id && availability ? [{ id, availability }] : [];
+                });
+                if (items.length)
+                    deliver(() => stream.onAvailability({ conversationId: data.conversation_id, items }));
+            }
             else if (event === 'cart' && stream.onCart && str(data.conversation_id)) {
                 const update = { conversationId: data.conversation_id, cart: cartOf(data.cart), carts: cartsOf(data.carts) };
                 deliver(() => stream.onCart(update));

package/dist/definition.js

@@ -42,6 +42,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 +53,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;

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 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 BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.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.js

@@ -6,14 +6,14 @@
  */
 /** 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. */

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,12 +128,30 @@ 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
  * entirely, and a bare address reads as the site's name (siteName), so the store a reply names stays in it.
  */
 export declare function stripLinks(text: string): string;
+/**
+ * Agentcard's reply as the shopper and the model read it, with every link taken out (stripLinks) and no line left pointing at
+ * one. A line that pointed at a link ends as a sentence when the answer sent the shopper what it pointed at, a product or a
+ * store card or a step's link, and goes when it sent none, so the reply never promises what the shopper does not get. 2026-10-27, chat.opencommerce.sh:
+ * "here's the stool on Wayfair:" reached the shopper with nothing after it.
+ */
+export declare function replyWithoutLinks(reply: string, sent: boolean): string;
 /**
  * An amount in its currency's minor unit, as the model reads it: the currency's own minor units place the
  * decimal point, so 1331 is $13.31 in USD, CA$13.31 in CAD and ¥1,331 in JPY. An amount whose currency
@@ -162,10 +192,11 @@ export declare function pickId(product: Pick<BuyToolProduct, 'id' | 'ref'>): str
 export declare function cardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'url'>): string | null;
 /**
  * The key of the card a product gets, or null when it gets none: a product with a page at its store,
- * or a flight option, which has no page, with an id a pick takes. A flight's card is how the shopper
- * taps the flight they want (2026-10-20: three flights listed in text, and no card to tap).
+ * or a flight option or a place to book, which can have no page, with an id a pick takes. A flight's card
+ * is how the shopper taps the flight they want (2026-10-20: three flights listed in text, and no card to tap),
+ * and a place's card is where the shopper reads whether it has room.
  */
-export declare function productCardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'url' | 'flight'>): string | null;
+export declare function productCardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'url' | 'flight' | 'availability'>): 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;
 /**
@@ -175,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
@@ -183,25 +224,36 @@ 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. 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.
+ *
+ * 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