@agent-cards/commerce-sdk 0.18.11 → 0.18.14

package/dist/buy-tool.d.ts

@@ -34,6 +34,7 @@
 import type { BuyCardSize } from './card-size.js';
 import type { BuyPlan } from './plan.js';
 import type { BuyMerchantStatusUpdate, BuySearchStatus } from './search-status.js';
+import { type BuyGroupsUpdate } from './search-groups.js';
 import type { BuyFreshness, BuyRecheck, BuyStoreCheckUpdate } from './client.js';
 import type { BuyFulfilledBy } from './fulfilled-by.js';
 import { AgentcardClient, type BuyCart, type BuyCartBuilding, type BuyChoice, type BuyCodeRequest, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyTurnStatus, type BuyAvailability, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
@@ -421,6 +422,11 @@ export interface BuyToolOptions extends BuyStoreWait {
      * search starts, then what it found. One that throws costs nothing but the call to it.
      */
     onMerchantStatus?: (update: BuyMerchantStatusUpdate) => void | Promise<void>;
+    /**
+     * Hears every group of a call's products each time one changes, and once more from the answer (`BuyGroupsUpdate`), each
+     * group's `product_ids` naming the cards' `productId`s. One that throws costs nothing but the call to it.
+     */
+    onGroups?: (update: BuyGroupsUpdate) => void | Promise<void>;
     /**
      * Hears each store behind a card while Agentcard checks its price and stock, then the store's answer
      * (`BuyStoreCheckUpdate`): `cardId` is the card's `productId`. One that throws costs nothing but the call to it.
@@ -662,6 +668,8 @@ export interface BuyToolTurnOptions extends BuyStoreWait {
     onAvailability?: BuyToolOptions['onAvailability'];
     /** Hears each store this turn's searches ask, as the tool's `onMerchantStatus` does. */
     onMerchantStatus?: BuyToolOptions['onMerchantStatus'];
+    /** Hears the groups of this turn's products, as the tool's `onGroups` does. */
+    onGroups?: BuyToolOptions['onGroups'];
     /** Hears each store behind this turn's cards as it is checked, as the tool's `onStoreCheck` does. */
     onStoreCheck?: BuyToolOptions['onStoreCheck'];
     /** Hears this turn's re-check of the shopper's quotes, as the tool's `onRecheck` does. */

package/dist/buy-tool.js

@@ -1,8 +1,10 @@
+import { groupsOf } from './search-groups.js';
 import { AgentcardApiError, AgentcardClient, cartBuildingOf, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
 import { directCall, isProductAsk } from './direct.js';
 import { forModel, forModelError, pickId, productPrice, productCardKey, shownProducts, shownStores, stripLinks } from './model-view.js';
 import { choiceLines, leadsIntoList, messageForShopper, messagesListChoice, replyAsWritten, textingStyle } from './texting.js';
+import { onlyListMarks } from './list-marks.js';
 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';
@@ -777,7 +779,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', 'onMerchantStatus', 'onStoreCheck', 'onRecheck', 'onFreshness']) {
+    for (const key of ['onStatus', 'onFound', 'onAvailability', 'onMerchantStatus', 'onGroups', 'onStoreCheck', 'onRecheck', 'onFreshness']) {
         if (o[key] !== undefined && typeof o[key] !== 'function')
             throw new TypeError(`Pass ${key} as a function, or leave it out.`);
     }
@@ -859,6 +861,7 @@ export function buyTool(options) {
         onFound: o.onFound,
         onAvailability: o.onAvailability,
         onMerchantStatus: o.onMerchantStatus,
+        onGroups: o.onGroups,
         onStoreCheck: o.onStoreCheck,
         onRecheck: o.onRecheck,
         onFreshness: o.onFreshness,
@@ -1664,7 +1667,14 @@ export function buyTool(options) {
         // A step link held for the message that introduces it goes out before this call hands over any of its own.
         explicit?.release?.();
         const withdrawalsAtStart = withdrawals;
-        const input = parseBuyToolInput(raw);
+        const parsedInput = parseBuyToolInput(raw);
+        // A tapped turn's first call that names no product and no store picks the tapped card (TurnState.tapped).
+        const tappedId = explicit?.tapped ?? null;
+        if (explicit)
+            explicit.tapped = null;
+        const input = tappedId && !parsedInput.confirm && !parsedInput.new_order && !parsedInput.product_id && !parsedInput.store_id
+            ? { ...parsedInput, product_id: tappedId }
+            : parsedInput;
         // With carts at more than one store waiting, a new order would drop every one of them: "cancel the
         // reservation, keep the flowers" started a new conversation and lost the flowers cart (2026-10-20).
         // The ask goes to the same purchase instead, and Agentcard drops only the cart it names.
@@ -1783,7 +1793,9 @@ export function buyTool(options) {
             let heldTexts = [];
             /** Shows a message through onText, its lists as bullets (messageForShopper); `told` keeps each of Agentcard's messages in it as written. */
             const showMessage = async (message, texts, conversationId) => {
-                await speak(messageForShopper(message, leadIn, t.texting), { conversationId });
+                // A message of list marks or punctuation alone, such as `1.; 2.`, says nothing, and the shopper never reads it (list-marks.ts).
+                if (!onlyListMarks(message))
+                    await speak(messageForShopper(message, leadIn, t.texting), { conversationId });
                 leadIn = leadsIntoList(message);
                 told.push(...texts);
             };
@@ -1995,6 +2007,21 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
+                    ...(t.onGroups
+                        ? {
+                            onGroups: async (update) => {
+                                // The answer's groups go out once the call has its answer, below, whether it streamed or not.
+                                if (update.final)
+                                    return;
+                                try {
+                                    await t.onGroups({ ...update, groups: update.groups.map((g) => ({ ...g, product_ids: g.product_ids.map((id) => cardOfId.get(id) ?? id) })) });
+                                }
+                                catch {
+                                    // The app's display failing never fails the turn.
+                                }
+                            },
+                        }
+                        : {}),
                     ...(t.onStoreCheck
                         ? {
                             onStoreCheck: async (update) => {
@@ -2138,6 +2165,17 @@ export function buyTool(options) {
                 }
             }
             ack?.cancel();
+            // The answer's groups, each product named by the card it goes out as, as `pickId` names a card.
+            if (t.onGroups && turn?.catalog) {
+                const cardOf = new Map(turn.catalog.items.map((item) => [item.id, pickId({ id: item.id, ref: item.ref }) ?? item.id]));
+                const groups = groupsOf(turn).map(({ products: _, ...g }) => ({ ...g, product_ids: g.product_ids.map((id) => cardOf.get(id) ?? id) }));
+                try {
+                    await t.onGroups({ conversationId: turn.conversation_id || null, groups, final: true });
+                }
+                catch {
+                    // The app's display failing never fails the call.
+                }
+            }
             const settled = plan && 'local' in plan ? plan.local : turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirmSent, startedAt);
             await t.ackOut;
             // A newer message from the shopper stopped this turn, and its own turn answers: this one ends here and says nothing
@@ -2393,7 +2431,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', 'onMerchantStatus', 'onStoreCheck', 'onRecheck', 'onFreshness', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', 'onMerchantStatus', 'onGroups', 'onStoreCheck', 'onRecheck', 'onFreshness', '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.`);
         }
@@ -2478,6 +2516,7 @@ export function buyTool(options) {
             onFound: own.onFound ?? o.onFound,
             onAvailability: own.onAvailability ?? o.onAvailability,
             onMerchantStatus: own.onMerchantStatus ?? o.onMerchantStatus,
+            onGroups: own.onGroups ?? o.onGroups,
             onStoreCheck: own.onStoreCheck ?? o.onStoreCheck,
             onRecheck: own.onRecheck ?? o.onRecheck,
             onFreshness: own.onFreshness ?? o.onFreshness,
@@ -2587,6 +2626,7 @@ export function buyTool(options) {
         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;
+        state.tapped = tappedId;
         // 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

package/dist/client.d.ts

@@ -11,6 +11,7 @@
 import { type BuyTrip } from './trip.js';
 import { type BuyPlan } from './plan.js';
 import { type BuyMerchantStatusUpdate, type BuySearchStatus } from './search-status.js';
+import { type BuyGroup, type BuyGroupsUpdate } from './search-groups.js';
 import { type BuyFulfilledBy } from './fulfilled-by.js';
 import { type BuyCardSize } from './card-size.js';
 import { type AgentcardListener, type ListenOptions } from './listen.js';
@@ -196,6 +197,11 @@ export interface BuyStreamHandlers {
      * follow one store, keep the updates `isMerchantStatusAt(update, 'walmart.com')` accepts. The answer's `search` holds every store.
      */
     onMerchantStatus?: (update: BuyMerchantStatusUpdate) => void | Promise<void>;
+    /**
+     * Every group of the turn's products (BuyGroup), each time one changes, and once more from the answer. An answer with no
+     * groups comes as one group holding every product, as `groupsOf` reads it. Draw one grid per group, in the order given.
+     */
+    onGroups?: (update: BuyGroupsUpdate) => void | Promise<void>;
     /**
      * Agentcard reads the shopper's quotes again: on their return after a gap, or before a yes to a price older than its
      * window. Comes with `phase: 'started'`, the line to show at once and every item `checking`, then `phase: 'finished'` with
@@ -557,6 +563,8 @@ export interface BuyCatalog {
     merchant_name: string;
     items: BuyCatalogItem[];
     presented: boolean;
+    /** The groups `items` come in, one per store or item asked for (BuyGroup); absent from an older API. `groupsOf` reads them. */
+    groups?: BuyGroup[];
 }
 /** The product a `pick` named, by its catalog id and ref, and whether the cart now holds it. */
 export interface BuyPick {

package/dist/client.js

@@ -11,6 +11,7 @@
 import { tripOf } from './trip.js';
 import { planOf } from './plan.js';
 import { merchantStatusOf, searchOf } from './search-status.js';
+import { groupListOf, groupOf, groupsOf } from './search-groups.js';
 import { isRecord } from './verify.js';
 import { failedPartyOf, fulfilledByField } from './fulfilled-by.js';
 import { cardSizeField } from './card-size.js';
@@ -25,7 +26,7 @@ export const STATUS_WORDING = Object.freeze({
     searching_wider: 'Checking more stores for this…',
 });
 /** The handlers that ask Agentcard to stream a turn. */
-const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability', 'onReplyWritten', 'onMerchantStatus', 'onRecheck', 'onFreshness', 'onStoreCheck'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability', 'onReplyWritten', 'onMerchantStatus', 'onGroups', 'onRecheck', 'onFreshness', 'onStoreCheck'];
 const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -299,7 +300,8 @@ function catalogOf(v) {
     if (!isRecord(v))
         return null;
     const items = catalogItemsOf(v.items);
-    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
+    const groups = groupListOf(v.groups);
+    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true, ...(groups ? { groups } : {}) };
 }
 /** A catalog block's products, as `items` or `more` lists them. */
 function catalogItemsOf(v) {
@@ -596,6 +598,11 @@ async function readStreamedTurn(res, stream, timeoutMs) {
         delivering = delivering.then(() => hand()).catch(() => { });
     };
     let failure = null;
+    // The turn's groups so far, in the order they first came; a group sent again takes its own place.
+    let groups = [];
+    // Whether a `group` event already carried the turn's final groups, which an answer with no catalog (a search that found
+    // nothing, a failed turn) can only say that way; the envelope's groups are the same, so they are not handed on twice.
+    let groupsFinal = false;
     try {
         await eachEvent(res, (event, text) => {
             const data = parseJson(text);
@@ -606,6 +613,12 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             const named = conversationId;
             if (event === 'envelope') {
                 envelope = data;
+                const catalog = catalogOf(data.catalog);
+                if (stream.onGroups && catalog && !groupsFinal) {
+                    // An answer whose search found nothing still comes, as one `empty` group, so the app hears the search ended.
+                    const final = groupsOf({ catalog, search: searchOf(data.search) }).map(({ products: _, ...g }) => g);
+                    deliver(() => stream.onGroups({ conversationId: named, groups: final, final: true }));
+                }
                 return true;
             }
             if (event === 'progress' && typeof data.stage === 'string' && PROGRESS_STAGES.has(data.stage) && stream.onProgress) {
@@ -694,6 +707,25 @@ async function readStreamedTurn(res, stream, timeoutMs) {
                     deliver(() => stream.onStoreCheck(update));
                 }
             }
+            else if (event === 'group' && stream.onGroups) {
+                // One group as it changes, or the whole list; an event with neither is read past.
+                const changed = Array.isArray(data.groups) ? groupListOf(data.groups) ?? [] : [groupOf(data.group)].flatMap((g) => g ?? []);
+                if (!changed.length)
+                    return;
+                const final = data.final === true;
+                // A final list is the turn's whole answer: it replaces the groups held, whose ids it may have split into one per ask.
+                if (final && Array.isArray(data.groups))
+                    groups = changed;
+                else {
+                    for (const g of changed) {
+                        const at = groups.findIndex((held) => held.id === g.id);
+                        groups = at < 0 ? [...groups, g] : groups.map((held, i) => (i === at ? g : held));
+                    }
+                }
+                const now = groups;
+                groupsFinal ||= final;
+                deliver(() => stream.onGroups({ conversationId: named, groups: now, final }));
+            }
             else if (event === 'merchant' && stream.onMerchantStatus) {
                 const update = merchantStatusOf(data);
                 if (update)

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type
 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 { 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';

package/dist/index.js

@@ -4,6 +4,7 @@ export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, } fr
 export { ORDER_STEPS, updateOrder, arrivalText, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, } from './handler.js';
 export { searchAt, isMerchantStatusAt, merchantStatusLine, searchStatusLines, } from './search-status.js';
+export { groupsOf, } from './search-groups.js';
 export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, STATUS_WORDING, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, typingDelay, } from './messages.js';

package/dist/list-marks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A list mark with nothing after it is no message. When a reply's list items were only links or photos, such as
+ * `1. ![Bentgo Classic Lunch Box](...); 2. ![Twfbrm Bento Boxes](...)`, taking the links out (stripLinks) left the marks
+ * alone, and on 2026-11-04 a shopper on chat.opencommerce.sh read a message that said only `1.; 2.`. These read a text for
+ * marks a removed item emptied, so an item that keeps its words keeps its number, and a mark with none goes.
+ */
+/** True when a message holds list marks or punctuation and nothing else, so it says nothing to the shopper. */
+export declare function onlyListMarks(text: string): boolean;
+/**
+ * The text without the list marks an item no longer follows, and without a line left with marks and punctuation alone.
+ * A line that was blank stays blank, and every other line stays as written.
+ */
+export declare function withoutEmptyMarks(text: string): string;

package/dist/list-marks.js

@@ -0,0 +1,40 @@
+/**
+ * A list mark with nothing after it is no message. When a reply's list items were only links or photos, such as
+ * `1. ![Bentgo Classic Lunch Box](...); 2. ![Twfbrm Bento Boxes](...)`, taking the links out (stripLinks) left the marks
+ * alone, and on 2026-11-04 a shopper on chat.opencommerce.sh read a message that said only `1.; 2.`. These read a text for
+ * marks a removed item emptied, so an item that keeps its words keeps its number, and a mark with none goes.
+ */
+/** A list mark as a reply writes one: `1.`, `2)`, or a bullet. */
+const MARK = String.raw `(?:\d{1,2}[.)]|[•*+-])`;
+/** A line, or a whole message, of list marks and punctuation alone, with no word or number of an item. */
+const ONLY_MARKS = new RegExp(String.raw `^(?:\s|[.,;:!?…·]|${MARK})*$`, 'u');
+/** True when a message holds list marks or punctuation and nothing else, so it says nothing to the shopper. */
+export function onlyListMarks(text) {
+    return /\S/.test(text) && ONLY_MARKS.test(text);
+}
+// An emptied mark that opens a list, at the line's start or after the colon that leads into it, before another mark
+// (`1.; 2. Twfbrm`, `Options: 1.; 2. Travel mug`); one between two semicolons or at the line's end after one (`Bentgo; 2.;
+// 3. Twfbrm`, `Bentgo; 2.`). A number after a colon with nothing after it stays, since `Size: 9.` gives a value, and so does a
+// number inside a sentence, `size 9, 10.`.
+const LEADING_EMPTY = new RegExp(String.raw `(^[ \t]*|:[ \t]*)(?:${MARK}[ \t;,]*)+(?=\d{1,2}[.)][ \t]|•[ \t])`, 'gm');
+const BETWEEN_EMPTY = new RegExp(String.raw `[ \t]*;[ \t]*${MARK}[ \t]*(?=;|$)`, 'gm');
+// A list a colon leads into whose every item went, `Options: 1.; 2.`: its numbers go and the lead-in keeps its colon. A
+// single number after a colon, `Size: 9.`, has no `;` to mark it as a list, and stays.
+const EMPTY_AFTER_COLON = new RegExp(String.raw `:[ \t]*${MARK}(?:[ \t]*;[ \t]*${MARK})+[ \t;]*$`, 'gm');
+/**
+ * The text without the list marks an item no longer follows, and without a line left with marks and punctuation alone.
+ * A line that was blank stays blank, and every other line stays as written.
+ */
+export function withoutEmptyMarks(text) {
+    return text
+        .split('\n')
+        .flatMap((line) => {
+        if (!/\S/.test(line))
+            return [line];
+        const kept = line.replace(LEADING_EMPTY, '$1').replace(EMPTY_AFTER_COLON, ':').replace(BETWEEN_EMPTY, '');
+        return ONLY_MARKS.test(kept) ? [] : [kept];
+    })
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}

package/dist/model-view.d.ts

@@ -184,7 +184,8 @@ export interface BuyToolModelView {
     };
 }
 /**
- * The text with every link taken out: a Markdown link keeps its label, an address with a path or a scheme goes
+ * The text with every link taken out: a Markdown link keeps its label unless the label only names the link
+ * (store-pages.ts LINK_WORD_LINKS), a Markdown image goes whole, 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;
@@ -192,9 +193,10 @@ 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.
+ * "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.
  */
-export declare function replyWithoutLinks(reply: string, sent: boolean): string;
+export declare function replyWithoutLinks(reply: string, sent: boolean, pages?: readonly (string | null | undefined)[]): 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

package/dist/model-view.js

@@ -1,5 +1,7 @@
 import { SENTENCE_END, lastSentenceStart, leadsIn, withoutLeadIn } from './sentences.js';
 import { toMessages } from './messages.js';
+import { GONE, LINK_WORD_LINKS, MARKDOWN_IMAGE, holdStorePages, namesOnlyALink, withoutGoneLines } from './store-pages.js';
+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']);
 const MODEL_STATUSES = new Set(['needs_input', 'needs_card', 'approval_sent', 'placing', 'order_placed', 'declined']);
@@ -44,11 +46,15 @@ function wwwName(address) {
     return host && !/[/?#]/.test(host) ? siteName(host) + (closing ?? '') : '';
 }
 /**
- * The text with every link taken out: a Markdown link keeps its label, an address with a path or a scheme goes
+ * The text with every link taken out: a Markdown link keeps its label unless the label only names the link
+ * (store-pages.ts LINK_WORD_LINKS), a Markdown image goes whole, 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 function stripLinks(text) {
-    return String(text ?? '')
+    // A list item that was only a link leaves its mark behind, and the mark goes with it (list-marks.ts).
+    return withoutEmptyMarks(withoutGoneLines(String(text ?? '')
+        .replace(MARKDOWN_IMAGE, GONE)
+        .replace(LINK_WORD_LINKS, GONE))
         .replace(MARKDOWN_LINK, '$1')
         .replace(SCHEME_URL, '')
         .replace(WWW_URL, wwwName)
@@ -59,7 +65,7 @@ export function stripLinks(text) {
         .replace(/[ \t]{2,}/g, ' ')
         .replace(/[ \t]+$/gm, '')
         .replace(/\n{3,}/g, '\n\n')
-        .trim();
+        .trim());
 }
 /**
  * A line that points at a link with a colon, the link after it on the same line or alone on the next: `here's the stool on
@@ -74,10 +80,14 @@ const POINTS_AT_LINK = /^([^\n]*?\S)[ \t]*:[ \t]*(?:\n[ \t]*)?<?(?:https?:\/\/|(
  * 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.
+ * "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.
  */
-export function replyWithoutLinks(reply, sent) {
-    return stripLinks(String(reply ?? '').replace(POINTS_AT_LINK, (_line, lead) => (sent ? `${lead}.` : '')));
+export function replyWithoutLinks(reply, sent, pages = []) {
+    // 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)))));
 }
 /** A currency's minor units as Intl knows them: 2 for USD and CAD, 0 for JPY. */
 function minorUnits(format) {
@@ -301,7 +311,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),
+        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)]),
         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/dist/search-groups.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The groups an answer's products come in: one per store or item the shopper asked for, such as a vacuum at Amazon and a
+ * laundry hamper at Target, each with its own stores, status and products. The answer's `catalog.groups` carries them beside
+ * the flat `catalog.items`, which every group's `product_ids` point into; a streamed turn's `group` events carry each group
+ * as it changes. `groupsOf` reads them, and reads an answer with no groups as one group holding every product, so an app
+ * draws a grid per group whatever the answer carries.
+ */
+import { type BuyMerchantStatus } from './search-status.js';
+import type { BuyCatalog, BuyCatalogItem } from './client.js';
+/** What a group holds: products, or one part of a trip. */
+export type BuyGroupKind = 'product' | 'flight' | 'stay' | 'car' | 'event' | 'table';
+/**
+ * Where a group stands. `loading`: its searches still run. `ready`: it has products to show. `empty`: its searches
+ * answered with none. `failed`: its searches failed. `needs`: it waits for details the shopper has not given, in `missing`.
+ */
+export type BuyGroupStatus = 'loading' | 'ready' | 'empty' | 'failed' | 'needs';
+/** One group of an answer's products, as Agentcard sends it. */
+export interface BuyGroup {
+    /** The group's id, the same on every update of the group within a turn. */
+    id: string;
+    kind: BuyGroupKind;
+    /** The group's heading, to show the shopper: `Vacuums at Amazon`. */
+    label: string;
+    /** The part of the shopper's message this group answers: `a vacuum on Amazon`. */
+    ask: string;
+    /** Each store the group searched, in the order its search started. */
+    stores: BuyMerchantStatus[];
+    status: BuyGroupStatus;
+    /** `full`: draw the group's products as a grid. `summary`: draw only its `summary` line, which the shopper taps to see them. */
+    display: 'full' | 'summary';
+    /** The ids of the group's products in `catalog.items`, in the order to show them. */
+    product_ids: string[];
+    /** One line for the group, such as `Also at Home Depot from $89`; absent when Agentcard wrote none. */
+    summary?: string;
+    /** What the group assumed that the shopper did not say, such as `arrival Dec 24`; absent when it assumed nothing. */
+    assumes?: string;
+    /** The details a `needs` group waits for, such as `pickup time`; absent otherwise. */
+    missing?: string[];
+}
+/** A group with its products read from the answer's catalog, in the group's order. */
+export interface BuyGroupWithProducts extends BuyGroup {
+    products: BuyCatalogItem[];
+}
+/** The groups of a running turn, every time one of them changes. */
+export interface BuyGroupsUpdate {
+    conversationId: string | null;
+    /** Every group the turn has so far, in the shopper's order. */
+    groups: BuyGroup[];
+    /** True for the groups the finished answer carries, the last update of the turn; false while its searches run. */
+    final: boolean;
+}
+/** One group as Agentcard sent it, or null for one with no id or a kind or status this version does not know. */
+export declare function groupOf(v: unknown): BuyGroup | null;
+/** A list of groups as Agentcard sent it, or undefined when it sent none. */
+export declare function groupListOf(v: unknown): BuyGroup[] | undefined;
+/** The parts of an answer `groupsOf` reads: a `BuyTurn`, or any answer that carries its catalog and search. */
+export interface BuyGroupsSource {
+    catalog: BuyCatalog | null;
+    search?: {
+        final: boolean;
+        merchants: BuyMerchantStatus[];
+    } | null;
+}
+/**
+ * The answer's groups, each with its products read from the catalog in the group's order; an id the catalog does not hold
+ * is left out. An answer with no groups reads as one `product` group holding every product, `full`, with the answer's
+ * stores: `loading` while a store's search still runs, `ready` with products, `empty` without. An answer with no catalog
+ * reads as no groups. It reads the answer alone, so a stored answer read back later gives the groups the live turn gave.
+ */
+export declare function groupsOf(answer: BuyGroupsSource): BuyGroupWithProducts[];

package/dist/search-groups.js

@@ -0,0 +1,60 @@
+/**
+ * The groups an answer's products come in: one per store or item the shopper asked for, such as a vacuum at Amazon and a
+ * laundry hamper at Target, each with its own stores, status and products. The answer's `catalog.groups` carries them beside
+ * the flat `catalog.items`, which every group's `product_ids` point into; a streamed turn's `group` events carry each group
+ * as it changes. `groupsOf` reads them, and reads an answer with no groups as one group holding every product, so an app
+ * draws a grid per group whatever the answer carries.
+ */
+import { searchOf } from './search-status.js';
+const KINDS = new Set(['product', 'flight', 'stay', 'car', 'event', 'table']);
+const STATUSES = new Set(['loading', 'ready', 'empty', 'failed', 'needs']);
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (v) => (typeof v === 'string' && v.trim() !== '' ? v : null);
+const texts = (v) => (Array.isArray(v) ? v.filter((s) => text(s) !== null) : []);
+/** One group as Agentcard sent it, or null for one with no id or a kind or status this version does not know. */
+export function groupOf(v) {
+    if (!isRecord(v))
+        return null;
+    const id = text(v.id);
+    if (!id || typeof v.kind !== 'string' || !KINDS.has(v.kind) || typeof v.status !== 'string' || !STATUSES.has(v.status))
+        return null;
+    const stores = searchOf({ search_id: id, merchants: Array.isArray(v.stores) ? v.stores : [] })?.merchants ?? [];
+    const summary = text(v.summary);
+    const assumes = text(v.assumes);
+    const missing = texts(v.missing);
+    return {
+        id, kind: v.kind, label: text(v.label) ?? '', ask: text(v.ask) ?? '', stores, status: v.status,
+        display: v.display === 'summary' ? 'summary' : 'full', product_ids: texts(v.product_ids),
+        ...(summary ? { summary } : {}), ...(assumes ? { assumes } : {}), ...(missing.length ? { missing } : {}),
+    };
+}
+/** A list of groups as Agentcard sent it, or undefined when it sent none. */
+export function groupListOf(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const groups = v.flatMap((g) => groupOf(g) ?? []);
+    return groups.length ? groups : undefined;
+}
+/**
+ * The answer's groups, each with its products read from the catalog in the group's order; an id the catalog does not hold
+ * is left out. An answer with no groups reads as one `product` group holding every product, `full`, with the answer's
+ * stores: `loading` while a store's search still runs, `ready` with products, `empty` without. An answer with no catalog
+ * reads as no groups. It reads the answer alone, so a stored answer read back later gives the groups the live turn gave.
+ */
+export function groupsOf(answer) {
+    const catalog = answer.catalog;
+    if (!catalog)
+        return [];
+    const byId = new Map(catalog.items.map((item) => [item.id, item]));
+    // Read again here, so an answer kept as JSON and read back later, or a raw body, gives the same groups as the live turn.
+    const groups = groupListOf(catalog.groups);
+    if (groups) {
+        return groups.map((g) => ({ ...g, products: g.product_ids.flatMap((id) => byId.get(id) ?? []) }));
+    }
+    const search = answer.search ?? null;
+    const status = search && !search.final ? 'loading' : catalog.items.length ? 'ready' : 'empty';
+    return [{
+            id: 'all', kind: 'product', label: catalog.merchant_name, ask: '', stores: search?.merchants ?? [], status, display: 'full',
+            product_ids: catalog.items.map((item) => item.id), products: catalog.items,
+        }];
+}

package/dist/store-pages.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The store pages a reply may keep, and the words that only name a link.
+ *
+ * Every link comes out of what the shopper reads (model-view.ts stripLinks), with one exception: the page at the store of a
+ * product or store card this answer sent, written as the card carries it. The shopper asked for it, and it is the real page
+ * at the store. A referral or tracking address (buy.trychannel3.com) is never one, and neither is a photo's address.
+ *
+ * 2026-11-02, chat.opencommerce.sh (conv_b1eb3d1508196604653217c0): a reply about a rack at Amazon ended
+ * "Link: https://www.amazon.com/dp/B0BS765YQL" and "Photo: https://m.media-amazon.com/...jpg", and the shopper read "link."
+ * and "photo." as a message of its own. The card's page now stays, and a line that named only a removed link goes.
+ */
+/** True when `text` holds nothing but words that name a link, so it goes with the link. */
+export declare function namesOnlyALink(text: string): boolean;
+/** A Markdown image. A chat shows its alt text, never the picture. */
+export declare const MARKDOWN_IMAGE: RegExp;
+/** Markdown links whose labels only name the link, at the end of a line or making up all of it, with the marks between them. A sentence's own closing mark before them stays. */
+export declare const LINK_WORD_LINKS: RegExp;
+/**
+ * The reply with each address of a card's store page held aside, and the function that puts them back once every other link
+ * is gone. A Markdown link to such a page reads as its label then the address, or the address alone when its label only named
+ * it. An address that only shares a page's host is not that page and comes out as before.
+ */
+export declare function holdStorePages(reply: string, pages: readonly (string | null | undefined)[]): {
+    text: string;
+    restore: (text: string) => string;
+};
+/** What a removed line leaves in its place until its newline goes with it (withoutGoneLines). */
+export declare const GONE = "\u2064";
+/** The text with every line that held only a removed link taken out with its newline, so no paragraph break is left where it was. */
+export declare function withoutGoneLines(text: string): string;

package/dist/store-pages.js

@@ -0,0 +1,92 @@
+/**
+ * The store pages a reply may keep, and the words that only name a link.
+ *
+ * Every link comes out of what the shopper reads (model-view.ts stripLinks), with one exception: the page at the store of a
+ * product or store card this answer sent, written as the card carries it. The shopper asked for it, and it is the real page
+ * at the store. A referral or tracking address (buy.trychannel3.com) is never one, and neither is a photo's address.
+ *
+ * 2026-11-02, chat.opencommerce.sh (conv_b1eb3d1508196604653217c0): a reply about a rack at Amazon ended
+ * "Link: https://www.amazon.com/dp/B0BS765YQL" and "Photo: https://m.media-amazon.com/...jpg", and the shopper read "link."
+ * and "photo." as a message of its own. The card's page now stays, and a line that named only a removed link goes.
+ */
+/** A label that only names the link it stood for: `link`, `photo`, `here's the link`. Once the link is gone it says nothing. */
+const LINK_WORDS = String.raw `(?:here(?:'s|\s+is)?\s+)?(?:(?:the|a|an|this|its|product|store)\s+)*(?:links?|photos?|pics?|pictures?|images?|urls?|pages?|listings?|here)`;
+const ONLY_LINK_WORDS = new RegExp(String.raw `^\s*[-*•]?\s*${LINK_WORDS}\s*[.:!]?\s*$`, 'i');
+/** True when `text` holds nothing but words that name a link, so it goes with the link. */
+export function namesOnlyALink(text) {
+    return ONLY_LINK_WORDS.test(String(text ?? '').replace(/\*\*|__/g, ''));
+}
+/** A Markdown image. A chat shows its alt text, never the picture. */
+export const MARKDOWN_IMAGE = /!\[[^\]\n]*\]\([^)\n]*\)/g;
+/** Markdown links whose labels only name the link, at the end of a line or making up all of it, with the marks between them. A sentence's own closing mark before them stays. */
+export const LINK_WORD_LINKS = new RegExp(String.raw `(?:[ \t]*(?:[,;|&·•-]|\band\b|\bor\b)?[ \t]*\[[ \t]*(?:\*\*|__)?${LINK_WORDS}(?:\*\*|__)?[ \t]*\]\([^)\n]*\)[.,;:!]?)+[ \t]*$`, 'gim');
+/** Hosts that only count a click and send the shopper on: never the store's own page. */
+const TRACKING_HOSTS = ['trychannel3.com'];
+/** A page as compared here: host without `www.`, path without a trailing slash, and its query. Null for an address that is no web page. */
+function pageKey(address) {
+    try {
+        const url = new URL(address);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return null;
+        const host = url.hostname.toLowerCase().replace(/^www\./, '');
+        if (TRACKING_HOSTS.some((tracking) => host === tracking || host.endsWith(`.${tracking}`)))
+            return null;
+        return `${host}${url.pathname.replace(/\/+$/, '')}${url.search}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** A full address in a reply, and the closing marks of its sentence after it. */
+const ADDRESS = /https?:\/\/[^\s<>"'`)\]]+/gi;
+/** A Markdown link with a full address. */
+const MARKDOWN_ADDRESS = /\[([^\]\n]*)\]\((https?:\/\/[^)\s]+)\)/gi;
+/** The mark that holds a kept page's place while every other link comes out: invisible, and no link pattern reads it. */
+const HOLD = (i) => `⁣${i}⁣`;
+const HELD = /⁣(\d+)⁣/g;
+/**
+ * The reply with each address of a card's store page held aside, and the function that puts them back once every other link
+ * is gone. A Markdown link to such a page reads as its label then the address, or the address alone when its label only named
+ * it. An address that only shares a page's host is not that page and comes out as before.
+ */
+export function holdStorePages(reply, pages) {
+    const keys = new Set(pages.map((page) => (typeof page === 'string' ? pageKey(page) : null)).filter((key) => key !== null));
+    const held = [];
+    const hold = (address) => {
+        const key = pageKey(address);
+        if (key === null || !keys.has(key))
+            return null;
+        held.push(address);
+        return HOLD(held.length - 1);
+    };
+    if (keys.size === 0)
+        return { text: reply, restore: (text) => text };
+    /** A Markdown link to a held page reads as its label then the page, or the page alone when its label only named it. */
+    const labelled = (label, mark) => (namesOnlyALink(label) || label.trim() === '' ? mark : `${label.trim()}: ${mark}`);
+    // Each card's page exactly as the card carries it goes first, in a Markdown link or on its own, so a page whose address
+    // holds a bracket, such as `stool_(oak)`, is held whole before MARKDOWN_ADDRESS and ADDRESS, which stop at a bracket.
+    const exact = [...new Set(pages.filter((page) => typeof page === 'string' && pageKey(page) !== null))].sort((a, b) => b.length - a.length);
+    const text = exact
+        .reduce((out, page) => {
+        const quoted = page.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const inLink = out.replace(new RegExp(String.raw `\[([^\]\n]*)\]\(${quoted}\)`, 'g'), (_whole, label) => labelled(label, HOLD(held.push(page) - 1)));
+        // The page alone, never the start of a longer address: what follows it ends the address or the sentence.
+        return inLink.replace(new RegExp(String.raw `${quoted}(?=$|[\s<>"'\x60\]]|[.,;:!?)]+(?:\s|$))`, 'g'), () => HOLD(held.push(page) - 1));
+    }, reply)
+        .replace(MARKDOWN_ADDRESS, (whole, label, address) => {
+        const mark = hold(address);
+        return mark === null ? whole : labelled(label, mark);
+    })
+        .replace(ADDRESS, (whole) => {
+        const [, address, closing] = /^(.*?)([.,;:!?]*)$/.exec(whole) ?? [];
+        const mark = address ? hold(address) : null;
+        return mark === null ? whole : `${mark}${closing ?? ''}`;
+    });
+    return { text, restore: (out) => out.replace(HELD, (_mark, i) => held[Number(i)] ?? '') };
+}
+/** What a removed line leaves in its place until its newline goes with it (withoutGoneLines). */
+export const GONE = '\u2064';
+/** The text with every line that held only a removed link taken out with its newline, so no paragraph break is left where it was. */
+export function withoutGoneLines(text) {
+    return text.replace(/^[ \t]*\u2064[ \t]*(?:\n|$)/gm, '').replace(/[ \t]*\u2064/g, '');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.18.11",
+  "version": "0.18.14",
   "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",