@agent-cards/commerce-sdk 0.18.5 → 0.18.7

package/dist/model-view.js

@@ -164,7 +164,12 @@ export function productCardKey(product) {
         return cardKey(product);
     return product.flight || product.availability ? pickId(product) : null;
 }
-function cartView(cart) {
+/** True when `store`, the domain an answer's `cart_building` names, is the store `cart` is at. */
+function buildingAt(cart, store) {
+    const building = store?.trim().toLowerCase();
+    return !!building && [cart.merchant, cart.store?.id].some((name) => typeof name === 'string' && name.toLowerCase() === building);
+}
+function cartView(cart, building) {
     return {
         store: stripLinks(cart.store?.name ?? cart.merchant_name) || stripLinks(cart.merchant),
         items: cart.items.map((line) => ({
@@ -179,10 +184,14 @@ function cartView(cart) {
             line_total: money(line.lineTotalCents ?? (typeof line.priceCents === 'number' ? line.priceCents * line.qty : null), cart.currency),
             options: (line.options ?? []).map(stripLinks).filter((o) => o !== ''),
             variant: line.variant ? stripLinks(line.variant) || null : null,
+            ...(line.fulfilled_by ? { fulfilled_by: stripLinks(line.fulfilled_by.line) } : {}),
         })),
         fees: cart.serviceFeesCents !== null && cart.serviceFeesCents > 0 ? money(cart.serviceFeesCents, cart.currency) : null,
         fees_status: cart.serviceFeesStatus,
         fee_lines: (cart.merchantFeeLines ?? []).map((line) => ({ label: stripLinks(line.label), amount: money(line.amountCents, cart.currency) })),
+        ...(cart.discounts?.length ? { discounts: cart.discounts.map((d) => ({ label: stripLinks(d.label), amount: money(d.amountCents, cart.currency), amount_cents: d.amountCents, kind: d.kind, code: d.code })) } : {}),
+        ...(cart.pricing === true || buildingAt(cart, building) ? { pricing: true } : {}),
+        ...(cart.hold ? { hold: { amount: money(cart.hold.amountCents, cart.currency), amount_cents: cart.hold.amountCents, reason: cart.hold.reason } } : {}),
         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,
@@ -196,12 +205,42 @@ function cartView(cart) {
 /** What an estimated total leaves out: tax, and shipping or delivery, less what the store's own fee lines already carry
  *  (a 1-800-Flowers estimate holds its Florist Delivery and Sales Tax). Null when the lines carry both. */
 function leftOut(lines) {
+    return leftOutWords(leftOutParts(lines), 1);
+}
+function leftOutParts(lines) {
     const parts = [];
     if (!lines.some((l) => /\btax\b/i.test(l.label)))
         parts.push('tax');
     if (!lines.some((l) => /\b(?:deliver(?:y|ies)?|shipping)\b/i.test(l.label)))
         parts.push('shipping or delivery');
-    return parts.length ? `${parts.join(' and ')}, which the store adds at checkout` : null;
+    return parts;
+}
+function leftOutWords(parts, stores) {
+    return parts.length ? `${parts.join(' and ')}, which the ${stores === 1 ? 'store adds' : 'stores add'} at checkout` : null;
+}
+/**
+ * The carts' grand totals, one per currency, summed from each cart's `totalCents`, which already holds its tip, fees and
+ * tax: a display string is never parsed. Carts in two currencies are never added together.
+ */
+export function grandTotals(carts) {
+    const groups = new Map();
+    for (const cart of carts) {
+        const code = typeof cart.currency === 'string' && cart.currency.trim() !== '' ? cart.currency.trim().toUpperCase() : null;
+        groups.set(code, [...(groups.get(code) ?? []), cart]);
+    }
+    return [...groups].map(([currency, group]) => {
+        const cents = group.reduce((sum, cart) => sum + cart.totalCents, 0);
+        const estimates = group.filter((cart) => cart.totalIsEstimate === true);
+        const parts = new Set(estimates.flatMap((cart) => leftOutParts(cart.merchantFeeLines ?? [])));
+        return {
+            amount: money(cents, currency),
+            amount_cents: cents,
+            currency,
+            is_estimate: estimates.length > 0,
+            leaves_out: leftOutWords(['tax', 'shipping or delivery'].filter((part) => parts.has(part)), estimates.length),
+            stores: group.length,
+        };
+    });
 }
 /** How long until `iso`, from `now`, as the shopper reads it: `about 24 hours`, `about 15 minutes`, `no longer`, or null. */
 export function expiresIn(iso, now = Date.now()) {
@@ -244,8 +283,8 @@ export function forModel(result) {
                 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),
-        cart: result.cart ? cartView(result.cart) : null,
-        carts: (result.carts ?? []).map(cartView),
+        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) })),
         approval_expires_at: typeof result.approval_expires_at === 'string' ? stripLinks(result.approval_expires_at) || null : null,
         link_expires_in: expiresIn(linkExpiry(result)),
@@ -267,6 +306,7 @@ export function forModel(result) {
         store_pick: result.store_pick && stripLinks(result.store_pick.store_id) === result.store_pick.store_id
             ? { store_id: result.store_pick.store_id, selected: result.store_pick.selected === true }
             : null,
+        grand_totals: grandTotals(result.carts ?? []),
         ...(yesCarriedView(result) ? { yes_carried: yesCarriedView(result) } : {}),
     };
 }
@@ -393,6 +433,17 @@ const LIST_NUMBER = /(?<!\ba )(?<!\ban )(?:#(\d{1,2})\b|\bnumber (\d{1,2})\b)/i;
  * `there's also ...`, `you could also ...`. One that names a card is the list, whatever the reply recommended before it.
  */
 const MORE_OF_LIST = /^[\s*_"'(]*(?:(?:and|plus|but|or)\s+)?(?:others?\b[^.!?:]{0,40}?\b(?:are|is|include|includes|would be)\b|there(?:'s|’s|\s+is|\s+are)\s+also\b|(?:you|we)\s+(?:could|can|might)\s+also\b)/i;
+/**
+ * A sentence whose subject is the list's items, named by nothing but a pointer back at them and followed by its verb:
+ * `both are ...`, `these ship ...`, `the two cost ...`, `all three come ...`, `they're ...`. A pointer that leads a
+ * noun, `Both Visa and Mastercard are accepted.`, `Both taste and price matter.` or `Either way, ...`, points at no item and never
+ * matches: a word read as the verb but joined to another by `and` or `or` is a noun.
+ */
+const POINTS_BACK = /^[\s*_"'(]*(?:(?:and|but|so|plus)\s+)?(?:both|these|those|either|neither|they|the (?:two|three|four|five)|all (?:two|three|four|five|of (?:them|these|those))|each of (?:them|these|those))(?:\s+of\s+(?:them|these|those))?(?:'re|’re|\s+(?:(?:also|all|only|each|usually|both)\s+)?(?:are|is|were|was|have|has|had|come|comes|ship|ships|cost|costs|run|runs|sell|sells|look|looks|work|works|seem|seems|can|could|will|would|should|might|do|does|offer|offers|include|includes|take|takes|use|uses|weigh|weighs|arrive|arrives|carry|carries|fit|fits|need|needs|sit|sits|taste|tastes|smell|smells|feel|feels|make|makes|go|goes|pair|pairs|brew|brews|roast|roasts|stay|stays|last|lasts|hold|holds|don['’]t|doesn['’]t|didn['’]t|aren['’]t|isn['’]t|won['’]t|can['’]t|wouldn['’]t)\b(?!\s+(?:and|or)\b))/i;
+/** How far a line is set in, a tab counting as four spaces, so a nested list line reads as deeper than its item. */
+function indentOf(line) {
+    return (/^[ \t]*/.exec(line)?.[0] ?? '').replace(/\t/g, '    ').length;
+}
 /** An amount a text gives after a currency sign, such as `$22.89` or `¥1,331`. */
 const AMOUNT = /[$£€¥]\s?(\d{1,3}(?:,\d{3})+|\d+)(\.\d+)?/g;
 /** Words that tell no product from another: a card's brand or its distinctive words are never one of these. */
@@ -629,9 +680,11 @@ function inlineList(line, cards) {
  * points at a number the list gave (`the dishwand in #8`), a sentence that goes on to more of the list (`other 6-packs
  * are ...`, `there's also ...`) and names a card, and, past the one or two products a reply recommends in words, each
  * further sentence that names another card. A list written on one line goes the same way, item by item (inlineList),
- * and so does a list line written without a bullet, whole, up to the question on it. What is left is the reply around
- * the list, such as `found these at amazon.` and `which one do you want?`. A reply whose cards went out names none of
- * them twice over. A list that keeps an item for a product no card shows keeps its lead-in, and the two read as one
+ * and so does a list line written without a bullet, whole, up to the question on it. The lines set in under a list
+ * line that goes, its details such as `  - ships from London`, go with it, and once the list went, a sentence that only
+ * points back at it, `both are priced in foreign currency`, goes when the cards show another number than it counts.
+ * What is left is the reply around the list, such as `found these at amazon.` and `which one do you want?`. A reply
+ * whose cards went out names none of them twice over. A list that keeps an item for a product no card shows keeps its lead-in, and the two read as one
  * message (toMessages), so the shopper never reads `two options came in under $20:` on its own.
  *
  * Each card is its name, or its name and its price as the model reads it (`{ name, price: '$22.89' }`): with the price,
@@ -653,10 +706,14 @@ export function withoutCardList(reply, cardNames) {
     };
     // The numbers the dropped list gave, so a number of a product's own, `a #2 Phillips head`, keeps its sentence.
     const numbers = new Set();
+    // How many items of a list written inline went: with the list lines that went, the count a pointer such as `these` means.
+    let inlineGone = 0;
+    // The lines whose inline list went whole: the lines set in under one describe its items, and go with them.
+    const inlineEmptied = new Set();
     // A list a line writes inline goes the way a list of lines does: each item that names a card, and the sentence that
     // led into the list once every item went. An item for a product no card shows stays, with the lead, and so does a
     // list that opens the line, `1) a mug; 2) a candle; 3) a soap box`, item by item rather than as one list line.
-    const unlisted = (line) => {
+    const unlisted = (line, index) => {
         const list = inlineList(line, cards);
         const gone = list?.items.map((item) => cardsNamed(item.body, cards, true).length > 0) ?? [];
         if (!list || !gone.some(Boolean))
@@ -665,6 +722,9 @@ export function withoutCardList(reply, cardNames) {
             if (gone[k] && item.number !== null)
                 numbers.add(item.number);
         });
+        inlineGone += gone.filter(Boolean).length;
+        if (gone.every(Boolean))
+            inlineEmptied.add(index);
         const after = line.slice(list.end).trimStart();
         if (gone.every(Boolean))
             return `${line.slice(0, list.lead).trimEnd()} ${after}`.trim();
@@ -672,22 +732,37 @@ export function withoutCardList(reply, cardNames) {
         const close = /[.!?]$/.test(left[left.length - 1]) ? '' : '.';
         return [line.slice(0, list.items[0].start).trimEnd(), `${left.join('; ')}${close}`, after].filter((part) => part !== '').join(' ');
     };
-    const lines = reply.split('\n').map(unlisted);
-    const kind = lines.map((line) => {
-        if (LIST_ITEM.test(line))
-            return cardsNamed(line.replace(LIST_ITEM, ''), cards, true).length > 0 ? 'item' : 'kept';
-        return opensCard(line) ? 'named' : 'kept';
+    const written = reply.split('\n');
+    const lines = written.map(unlisted);
+    // A line set in deeper than a list line that names a card is that item's detail, such as `  - ships from London`
+    // under `- Square Mile Red Brick, £13.50`: it goes with its item (`under`), since what it describes is the card.
+    let item = null;
+    const kind = lines.map((line, i) => {
+        if (inlineEmptied.has(i)) {
+            // A list nested under an item already dropped keeps that item's depth, so the lines after it still go with their item.
+            const at = indentOf(written[i]);
+            if (item === null || at <= item)
+                item = at;
+            return 'kept';
+        }
+        if (line.trim() === '')
+            return 'kept';
+        if (item !== null && indentOf(line) > item)
+            return 'under';
+        const of = LIST_ITEM.test(line) ? (cardsNamed(line.replace(LIST_ITEM, ''), cards, true).length > 0 ? 'item' : 'kept') : opensCard(line) ? 'named' : 'kept';
+        item = of === 'kept' ? null : indentOf(line);
+        return of;
     });
     const dropped = kind.map((of) => of !== 'kept');
     lines.forEach((line, i) => {
-        const number = dropped[i] ? Number(/^\s*(\d{1,2})[.)]\s/.exec(line)?.[1]) : NaN;
+        const number = dropped[i] && kind[i] !== 'under' ? Number(/^\s*(\d{1,2})[.)]\s/.exec(line)?.[1]) : NaN;
         if (Number.isInteger(number))
             numbers.add(number);
     });
     // The list a line leads into: the lines from the next one with words on it to the first that is not a list line, so a
     // question on the line after the last item, `Which one?`, is no part of the list. A blank line between two list lines
     // is no end of it, as toMessages reads one, so a list that keeps an item past the blank keeps its lead.
-    const listLine = (j) => LIST_ITEM.test(lines[j]) || kind[j] === 'named';
+    const listLine = (j) => LIST_ITEM.test(lines[j]) || kind[j] === 'named' || kind[j] === 'under';
     const listAfter = (line) => {
         const start = lines.findIndex((after, j) => j > line && after.trim() !== '');
         if (start === -1)
@@ -709,8 +784,20 @@ export function withoutCardList(reply, cardNames) {
     };
     const named = new Set();
     const kept = [];
+    // Once a list went, a sentence that only points back at its items, `both are priced in foreign currency` or `these ship
+    // free`, reads against the cards. It stays when it counts what the cards show, `both` beside two cards, and goes when the
+    // cards show another number, as eight cards beside `both` do: the shopper cannot tell which two it means.
+    const listed = kind.filter((of) => of === 'item' || of === 'named').length + inlineGone;
+    const pointsElsewhere = (sentence) => {
+        const pointer = POINTS_BACK.exec(sentence);
+        if (!pointer || listed === 0)
+            return false;
+        const counted = /\b(both|either|neither|two|three|four|five)\b/i.exec(pointer[0])?.[1]?.toLowerCase();
+        const count = counted ? { both: 2, either: 2, neither: 2, two: 2, three: 3, four: 4, five: 5 }[counted] : listed;
+        return count !== cards.length;
+    };
     lines.forEach((line, i) => {
-        if (kind[i] === 'item')
+        if (kind[i] === 'item' || kind[i] === 'under')
             return;
         let text = line;
         // The line that leads into a list whose every line went loses the sentence that leads in: `Two I'd suggest:` or
@@ -727,6 +814,8 @@ export function withoutCardList(reply, cardNames) {
             if (place && numbers.has(Number(place[1] ?? place[2])))
                 return [];
             const found = cardsNamed(sentence, cards, false);
+            if (found.length === 0 && !ASKS.test(sentence) && !/:\s*$/.test(sentence) && pointsElsewhere(sentence))
+                return [];
             if (kind[i] === 'named') {
                 const card = found.length > 0 || opensCard(sentence);
                 asked ||= ASKS.test(sentence);

package/dist/plan.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A checkout plan on a purchase answer: the items a shopper chose to book together, booked in the order they depend on each
+ * other on one approval, such as a trip's flight first, then its hotel and car. The same object rides `plan.updated`, so a
+ * tracker redraws from either. Null on an answer with no plan, and on an older API.
+ */
+export type BuyPlanStatus = 'preparing' | 'running' | 'done' | 'partly_done' | 'stopped';
+export type BuyPlanItemState = 'draft' | 'quoted' | 'approved' | 'booking' | 'confirmed' | 'pending' | 'needs_input' | 'failed' | 'skipped' | 'cancelled';
+export interface BuyPlanItem {
+    /** The item's key in its plan: `flight`, `hotel`, `car`. */
+    key: string;
+    kind: string;
+    state: BuyPlanItemState;
+    name: string;
+    /** What the shopper pays for it: the confirmed price once booked, the quote before. */
+    price_cents: number | null;
+    /** A changed price waiting for the shopper's answer, or null. */
+    asked_cents: number | null;
+    /** The supplier's confirmation number once booked. */
+    confirmation: string | null;
+    /** The keys of the items it books after. */
+    depends_on: string[];
+    /** Why it waits or did not book, such as `price_changed` or `approval_required`, or null. */
+    reason: string | null;
+}
+export interface BuyPlan {
+    id: string;
+    status: BuyPlanStatus;
+    /** Moves on every change: keep the highest one seen. */
+    version: number;
+    currency: string;
+    total_cents: number;
+    charged_cents: number;
+    /** When the items waiting on a paused one are let go, or null. */
+    hold_until: string | null;
+    items: BuyPlanItem[];
+}
+/**
+ * The plan an answer carries, or null when it carries none or one this version cannot read: a status or an item state this
+ * version does not know, a missing total, or an item it cannot read. A tracker never shows a guessed state or a zero total.
+ */
+export declare function planOf(value: unknown): BuyPlan | null;

package/dist/plan.js

@@ -0,0 +1,34 @@
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const text = (v) => (typeof v === 'string' ? v : null);
+const STATUSES = new Set(['preparing', 'running', 'done', 'partly_done', 'stopped']);
+const STATES = new Set(['draft', 'quoted', 'approved', 'booking', 'confirmed', 'pending', 'needs_input', 'failed', 'skipped', 'cancelled']);
+function itemOf(i) {
+    if (!isRecord(i) || !text(i.key) || !text(i.state) || !STATES.has(i.state))
+        return null;
+    return {
+        key: i.key, kind: text(i.kind) ?? '', state: i.state, name: text(i.name) ?? '',
+        price_cents: num(i.price_cents), asked_cents: num(i.asked_cents), confirmation: text(i.confirmation),
+        depends_on: Array.isArray(i.depends_on) ? i.depends_on.filter((d) => typeof d === 'string') : [], reason: text(i.reason),
+    };
+}
+/**
+ * The plan an answer carries, or null when it carries none or one this version cannot read: a status or an item state this
+ * version does not know, a missing total, or an item it cannot read. A tracker never shows a guessed state or a zero total.
+ */
+export function planOf(value) {
+    if (!isRecord(value) || !text(value.id) || !Array.isArray(value.items) || !STATUSES.has(text(value.status) ?? ''))
+        return null;
+    const total = num(value.total_cents);
+    const charged = num(value.charged_cents);
+    const version = num(value.version);
+    if (total === null || charged === null || version === null)
+        return null;
+    const items = value.items.map(itemOf);
+    if (items.some((i) => i === null))
+        return null;
+    return {
+        id: value.id, status: value.status, version, currency: text(value.currency) ?? 'USD',
+        total_cents: total, charged_cents: charged, hold_until: text(value.hold_until), items: items,
+    };
+}

package/dist/search-status.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Where each store a turn searches stands: the `merchant` events of a streamed turn, one each time a store's status changes, and
+ * the `search` block of the answer, every store at once.
+ */
+/**
+ * Where one store stands in a turn's search.
+ *
+ * - `searching`: Agentcard is still searching the store.
+ * - `confirmed`: the store's own site answered with products, their price and stock read live in this search.
+ * - `recently_confirmed`: products Agentcard already knew, their price and stock read live at the store in the last hour.
+ * - `confirmation_unavailable`: products found for the store, none of them read live there in this search.
+ * - `no_results`: the store answered, with nothing for the ask.
+ * - `timed_out`: the search answered without the store, which was still running.
+ * - `failed`: the store's search failed.
+ */
+export type BuyMerchantSearchStatus = 'searching' | 'confirmed' | 'recently_confirmed' | 'no_results' | 'timed_out' | 'confirmation_unavailable' | 'failed';
+/** One store in the answer's `search` block, as Agentcard sends it. */
+export interface BuyMerchantStatus {
+    /** The store's id: a store Agentcard knows by name, such as `walmart`, or the store's domain, such as `livlyclothing.com`. */
+    merchant: string;
+    /** The store's name, to show the shopper: `Walmart`. */
+    merchant_name: string;
+    status: BuyMerchantSearchStatus;
+    /** How many products the search found at the store. */
+    results: number;
+    /** How many of them had their price and stock read live (`confirmed`) or in the last hour (`recently_confirmed`). */
+    confirmed: number;
+    /** Milliseconds from the start of the store's search to its first product; null when it found none. */
+    first_result_ms: number | null;
+    /** Milliseconds the store's search took, or has taken so far while it reads `searching`. */
+    ms: number;
+}
+/** Every store the turn searched, as the answer carries them. */
+export interface BuySearchStatus {
+    /** The id of this turn's search. A later turn that searches again has a new one. */
+    search_id: string;
+    /** True once no store is still being searched. False when the answer left while one still ran. */
+    final: boolean;
+    /** Milliseconds from the first store's search to the last store's answer. */
+    elapsed_ms: number;
+    /** Each store, in the order its search started. */
+    merchants: BuyMerchantStatus[];
+    /** Agentcard's own product index, when the turn read it: how many products it answered and in how many milliseconds. */
+    index: {
+        results: number;
+        ms: number;
+    } | null;
+}
+/** One store's status the moment it changes, while the turn runs. */
+export interface BuyMerchantStatusUpdate {
+    conversationId: string;
+    searchId: string;
+    merchant: string;
+    merchantName: string;
+    status: BuyMerchantSearchStatus;
+    results: number;
+    confirmed: number;
+    firstResultMs: number | null;
+    ms: number;
+}
+/** The answer's `search` block, or null when the answer carries none. */
+export declare function searchOf(v: unknown): BuySearchStatus | null;
+/** A `merchant` event's update, or null for one with no conversation, no search or a store this version cannot read. */
+export declare function merchantStatusOf(data: Record<string, unknown>): BuyMerchantStatusUpdate | null;
+/**
+ * The search block with only the store you name, matched by its id, its domain or its name, so a caller that searched one store
+ * reads that store's status: `searchAt(turn.search, 'walmart.com')`. Null when the block is null; an empty `merchants` when the
+ * turn did not search that store.
+ */
+export declare function searchAt(search: BuySearchStatus | null, store: string): BuySearchStatus | null;
+/** Whether a `merchant` event is about the store you name, as `searchAt` matches it. */
+export declare function isMerchantStatusAt(update: BuyMerchantStatusUpdate, store: string): boolean;

package/dist/search-status.js

@@ -0,0 +1,78 @@
+/**
+ * Where each store a turn searches stands: the `merchant` events of a streamed turn, one each time a store's status changes, and
+ * the `search` block of the answer, every store at once.
+ */
+const MERCHANT_STATUSES = new Set(['searching', 'confirmed', 'recently_confirmed', 'no_results', 'timed_out', 'confirmation_unavailable', 'failed']);
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (v) => (typeof v === 'string' && v !== '' ? v : null);
+const count = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.round(v) : 0);
+const msOrNull = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.round(v) : null);
+/** One store as Agentcard sent it, or null for a line with no store or a status this version does not know. */
+function merchantOf(v) {
+    if (!isRecord(v))
+        return null;
+    const merchant = text(v.merchant);
+    if (!merchant || typeof v.status !== 'string' || !MERCHANT_STATUSES.has(v.status))
+        return null;
+    return {
+        merchant,
+        merchant_name: text(v.merchant_name) ?? merchant,
+        status: v.status,
+        results: count(v.results),
+        confirmed: count(v.confirmed),
+        first_result_ms: msOrNull(v.first_result_ms),
+        ms: count(v.ms),
+    };
+}
+/** The answer's `search` block, or null when the answer carries none. */
+export function searchOf(v) {
+    if (!isRecord(v) || !text(v.search_id) || !Array.isArray(v.merchants))
+        return null;
+    const index = isRecord(v.index) ? { results: count(v.index.results), ms: count(v.index.ms) } : null;
+    return {
+        search_id: v.search_id,
+        final: v.final !== false,
+        elapsed_ms: count(v.elapsed_ms),
+        merchants: v.merchants.flatMap((m) => merchantOf(m) ?? []),
+        index,
+    };
+}
+/** A `merchant` event's update, or null for one with no conversation, no search or a store this version cannot read. */
+export function merchantStatusOf(data) {
+    const conversationId = text(data.conversation_id);
+    const searchId = text(data.search_id);
+    const line = merchantOf(data);
+    if (!conversationId || !searchId || !line)
+        return null;
+    return {
+        conversationId, searchId, merchant: line.merchant, merchantName: line.merchant_name, status: line.status,
+        results: line.results, confirmed: line.confirmed, firstResultMs: line.first_result_ms, ms: line.ms,
+    };
+}
+/** The stores whose domain is not their Agentcard id with `.com` after it, as Agentcard maps them (merchant-status.ts). */
+const KEY_OF_DOMAIN = { 'mcmaster.com': 'mcmastercarr', 'shop.tiktok.com': 'tiktok', 'tiktok.com': 'tiktok' };
+/** A store as you may name it, and as Agentcard names it, folded to one form: `Walmart`, `walmart.com` and `walmart` are one store. */
+function storeKey(store) {
+    const bare = store.trim().toLowerCase().replace(/^https?:\/\//, '').replace(/^www\./, '').replace(/\/.*$/, '');
+    if (KEY_OF_DOMAIN[bare])
+        return KEY_OF_DOMAIN[bare];
+    // An accent and an ampersand are spelled out as Agentcard's ids spell them: `Pokémon Center`, `Barnes & Noble`.
+    const word = (s) => s.normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/&/g, 'and').replace(/[^a-z0-9]/g, '');
+    return bare.endsWith('.com') ? word(bare.slice(0, -4)) : bare.includes('.') ? bare : word(bare.replace(/^the\s+/, ''));
+}
+/**
+ * The search block with only the store you name, matched by its id, its domain or its name, so a caller that searched one store
+ * reads that store's status: `searchAt(turn.search, 'walmart.com')`. Null when the block is null; an empty `merchants` when the
+ * turn did not search that store.
+ */
+export function searchAt(search, store) {
+    if (!search)
+        return null;
+    const want = storeKey(store);
+    return { ...search, merchants: search.merchants.filter((m) => storeKey(m.merchant) === want || storeKey(m.merchant_name) === want) };
+}
+/** Whether a `merchant` event is about the store you name, as `searchAt` matches it. */
+export function isMerchantStatusAt(update, store) {
+    const want = storeKey(store);
+    return storeKey(update.merchant) === want || storeKey(update.merchantName) === want;
+}

package/dist/store-wait.d.ts

@@ -0,0 +1,27 @@
+import type { BuyToolProduct } from './buy-tool.js';
+/**
+ * What happens to a store that answers after the reply: `stream` sends its cards after the reply, in the same turn, as
+ * the card events every streamed turn carries; `hold` keeps them out of the turn, so the reply is the turn's last word.
+ */
+export type BuyLateResults = 'stream' | 'hold';
+/** The store wait of a tool or a turn. */
+export interface BuyStoreWait {
+    /** How long, in milliseconds, the reply waits for store searches before Agentcard writes it. */
+    storeWaitMs?: number;
+    /** What happens to a store that answers after the reply. */
+    lateResults?: BuyLateResults;
+}
+/** The request fields a store wait sends, none when it names nothing. */
+export interface BuyStoreWaitFields {
+    store_wait_ms?: number;
+    late_results?: BuyLateResults;
+}
+/** Checks a store wait passed to `buyTool` (`where` is empty) or to a turn (`where` reads ' to the turn'), and throws a TypeError for one that cannot work. */
+export declare function checkStoreWait(wait: BuyStoreWait, where?: string): void;
+/** The fields a request carries for a turn's store wait: the turn's own, else the tool's. */
+export declare function storeWaitFields(turn: BuyStoreWait, tool: BuyStoreWait): BuyStoreWaitFields;
+/**
+ * The answer's products with the cards of a store that answered after the reply added at the end, each once: the answer
+ * can list them already, when the turn's last word came after them, and a late card it lists is left as the answer has it.
+ */
+export declare function withLateCards(products: readonly BuyToolProduct[], late: readonly BuyToolProduct[]): BuyToolProduct[];

package/dist/store-wait.js

@@ -0,0 +1,41 @@
+/**
+ * How long a reply waits for store searches, and what happens to a store that answers after it: the `storeWaitMs` and
+ * `lateResults` options of `buyTool` and `buy.turn`, sent on every request as `store_wait_ms` and `late_results`. Left
+ * out, nothing is sent and Agentcard keeps its own wait.
+ */
+import { pickId, productCardKey } from './model-view.js';
+/** Checks a store wait passed to `buyTool` (`where` is empty) or to a turn (`where` reads ' to the turn'), and throws a TypeError for one that cannot work. */
+export function checkStoreWait(wait, where = '') {
+    const ms = wait.storeWaitMs;
+    if (ms !== undefined && (typeof ms !== 'number' || !Number.isInteger(ms) || ms < 0)) {
+        throw new TypeError(`Pass storeWaitMs${where} as a whole number of milliseconds, 0 or more, or leave it out.`);
+    }
+    const late = wait.lateResults;
+    if (late !== undefined && late !== 'stream' && late !== 'hold') {
+        throw new TypeError(`Pass lateResults${where} as 'stream' or 'hold', or leave it out.`);
+    }
+}
+/** The fields a request carries for a turn's store wait: the turn's own, else the tool's. */
+export function storeWaitFields(turn, tool) {
+    const ms = turn.storeWaitMs ?? tool.storeWaitMs;
+    const late = turn.lateResults ?? tool.lateResults;
+    return { ...(ms !== undefined ? { store_wait_ms: ms } : {}), ...(late !== undefined ? { late_results: late } : {}) };
+}
+/**
+ * The answer's products with the cards of a store that answered after the reply added at the end, each once: the answer
+ * can list them already, when the turn's last word came after them, and a late card it lists is left as the answer has it.
+ */
+export function withLateCards(products, late) {
+    // A product with no link-free id is told apart by its page, so two stores' offers of one title stay two.
+    const keyOf = (product) => pickId(product) ?? productCardKey(product) ?? `name:${product.name}`;
+    const held = new Set(products.map(keyOf));
+    const added = [];
+    for (const product of late) {
+        const key = keyOf(product);
+        if (held.has(key))
+            continue;
+        held.add(key);
+        added.push(product);
+    }
+    return [...products, ...added];
+}

package/dist/trip-ask.d.ts

@@ -13,7 +13,7 @@
  * an ask goes straight only with a shopping verb (`book a flight to Loreto`), as before.
  *
  * `inCapabilities` on: the tool's description says it plans and books trips, flights and hotels, tells the model to call it
- * for a trip ask with no dates or airport, and names flights and hotels when the shopper asks what it can do. Off: the
+ * for a trip ask with no dates or airport, and leads with a whole trip when the shopper asks what it can do for travel. Off: the
  * description is the text it was before, word for word.
  */
 export declare const TRAVEL: {

package/dist/trip-ask.js

@@ -13,7 +13,7 @@
  * an ask goes straight only with a shopping verb (`book a flight to Loreto`), as before.
  *
  * `inCapabilities` on: the tool's description says it plans and books trips, flights and hotels, tells the model to call it
- * for a trip ask with no dates or airport, and names flights and hotels when the shopper asks what it can do. Off: the
+ * for a trip ask with no dates or airport, and leads with a whole trip when the shopper asks what it can do for travel. Off: the
  * description is the text it was before, word for word.
  */
 export const TRAVEL = { goStraight: true, inCapabilities: true };
@@ -52,9 +52,9 @@ export function withoutTripVerb(text) {
     return TRAVEL.goStraight && isTripAsk(text) ? text.replace(TRIP_VERB, '') : text;
 }
 const OPENING_LINE = 'Buy what this shopper asks for at real stores.';
-const TRAVEL_LINES = 'You also plan and book trips: flights and hotels. When the shopper asks to plan a trip, or for flights or a hotel, such as "help me plan a trip to Loreto" or "flights and hotels in loreto", call this tool with their words, even when they name no dates and no place they leave from: Agentcard asks them for what it needs.';
-const CAPABILITY_END = 'so name those, and no other store unless a result showed it.';
-const CAPABILITY_TRAVEL = 'Name flights and hotels for a trip among the kinds of things you can do.';
+const TRAVEL_LINES = 'You also plan and book trips: flights, hotels and rental cars. When the shopper asks to plan a trip, or for flights or a hotel, such as "help me plan a trip to Loreto" or "flights and hotels in loreto", call this tool with their words, even when they name no dates and no place they leave from: Agentcard asks them for what it needs.';
+const CAPABILITY_END = 'Name no other store unless a result showed it.';
+const CAPABILITY_TRAVEL = 'Name whole trips among the kinds of things you can do. When the shopper asks what you can do for travel, lead with planning a whole trip, the flights, a hotel and a rental car together, then name the parts they can book on their own: flights, hotels and rental cars.';
 /** The tool's description with travel named, when `inCapabilities` is on (or `on` says so); the description as given when off. */
 export function withTravel(description, on = TRAVEL.inCapabilities) {
     if (!on)

package/examples/anthropic.mjs

@@ -6,7 +6,7 @@
 // Sandbox credentials place no real order. SHOPPER_ID is your own id for the shopper you play.
 import readline from 'node:readline';
 import Anthropic from '@anthropic-ai/sdk';
-import { AgentcardClient, buyTool } from '@agent-cards/commerce-sdk';
+import { AgentcardClient, appInstructions, buyTool } from '@agent-cards/commerce-sdk';
 
 const agentcard = new AgentcardClient({
   clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
@@ -33,7 +33,8 @@ for await (const line of terminal) {
   const runner = anthropic.beta.messages.toolRunner({
     model: 'claude-opus-5-5',
     max_tokens: 16000,
-    system: 'You are a shopping assistant. Buy what the shopper asks for with the buy tool.',
+    // Agentcard's recommended instructions: what it can do and how to use the buy tool. A terminal shows plain text.
+    system: appInstructions({ markdown: false }),
     tools: [buy],
     messages: [...messages, { role: 'user', content: said }],
     // When a safety classifier declines a request, Anthropic answers it with a fallback model instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.18.5",
+  "version": "0.18.7",
   "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",
@@ -27,11 +27,12 @@
   },
   "scripts": {
     "_comment_build": "Zero runtime dependencies: node:crypto is the one import, and the buy tool calls the global fetch. TypeScript is pinned, not installed, as in @agent-cards/sdk. types/node.d.ts declares the two node:crypto functions the source calls, so the build needs no @types package and the published declarations name no Node type; FetchLike names AbortSignal, which every runtime with fetch declares.",
-    "build": "npx -y -p typescript@5.9.3 tsc",
+    "build": "node scripts/app-instructions.mjs && npx -y -p typescript@5.9.3 tsc",
     "prepublishOnly": "pnpm build",
     "test": "pnpm build && node --test test/*.test.mjs",
     "verify:pack": "node scripts/verify-pack.mjs",
-    "_comment_pack": "verify:pack lists what npm would publish (npm pack --dry-run) and fails on a missing manifest target, README or example, or on a test, source, shim or build-cache file; then it loads the built root and checks the names the README imports. The release workflow runs it after the build."
+    "_comment_pack": "verify:pack lists what npm would publish (npm pack --dry-run) and fails on a missing manifest target, README or example, or on a test, source, shim or build-cache file; then it loads the built root and checks the names the README imports. The release workflow runs it after the build.",
+    "_comment_instructions": "The build first copies the instructions for an app's own model (appInstructions) from apps/agent-voice/kb/app.md into src/app-instructions.generated.ts, which git ignores, so the published text always matches the voice package at the commit it was built from."
   },
   "keywords": [
     "agentcard",