@agent-cards/commerce-sdk 0.19.0 → 0.20.0

package/dist/basket.d.ts

@@ -1,6 +1,6 @@
 /**
  * A basket on a purchase answer: the carts at several sellers that one approval pays, each seller charging the card
- * separately for no more than its line. `approval_url` is the one link the shopper approves on while the basket waits for
+ * separately for exactly its line, or up to its hold for a store that charges its final amount (`held`). `approval_url` is the one link the shopper approves on while the basket waits for
  * that approval or pays under it. Null on an answer with no basket, and on an older API.
  *
  * A basket whose stores reach their payment step after this answer has no link yet: the link then arrives as a
@@ -17,15 +17,26 @@ export interface BuyBasketLine {
     /** The seller as the shopper knows it: the store or the airline. */
     seller: string;
     status: BuyBasketLineStatus;
+    /** The seller's cart total, the amount to show for this line. */
     total_cents: number;
-    /** The most this seller may charge: its total_cents, since a seller is paid exactly the amount the shopper approved. */
+    /**
+     * The most this seller may charge. It equals total_cents for a seller that quotes its final price: that seller is paid
+     * exactly the amount the shopper approved. A store that charges its final amount when the order is placed holds the
+     * card above its total, and cap_cents is that hold.
+     */
     cap_cents: number;
+    /**
+     * True when cap_cents is above total_cents: show the total and the hold beside it, as in "Walmart $100.00, card held up
+     * to $125.00, you pay only the final amount".
+     */
+    held: boolean;
 }
 export interface BuyBasket {
     id: string;
     status: BuyBasketStatus;
+    /** The sum of the sellers' cart totals, the amount the shopper approves. */
     total_cents: number;
-    /** The most every seller together may charge: total_cents, the sum of what each seller is paid. */
+    /** The most every seller together may charge: total_cents, plus the hold above each held line's total. */
     cap_cents: number;
     currency: string;
     approval_url: string | null;

package/dist/basket.js

@@ -15,7 +15,9 @@ export function basketOf(v) {
     for (const l of v.lines) {
         if (!isRecord(l) || typeof l.seller !== 'string' || typeof l.status !== 'string' || !LINE_STATUSES.has(l.status) || !whole(l.total_cents) || !whole(l.cap_cents))
             return null;
-        lines.push({ seller: l.seller, status: l.status, total_cents: l.total_cents, cap_cents: l.cap_cents });
+        if (l.cap_cents < l.total_cents)
+            return null;
+        lines.push({ seller: l.seller, status: l.status, total_cents: l.total_cents, cap_cents: l.cap_cents, held: l.cap_cents > l.total_cents });
     }
     return { id: v.id, status: v.status, total_cents: v.total_cents, cap_cents: v.cap_cents, currency: v.currency,
         approval_url: typeof v.approval_url === 'string' ? v.approval_url : null, expires_at: v.expires_at, lines };

package/dist/buy-tool.d.ts

@@ -604,6 +604,15 @@ export interface BuyTool {
      * call's answer tells the model where the purchase stands. Post `message.text` then, as before.
      */
     nextStep(message: ShopperMessage, options?: BuyToolTurnOptions): BuyToolTurn | null;
+    /**
+     * The carts this tool last showed, with the cart an `order_placed` message is about marked placed: its `totalStatus`
+     * reads `placed` and its total is the total the order placed at. A store that sets its final amount later names only an
+     * estimate, and the cart keeps `totalIsEstimate` true at that estimate. The tool's `onCart` hears the carts before the
+     * promise settles, so await it in your webhook's `onMessage`. Pass every message `onMessage` got. Answers null for any
+     * other message, a message about another conversation or shopper, or one whose cart this tool cannot tell: the message
+     * names a store none of the carts is at, and more than one cart is on the table.
+     */
+    placedCarts(message: ShopperMessage): Promise<BuyCart[] | null>;
 }
 /**
  * One thing a turn hands the shopper: a message, such as the instant reply or a paragraph your model

package/dist/buy-tool.js

@@ -769,7 +769,7 @@ function endTurn(state) {
  * The hash alone is not enough, since a store pricing a cart again changes `pricing` and its total under one hash.
  */
 function cartsKey(carts) {
-    return JSON.stringify(carts.map((c) => [c.hash, c.totalCents, c.pricing === true, c.totalIsEstimate, c.items.map((i) => [i.line_id, i.qty, i.lineTotalCents])]));
+    return JSON.stringify(carts.map((c) => [c.hash, c.totalCents, c.pricing === true, c.totalIsEstimate, c.totalStatus, c.items.map((i) => [i.line_id, i.qty, i.lineTotalCents])]));
 }
 export function buyTool(options) {
     const o = options ?? {};
@@ -934,6 +934,24 @@ export function buyTool(options) {
     let callsStarted = 0;
     let cartsFromCall = 0;
     let lastCarts = [];
+    /**
+     * The carts an order placed marked (`placedCarts`), by hash, with their conversation: an answer in that conversation that
+     * still lists one, such as a call that began before the order placed, shows it placed. The first answer that no longer
+     * lists it forgets it, so the same items carted again later are a new purchase.
+     */
+    const placedByHash = new Map();
+    const placedIn = (hash, conversationId) => {
+        const kept = placedByHash.get(hash);
+        return kept && (!kept.conversationId || !conversationId || kept.conversationId === conversationId) ? kept.cart : undefined;
+    };
+    const withPlaced = (carts, conversationId) => carts.map((c) => placedIn(c.hash, conversationId) ?? c);
+    /** The conversation the carts that left the table were in. */
+    let leftCartsIn = null;
+    /** The newest call whose answer set the carts the tool keeps. */
+    let cartsKeptFromCall = 0;
+    const cartKey = (c) => `${c.merchant}|${c.store?.id ?? ''}`;
+    /** The carts an answer took off the table, newest first, at most five: an order placed before its message arrived leaves its cart here. */
+    let leftCarts = [];
     /** The cart the last answer showed: the cart a confirm sent now confirms. */
     let lastShownCart = null;
     /**
@@ -2144,10 +2162,11 @@ export function buyTool(options) {
                         : {}),
                     ...(t.onCart
                         ? {
-                            onCart: async ({ cart, carts, conversationId }) => {
+                            onCart: async ({ cart: sent, carts: sentCarts, conversationId }) => {
                                 // A newer call already handed on its carts: this older stream's are stale, however late they come.
                                 if (callNo < cartsFromCall)
                                     return;
+                                const [cart, carts] = [sent ? placedIn(sent.hash, conversationId) ?? sent : sent, withPlaced(sentCarts, conversationId)];
                                 t.cartsHeard = cartsKey(carts);
                                 cartsFromCall = callNo;
                                 try {
@@ -2329,7 +2348,26 @@ export function buyTool(options) {
             // A refusal reports no carts, so only a turn's answer says how many wait, and whether a checkout just ended with none.
             if (turn) {
                 lastCartCount = result.carts.length;
-                lastCarts = result.carts;
+                // A cart an order placed reads placed in every answer that still lists it.
+                const answeredIn = result.conversation_id ?? lastConversationId;
+                result.carts = withPlaced(result.carts, answeredIn);
+                if (result.cart)
+                    result.cart = placedIn(result.cart.hash, answeredIn) ?? result.cart;
+                // Only the newest call's answer moves what the tool keeps: an older call's answer is no word on the carts as they stand.
+                if (callNo >= cartsKeptFromCall) {
+                    cartsKeptFromCall = callNo;
+                    for (const hash of [...placedByHash.keys()])
+                        if (!result.error_code && !result.carts.some((c) => c.hash === hash))
+                            placedByHash.delete(hash);
+                    // The carts that left the table, newest first, one per store. A cart the answer still holds at the same store, edited
+                    // or priced again, is the same purchase in a new version, so its older version never counts as one that left.
+                    const left = lastCarts.filter((c) => !result.carts.some((n) => n.hash === c.hash || cartKey(n) === cartKey(c)));
+                    // A new conversation is a new purchase: the carts that left the one before it are no longer its carts.
+                    const sameConversation = !answeredIn || !leftCartsIn || answeredIn === leftCartsIn;
+                    leftCarts = [...(sameConversation ? left : []), ...(sameConversation ? leftCarts : []).filter((c) => !left.some((n) => cartKey(n) === cartKey(c)))].slice(0, 5);
+                    leftCartsIn = answeredIn ?? leftCartsIn;
+                    lastCarts = result.carts;
+                }
                 // The answer's carts are the conversation's as they stand, an empty list included: onCart hears them when the stream
                 // sent none or older ones, so an app never keeps showing a cart Agentcard no longer holds (a stream sends a cart only
                 // when a tool changed it, and a call with stream: false sends none).
@@ -2391,8 +2429,8 @@ export function buyTool(options) {
                 held.add(id);
                 tappable.push(product);
             }
-            lastAnswerProducts = shown.map((product) => ({ productId: pickId(product), name: product.name }));
-            lastTappable = tappable.map((product) => ({ productId: pickId(product), name: product.name }));
+            lastAnswerProducts = shown.map((product) => ({ productId: pickId(product), name: product.name, store: product.store }));
+            lastTappable = tappable.map((product) => ({ productId: pickId(product), name: product.name, store: product.store }));
             // 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 = [];
@@ -2489,6 +2527,45 @@ export function buyTool(options) {
             client.answered(externalUserId, message, threadId);
         return openTurn(nextStepPrompt(message), options, message);
     };
+    /** The carts with the one an order_placed message is about marked placed at its total (`BuyTool.placedCarts`). */
+    const placedCarts = async (message) => {
+        if (!message || typeof message !== 'object' || message.kind !== 'order_placed')
+            return null;
+        if (client.company && message.externalUserId !== externalUserId)
+            return null;
+        if (message.conversationId && lastConversationId && message.conversationId !== lastConversationId)
+            return null;
+        const store = message.facts?.merchantName?.trim().toLowerCase();
+        const named = (pool) => (store ? pool.filter((c) => [c.merchant_name, c.store?.name, c.store?.id, c.merchant].some((n) => n?.trim().toLowerCase() === store)) : []);
+        const [open, left] = [named(lastCarts), named(leftCarts)];
+        // The one cart the message names, on the table or one an answer took off it once the order placed, else the only cart.
+        // A name that fits more than one cart, an open one and one that left included, tells none apart: the order may be either.
+        const cart = open.length + left.length > 1 ? null
+            : open[0] ?? left[0] ?? (lastCarts.length === 1 ? lastCarts[0] : lastCarts.length === 0 && leftCarts.length === 1 ? leftCarts[0] : null);
+        if (!cart)
+            return null;
+        const [total, estimate] = [message.facts?.totalCents, message.facts?.estimatedTotalCents];
+        const final = typeof total === 'number' && total >= 0;
+        const placed = {
+            ...cart,
+            totalStatus: 'placed',
+            ...(final ? { totalCents: total, totalIsEstimate: false } : typeof estimate === 'number' && estimate >= 0 ? { totalCents: estimate, totalIsEstimate: true } : {}),
+        };
+        // A cart an answer took off the table is shown again, placed, beside the carts still open.
+        const carts = lastCarts.includes(cart) ? lastCarts.map((c) => (c === cart ? placed : c)) : [...lastCarts, placed];
+        leftCarts = leftCarts.filter((c) => c !== cart);
+        lastCarts = carts;
+        placedByHash.set(cart.hash, { cart: placed, conversationId: lastConversationId });
+        if (o.onCart && lastConversationId) {
+            try {
+                await o.onCart(placed, { carts, conversationId: lastConversationId });
+            }
+            catch {
+                // The app's display failing never fails the message.
+            }
+        }
+        return carts;
+    };
     const openTurn = (shopperText, options, event) => {
         const own = options ?? {};
         if (typeof own !== 'object')
@@ -2919,5 +2996,5 @@ export function buyTool(options) {
             say: { value: sayWhole, enumerable: false },
         });
     };
-    return toolOf(answer, { instantAck, instantReaction, turn, nextStep }, {});
+    return toolOf(answer, { instantAck, instantReaction, turn, nextStep, placedCarts }, {});
 }

package/dist/client.d.ts

@@ -472,6 +472,8 @@ export interface BuyCartHold {
     amountCents: number;
     reason: 'flight' | 'hotel' | 'checkout_estimate';
 }
+/** Where a cart's total stands: an estimate, the store's confirmed total, or the total of the order placed. */
+export type BuyCartTotalStatus = 'estimate' | 'confirmed' | 'placed';
 export interface BuyCart {
     merchant: string;
     merchant_name: string;
@@ -494,6 +496,13 @@ export interface BuyCart {
      * known fees only: show it as an estimate. DoorDash prices a cart once the shopper's own account holds it.
      */
     totalIsEstimate: boolean;
+    /**
+     * Where `totalCents` stands: `estimate` before the store priced the cart, `confirmed` once the store priced it, such
+     * as when the approval asks for the store's total, and `placed` once the order is placed (`buy.placedCarts`). A placed
+     * order whose store has not set its final amount yet keeps `totalIsEstimate` true. An older API sends none, and the
+     * cart reads `estimate` when `totalIsEstimate` is true, else `confirmed`.
+     */
+    totalStatus: BuyCartTotalStatus;
     /** The ISO 4217 code the store prices the cart in, or null when Agentcard sent none. */
     currency: string | null;
     approvedCeilingCents: number | null;

package/dist/client.js

@@ -232,6 +232,11 @@ function feesOf(v) {
             && amount !== null && Number.isSafeInteger(amount) && amount >= 0 ? 'known' : 'unknown';
     return { serviceFeesCents: status === 'known' ? amount : null, serviceFeesStatus: status };
 }
+function totalStatusOf(v) {
+    if (v.totalStatus === 'estimate' || v.totalStatus === 'confirmed' || v.totalStatus === 'placed')
+        return v.totalStatus;
+    return v.totalIsEstimate === true ? 'estimate' : 'confirmed';
+}
 function cartOf(v) {
     if (!isRecord(v) || !str(v.hash) || !str(v.merchant))
         return null;
@@ -265,6 +270,7 @@ function cartOf(v) {
         tipCents: num(v.tipCents) ?? 0,
         totalCents: num(v.totalCents) ?? 0,
         totalIsEstimate: v.totalIsEstimate === true,
+        totalStatus: totalStatusOf(v),
         currency: str(v.currency),
         approvedCeilingCents: num(v.approvedCeilingCents),
         hold: holdOf(v.hold),

package/dist/direct.d.ts

@@ -21,10 +21,11 @@ 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. A place (`the second one`) reads these. */
+    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends and the store that sells each. A place (`the second one`) reads these. */
     products?: ReadonlyArray<{
         productId: string | null;
         name: string;
+        store?: string | null;
     }>;
     /**
      * Every product card the shopper can tap by its name, each once: the answer's and the ones its searches sent as they answered,
@@ -35,6 +36,7 @@ export interface DirectContext {
     tappable?: ReadonlyArray<{
         productId: string | null;
         name: string;
+        store?: string | null;
     }>;
     /**
      * Every product card an earlier answer of this conversation showed, each once, newest first. A card's tap whose name no card

package/dist/direct.js

@@ -164,6 +164,33 @@ function tappedName(raw) {
     const name = TAP.exec(raw.trim())?.[1]?.trim();
     return name ? name : null;
 }
+/**
+ * The words a pick by one word of a product's name says around that word, as `nameWords` spells them: `lets do the X ones`,
+ * `I'll take the X`, `go with X`, `X please`, `X, 2 of them`, `X is fine`. A yes, a no or any other word is not among them.
+ */
+const PICK_FRAME = new Set('the a an one ones that this lets let s do go with i ll take get want give me is fine good works uh uhh um umm please pls plz of them those it x pack packs'.split(' '));
+/** The stores a message names by brand, `home depot` and `barnes & noble` whole, as the words `nameWords` spells them. */
+const STORE_NAMED = new RegExp(`(?<![\\p{L}\\p{N}])(?:${STORES})(?![\\p{L}\\p{N}])`, 'gu');
+function storesNamed(raw) {
+    return [...String(raw ?? '').toLowerCase().matchAll(STORE_NAMED)].map((match) => nameWords(match[0]));
+}
+/**
+ * True when a message picks this product by a word only its name holds, such as its brand. Every other word of the message is the
+ * product's own or a pick frame's (`PICK_FRAME`), and the word is no part of a store's name the message holds (`home depot`), or of
+ * the product's own store, unless the product's name opens with that store's name, as Amazon Basics does. On 2026-11-05
+ * (conv_64712285dd09f5bbab6fc737) the agent showed eight books and offered to look at eBay, the shopper answered "yes ebay
+ * specifically", and "ebay", held by "The Expert Guide To Cashing In On eBay" alone, went as a tap on that card.
+ */
+function marksProduct(raw, said, product, cards) {
+    const own = nameWords(product.name).split(' ');
+    const title = ` ${own.join(' ')} `;
+    // Each store the message names, and the product's own store, unless the product's name opens with it (a store's own brand).
+    const stores = [...storesNamed(raw), nameWords(product.store ?? '')].filter((store) => store !== '' && !title.startsWith(` ${store} `));
+    const isStore = (word) => stores.some((store) => store.split(' ').includes(word));
+    const words = said.split(' ');
+    const marks = words.filter((word) => word.length >= 4 && !/^\d/.test(word) && own.includes(word) && !isStore(word) && cards.filter((card) => nameWords(card.name).split(' ').includes(word)).length === 1);
+    return marks.length > 0 && words.every((word) => own.includes(word) || PICK_FRAME.has(word) || /^\d+$/.test(word));
+}
 /** 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 ?? [];
@@ -213,9 +240,7 @@ function pickOf(raw, bare, context) {
         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) => 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));
+        const marked = byName.filter((product) => marksProduct(raw, said, product, byName));
         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);

package/dist/index.d.ts

@@ -1,18 +1,18 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatureReason, type AgentcardEvent, type VerifyOptions, } from './verify.js';
 export { shopperLocationOf, type ShopperLocation, type ShopperShipTo, type BuyShopperLocation } from './shopper-location.js';
-export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.js';
+export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, type CardRefusal, } 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 { searchAt, isMerchantStatusAt, merchantStatusLine, searchStatusLines, type BuySearchStatus, type BuyMerchantStatus, type BuyMerchantSearchStatus, type BuyMerchantStatusUpdate, } from './search-status.js';
 export { groupsOf, type BuyGroup, type BuyGroupKind, type BuyGroupStatus, type BuyGroupWithProducts, type BuyGroupsSource, type BuyGroupsUpdate, } from './search-groups.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 BuyStoreCheckUpdate, type BuyFoundUpdate, type BuyTurnStatus, STATUS_WORDING, type BuySegmentUpdate, type BuyRecheck, type BuyFreshness, type BuyFreshnessState, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyCartDiscount, type BuyCartHold, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyFlightParty, type BuyPaymentSource, type BuyConversation, type BuyLatestReply, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyCodeRequest, type BuyChoiceGroup, type BuyChoiceDelivery, type BuyChoiceOption, } 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 BuyStoreCheckUpdate, type BuyFoundUpdate, type BuyTurnStatus, STATUS_WORDING, type BuySegmentUpdate, type BuyRecheck, type BuyFreshness, type BuyFreshnessState, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyCartDiscount, type BuyCartHold, type BuyCartTotalStatus, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyFlightParty, type BuyPaymentSource, type BuyConversation, type BuyLatestReply, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyCodeRequest, type BuyChoiceGroup, type BuyChoiceDelivery, 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, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, type BuyToolModelView, type BuyToolModelCart, type BuyToolGrandTotal, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
+export { forModel, cartsForModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, type BuyToolModelView, type BuyToolModelCart, type BuyToolGrandTotal, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
 export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice, type ReplyAsWrittenOptions } from './texting.js';
 export { appInstructions, APP_INSTRUCTIONS_VERSION, type AppInstructionsOptions } from './app-instructions.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';

package/dist/index.js

@@ -12,7 +12,7 @@ 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, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, } from './model-view.js';
+export { forModel, cartsForModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, } from './model-view.js';
 export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice } from './texting.js';
 export { appInstructions, APP_INSTRUCTIONS_VERSION } from './app-instructions.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';

package/dist/message.d.ts

@@ -59,6 +59,25 @@ export interface PurchaseFacts {
     validUntil?: string;
     /** 1 for a cart's first nudge, 2 for its second. */
     nudgeNumber?: number;
+    /**
+     * On an `order_failed` whose card the store's payment processor refused after the approval: why it refused the card,
+     * and whether any money moved, so your app can show the reason without reading `reason`'s words.
+     */
+    cardRefusal?: CardRefusal;
+    /** The one step that moves the purchase on: `add_card`, with the add-a-card link in `cardLinkUrl`. */
+    nextAction?: 'add_card' | (string & {});
+    /**
+     * When `cardLinkUrl` stops working, as an ISO 8601 timestamp, on a message that stays true after it does (`order_failed`):
+     * past it, ask Agentcard for a new link instead of sending this one.
+     */
+    cardLinkExpiresAt?: string;
+}
+/** Why a store's payment processor refused the shopper's card, and whether any money moved. */
+export interface CardRefusal {
+    /** `incorrect_number`, `insufficient_funds`, `expired_card`, `incorrect_cvc`, or `card_declined` for any other refusal. */
+    reason: 'incorrect_number' | 'insufficient_funds' | 'expired_card' | 'incorrect_cvc' | 'card_declined' | (string & {});
+    /** `none`: nothing was charged. `unknown`: Agentcard has no confirmation yet either way. */
+    charged: 'none' | 'unknown' | (string & {});
 }
 /** A `purchase.message` event, read. */
 export interface PurchaseMessage {

package/dist/message.js

@@ -18,6 +18,8 @@ const STRING_FACTS = [
     ['card_link_url', 'cardLinkUrl'],
     ['retry_until', 'retryUntil'],
     ['valid_until', 'validUntil'],
+    ['next_action', 'nextAction'],
+    ['card_link_expires_at', 'cardLinkExpiresAt'],
 ];
 const NUMBER_FACTS = [
     ['total_cents', 'totalCents'],
@@ -39,6 +41,10 @@ function readFacts(raw) {
         if (typeof value === 'number' && Number.isFinite(value))
             facts[name] = value;
     }
+    const refusal = raw.card_refusal;
+    if (isRecord(refusal) && typeof refusal.reason === 'string' && refusal.reason !== '') {
+        facts.cardRefusal = { reason: refusal.reason, charged: typeof refusal.charged === 'string' && refusal.charged !== '' ? refusal.charged : 'unknown' };
+    }
     return facts;
 }
 function requiredString(data, field) {

package/dist/model-view.d.ts

@@ -51,6 +51,11 @@ export interface BuyToolModelCart {
     total: string;
     /** True when the store has not priced its fees and tax yet: `total` is an estimate, never the final amount. */
     total_is_estimate: boolean;
+    /**
+     * Where `total` stands: `estimate` before the store priced the cart, `confirmed` once the store priced it, and `placed`
+     * once the order is placed. `total` is the final amount unless `total_is_estimate` is true.
+     */
+    total_status: 'estimate' | 'confirmed' | 'placed';
     /** What an estimated `total` leaves out, in words the model can repeat; null when the store priced the cart. */
     total_leaves_out: string | null;
     /** The most the shopper's card can be held for this cart: above `total` at a store that prices its final at checkout, `total` itself for a flight, which holds exactly that; else null. */
@@ -194,9 +199,11 @@ export declare function stripLinks(text: string): string;
  * 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. The page of a card the answer sent, `pages`,
- * stays as written.
+ * stays as written. A line that points at a step link the answer hands the app, `stepLinks`, keeps its words as a sentence
+ * whether or not the tool sent it: the app sends that link itself. 2026-11-05, a company's app with no sendLink: Marshalls'
+ * one-line sign-in ask went whole, and the app read an empty reply beside the sign-in link.
  */
-export declare function replyWithoutLinks(reply: string, sent: boolean, pages?: readonly (string | null | undefined)[]): string;
+export declare function replyWithoutLinks(reply: string, sent: boolean, pages?: readonly (string | null | undefined)[], stepLinks?: readonly string[]): 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
@@ -264,6 +271,8 @@ export declare function expiresIn(iso: string | null | undefined, now?: number):
  * whether the shopper has each link. A status this version does not know
  * reads as `needs_input`.
  */
+/** The carts and their grand totals as the model reads them, for carts a turn's answer did not bring, such as `buy.placedCarts`'. */
+export declare function cartsForModel(carts: readonly BuyCart[]): Pick<BuyToolModelView, 'carts' | 'grand_totals'>;
 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

package/dist/model-view.js

@@ -4,6 +4,8 @@ import { GONE, LINK_WORD_LINKS, MARKDOWN_IMAGE, holdStorePages, namesOnlyALink,
 import { withoutEmptyMarks } from './list-marks.js';
 /** The steps the shopper takes on a page a link opens: the message that asks for one is one short line. */
 const STEP_ACTIONS = new Set(['store_login', 'add_card', 'approve']);
+/** The links an answer hands over for a step the shopper takes: the add-card, approval and store sign-in links. */
+const STEP_LINKS = new Set(['vault', 'approval', 'store_login']);
 const MODEL_STATUSES = new Set(['needs_input', 'needs_card', 'approval_sent', 'placing', 'order_placed', 'declined']);
 /** At most twenty products reach the model. Agentcard's /buy answer lists up to eight, so this cap holds only for an older answer. */
 const MAX_PRODUCTS = 20;
@@ -81,13 +83,15 @@ const POINTS_AT_LINK = /^([^\n]*?\S)[ \t]*:[ \t]*(?:\n[ \t]*)?<?(?:https?:\/\/|(
  * 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. The page of a card the answer sent, `pages`,
- * stays as written.
+ * stays as written. A line that points at a step link the answer hands the app, `stepLinks`, keeps its words as a sentence
+ * whether or not the tool sent it: the app sends that link itself. 2026-11-05, a company's app with no sendLink: Marshalls'
+ * one-line sign-in ask went whole, and the app read an empty reply beside the sign-in link.
  */
-export function replyWithoutLinks(reply, sent, pages = []) {
+export function replyWithoutLinks(reply, sent, pages = [], stepLinks = []) {
     // A card's own store page stays where the reply wrote it (store-pages.ts), and a line whose words only named a link goes with it.
     // A bold label keeps its colon outside the bold (`**Photo:** <address>` reads `**Photo**: <address>`), so it reads as a label.
     const { text, restore } = holdStorePages(String(reply ?? '').replace(/(\*\*|__)([^*_\n]+?):\1/g, '$1$2$1:'), pages);
-    return restore(stripLinks(withoutGoneLines(text.replace(POINTS_AT_LINK, (_line, lead) => (sent && !namesOnlyALink(lead) ? `${lead}.` : GONE)))));
+    return restore(stripLinks(withoutGoneLines(text.replace(POINTS_AT_LINK, (line, lead) => ((sent || stepLinks.some((url) => line.includes(url))) && !namesOnlyALink(lead) ? `${lead}.` : GONE)))));
 }
 /** A currency's minor units as Intl knows them: 2 for USD and CAD, 0 for JPY. */
 function minorUnits(format) {
@@ -226,6 +230,7 @@ function cartView(cart, building) {
         tip: cart.tipCents > 0 ? money(cart.tipCents, cart.currency) : null,
         total: money(cart.totalCents, cart.currency) ?? money(0, cart.currency),
         total_is_estimate: cart.totalIsEstimate === true,
+        total_status: cart.totalStatus,
         // 2026-10-21, swarm-bigbox-a10: an estimate read "about $18.41 total with tax and shipping" to the shopper. The words
         // ride beside the flag, so the model never has to guess which side of the total tax and shipping sit on.
         total_leaves_out: cart.totalIsEstimate === true ? leftOut(cart.merchantFeeLines ?? []) : null,
@@ -299,6 +304,10 @@ function linkExpiry(result) {
  * whether the shopper has each link. A status this version does not know
  * reads as `needs_input`.
  */
+/** The carts and their grand totals as the model reads them, for carts a turn's answer did not bring, such as `buy.placedCarts`'. */
+export function cartsForModel(carts) {
+    return { carts: carts.map((cart) => cartView(cart)), grand_totals: grandTotals(carts) };
+}
 export function forModel(result) {
     const status = typeof result.status === 'string' && MODEL_STATUSES.has(result.status) ? result.status : 'needs_input';
     const products = shownProducts(result.products);
@@ -313,7 +322,7 @@ export function forModel(result) {
                 question: result.choice.question === null ? null : stripLinks(result.choice.question),
                 groups: result.choice.groups.map((group) => ({ name: stripLinks(group.name), required: group.required, options: group.options.map((option) => `${stripLinks(option.label)}${option.price_delta_cents ? ` (+$${(option.price_delta_cents / 100).toFixed(2)})` : ''}`) })),
             } } : {}),
-        reply: replyWithoutLinks(result.reply, products.some(held) || stores.some(heldStore) || result.link_sent === true, [...products.filter(held).map((product) => product.url), ...stores.filter(heldStore).map((store) => store.url)]),
+        reply: replyWithoutLinks(result.reply, products.some(held) || stores.some(heldStore) || result.link_sent === true, [...products.filter(held).map((product) => product.url), ...stores.filter(heldStore).map((store) => store.url)], (result.links ?? []).flatMap((link) => (STEP_LINKS.has(link.kind) && typeof link.url === 'string' && link.url !== '' ? [link.url] : []))),
         cart: result.cart ? cartView(result.cart, result.cart_building?.store) : null,
         carts: (result.carts ?? []).map((cart) => cartView(cart, result.cart_building?.store)),
         products: products.map((product) => ({ product_id: pickId(product), name: stripLinks(product.name), store: stripLinks(product.store ?? ''), price: productPrice(product), link_sent: held(product) })),

package/package.json

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