@agent-cards/commerce-sdk 0.18.5 → 0.18.7

package/dist/buy-tool.js

@@ -1,36 +1,3 @@
-/**
- * The buy tool: one call that buys for one shopper, in one object that every
- * agent framework takes. `answer` sends the model's input to Agentcard and
- * returns the whole answer for your code, with the status, Agentcard's
- * reply, the cart and its hash, the products and the links. `forModel` turns
- * that answer into what the model may read, with every link taken out, and
- * `run`, `execute` and `handle` return that view as JSON text. A link
- * reaches the shopper through `sendLink`, and each call waits for it before
- * it returns: the Vault and approval links, then the store page of each
- * product the model reads.
- *
- * Agentcard keeps the conversation: every call continues the shopper's open
- * purchase (`resume: true`), and a confirm places the cart Agentcard last
- * showed (`confirm: true`). The tool keeps one thing between calls: the store
- * pages it sent last. Agentcard repeats the last search in each answer for a
- * while, so a list it shows again in the same conversation does not reach
- * the shopper twice. A tool built for each message buys the same way, and
- * sends such a list again.
- *
- * Two answers make the tool wait before it returns. A placement Agentcard is
- * still finishing gets one 12-second pause and one read of the conversation.
- * A turn that outlived Agentcard's budget gets a read every 5 seconds for up
- * to a minute, until the turn ends.
- *
- * `turn` binds the tool to one shopper message: the calls the model makes
- * through it hand their links, answers and instant reply to that turn's own
- * callbacks and lists, so a shopper who sends a second message before the
- * first is answered never gets one message's cards beside the other's reply.
- * Every turn of one tool still shares the shopper's conversation state, such
- * as the store pages already sent. A turn with `onItem` hands the app its
- * messages and links as one sequence, in the order they happened, and spaces
- * the messages like someone texting.
- */
 import { AgentcardApiError, AgentcardClient, cartBuildingOf, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
 import { directCall, isProductAsk } from './direct.js';
@@ -39,6 +6,7 @@ import { choiceLines, leadsIntoList, messageForShopper, messagesListChoice, repl
 import { joinLeadIns, leadInJoiner, messageStream, paceOf, paragraphsOf, sleep, toMessages, typingHook } from './messages.js';
 import { isStale, messageInChat } from './shopper-message.js';
 import { actionLinkId, isActionLink } from './action-links.js';
+import { checkStoreWait, storeWaitFields, withLateCards } from './store-wait.js';
 import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, asksForSimilar, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, readsAsAckLine, slowStepLine } from './ack.js';
 /** The action a product of `merchant` takes (BuyToolProductAction). */
 export function productAction(merchant) {
@@ -151,6 +119,8 @@ const CART_CHANGED = 'The cart changed since the shopper saw it. Show the shoppe
 const NOTHING_TO_CONFIRM = 'There is no cart to confirm yet. Ask the shopper what they want.';
 const ADDRESS_CHANGED = 'The delivery address changed since this cart was built. Ask for the cart again, and Agentcard prices it for the new address.';
 const STORE_PICK_GONE = "The store the shopper picked is no longer among the stores Agentcard found, so no store was chosen. Call this tool again with the shopper's words and store_id null, and Agentcard searches again.";
+/** The most product cards a tool keeps from earlier answers for a tap on an older card. */
+const SHOWN_BEFORE_MAX = 200;
 const PICK_GONE = "The product the shopper picked is no longer among the products Agentcard found, so nothing was added. Call this tool again with the shopper's words and product_id null, and Agentcard searches again.";
 /** One cart line as the order holds it: the product, its variant, its choices and its quantity. Prices are left out. */
 const lineKey = (line) => JSON.stringify([line.product_id ?? String(line.name ?? '').trim().toLowerCase(), line.variant ?? null, [...(line.options ?? [])].sort(), line.qty]);
@@ -272,7 +242,7 @@ export function productsOf(turn) {
 /** A product's card as `sendLink` hears it: the id the model reads and a pick takes, never the store page, which is `url`. A flight option has no page at a store: its card carries no url, and its productId picks it. */
 function productLink(product) {
     const productId = pickId(product);
-    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), store: product.store ?? null, storeDomain: product.storeDomain ?? null, expiresAt: null, ...(product.availability ? { availability: product.availability } : {}) };
+    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), store: product.store ?? null, storeDomain: product.storeDomain ?? null, expiresAt: null, ...(product.availability ? { availability: product.availability } : {}), ...(product.fulfilledBy ? { fulfilledBy: product.fulfilledBy } : {}) };
 }
 /** A host name: dot-separated labels of letters, digits and hyphens, ending in a letters-only top-level label. */
 const STORE_HOST = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
@@ -308,6 +278,7 @@ function productsOfCatalog(catalog) {
         action: productAction(catalog.merchant),
         linkSent: false,
         ...(item.availability ? { availability: item.availability } : {}),
+        ...(item.fulfilled_by ? { fulfilledBy: item.fulfilled_by } : {}),
     }));
 }
 /** The stores an answer presents, as the tool reads them. */
@@ -352,6 +323,9 @@ function answerOf(turn) {
         hashes: hashesOf(turn.cart, turn.carts),
         cart_building: turn.cart_building,
         choice: turn.choice ?? null,
+        code_request: turn.code_request ?? null,
+        plan: turn.plan ?? null,
+        search: turn.search ?? null,
         envelope: turn.raw,
     };
 }
@@ -419,6 +393,13 @@ const CARD_ASK = /\b(?:add|save|link|enter|attach)\s+(?:a|your|the)\s+(?:(?:paym
  * which `askingForNamedStep` replaces when Agentcard names a step that comes first. Every message after it waits behind
  * it, so the shopper reads them in order; a message before it goes out at once.
  */
+/**
+ * Agentcard's messages of an answer, as written, that the shopper read in full through the early reply (onWrittenText)
+ * before the call ended, by the answer they belong to. `turn.replyAsWritten` hands them back for the turn's last answer and
+ * `turn.say` of them sends nothing, so the app shows no second reply and its model is not asked to word one
+ * (chat.opencommerce.sh, 2026-10-29: after "i found 16 more hotels" the model wrote a second recommendation of the same hotels).
+ */
+const readAsWritten = new WeakMap();
 function waitsForAnswer(message) {
     return CARD_ASK.test(message) || new RegExp(URL_IN_TEXT.source, 'i').test(message);
 }
@@ -771,6 +752,7 @@ export function buyTool(options) {
         throw new TypeError('Pass threadId as your own id for the chat or thread, 1 to 200 characters, or leave it out.');
     }
     const threadId = o.threadId?.trim();
+    checkStoreWait(o);
     /** Whether a message is this tool's to read (`messageInChat`): its chat's purchase, or news about the shopper alone. */
     const inThisThread = (message) => messageInChat(message, threadId);
     if (o.sendLink !== undefined && typeof o.sendLink !== 'function') {
@@ -788,7 +770,7 @@ export function buyTool(options) {
     if (o.stream !== undefined && o.stream !== false)
         throw new TypeError('Pass stream as false to wait for each whole answer, or leave it out.');
     const onProgress = o.onProgress;
-    for (const key of ['onStatus', 'onFound', 'onAvailability']) {
+    for (const key of ['onStatus', 'onFound', 'onAvailability', 'onMerchantStatus']) {
         if (o[key] !== undefined && typeof o[key] !== 'function')
             throw new TypeError(`Pass ${key} as a function, or leave it out.`);
     }
@@ -844,6 +826,9 @@ export function buyTool(options) {
     const { onWorking, onReaction } = ackRoutes(o.onWorking, o.onReaction);
     /** Calls running now, when the last one ended, and the template the instant reply used last. */
     let running = 0;
+    // When the newest call of this tool started: a late reply on the conversation answers the newest shopper message, so a call
+    // that a newer one followed no longer owns it.
+    let newestCallAt = 0;
     let lastEndedAt = Number.NEGATIVE_INFINITY;
     let lastTemplate = -1;
     /** Counts the model's turns: the calls of one turn share its number. */
@@ -866,6 +851,7 @@ export function buyTool(options) {
         onStatus: o.onStatus,
         onFound: o.onFound,
         onAvailability: o.onAvailability,
+        onMerchantStatus: o.onMerchantStatus,
         onProducts: o.onProducts,
         onText: o.onText,
         texting: textingByDefault,
@@ -942,6 +928,9 @@ export function buyTool(options) {
     let lastAnswerProducts = [];
     /** Every product card of the last answer's call the shopper can tap by name, each once (the answer's and the streamed). */
     let lastTappable = [];
+    /** Every product card this conversation's answers showed, newest first, each once: a tap on an older card reads these. */
+    let shownBefore = [];
+    let shownIn = null;
     let lastAnswerStores = [];
     let previousTurn = null;
     /** The names of the stores the last answer that listed stores showed: a message that names one, as a tap on its card does, picks it. */
@@ -1278,7 +1267,8 @@ export function buyTool(options) {
      * picks one first. A placement another attempt is still finishing keeps the
      * reading going and ends as `placing`, never as the cart. A minute without
      * any of them returns Agentcard's own answer, or what the last read showed
-     * while the turn still ran.
+     * while the turn still ran. A turn that ended with a reply of its own
+     * (`latest_reply`) answers with that reply and the products it showed.
      */
     const awaitCart = async (base, conversationId, since) => {
         const shown = new Set(base.hashes);
@@ -1313,13 +1303,18 @@ export function buyTool(options) {
                 // conversation and it shows one cart. With carts at two stores `confirm: true` still names the
                 // cart an earlier answer showed, so none is offered: the shopper's pick goes out as an ask.
                 const one = conversation.carts.length === 1 ? newest : null;
+                // The reply the turn wrote after its early answer is what the shopper waited for: it goes out in place of the
+                // tool's own line, with the products it showed (conv_054988b998634b16ab4a91d9, 2026-10-30: a stop message
+                // written while the shopper read "one moment" was never shown, and the model was told to call again).
+                const late = conversation.turn_in_progress || newestCallAt > since ? null : conversation.latest_reply;
                 const answer = {
                     ...base,
-                    reply: one ? CART_READY : newest ? CHOOSE_CART : ANSWER_LATE,
+                    reply: late ? late.text : one ? CART_READY : newest ? CHOOSE_CART : ANSWER_LATE,
+                    ...(late?.catalog ? { products: productsOfCatalog(late.catalog) } : {}),
                     cart: one,
                     carts: conversation.carts,
                     hashes: conversation.carts.map((c) => c.hash),
-                    error_code: newest ? null : base.error_code,
+                    error_code: newest || late ? null : base.error_code,
                     // A read replaced the answer the step was named for, and names no step of its own: the reply asks.
                     next_action: null,
                     // The early answer judged the pick before the turn finished adding it.
@@ -1818,6 +1813,9 @@ export function buyTool(options) {
             let cardsOut = false;
             /** The product cards this call's searches sent out as they answered, which the shopper can tap whatever the answer lists. */
             const streamedCards = [];
+            /** Whether Agentcard said the reply is written (`reply_written`), and the cards that went out after it: a store that answered late. */
+            let replyWritten = false;
+            const lateCards = [];
             let heldCount = null;
             /** The card each catalog id of this call went out as (its `productId`), and the cards still `checking`, by conversation. */
             const cardOfId = new Map();
@@ -1934,13 +1932,19 @@ export function buyTool(options) {
                                 // The products past the cards are read after the cards went out, so the first card never waits for them.
                                 const keepMore = () => { if (t.onFound && early)
                                     moreFound = { conversationId: update.conversationId, links: productsOfCatalog({ ...update.catalog, items: update.more }).map(productLink) }; };
-                                if (!early)
+                                if (!early) {
+                                    // Without early cards nothing goes out here, but a store that answered after the reply still joins the result.
+                                    if (replyWritten)
+                                        lateCards.push(...productsOfCatalog(update.catalog));
                                     return;
+                                }
                                 // Products arrived before the instant reply was due: they are the reply.
                                 ack?.cancel();
                                 await t.ackOut;
                                 // The turn's own search presents its products, as a reply that lists them does.
-                                await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
+                                const out = await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
+                                if (replyWritten)
+                                    lateCards.push(...out.products);
                                 // A place shown `checking`, on a card or behind "show more", waits for the live search's word on it.
                                 noteCards([...productsOfCatalog(update.catalog), ...productsOfCatalog({ ...update.catalog, items: update.more })], update.conversationId);
                                 streamedCards.push(...productsOfCatalog(update.catalog));
@@ -1961,6 +1965,18 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
+                    ...(t.onMerchantStatus
+                        ? {
+                            onMerchantStatus: async (update) => {
+                                try {
+                                    await t.onMerchantStatus(update);
+                                }
+                                catch {
+                                    // The app's display failing never fails the turn.
+                                }
+                            },
+                        }
+                        : {}),
                     ...(t.onText || writtenText
                         ? {
                             onSegment: async ({ text, conversationId }) => {
@@ -1972,10 +1988,11 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
-                    ...(!t.onText && writtenText
+                    ...(early || t.onProducts
                         ? {
                             onReplyWritten: async () => {
-                                if (speak)
+                                replyWritten = true;
+                                if (speak || !writtenText)
                                     return;
                                 speak = writtenText;
                                 for (const message of unsaid.splice(0))
@@ -2021,10 +2038,15 @@ export function buyTool(options) {
             // Every request names the tool's thread, so Agentcard continues this chat's purchase and no other.
             if (threadId)
                 sent = { ...sent, thread_id: threadId };
+            // Every request names how long the reply waits for stores, and what happens to a store that answers after it.
+            sent = { ...sent, ...storeWaitFields(t.storeWait ?? {}, o) };
             if (plan && 'local' in plan) {
                 // Nothing went to Agentcard: the answer is where the purchase stands.
             }
             else {
+                // This call now owns the conversation's newest reply: an earlier call still waiting for its late reply gives it up.
+                // A call that threw on its input, or answered from where the purchase stands, sent nothing and takes none.
+                newestCallAt = Math.max(newestCallAt, startedAt);
                 try {
                     turn = await client.buy(sent, handlers);
                 }
@@ -2119,8 +2141,14 @@ export function buyTool(options) {
                 }
             }
             const read = choiceShown && !!turn && (settled.reply === turn.reply ? readEvery(told, turn.messages) : replaced && readEvery(told, paragraphsOf(settled.reply)));
+            // The shopper read the whole answer before the call ended, the late source's message included: the turn's reply is what
+            // they read, and nothing is worded again (chat.opencommerce.sh, 2026-10-29: after "i found 16 more hotels" the model
+            // wrote a second recommendation of the same hotels).
             const answer = withMessages(settled, turn);
-            const delivered = await deliver(answered.size > 0 ? { ...answer, products: withAnswers(answer.products) } : answer, { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
+            // A late reply read from the conversation presents the products of its own catalog, which the early answer never held.
+            const late = settled.envelope?.latest_reply;
+            const presented = turn?.catalog?.presented === true || (late?.text === settled.reply && late?.catalog?.presented === true);
+            const delivered = await deliver(answered.size > 0 ? { ...answer, products: withAnswers(answer.products) } : answer, { turn: callTurn, presented, owner: t }, send);
             // A count that came before any card (find mode puts its cards in the answer) goes out once the answer's cards did.
             if (heldCount && (delivered.products?.length ?? 0) > 0) {
                 const held = heldCount;
@@ -2145,11 +2173,15 @@ export function buyTool(options) {
                 : null;
             const result = {
                 ...delivered,
+                // The cards of a store that answered after the reply join the answer's, when the answer does not list them already.
+                ...(lateCards.length > 0 ? { products: withLateCards(delivered.products, lateCards) } : {}),
                 ...(t.ackDelivered ? { shopper_already_told_looking: true } : {}),
                 ...(read ? { shopper_already_read_reply: true } : {}),
                 ...(confirmSent ? { confirm_sent: true } : {}),
                 ...(yesCarried ? { yes_carried: yesCarried } : {}),
             };
+            if (read && speak && speak === writtenText)
+                readAsWritten.set(result, told.join('\n\n'));
             lastNextAction = result.next_action;
             lastReply = result.reply;
             // A refusal reports no carts, so only a turn's answer says how many wait, and whether a checkout just ended with none.
@@ -2199,6 +2231,13 @@ export function buyTool(options) {
             }
             lastAnswerProducts = shown.map((product) => ({ productId: pickId(product), name: product.name }));
             lastTappable = tappable.map((product) => ({ productId: pickId(product), name: product.name }));
+            // A new conversation starts the cards shown before afresh; each card keeps its newest showing, up to SHOWN_BEFORE_MAX.
+            if (result.conversation_id && result.conversation_id !== shownIn)
+                shownBefore = [];
+            if (result.conversation_id)
+                shownIn = result.conversation_id;
+            const fresh = new Set(lastTappable.map((product) => product.productId ?? `name:${product.name}`));
+            shownBefore = [...lastTappable, ...shownBefore.filter((product) => !fresh.has(product.productId ?? `name:${product.name}`))].slice(0, SHOWN_BEFORE_MAX);
             lastAnswerStores = storesShown.map((store) => ({ storeId: store.id, name: store.name }));
             t.results?.push(result);
             if (t.onResult) {
@@ -2292,7 +2331,7 @@ export function buyTool(options) {
         const own = options ?? {};
         if (typeof own !== 'object')
             throw new TypeError('Pass the turn options as an object, or leave them out.');
-        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', 'onMerchantStatus', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
             if (own[key] !== undefined && typeof own[key] !== 'function')
                 throw new TypeError(`Pass ${key} to the turn as a function, or leave it out.`);
         }
@@ -2310,6 +2349,7 @@ export function buyTool(options) {
         if (own.textingStyle !== undefined && typeof own.textingStyle !== 'boolean')
             throw new TypeError('Pass textingStyle to the turn as true or false, or leave it out.');
         const texting = own.textingStyle ?? textingByDefault;
+        checkStoreWait(own, ' to the turn');
         const hearText = own.onText ?? o.onText;
         // Messages are spaced only for an app that hears each one as it goes out.
         const pauseOf = paceOf(own.pace);
@@ -2375,6 +2415,7 @@ export function buyTool(options) {
             onStatus: own.onStatus ?? o.onStatus,
             onFound: own.onFound ?? o.onFound,
             onAvailability: own.onAvailability ?? o.onAvailability,
+            onMerchantStatus: own.onMerchantStatus ?? o.onMerchantStatus,
             onProducts: own.onProducts ?? o.onProducts,
             // Agentcard's message takes its place in the turn's sequence, after the items before it, and goes to onText alone, so
             // an app that passes onItem too hears it once.
@@ -2386,6 +2427,7 @@ export function buyTool(options) {
                 ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : onMessage?.(text)))
                 : undefined,
             texting,
+            storeWait: { storeWaitMs: own.storeWaitMs, lateResults: own.lateResults },
             onCart: own.onCart ?? o.onCart,
             tell: onItem || baseOnWorking ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
             links: [],
@@ -2478,13 +2520,17 @@ export function buyTool(options) {
         const results = state.results;
         // A pick or an answer goes straight only after a turn that ended on Agentcard's answer, and never while a call still runs.
         const answered = previousTurn !== null && (previousTurn.results?.length ?? 0) > 0;
+        // A tap names its card by the id its link carried, whatever answer showed it: the pick goes straight with that id.
+        const tappedId = typeof options?.tapped?.productId === 'string' && options.tapped.productId.trim() ? options.tapped.productId.trim() : null;
         // A `nextStep` turn's call is the same whatever the model writes (`stepPlan` reads where the purchase stands), so it goes
         // straight too: with `replyAsWritten`, a step whose answer is a link, such as the approval after a saved card, needs no model.
         const direct = !directOn || running > 0
             ? null
             : event
                 ? { input: { ask: NEXT_STEP_ASK, confirm: false, new_order: false, product_id: null, store_id: null }, reason: 'next_step' }
-                : directCall(String(shopperText ?? ''), { answered, nextAction: lastNextAction, asked: lastReply, products: lastAnswerProducts, tappable: lastTappable, stores: lastAnswerStores });
+                : tappedId && String(shopperText ?? '').trim()
+                    ? { input: { ask: String(shopperText).trim(), confirm: false, new_order: false, product_id: tappedId, store_id: null }, reason: 'pick' }
+                    : directCall(String(shopperText ?? ''), { answered, nextAction: lastNextAction, asked: lastReply, products: lastAnswerProducts, tappable: lastTappable, shownBefore, stores: lastAnswerStores });
         // Agentcard writes the line for a search the turn sends straight. A turn the app's model runs gets the model's own line,
         // or the wait line below.
         state.agentcardAcks = (ask) => direct !== null && direct.reason === 'product_ask' && ask.trim() === direct.input.ask.trim();
@@ -2595,6 +2641,10 @@ export function buyTool(options) {
         /** Says a whole text as the turn's messages, after every item before it (`say()`). */
         const sayWhole = (whole) => {
             writesThroughTurn = true;
+            // The reply the shopper already read as Agentcard wrote it (`readAsWritten`), of the turn's last answer: saying it again sends nothing.
+            const read = results.length > 0 ? readAsWritten.get(results[results.length - 1]) : undefined;
+            if (read && whole === read)
+                return releaseForReply();
             firstWords(whole);
             if (state.modelTurn && /\S/.test(String(whole ?? '')))
                 state.modelTurn.spoke = true;
@@ -2678,7 +2728,7 @@ export function buyTool(options) {
             results: { get: () => [...results], enumerable: false },
             direct: { value: direct, enumerable: false },
             stopped: { get: () => state.stopped === true, enumerable: false },
-            replyAsWritten: { get: () => (written && results.length > 0 && !state.stopped ? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
+            replyAsWritten: { get: () => (written && results.length > 0 && !state.stopped ? readAsWritten.get(results[results.length - 1]) ?? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
             items: { get: () => feed.items.map((item) => (item.kind === 'link' ? { kind: 'link', link: { ...item.link } } : { ...item })), enumerable: false },
             // Each message joins the feed the moment it is cut, so a link the tool hands over during a pause never overtakes text already written.
             // A step link held for this message goes out right after its last paragraph, once the stream ends.

package/dist/client.d.ts

@@ -1,3 +1,16 @@
+/**
+ * The client the buy tool calls Agentcard with. A company builds one from its
+ * client credentials, and every shopper's tool shares the one access token it
+ * exchanges them for; or a tool runs on one shopper's own access token. The
+ * global fetch is the only transport, so the package keeps no dependencies.
+ *
+ * The answer fields and the error codes follow the buy module of
+ * @agent-cards/sdk (packages/checkout/src/buy.ts: turnOf, buyError), and the
+ * token cache follows its client (packages/checkout/src/client.ts accessToken).
+ */
+import { type BuyPlan } from './plan.js';
+import { type BuyMerchantStatusUpdate, type BuySearchStatus } from './search-status.js';
+import { type BuyFulfilledBy } from './fulfilled-by.js';
 import { type AgentcardListener, type ListenOptions } from './listen.js';
 import { type ShopperMessage } from './shopper-message.js';
 /** The fetch the client calls: Node 18 and later have one built in. */
@@ -151,6 +164,11 @@ export interface BuyStreamHandlers {
     onReplyWritten?: (update: {
         conversationId: string | null;
     }) => void | Promise<void>;
+    /**
+     * Each store the turn searches, the moment its status changes: `searching` when its search starts, then what it found. To
+     * follow one store, keep the updates `isMerchantStatusAt(update, 'walmart.com')` accepts. The answer's `search` holds every store.
+     */
+    onMerchantStatus?: (update: BuyMerchantStatusUpdate) => 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. */
@@ -241,6 +259,16 @@ export interface BuyRequest {
      * another thread is refused (409 `thread_mismatch`). Leave it out for an app with one chat per shopper.
      */
     thread_id?: string;
+    /**
+     * How long, in milliseconds, the reply waits for store searches before Agentcard writes it. Left out, Agentcard keeps
+     * its own wait. `buyTool({ storeWaitMs })` sends it on every request.
+     */
+    store_wait_ms?: number;
+    /**
+     * What happens to a store that answers after the reply: `stream` sends its cards after the reply in the same streamed
+     * turn, before the answer; `hold` keeps them out of the turn. Left out, Agentcard does as it does today.
+     */
+    late_results?: 'stream' | 'hold';
     /** Drop the cart on the table and start a new order. */
     new_order?: true;
     /**
@@ -325,6 +353,8 @@ export interface BuyCartLine {
     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;
+    /** Who sells or books the line, where that is not the store the cart names (`via StubHub`); absent when Agentcard named none. */
+    fulfilled_by?: BuyFulfilledBy;
 }
 /**
  * A cart as Agentcard answers it. `totalCents` is the all-in figure the shopper sees; `hash` is what a confirm names.
@@ -335,6 +365,25 @@ export interface BuyCartFeeLine {
     label: string;
     amountCents: number;
 }
+/**
+ * A discount or a coupon inside a cart's total, as the store labels it. `amountCents` is negative. `kind` is `discount`
+ * for one the store applied on its own, such as a promotion, and `coupon` for a code entered at the store's checkout,
+ * which `code` names; `code` is null for a discount.
+ */
+export interface BuyCartDiscount {
+    label: string;
+    amountCents: number;
+    kind: 'discount' | 'coupon';
+    code: string | null;
+}
+/**
+ * Why a cart's card is held for `amountCents`: `flight` and `hotel` for the hold a booking places on the card, and
+ * `checkout_estimate` for the headroom above a store's total that covers tax and shipping and is released unused.
+ */
+export interface BuyCartHold {
+    amountCents: number;
+    reason: 'flight' | 'hotel' | 'checkout_estimate';
+}
 export interface BuyCart {
     merchant: string;
     merchant_name: string;
@@ -346,6 +395,10 @@ export interface BuyCart {
     serviceFeesStatus?: 'known' | 'pending' | 'unknown';
     /** The store's own fee and tax lines inside `serviceFeesCents`, or null when the store itemized none. */
     merchantFeeLines: BuyCartFeeLine[] | null;
+    /** The discounts and coupons inside `totalCents`, which `merchantFeeLines` also lists. Empty when there are none, and from an older API. */
+    discounts?: BuyCartDiscount[];
+    /** True while the store's checkout builds this cart again, so `totalCents` is not its price yet. False from an older API. */
+    pricing?: boolean;
     tipCents: number;
     totalCents: number;
     /**
@@ -356,6 +409,8 @@ export interface BuyCart {
     /** The ISO 4217 code the store prices the cart in, or null when Agentcard sent none. */
     currency: string | null;
     approvedCeilingCents: number | null;
+    /** Why the card is held for `approvedCeilingCents`, or null when nothing is held or the API is older. */
+    hold?: BuyCartHold | null;
     hash: string;
 }
 /** A product a search found. `priceCents` is in the minor unit of `currency`, the store's ISO 4217 code. */
@@ -392,6 +447,8 @@ export interface BuyCatalogItem {
     url: string | null;
     /** Whether a place has room at the asked time (BuyAvailability). Absent on a product with no such question. */
     availability?: BuyAvailability;
+    /** Who sells or books the product, where that is not the store the card names (`booked with OpenTable`); absent when Agentcard named none. */
+    fulfilled_by?: BuyFulfilledBy;
 }
 /**
  * The products the last search found. `presented` is true when this answer's reply presents them: the
@@ -489,6 +546,19 @@ export interface BuyPaymentSource {
  * (the code a booking texted them), then `approve` (the approval link). A value this version does
  * not know reads as null.
  */
+/**
+ * A store checkout waiting for the one-time code Stripe Link or Shop Pay sent the shopper: which wallet, whether it was a
+ * text or an email, and where it went, masked to a phone's last two digits ("••21") or an email's first letter and domain
+ * ("j•••@example.com"). The shopper sends the code as their next message, as `next_action: 'verification_code'` says.
+ */
+export interface BuyCodeRequest {
+    store: string;
+    wallet: 'link' | 'shop_pay';
+    channel: 'text' | 'email';
+    destination: string | null;
+}
+/** An answer's code request, from its `browser_checkout` when that checkout waits on a wallet's code; null otherwise. */
+export declare function codeRequestOf(value: unknown): BuyCodeRequest | 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
@@ -517,6 +587,8 @@ export interface BuyTurn {
     approval_url: string | null;
     charge_status: string | null;
     error_code: string | null;
+    /** The party of the purchase this answer says failed, such as StubHub for a ticket, so an app names who stopped it; null when none is named. */
+    fulfilled_by: BuyFulfilledBy | null;
     authorization_id: string | null;
     merchant_total_cents: number | null;
     merchant_currency: string | null;
@@ -527,6 +599,8 @@ export interface BuyTurn {
     approval_in_progress: boolean | null;
     /** The one step the shopper takes next, or null when nothing waits on them or Agentcard named none. */
     next_action: BuyNextAction | null;
+    /** The wallet's code a store checkout waits for, with where it went, or null when none waits (BuyCodeRequest). */
+    code_request: BuyCodeRequest | null;
     /** The page where the shopper signs in to a store's own account before Agentcard can buy there. */
     store_login_url: string | null;
     store_login_expires_at: string | null;
@@ -542,6 +616,10 @@ export interface BuyTurn {
     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 checkout plan this answer's yes started or moved, with each item's state; null when none, and on an older API. */
+    plan: BuyPlan | null;
+    /** Every store the turn searched and where each stands; null for a turn that searched none, and on an older API. */
+    search: BuySearchStatus | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -581,8 +659,22 @@ export interface BuyConversation {
     last_checkout: BuyLastCheckout | null;
     orders: BuyOrder[];
     carts: BuyCart[];
+    /**
+     * The reply Agentcard wrote since the shopper's last message, once no turn runs: the answer a call that ended with
+     * `turn_timeout` never got. Null while a turn runs, when no reply was written since, and on an older API.
+     */
+    latest_reply: BuyLatestReply | null;
     raw: Record<string, unknown>;
 }
+/** A reply a conversation read hands back: its text, its messages, and the products it showed. */
+export interface BuyLatestReply {
+    message_id: string;
+    text: string;
+    messages: string[];
+    /** The products the reply showed, when the call that asked ended before it was written; null otherwise. */
+    catalog: BuyCatalog | null;
+    created_at: string | null;
+}
 /** A Vault link: the page where a shopper connects and adds a card. */
 export interface VaultLink {
     id: string;