@agent-cards/commerce-sdk 0.14.0 → 0.15.0

package/README.md

@@ -458,6 +458,7 @@ const buy = buyTool({
 - `onStatus` hears each step the moment Agentcard starts it, as a line to show in place of loading dots: `searching Target and Walmart`, `adding it to your cart`, `working through the store's checkout`. `step` names the step, such as `searching` or `adding_to_cart`, for an app that writes its own words. A call that only writes its reply sends none, so keep your dots until the first line comes.
 - `onFound` hears how many products the searches found, after the cards it counts: `shown` cards of `found` products, such as "8 of 23 shown", each time the count grows. `more` holds the products past the cards as product links, in the order they were found, for a "show more" that runs no new search. The model never reads them.
 - `onProgress` still hears the stage, `searching`, `building_cart`, `checking_out` or `working`.
+- `onAvailability` hears whether the places a booking's cards show have room at the time the shopper asked for. A place's card can go out before Agentcard's live search knows: its `availability` reads `checking`, so show it without its choose button. The update names each card by its `productId` with `available` (its open times in `slots`, empty when none were named), `unavailable` (full then) or `unknown` (the search could not say). Change the card in place, and offer it as a choice only when it reads `available`. A call that ends with a card still `checking` sends `unknown` for it. Every other card, a retail product's included, carries no `availability`.
 - `onProducts` hears the products a search found the moment it answers, before Agentcard writes its reply, with the conversation, when the search ran (`asOf`) and the store's name. With `sendLink`, each product's card goes out then too, a few seconds before the answer, and the answer sends only the cards it adds. Pass `earlyCards: false` to send only the cards the answer names, with the answer: the reply often names only some of a search's products.
 - `onText` hears each message Agentcard writes, links included, the moment it is written, and after the cards of the search it is about.
 - `onCart` hears the cart a confirm would place, or null, and every cart on the table, each time a call builds or changes one, before the message that announces it.

package/dist/buy-tool.d.ts

@@ -31,7 +31,7 @@
  * messages and links as one sequence, in the order they happened, and spaces
  * the messages like someone texting.
  */
-import { AgentcardClient, type BuyCart, type BuyCartBuilding, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyTurnStatus, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
+import { AgentcardClient, type BuyCart, type BuyCartBuilding, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyTurnStatus, type BuyAvailability, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
 import { type DirectCall } from './direct.js';
 import { type BuyToolModelView } from './model-view.js';
@@ -112,6 +112,12 @@ export interface BuyToolLink {
     storeId?: string;
     /** On a store link: the store's delivery estimate in minutes, or null when the store showed none. */
     etaMinutes?: number | null;
+    /**
+     * On a product link for a place to book: whether it has room at the time the shopper asked for. Offer the card as a
+     * choice only when it reads `available`; `checking` changes in place once `onAvailability` hears the live answer.
+     * Absent on every other card, such as a retail product's.
+     */
+    availability?: BuyAvailability;
 }
 /** A store the answer's reply presents to choose from. */
 export interface BuyToolStore {
@@ -158,6 +164,8 @@ export interface BuyToolProduct {
      * conversation.
      */
     linkSent: boolean;
+    /** For a place to book: whether it has room at the asked time. Absent on a product with no such question. */
+    availability?: BuyAvailability;
 }
 /** One answer of the buy tool, whole, for your code. Hand it to `forModel` before a model reads it. */
 export interface BuyToolResult {
@@ -230,6 +238,18 @@ export type BuyAckMode = 'reaction' | 'text' | 'none';
  * product links the app reveals on "show more" with no new search; the model never reads them. Find mode sends a count
  * with no `more`.
  */
+/**
+ * What Agentcard's live search said of places whose cards went out as `checking`, each matched to its card by the
+ * card's `productId`. A call that ends without saying sends `unknown` for each card it left `checking`, so no card
+ * waits for an answer that is not coming.
+ */
+export interface BuyToolAvailability {
+    conversationId: string;
+    items: Array<{
+        productId: string;
+        availability: BuyAvailability;
+    }>;
+}
 export interface BuyToolFound {
     conversationId: string;
     shown: number;
@@ -317,6 +337,12 @@ export interface BuyToolOptions {
      * comes. One that throws costs nothing but the call to it.
      */
     onFound?: (found: BuyToolFound) => void | Promise<void>;
+    /**
+     * Hears whether the places a call's cards show have room (`BuyToolAvailability`), right after the cards it changes went
+     * out through `sendLink`: change each card in place, by its `productId`. It needs `earlyCards`, the default. One that
+     * throws costs nothing but the call to it.
+     */
+    onAvailability?: (update: BuyToolAvailability) => void | Promise<void>;
     /**
      * Hears the products a call's search found, the moment the search answers and before Agentcard writes its reply,
      * with the conversation, when the search ran (`asOf`, as the answer's `catalog.as_of` names it) and the store's name.
@@ -532,6 +558,8 @@ export interface BuyToolTurnOptions {
     onStatus?: BuyToolOptions['onStatus'];
     /** Hears how many products this turn's calls found, as the tool's `onFound` does. */
     onFound?: BuyToolOptions['onFound'];
+    /** Hears whether the places this turn's cards show have room, as the tool's `onAvailability` does. */
+    onAvailability?: BuyToolOptions['onAvailability'];
     /** Hears the products each search of this turn's calls found, the moment it answers, as the tool's `onProducts` does. */
     onProducts?: BuyToolOptions['onProducts'];
     /**

package/dist/buy-tool.js

@@ -201,7 +201,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] : []), expiresAt: null };
+    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] : []), expiresAt: null, ...(product.availability ? { availability: product.availability } : {}) };
 }
 function productsOfCatalog(catalog) {
     return (catalog.items ?? [])
@@ -220,6 +220,7 @@ function productsOfCatalog(catalog) {
         url: item.url ?? null,
         action: productAction(catalog.merchant),
         linkSent: false,
+        ...(item.availability ? { availability: item.availability } : {}),
     }));
 }
 /** The stores an answer presents, as the tool reads them. */
@@ -673,7 +674,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']) {
+    for (const key of ['onStatus', 'onFound', 'onAvailability']) {
         if (o[key] !== undefined && typeof o[key] !== 'function')
             throw new TypeError(`Pass ${key} as a function, or leave it out.`);
     }
@@ -745,6 +746,7 @@ export function buyTool(options) {
         onProgress,
         onStatus: o.onStatus,
         onFound: o.onFound,
+        onAvailability: o.onAvailability,
         onProducts: o.onProducts,
         onText: o.onText,
         onCart: o.onCart,
@@ -1476,6 +1478,8 @@ export function buyTool(options) {
         // A confirm or a pick of what the shopper saw never hears "looking for": once the call is slow, it hears a
         // fixed line that names nothing they said (slowStepLine), so a 20-second checkout or menu read is never silent.
         const ack = t.event ? null : holdAck(ask, t, confirm ? 'confirm' : pick?.product_id ? 'product' : pick ? 'pick' : null);
+        /** Says `unknown` of every card the call left `checking`; it runs once the answer's cards went out, or when the call fails. */
+        let settleLeft = null;
         try {
             let turn = null;
             let refusal;
@@ -1491,6 +1495,55 @@ export function buyTool(options) {
             /** Whether this call's cards went out, and a count that came before them. */
             let cardsOut = false;
             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();
+            const checking = new Map();
+            /**
+             * What the live search answered for each card, so a later copy of the same place, such as a card whose first send
+             * failed and goes out again with the answer, carries that answer and never goes back to `checking`.
+             */
+            const answered = new Map();
+            const withAnswers = (products) => answered.size === 0 ? products : products.map((product) => {
+                const known = product.availability ? answered.get(pickId(product) ?? '') : undefined;
+                return known ? { ...product, availability: known } : product;
+            });
+            /**
+             * Notes the card each product goes out as, and each place still `checking`, whichever way the app got it: a card
+             * through `sendLink` now or on a later try, or a product past the cards that `onFound` hands over for "show more".
+             */
+            const noteCards = (products, conversationId) => {
+                for (const product of products) {
+                    const productId = pickId(product);
+                    if (!productId)
+                        continue;
+                    cardOfId.set(product.id, productId);
+                    if (product.availability?.status === 'checking' && !answered.has(productId))
+                        checking.set(productId, conversationId);
+                }
+            };
+            /** Hands the app what the live search said of the places, each by its card, and settles those cards. */
+            settleLeft = async () => {
+                if (!t.onAvailability || !early)
+                    return;
+                const left = [...checking];
+                for (const conversationId of new Set(left.map(([, c]) => c))) {
+                    await tellAvailability(conversationId, left.filter(([, c]) => c === conversationId).map(([productId]) => ({ productId, availability: { status: 'unknown' } })));
+                }
+            };
+            const tellAvailability = async (conversationId, items) => {
+                for (const item of items) {
+                    checking.delete(item.productId);
+                    answered.set(item.productId, item.availability);
+                }
+                if (!t.onAvailability || items.length === 0)
+                    return;
+                try {
+                    await t.onAvailability({ conversationId, items });
+                }
+                catch {
+                    // The app's display failing never fails the call.
+                }
+            };
             /** Hands the app one count with the products past the cards of the catalog it counts. */
             const tellCount = async ({ conversationId, shown, found }) => {
                 const more = moreFound?.conversationId === conversationId ? moreFound.links : [];
@@ -1546,7 +1599,9 @@ export function buyTool(options) {
                                 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, productsOfCatalog(update.catalog)), { turn: callTurn, presented: true, owner: t }, send);
+                                await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
+                                // 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);
                                 keepMore();
                                 cardsOut = true;
                                 // A count held for these cards goes out now, unless the catalog carries its own, which follows it.
@@ -1557,6 +1612,13 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
+                    ...(t.onAvailability && early
+                        ? {
+                            onAvailability: async ({ conversationId, items }) => {
+                                await tellAvailability(conversationId, items.map(({ id, availability }) => ({ productId: cardOfId.get(id) ?? id, availability })));
+                            },
+                        }
+                        : {}),
                     ...(t.onText
                         ? {
                             onSegment: async ({ text, conversationId }) => {
@@ -1654,13 +1716,19 @@ export function buyTool(options) {
             // Every message of Agentcard's own answer reached the shopper through onText, so the model adds nothing to it. An answer
             // whose card ask gave way to the named step was read the same way once every message of it, that ask last, went out.
             const read = !!turn && (settled.reply === turn.reply ? readEvery(told, turn.messages) : replaced && readEvery(told, toMessages(settled.reply)));
-            const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
+            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 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;
                 heldCount = null;
                 await tellCount(held);
             }
+            // A call that ends with cards still `checking`, the answer's own cards included, says `unknown` of each, so none waits
+            // for an answer that is not coming.
+            if (delivered.conversation_id)
+                noteCards(delivered.products ?? [], delivered.conversation_id);
+            await settleLeft();
             // The message that asks for a step link already went out, so the link follows it now instead of waiting for the model's.
             // The call waits for it, and one that fails to send fails the call, as a step link the turn does not hold does.
             if (read)
@@ -1709,6 +1777,8 @@ export function buyTool(options) {
             return result;
         }
         finally {
+            // A call that fails, Agentcard's error or a thrown handler, still settles the cards it left `checking`.
+            await settleLeft?.().catch(() => { });
             ack?.cancel();
             running -= 1;
             lastEndedAt = Date.now();
@@ -1782,7 +1852,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', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', '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.`);
         }
@@ -1861,6 +1931,7 @@ export function buyTool(options) {
             onProgress: own.onProgress ?? onProgress,
             onStatus: own.onStatus ?? o.onStatus,
             onFound: own.onFound ?? o.onFound,
+            onAvailability: own.onAvailability ?? o.onAvailability,
             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.

package/dist/client.d.ts

@@ -51,6 +51,30 @@ export interface BuyCatalogUpdate {
     /** The products found past the cards, in the order they were found, to show on "show more" with no new search. */
     more: BuyCatalog['items'];
 }
+/**
+ * Whether a place a card shows has room at the time the shopper asked for: `checking` while Agentcard's live search runs,
+ * `available` once it found the place open, with the open times it named in `slots` (empty when it named none),
+ * `unavailable` when it found the place full then, and `unknown` when the search ended without saying either way. Only
+ * `available` is a place to offer as a choice. A product with no such question, such as a retail product, carries none.
+ */
+export type BuyAvailability = {
+    status: 'checking';
+} | {
+    status: 'available';
+    slots: string[];
+} | {
+    status: 'unavailable';
+} | {
+    status: 'unknown';
+};
+/** What Agentcard's live search said of the places a running turn's cards show, matched to each card by its catalog `id`. */
+export interface BuyAvailabilityUpdate {
+    conversationId: string;
+    items: Array<{
+        id: string;
+        availability: BuyAvailability;
+    }>;
+}
 /** How many products a running turn found so far, and how many of them it shows: "8 of 23 shown". */
 export interface BuyFoundUpdate {
     conversationId: string;
@@ -107,6 +131,8 @@ export interface BuyStreamHandlers {
     onCart?: (update: BuyCartUpdate) => void | Promise<void>;
     /** Each piece of a message as Agentcard writes it. Passing it asks Agentcard for the pieces (`?stream=deltas`). */
     onDelta?: (update: BuyDeltaUpdate) => void | Promise<void>;
+    /** Whether the places the turn's cards show have room, once Agentcard's live search says, after the cards it changes. */
+    onAvailability?: (update: BuyAvailabilityUpdate) => void | Promise<void>;
 }
 export declare const DEFAULT_BASE_URL = "https://api.agentcard.sh";
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -301,6 +327,8 @@ export interface BuyCatalogItem {
     store: BuyStore | null;
     /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
     url: string | null;
+    /** Whether a place has room at the asked time (BuyAvailability). Absent on a product with no such question. */
+    availability?: BuyAvailability;
 }
 /**
  * The products the last search found. `presented` is true when this answer's reply presents them: the

package/dist/client.js

@@ -11,7 +11,7 @@
 import { isRecord } from './verify.js';
 import { listenToAgentcard } from './listen.js';
 /** The handlers that ask Agentcard to stream a turn. */
-const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onCart', 'onDelta'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onCart', 'onDelta', 'onAvailability'];
 const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -223,9 +223,30 @@ function catalogItemsOf(v) {
             ...(flight ? { flight } : {}),
             store: storeOf(i.store),
             url: pageUrl(i.url),
+            ...availabilityField(i),
         };
     }) : [];
 }
+/**
+ * A place's availability as Agentcard marks it: `checking`, `open` or `available` with the times in `slots`, `none` or
+ * `unavailable`, and `unknown`. A mark this version does not know reads as `unknown`, so no place is offered on a guess.
+ */
+function availabilityOf(v) {
+    const mark = v.availability;
+    if (mark === 'checking')
+        return { status: 'checking' };
+    if (mark === 'open' || mark === 'available') {
+        const slots = Array.isArray(v.slots) ? v.slots.filter((s) => typeof s === 'string' && s.trim() !== '') : [];
+        return { status: 'available', slots };
+    }
+    if (mark === 'none' || mark === 'unavailable')
+        return { status: 'unavailable' };
+    return typeof mark === 'string' ? { status: 'unknown' } : null;
+}
+function availabilityField(v) {
+    const availability = availabilityOf(v);
+    return availability ? { availability } : {};
+}
 /** A count Agentcard sent: a whole number, never negative. Null otherwise. */
 function countOf(v) {
     return typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : null;
@@ -424,7 +445,7 @@ async function eachEvent(res, onEvent) {
 }
 /**
  * A streamed purchase turn, read to its `envelope`: the same answer a JSON turn returns, with its
- * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment` and `cart` goes to its handler
+ * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment`, `cart` and `venue_availability` goes to its handler
  * on the way, and any other event, such as a `ping` or a `tool`, is read past. A stream that breaks or
  * ends before its envelope, once it named the conversation, reads as a turn past its budget
  * (`turn_timeout`), so the tool reads the conversation for what the turn left instead of losing it.
@@ -503,6 +524,15 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             else if (event === 'segment' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onSegment) {
                 deliver(() => stream.onSegment({ conversationId: named, text: data.text }));
             }
+            else if (event === 'venue_availability' && stream.onAvailability && str(data.conversation_id) && Array.isArray(data.items)) {
+                const items = data.items.filter(isRecord).flatMap((i) => {
+                    const id = str(i.id);
+                    const availability = availabilityOf(i);
+                    return id && availability ? [{ id, availability }] : [];
+                });
+                if (items.length)
+                    deliver(() => stream.onAvailability({ conversationId: data.conversation_id, items }));
+            }
             else if (event === 'cart' && stream.onCart && str(data.conversation_id)) {
                 const update = { conversationId: data.conversation_id, cart: cartOf(data.cart), carts: cartsOf(data.carts) };
                 deliver(() => stream.onCart(update));

package/dist/index.d.ts

@@ -2,10 +2,10 @@ export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatur
 export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.js';
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, } from './client.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
-export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
+export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolAvailability, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
 export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION, type AckForOptions } from './ack.js';
 export { directCall, isProductAsk, type DirectCall, type DirectContext, type DirectReason } from './direct.js';
 export { forModel, forModelError, replyAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } from './model-view.js';

package/dist/model-view.d.ts

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

package/dist/model-view.js

@@ -59,6 +59,24 @@ export function stripLinks(text) {
         .replace(/\n{3,}/g, '\n\n')
         .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
+ * Wayfair: https://www.wayfair.com/...`, one in angle brackets, or a bare address with a path or query (`vault.agentcard.sh?token=...`,
+ * never a bare `www.walmart.com`, which stripLinks keeps as the store's name). Every such
+ * link comes out of what the shopper reads (stripLinks), and the colon would then point at nothing. A Markdown link is not one:
+ * stripLinks keeps its label, which the shopper reads after the colon. A question mark that ends the sentence is not a query,
+ * as HOST_PATH reads it (`Buy from: glossier.com?`), and a page whose path ends in a bracket keeps it (`stool_(oak)`).
+ */
+const POINTS_AT_LINK = /^([^\n]*?\S)[ \t]*:[ \t]*(?:\n[ \t]*)?<?(?:https?:\/\/|(?:www\.)?(?:[\p{L}\p{N}-]+\.)+\p{L}{2,}(?:[/#]|\?(?![.,;:!?]*(?:[\s<>"'`)\]]|$))))[^\s<>"'`\]]*>?[ \t]*[.!]?[ \t]*$/gimu;
+/**
+ * Agentcard's reply as the shopper and the model read it, with every link taken out (stripLinks) and no line left pointing at
+ * one. A line that pointed at a link ends as a sentence when the answer sent the shopper what it pointed at, a product or a
+ * store card or a step's link, and goes when it sent none, so the reply never promises what the shopper does not get. 2026-10-27, chat.opencommerce.sh:
+ * "here's the stool on Wayfair:" reached the shopper with nothing after it.
+ */
+export function replyWithoutLinks(reply, sent) {
+    return stripLinks(String(reply ?? '').replace(POINTS_AT_LINK, (_line, lead) => (sent ? `${lead}.` : '')));
+}
 /** A currency's minor units as Intl knows them: 2 for USD and CAD, 0 for JPY. */
 function minorUnits(format) {
     return format.resolvedOptions().maximumFractionDigits ?? 0;
@@ -135,13 +153,14 @@ export function cardKey(product) {
 }
 /**
  * The key of the card a product gets, or null when it gets none: a product with a page at its store,
- * or a flight option, which has no page, with an id a pick takes. A flight's card is how the shopper
- * taps the flight they want (2026-10-20: three flights listed in text, and no card to tap).
+ * or a flight option or a place to book, which can have no page, with an id a pick takes. A flight's card
+ * is how the shopper taps the flight they want (2026-10-20: three flights listed in text, and no card to tap),
+ * and a place's card is where the shopper reads whether it has room.
  */
 export function productCardKey(product) {
     if (typeof product.url === 'string' && product.url !== '')
         return cardKey(product);
-    return product.flight ? pickId(product) : null;
+    return product.flight || product.availability ? pickId(product) : null;
 }
 function cartView(cart) {
     return {
@@ -218,7 +237,7 @@ export function forModel(result) {
         status,
         next_action: result.next_action ?? null,
         ...(result.cart_building ? { cart_building: { store: stripLinks(result.cart_building.store) } } : {}),
-        reply: stripLinks(result.reply),
+        reply: replyWithoutLinks(result.reply, products.some(held) || stores.some(heldStore) || result.link_sent === true),
         cart: result.cart ? cartView(result.cart) : null,
         carts: (result.carts ?? []).map(cartView),
         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.14.0",
+  "version": "0.15.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.",
   "type": "module",
   "main": "dist/index.js",