@agent-cards/commerce-sdk 0.18.6 → 0.18.7

package/dist/app-instructions.generated.d.ts

@@ -1,5 +1,5 @@
 /** The version of the voice package the text was copied from. */
-export declare const VOICE_VERSION = "0.2.79";
+export declare const VOICE_VERSION = "0.2.80";
 export declare const APP_TEXT: {
     readonly core: "You help a shopper buy what they ask for, with the `buy` tool from Agentcard.\n\nWhen the shopper asks what you can do, answer from these lines without calling the tool:\n- You buy from Amazon, Walmart, Target, Best Buy and thousands more stores. Say \"and thousands more stores\" every time you name the stores you shop, in a reply about one kind of thing too, such as \"travel gear from Amazon, Target and thousands more stores\". Never let a few names read as the whole list, never say \"most online stores\", \"plenty more\" or \"many more\", and never give a number of stores.\n- You plan a whole trip: the flights, a hotel and a rental car together. When they ask what you can do for travel, lead with the whole trip, then name the parts they can book on their own.\n- You order food delivery and book restaurant tables.\n\nHow you use the buy tool:\n- Call it for anything the shopper wants to find, buy, book or order, a trip with no dates or airport yet included: the tool asks for what it still needs.\n- Never say whether you can buy at a store the shopper names, either way. Only the tool knows, so say you will look and call it.\n- Never write a link. Each link reaches the shopper on its own, so when `link_sent` is true, tell them a link is waiting for them.\n- Tell the shopper no reply is needed only when `shopper_need_not_reply` is true.\n- Ask for one thing per message, the step `next_action` names, and leave every later step for a later message.\n- Never tell the shopper you can't show Markdown, a table or other formatting, and never say you keep to plain text.";
     readonly markdown: "The app shows your words as Markdown. When the shopper asks for a table, a list or bold, write it in Markdown. Use a list or a table where it reads better than a sentence, and keep each message short all the same.";

package/dist/app-instructions.generated.js

@@ -1,6 +1,6 @@
 // GENERATED by scripts/app-instructions.mjs from apps/agent-voice/kb/app.md. Do not edit: edit kb/app.md.
 /** The version of the voice package the text was copied from. */
-export const VOICE_VERSION = "0.2.79";
+export const VOICE_VERSION = "0.2.80";
 export const APP_TEXT = {
     "core": "You help a shopper buy what they ask for, with the `buy` tool from Agentcard.\n\nWhen the shopper asks what you can do, answer from these lines without calling the tool:\n- You buy from Amazon, Walmart, Target, Best Buy and thousands more stores. Say \"and thousands more stores\" every time you name the stores you shop, in a reply about one kind of thing too, such as \"travel gear from Amazon, Target and thousands more stores\". Never let a few names read as the whole list, never say \"most online stores\", \"plenty more\" or \"many more\", and never give a number of stores.\n- You plan a whole trip: the flights, a hotel and a rental car together. When they ask what you can do for travel, lead with the whole trip, then name the parts they can book on their own.\n- You order food delivery and book restaurant tables.\n\nHow you use the buy tool:\n- Call it for anything the shopper wants to find, buy, book or order, a trip with no dates or airport yet included: the tool asks for what it still needs.\n- Never say whether you can buy at a store the shopper names, either way. Only the tool knows, so say you will look and call it.\n- Never write a link. Each link reaches the shopper on its own, so when `link_sent` is true, tell them a link is waiting for them.\n- Tell the shopper no reply is needed only when `shopper_need_not_reply` is true.\n- Ask for one thing per message, the step `next_action` names, and leave every later step for a later message.\n- Never tell the shopper you can't show Markdown, a table or other formatting, and never say you keep to plain text.",
     "markdown": "The app shows your words as Markdown. When the shopper asks for a table, a list or bold, write it in Markdown. Use a list or a table where it reads better than a sentence, and keep each message short all the same.",

package/dist/buy-tool.d.ts

@@ -32,7 +32,9 @@
  * the messages like someone texting.
  */
 import type { BuyPlan } from './plan.js';
-import { AgentcardClient, type BuyCart, type BuyCartBuilding, type BuyChoice, 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 { BuyMerchantStatusUpdate, BuySearchStatus } from './search-status.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';
 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';
@@ -90,6 +92,11 @@ export interface BuyToolLink {
     storeDomain?: string | null;
     /** On a product link: the product's name. */
     title?: string;
+    /**
+     * On a product link: who sells or books the product, where that is not the store it names, such as a ticket's
+     * `{ name: 'StubHub', kind: 'marketplace', line: 'via StubHub' }`. Show `line` quietly under the price. Absent when none.
+     */
+    fulfilledBy?: BuyFulfilledBy;
     /**
      * On a product link: what taking the product does, so a button can say it. `reserve` is a table the
      * shopper reserves, `book` a flight, room, class or ticket they book, and `buy` anything they buy.
@@ -177,6 +184,8 @@ export interface BuyToolProduct {
     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;
+    /** Who sells or books it, where that is not the store it names (`via StubHub`); absent when Agentcard named none. */
+    fulfilledBy?: BuyFulfilledBy;
 }
 /** One answer of the buy tool, whole, for your code. Hand it to `forModel` before a model reads it. */
 export interface BuyToolResult {
@@ -234,6 +243,8 @@ export interface BuyToolResult {
     cart_building?: BuyCartBuilding | null;
     /** The checkout plan the answer started or moved, such as a trip's flight, hotel and car with each one's state; null when none. */
     plan?: BuyPlan | null;
+    /** Every store the answer's searches asked and where each stands (`searchAt` narrows it to one store); null when it searched none. */
+    search?: BuySearchStatus | null;
     /**
      * True when this call sent Agentcard a confirm: the shopper's yes, or the yes the tool carried past a step the shopper
      * finished outside the chat. Absent when the call sent the shopper's words or read the conversation.
@@ -258,6 +269,8 @@ export interface BuyToolResult {
      * values one per line under the question. Absent or null when the reply asks none.
      */
     choice?: BuyChoice | null;
+    /** The wallet's code a store checkout waits for, so an app can show a code box beside the reply; absent or null when none. */
+    code_request?: BuyCodeRequest | null;
     /** Agentcard's answer as it came: the purchase answer, or the body of the refusal. */
     envelope: Record<string, unknown>;
 }
@@ -389,6 +402,11 @@ export interface BuyToolOptions extends BuyStoreWait {
      * throws costs nothing but the call to it.
      */
     onAvailability?: (update: BuyToolAvailability) => void | Promise<void>;
+    /**
+     * Hears each store a call's searches ask, the moment its status changes (`BuyMerchantStatusUpdate`): `searching` when its
+     * search starts, then what it found. One that throws costs nothing but the call to it.
+     */
+    onMerchantStatus?: (update: BuyMerchantStatusUpdate) => 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.
@@ -616,6 +634,8 @@ export interface BuyToolTurnOptions extends BuyStoreWait {
     onFound?: BuyToolOptions['onFound'];
     /** Hears whether the places this turn's cards show have room, as the tool's `onAvailability` does. */
     onAvailability?: BuyToolOptions['onAvailability'];
+    /** Hears each store this turn's searches ask, as the tool's `onMerchantStatus` does. */
+    onMerchantStatus?: BuyToolOptions['onMerchantStatus'];
     /** 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

@@ -242,7 +242,7 @@ export function productsOf(turn) {
 /** A product's card as `sendLink` hears it: the id the model reads and a pick takes, never the store page, which is `url`. A flight option has no page at a store: its card carries no url, and its productId picks it. */
 function productLink(product) {
     const productId = pickId(product);
-    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), store: product.store ?? null, storeDomain: product.storeDomain ?? null, expiresAt: null, ...(product.availability ? { availability: product.availability } : {}) };
+    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), store: product.store ?? null, storeDomain: product.storeDomain ?? null, expiresAt: null, ...(product.availability ? { availability: product.availability } : {}), ...(product.fulfilledBy ? { fulfilledBy: product.fulfilledBy } : {}) };
 }
 /** A host name: dot-separated labels of letters, digits and hyphens, ending in a letters-only top-level label. */
 const STORE_HOST = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
@@ -278,6 +278,7 @@ function productsOfCatalog(catalog) {
         action: productAction(catalog.merchant),
         linkSent: false,
         ...(item.availability ? { availability: item.availability } : {}),
+        ...(item.fulfilled_by ? { fulfilledBy: item.fulfilled_by } : {}),
     }));
 }
 /** The stores an answer presents, as the tool reads them. */
@@ -322,7 +323,9 @@ function answerOf(turn) {
         hashes: hashesOf(turn.cart, turn.carts),
         cart_building: turn.cart_building,
         choice: turn.choice ?? null,
+        code_request: turn.code_request ?? null,
         plan: turn.plan ?? null,
+        search: turn.search ?? null,
         envelope: turn.raw,
     };
 }
@@ -767,7 +770,7 @@ export function buyTool(options) {
     if (o.stream !== undefined && o.stream !== false)
         throw new TypeError('Pass stream as false to wait for each whole answer, or leave it out.');
     const onProgress = o.onProgress;
-    for (const key of ['onStatus', 'onFound', 'onAvailability']) {
+    for (const key of ['onStatus', 'onFound', 'onAvailability', 'onMerchantStatus']) {
         if (o[key] !== undefined && typeof o[key] !== 'function')
             throw new TypeError(`Pass ${key} as a function, or leave it out.`);
     }
@@ -848,6 +851,7 @@ export function buyTool(options) {
         onStatus: o.onStatus,
         onFound: o.onFound,
         onAvailability: o.onAvailability,
+        onMerchantStatus: o.onMerchantStatus,
         onProducts: o.onProducts,
         onText: o.onText,
         texting: textingByDefault,
@@ -1961,6 +1965,18 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
+                    ...(t.onMerchantStatus
+                        ? {
+                            onMerchantStatus: async (update) => {
+                                try {
+                                    await t.onMerchantStatus(update);
+                                }
+                                catch {
+                                    // The app's display failing never fails the turn.
+                                }
+                            },
+                        }
+                        : {}),
                     ...(t.onText || writtenText
                         ? {
                             onSegment: async ({ text, conversationId }) => {
@@ -2315,7 +2331,7 @@ export function buyTool(options) {
         const own = options ?? {};
         if (typeof own !== 'object')
             throw new TypeError('Pass the turn options as an object, or leave them out.');
-        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', 'onMerchantStatus', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
             if (own[key] !== undefined && typeof own[key] !== 'function')
                 throw new TypeError(`Pass ${key} to the turn as a function, or leave it out.`);
         }
@@ -2399,6 +2415,7 @@ export function buyTool(options) {
             onStatus: own.onStatus ?? o.onStatus,
             onFound: own.onFound ?? o.onFound,
             onAvailability: own.onAvailability ?? o.onAvailability,
+            onMerchantStatus: own.onMerchantStatus ?? o.onMerchantStatus,
             onProducts: own.onProducts ?? o.onProducts,
             // Agentcard's message takes its place in the turn's sequence, after the items before it, and goes to onText alone, so
             // an app that passes onItem too hears it once.

package/dist/client.d.ts

@@ -9,6 +9,8 @@
  * token cache follows its client (packages/checkout/src/client.ts accessToken).
  */
 import { type BuyPlan } from './plan.js';
+import { type BuyMerchantStatusUpdate, type BuySearchStatus } from './search-status.js';
+import { type BuyFulfilledBy } from './fulfilled-by.js';
 import { type AgentcardListener, type ListenOptions } from './listen.js';
 import { type ShopperMessage } from './shopper-message.js';
 /** The fetch the client calls: Node 18 and later have one built in. */
@@ -162,6 +164,11 @@ export interface BuyStreamHandlers {
     onReplyWritten?: (update: {
         conversationId: string | null;
     }) => void | Promise<void>;
+    /**
+     * Each store the turn searches, the moment its status changes: `searching` when its search starts, then what it found. To
+     * follow one store, keep the updates `isMerchantStatusAt(update, 'walmart.com')` accepts. The answer's `search` holds every store.
+     */
+    onMerchantStatus?: (update: BuyMerchantStatusUpdate) => void | Promise<void>;
 }
 export declare const DEFAULT_BASE_URL = "https://api.agentcard.sh";
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -346,6 +353,8 @@ export interface BuyCartLine {
     ref: string | null;
     /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
     url: string | null;
+    /** Who sells or books the line, where that is not the store the cart names (`via StubHub`); absent when Agentcard named none. */
+    fulfilled_by?: BuyFulfilledBy;
 }
 /**
  * A cart as Agentcard answers it. `totalCents` is the all-in figure the shopper sees; `hash` is what a confirm names.
@@ -356,6 +365,25 @@ export interface BuyCartFeeLine {
     label: string;
     amountCents: number;
 }
+/**
+ * A discount or a coupon inside a cart's total, as the store labels it. `amountCents` is negative. `kind` is `discount`
+ * for one the store applied on its own, such as a promotion, and `coupon` for a code entered at the store's checkout,
+ * which `code` names; `code` is null for a discount.
+ */
+export interface BuyCartDiscount {
+    label: string;
+    amountCents: number;
+    kind: 'discount' | 'coupon';
+    code: string | null;
+}
+/**
+ * Why a cart's card is held for `amountCents`: `flight` and `hotel` for the hold a booking places on the card, and
+ * `checkout_estimate` for the headroom above a store's total that covers tax and shipping and is released unused.
+ */
+export interface BuyCartHold {
+    amountCents: number;
+    reason: 'flight' | 'hotel' | 'checkout_estimate';
+}
 export interface BuyCart {
     merchant: string;
     merchant_name: string;
@@ -367,6 +395,10 @@ export interface BuyCart {
     serviceFeesStatus?: 'known' | 'pending' | 'unknown';
     /** The store's own fee and tax lines inside `serviceFeesCents`, or null when the store itemized none. */
     merchantFeeLines: BuyCartFeeLine[] | null;
+    /** The discounts and coupons inside `totalCents`, which `merchantFeeLines` also lists. Empty when there are none, and from an older API. */
+    discounts?: BuyCartDiscount[];
+    /** True while the store's checkout builds this cart again, so `totalCents` is not its price yet. False from an older API. */
+    pricing?: boolean;
     tipCents: number;
     totalCents: number;
     /**
@@ -377,6 +409,8 @@ export interface BuyCart {
     /** The ISO 4217 code the store prices the cart in, or null when Agentcard sent none. */
     currency: string | null;
     approvedCeilingCents: number | null;
+    /** Why the card is held for `approvedCeilingCents`, or null when nothing is held or the API is older. */
+    hold?: BuyCartHold | null;
     hash: string;
 }
 /** A product a search found. `priceCents` is in the minor unit of `currency`, the store's ISO 4217 code. */
@@ -413,6 +447,8 @@ export interface BuyCatalogItem {
     url: string | null;
     /** Whether a place has room at the asked time (BuyAvailability). Absent on a product with no such question. */
     availability?: BuyAvailability;
+    /** Who sells or books the product, where that is not the store the card names (`booked with OpenTable`); absent when Agentcard named none. */
+    fulfilled_by?: BuyFulfilledBy;
 }
 /**
  * The products the last search found. `presented` is true when this answer's reply presents them: the
@@ -510,6 +546,19 @@ export interface BuyPaymentSource {
  * (the code a booking texted them), then `approve` (the approval link). A value this version does
  * not know reads as null.
  */
+/**
+ * A store checkout waiting for the one-time code Stripe Link or Shop Pay sent the shopper: which wallet, whether it was a
+ * text or an email, and where it went, masked to a phone's last two digits ("••21") or an email's first letter and domain
+ * ("j•••@example.com"). The shopper sends the code as their next message, as `next_action: 'verification_code'` says.
+ */
+export interface BuyCodeRequest {
+    store: string;
+    wallet: 'link' | 'shop_pay';
+    channel: 'text' | 'email';
+    destination: string | null;
+}
+/** An answer's code request, from its `browser_checkout` when that checkout waits on a wallet's code; null otherwise. */
+export declare function codeRequestOf(value: unknown): BuyCodeRequest | null;
 export type BuyNextAction = 'shipping_details' | 'guest_details' | 'store_login' | 'add_card' | 'confirm' | 'verification_code' | 'approve';
 /**
  * A cart the store's checkout is still building after an answer went out, at `store`, since `started_at`: its cart and
@@ -538,6 +587,8 @@ export interface BuyTurn {
     approval_url: string | null;
     charge_status: string | null;
     error_code: string | null;
+    /** The party of the purchase this answer says failed, such as StubHub for a ticket, so an app names who stopped it; null when none is named. */
+    fulfilled_by: BuyFulfilledBy | null;
     authorization_id: string | null;
     merchant_total_cents: number | null;
     merchant_currency: string | null;
@@ -548,6 +599,8 @@ export interface BuyTurn {
     approval_in_progress: boolean | null;
     /** The one step the shopper takes next, or null when nothing waits on them or Agentcard named none. */
     next_action: BuyNextAction | null;
+    /** The wallet's code a store checkout waits for, with where it went, or null when none waits (BuyCodeRequest). */
+    code_request: BuyCodeRequest | null;
     /** The page where the shopper signs in to a store's own account before Agentcard can buy there. */
     store_login_url: string | null;
     store_login_expires_at: string | null;
@@ -565,6 +618,8 @@ export interface BuyTurn {
     choice: BuyChoice | null;
     /** The checkout plan this answer's yes started or moved, with each item's state; null when none, and on an older API. */
     plan: BuyPlan | null;
+    /** Every store the turn searched and where each stands; null for a turn that searched none, and on an older API. */
+    search: BuySearchStatus | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }

package/dist/client.js

@@ -9,11 +9,13 @@
  * token cache follows its client (packages/checkout/src/client.ts accessToken).
  */
 import { planOf } from './plan.js';
+import { merchantStatusOf, searchOf } from './search-status.js';
 import { isRecord } from './verify.js';
+import { failedPartyOf, fulfilledByField } from './fulfilled-by.js';
 import { listenToAgentcard } from './listen.js';
 import { messageInChat } from './shopper-message.js';
 /** The handlers that ask Agentcard to stream a turn. */
-const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability', 'onReplyWritten'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability', 'onReplyWritten', 'onMerchantStatus'];
 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. */
@@ -59,6 +61,15 @@ const TRACEPARENT = /^[\da-f]{2}-[\da-f]{32}-[\da-f]{16}-[\da-f]{2}$/;
 // A tracestate is printable ASCII of at most 512 characters (W3C); any other value is left off, so it can never stop a purchase.
 const TRACESTATE = /^[\x20-\x7e]{1,512}$/;
 const pickTrace = (c) => typeof c.tracestate === 'string' && TRACESTATE.test(c.tracestate) ? { traceparent: c.traceparent, tracestate: c.tracestate } : { traceparent: c.traceparent };
+/** An answer's code request, from its `browser_checkout` when that checkout waits on a wallet's code; null otherwise. */
+export function codeRequestOf(value) {
+    if (!isRecord(value) || value.status !== 'needs_code' || !str(value.store) || !isRecord(value.code))
+        return null;
+    const { wallet, channel, destination } = value.code;
+    if ((wallet !== 'link' && wallet !== 'shop_pay') || (channel !== 'text' && channel !== 'email'))
+        return null;
+    return { store: value.store, wallet, channel, destination: str(destination) };
+}
 const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'store_login', 'add_card', 'confirm', 'verification_code', 'approve']);
 /**
  * A refusal, or a failure to reach Agentcard. `code` is the API's own
@@ -146,6 +157,23 @@ function feeLinesOf(v) {
     const lines = v.filter(isRecord).flatMap((f) => (str(f.label) && num(f.amountCents) !== null ? [{ label: f.label, amountCents: f.amountCents }] : []));
     return lines.length ? lines : null;
 }
+const HOLD_REASONS = new Set(['flight', 'hotel', 'checkout_estimate']);
+function holdOf(v) {
+    if (!isRecord(v) || typeof v.reason !== 'string' || !HOLD_REASONS.has(v.reason))
+        return null;
+    const amount = num(v.amountCents);
+    return amount !== null && amount > 0 ? { amountCents: amount, reason: v.reason } : null;
+}
+function discountsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter(isRecord).flatMap((d) => {
+        const amount = num(d.amountCents);
+        if (!str(d.label) || amount === null || !(amount < 0))
+            return [];
+        return [d.kind === 'coupon' ? { label: d.label, amountCents: amount, kind: 'coupon', code: str(d.code) } : { label: d.label, amountCents: amount, kind: 'discount', code: null }];
+    });
+}
 function feesOf(v) {
     const amount = num(v.serviceFeesCents);
     const status = v.merchantFeesPending === true || v.serviceFeesStatus === 'pending' ? 'pending'
@@ -174,16 +202,20 @@ function cartOf(v) {
                 product_id: str(i.product_id),
                 ref: str(i.ref),
                 url: pageUrl(i.url),
+                ...fulfilledByField(i),
             };
         }) : [],
         subtotalCents: num(v.subtotalCents),
         ...feesOf(v),
         merchantFeeLines: feeLinesOf(v.merchantFeeLines),
+        discounts: discountsOf(v.discounts),
+        pricing: v.pricing === true,
         tipCents: num(v.tipCents) ?? 0,
         totalCents: num(v.totalCents) ?? 0,
         totalIsEstimate: v.totalIsEstimate === true,
         currency: str(v.currency),
         approvedCeilingCents: num(v.approvedCeilingCents),
+        hold: holdOf(v.hold),
         hash: v.hash,
     };
 }
@@ -226,6 +258,7 @@ function catalogItemsOf(v) {
             store: storeOf(i.store),
             url: pageUrl(i.url),
             ...availabilityField(i),
+            ...fulfilledByField(i),
         };
     }) : [];
 }
@@ -286,6 +319,7 @@ export function turnOf(body) {
         approval_url: str(body.approval_url),
         charge_status: str(body.charge_status),
         error_code: str(body.error_code),
+        fulfilled_by: failedPartyOf(body.placements),
         authorization_id: str(body.authorization_id),
         merchant_total_cents: num(body.merchant_total_cents),
         merchant_currency: str(body.merchant_currency),
@@ -298,12 +332,14 @@ export function turnOf(body) {
         store_login_expires_at: str(body.store_login_expires_at),
         store_login_merchant_name: str(body.store_login_merchant_name),
         next_action: typeof body.next_action === 'string' && NEXT_ACTIONS.has(body.next_action) ? body.next_action : null,
+        code_request: codeRequestOf(body.browser_checkout),
         pick: isRecord(body.pick) && str(body.pick.product_id) ? { product_id: body.pick.product_id, ref: str(body.pick.ref), in_cart: body.pick.in_cart === true } : null,
         stores: storesOf(body.stores),
         store_pick: isRecord(body.store_pick) && str(body.store_pick.store_id) ? { store_id: body.store_pick.store_id, name: str(body.store_pick.name), selected: body.store_pick.selected === true } : null,
         cart_building: cartBuildingOf(body.cart_building),
         choice: choiceOf(body.choice),
         plan: planOf(body.plan),
+        search: searchOf(body.search),
         raw: body,
     };
 }
@@ -480,7 +516,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`, `reply_written`, `cart` and `venue_availability` goes to its handler
+ * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment`, `reply_written`, `cart`, `venue_availability` and `merchant` 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.
@@ -574,6 +610,11 @@ async function readStreamedTurn(res, stream, timeoutMs) {
                 if (items.length)
                     deliver(() => stream.onAvailability({ conversationId: data.conversation_id, items }));
             }
+            else if (event === 'merchant' && stream.onMerchantStatus) {
+                const update = merchantStatusOf(data);
+                if (update)
+                    deliver(() => stream.onMerchantStatus(update));
+            }
             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/fulfilled-by.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Who sells or books a product, where that is not the place its card names: a ticket "via StubHub", an event's tickets
+ * "sold by Gomry", a table "booked with OpenTable". Agentcard sends the party on a card, a cart line and a failed
+ * purchase as `fulfilled_by: { name, kind }`, and this file reads it and words the one quiet line an app shows under the
+ * price. A shopper who reads the party tells one seller's failure from another's, and from Agentcard's.
+ *
+ * Agentcard names only a party the shopper deals with, never the service behind it, and only where the store the card
+ * names does not sell it itself: a retail or Shopify card carries none.
+ */
+/** How the party relates to the product: a ticket marketplace, the seller, a table's or class's booking provider, an airline or a hotel. */
+export type BuyFulfilledByKind = 'marketplace' | 'seller' | 'booking_provider' | 'airline' | 'hotel';
+/** The party a shopper deals with for one card, cart line or failed purchase. `line` is the words to show, such as `via StubHub`. */
+export interface BuyFulfilledBy {
+    name: string;
+    kind: BuyFulfilledByKind;
+    line: string;
+}
+/** The quiet line for a party: `via StubHub`, `sold by Gomry`, `booked with OpenTable`, `flown by Delta`. */
+export declare function fulfilledByLine(party: {
+    name: string;
+    kind: BuyFulfilledByKind;
+}): string;
+/** `fulfilled_by` as Agentcard sent it, or null when it sent none, or a kind this version cannot word. */
+export declare function fulfilledByOf(v: unknown): BuyFulfilledBy | null;
+/** `{ fulfilled_by }` when Agentcard sent a party, else nothing: a card or a line with no party carries no field. */
+export declare function fulfilledByField(v: Record<string, unknown>): {
+    fulfilled_by?: BuyFulfilledBy;
+};
+/**
+ * The party of the first purchase an answer says failed (`placements[].fulfilled_by` beside an `error_code`), or null when
+ * that purchase names none: the turn's `error_code` is that first failure's, so a later failed purchase's party never
+ * stands beside it.
+ */
+export declare function failedPartyOf(placements: unknown): BuyFulfilledBy | null;

package/dist/fulfilled-by.js

@@ -0,0 +1,52 @@
+/**
+ * Who sells or books a product, where that is not the place its card names: a ticket "via StubHub", an event's tickets
+ * "sold by Gomry", a table "booked with OpenTable". Agentcard sends the party on a card, a cart line and a failed
+ * purchase as `fulfilled_by: { name, kind }`, and this file reads it and words the one quiet line an app shows under the
+ * price. A shopper who reads the party tells one seller's failure from another's, and from Agentcard's.
+ *
+ * Agentcard names only a party the shopper deals with, never the service behind it, and only where the store the card
+ * names does not sell it itself: a retail or Shopify card carries none.
+ */
+const LEAD = {
+    marketplace: 'via',
+    seller: 'sold by',
+    booking_provider: 'booked with',
+    airline: 'flown by',
+    hotel: 'booked with',
+};
+/** The quiet line for a party: `via StubHub`, `sold by Gomry`, `booked with OpenTable`, `flown by Delta`. */
+export function fulfilledByLine(party) {
+    return `${LEAD[party.kind]} ${party.name}`;
+}
+/** `fulfilled_by` as Agentcard sent it, or null when it sent none, or a kind this version cannot word. */
+export function fulfilledByOf(v) {
+    if (typeof v !== 'object' || v === null)
+        return null;
+    const { name, kind } = v;
+    if (typeof name !== 'string' || !name.trim() || typeof kind !== 'string' || !Object.hasOwn(LEAD, kind))
+        return null;
+    const party = { name: name.trim(), kind: kind };
+    return { ...party, line: fulfilledByLine(party) };
+}
+/** `{ fulfilled_by }` when Agentcard sent a party, else nothing: a card or a line with no party carries no field. */
+export function fulfilledByField(v) {
+    const party = fulfilledByOf(v.fulfilled_by);
+    return party ? { fulfilled_by: party } : {};
+}
+/**
+ * The party of the first purchase an answer says failed (`placements[].fulfilled_by` beside an `error_code`), or null when
+ * that purchase names none: the turn's `error_code` is that first failure's, so a later failed purchase's party never
+ * stands beside it.
+ */
+export function failedPartyOf(placements) {
+    if (!Array.isArray(placements))
+        return null;
+    for (const p of placements) {
+        if (typeof p !== 'object' || p === null)
+            continue;
+        const { error_code: code, fulfilled_by: party } = p;
+        if (typeof code === 'string' && code)
+            return fulfilledByOf(party);
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, ty
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
 export { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderStep, type OrderPathStep, type OrderStepState, type ArrivalTextOptions, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { 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 BuyLastAnswer, 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 BuyLatestReply, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyChoiceGroup, type BuyChoiceDelivery, type BuyChoiceOption, } from './client.js';
+export { searchAt, isMerchantStatusAt, type BuySearchStatus, type BuyMerchantStatus, type BuyMerchantSearchStatus, type BuyMerchantStatusUpdate, } from './search-status.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 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 BuyPaymentSource, type BuyConversation, type BuyLatestReply, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyCodeRequest, type BuyChoiceGroup, type BuyChoiceDelivery, type BuyChoiceOption, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
 export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolAvailability, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
@@ -20,3 +21,4 @@ export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS, type TurnStream, type Tu
 export { TURN_RECOVERY_ON, isTurnId, type TurnEvent, type TurnRecord, type TurnRecordStore } from './turn-record.js';
 export type { BuyLateResults, BuyStoreWait } from './store-wait.js';
 export { planOf, type BuyPlan, type BuyPlanItem, type BuyPlanItemState, type BuyPlanStatus } from './plan.js';
+export { fulfilledByLine, fulfilledByOf, type BuyFulfilledBy, type BuyFulfilledByKind } from './fulfilled-by.js';

package/dist/index.js

@@ -3,6 +3,7 @@ export { readPurchaseMessage, } from './message.js';
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, } from './shopper-message.js';
 export { ORDER_STEPS, updateOrder, arrivalText, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, } from './handler.js';
+export { searchAt, isMerchantStatusAt, } from './search-status.js';
 export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, typingDelay, } from './messages.js';
@@ -19,3 +20,4 @@ export { AGENTCARD_EVENT_TYPES, } from './events.js';
 export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS } from './turn-stream.js';
 export { TURN_RECOVERY_ON, isTurnId } from './turn-record.js';
 export { planOf } from './plan.js';
+export { fulfilledByLine, fulfilledByOf } from './fulfilled-by.js';

package/dist/model-view.d.ts

@@ -14,7 +14,8 @@ export interface BuyToolModelCart {
     /**
      * `price` is one unit's; `line_total` is what the line costs with its add-ons and quantity, and the
      * lines' totals add up before `fees`. `options` are the choices made on the line and `variant` the
-     * variant it is. `product_id` is the id the line's product carries in `products`, or null.
+     * variant it is. `product_id` is the id the line's product carries in `products`, or null. `fulfilled_by` is who
+     * sells or books the line where that is not the store, such as `via StubHub`; absent when Agentcard named none.
      */
     items: Array<{
         product_id: string | null;
@@ -24,6 +25,7 @@ export interface BuyToolModelCart {
         line_total: string | null;
         options: string[];
         variant: string | null;
+        fulfilled_by?: string;
     }>;
     fees: string | null;
     fees_status?: 'known' | 'pending' | 'unknown';
@@ -32,6 +34,19 @@ export interface BuyToolModelCart {
         label: string;
         amount: string;
     }>;
+    /**
+     * The discounts and coupons inside `total`, each negative, which `fee_lines` also lists: show them as money taken off,
+     * never add them to `total` again. `code` names a coupon's code. Absent when the cart has none.
+     */
+    discounts?: Array<{
+        label: string;
+        amount: string;
+        amount_cents: number;
+        kind: 'discount' | 'coupon';
+        code: string | null;
+    }>;
+    /** True while the store's checkout prices this cart, several stores at once included, so `total` is not its price yet; absent once it is priced. */
+    pricing?: true;
     tip: string | null;
     total: string;
     /** True when the store has not priced its fees and tax yet: `total` is an estimate, never the final amount. */
@@ -40,6 +55,16 @@ export interface BuyToolModelCart {
     total_leaves_out: string | null;
     /** The most the shopper's card can be held for this cart: above `total` at a store that prices its final at checkout, `total` itself for a flight, which holds exactly that; else null. */
     max_charge: string | null;
+    /**
+     * Why the card is held for `max_charge`: `flight` or `hotel` for a booking's hold on the card, which the shopper sees
+     * on their statement, and `checkout_estimate` for the headroom over a store's total, released unused. Show a hold line
+     * for `flight` and `hotel` alone. Absent when nothing is held.
+     */
+    hold?: {
+        amount: string;
+        amount_cents: number;
+        reason: 'flight' | 'hotel' | 'checkout_estimate';
+    };
 }
 export interface BuyToolModelProduct {
     /** What the model passes as `product_id` when the shopper picks this product: Agentcard's ref, never a link. Null when there is none. */

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,
@@ -274,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)),

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/package.json

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