@agent-cards/commerce-sdk 0.18.8 → 0.18.10

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.81";
+export declare const VOICE_VERSION = "0.2.83";
 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.81";
+export const VOICE_VERSION = "0.2.83";
 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

@@ -31,8 +31,10 @@
  * messages and links as one sequence, in the order they happened, and spaces
  * the messages like someone texting.
  */
+import type { BuyCardSize } from './card-size.js';
 import type { BuyPlan } from './plan.js';
 import type { BuyMerchantStatusUpdate, BuySearchStatus } from './search-status.js';
+import type { BuyFreshness, BuyRecheck, BuyStoreCheckUpdate } from './client.js';
 import type { BuyFulfilledBy } from './fulfilled-by.js';
 import { AgentcardClient, type BuyCart, type BuyCartBuilding, type BuyChoice, type BuyCodeRequest, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyTurnStatus, type BuyAvailability, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
@@ -97,6 +99,8 @@ export interface BuyToolLink {
      * `{ name: 'StubHub', kind: 'marketplace', line: 'via StubHub' }`. Show `line` quietly under the price. Absent when none.
      */
     fulfilledBy?: BuyFulfilledBy;
+    /** On a product link: the shopper's size as the store's read found it. Show `line` under the price when it is not null. */
+    shopperSize?: BuyCardSize;
     /**
      * 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.
@@ -134,6 +138,10 @@ export interface BuyToolLink {
      * Absent on every other card, such as a retail product's.
      */
     availability?: BuyAvailability;
+    /** On a product link: whether the product ships to the shopper's country, as on `BuyToolProduct.shipsToYou`. */
+    shipsToYou?: 'yes' | 'no';
+    /** On a product link: the note for a product that ranks down for where it ships, as on `BuyToolProduct.shipsNote`. */
+    shipsNote?: string;
 }
 /** A store the answer's reply presents to choose from. */
 export interface BuyToolStore {
@@ -184,8 +192,14 @@ 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;
+    /** Whether the product ships to the shopper's country (`BuyCatalogItem.ships_to_you`): `yes` or `no`, and absent when Agentcard cannot say or an older API sends none. */
+    shipsToYou?: 'yes' | 'no';
+    /** A short note for a product that ranks down for where it ships ("ships from the UK", "price in £"). Absent when there is none. */
+    shipsNote?: string;
     /** Who sells or books it, where that is not the store it names (`via StubHub`); absent when Agentcard named none. */
     fulfilledBy?: BuyFulfilledBy;
+    /** The shopper's size as the store's read found it (`men's 10.5 in stock`); absent when none was asked or read. */
+    shopperSize?: BuyCardSize;
 }
 /** One answer of the buy tool, whole, for your code. Hand it to `forModel` before a model reads it. */
 export interface BuyToolResult {
@@ -407,6 +421,18 @@ export interface BuyToolOptions extends BuyStoreWait {
      * search starts, then what it found. One that throws costs nothing but the call to it.
      */
     onMerchantStatus?: (update: BuyMerchantStatusUpdate) => void | Promise<void>;
+    /**
+     * Hears each store behind a card while Agentcard checks its price and stock, then the store's answer
+     * (`BuyStoreCheckUpdate`): `cardId` is the card's `productId`. One that throws costs nothing but the call to it.
+     */
+    onStoreCheck?: (update: BuyStoreCheckUpdate) => void | Promise<void>;
+    /**
+     * Hears Agentcard read the shopper's quotes again (`BuyRecheck`): at the start, the line to show and each item checking;
+     * at the end, the answer and each item's result. One that throws costs nothing but the call to it.
+     */
+    onRecheck?: (update: BuyRecheck) => void | Promise<void>;
+    /** Hears each quote's answer as its read lands (`BuyFreshness`). One that throws costs nothing but the call to it. */
+    onFreshness?: (update: BuyFreshness) => 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.
@@ -636,6 +662,12 @@ export interface BuyToolTurnOptions extends BuyStoreWait {
     onAvailability?: BuyToolOptions['onAvailability'];
     /** Hears each store this turn's searches ask, as the tool's `onMerchantStatus` does. */
     onMerchantStatus?: BuyToolOptions['onMerchantStatus'];
+    /** Hears each store behind this turn's cards as it is checked, as the tool's `onStoreCheck` does. */
+    onStoreCheck?: BuyToolOptions['onStoreCheck'];
+    /** Hears this turn's re-check of the shopper's quotes, as the tool's `onRecheck` does. */
+    onRecheck?: BuyToolOptions['onRecheck'];
+    /** Hears each quote's answer in this turn's re-check, as the tool's `onFreshness` does. */
+    onFreshness?: BuyToolOptions['onFreshness'];
     /** 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

@@ -223,12 +223,16 @@ export function nextStepPrompt(message) {
 /**
  * The pick as a later read of the conversation shows it: a pick the early answer found missing is in
  * the cart once a line carries its catalog id, as its product id or, for a retail product whose id is
- * its store page, as its page. A pick already in the cart, or none, stays as it was.
+ * its store page, as its page, or names its card by `ref`. A catalog card carted at a store page has the
+ * page as its line's id: on 2026-11-01 (conv_611973099c62bc0cdb2c041b) a pan set carted at kohls.com read
+ * as missing, so the model told the shopper the card it had just added was gone. A pick already in the
+ * cart, or none, stays as it was.
  */
 function pickAfter(pick, carts) {
     if (!pick || pick.in_cart)
         return pick;
-    const held = carts.some((c) => c.items.some((line) => line.product_id === pick.product_id || line.url === pick.product_id));
+    const names = (ref) => !!ref && (ref === pick.product_id || ref === pick.ref);
+    const held = carts.some((c) => c.items.some((line) => line.product_id === pick.product_id || line.url === pick.product_id || names(line.ref)));
     return held ? { ...pick, in_cart: true } : pick;
 }
 function hashesOf(cart, carts) {
@@ -242,7 +246,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 } : {}), ...(product.fulfilledBy ? { fulfilledBy: product.fulfilledBy } : {}) };
+    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 } : {}), ...(product.shipsToYou ? { shipsToYou: product.shipsToYou } : {}), ...(product.shipsNote ? { shipsNote: product.shipsNote } : {}), ...(product.shopperSize ? { shopperSize: product.shopperSize } : {}) };
 }
 /** 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,7 +282,10 @@ function productsOfCatalog(catalog) {
         action: productAction(catalog.merchant),
         linkSent: false,
         ...(item.availability ? { availability: item.availability } : {}),
+        ...(item.ships_to_you === 'yes' || item.ships_to_you === 'no' ? { shipsToYou: item.ships_to_you } : {}),
+        ...(item.ships_note ? { shipsNote: item.ships_note } : {}),
         ...(item.fulfilled_by ? { fulfilledBy: item.fulfilled_by } : {}),
+        ...(item.shopper_size ? { shopperSize: item.shopper_size } : {}),
     }));
 }
 /** The stores an answer presents, as the tool reads them. */
@@ -770,7 +777,7 @@ export function buyTool(options) {
     if (o.stream !== undefined && o.stream !== false)
         throw new TypeError('Pass stream as false to wait for each whole answer, or leave it out.');
     const onProgress = o.onProgress;
-    for (const key of ['onStatus', 'onFound', 'onAvailability', 'onMerchantStatus']) {
+    for (const key of ['onStatus', 'onFound', 'onAvailability', 'onMerchantStatus', 'onStoreCheck', 'onRecheck', 'onFreshness']) {
         if (o[key] !== undefined && typeof o[key] !== 'function')
             throw new TypeError(`Pass ${key} as a function, or leave it out.`);
     }
@@ -852,6 +859,9 @@ export function buyTool(options) {
         onFound: o.onFound,
         onAvailability: o.onAvailability,
         onMerchantStatus: o.onMerchantStatus,
+        onStoreCheck: o.onStoreCheck,
+        onRecheck: o.onRecheck,
+        onFreshness: o.onFreshness,
         onProducts: o.onProducts,
         onText: o.onText,
         texting: textingByDefault,
@@ -1920,9 +1930,16 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
-                    ...(early || t.onProducts
+                    ...(early || t.onProducts || t.onStoreCheck
                         ? {
                             onCatalog: async (update) => {
+                                // Each card's productId is noted as its catalog arrives, whether or not cards go out early, so a store
+                                // check that follows names the card the app drew.
+                                for (const product of [...productsOfCatalog(update.catalog), ...productsOfCatalog({ ...update.catalog, items: update.more })]) {
+                                    const productId = pickId(product);
+                                    if (productId)
+                                        cardOfId.set(product.id, productId);
+                                }
                                 try {
                                     await t.onProducts?.(productsOfCatalog(update.catalog), { conversationId: update.conversationId, asOf: update.asOf, merchantName: update.catalog.merchant_name });
                                 }
@@ -1933,8 +1950,9 @@ export function buyTool(options) {
                                 const keepMore = () => { if (t.onFound && early)
                                     moreFound = { conversationId: update.conversationId, links: productsOfCatalog({ ...update.catalog, items: update.more }).map(productLink) }; };
                                 if (!early) {
-                                    // Without early cards nothing goes out here, but a store that answered after the reply still joins the result.
-                                    if (replyWritten)
+                                    // Without early cards nothing goes out here, but a store that answered after the reply still joins the
+                                    // result for an app that draws products; one that asked only for store checks reads the answer as before.
+                                    if (replyWritten && t.onProducts)
                                         lateCards.push(...productsOfCatalog(update.catalog));
                                     return;
                                 }
@@ -1977,6 +1995,50 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
+                    ...(t.onStoreCheck
+                        ? {
+                            onStoreCheck: async (update) => {
+                                try {
+                                    await t.onStoreCheck({ ...update, cardId: cardOfId.get(update.cardId) ?? update.cardId });
+                                }
+                                catch {
+                                    // The app's display failing never fails the turn.
+                                }
+                            },
+                        }
+                        : {}),
+                    ...(t.onRecheck
+                        ? {
+                            onRecheck: async (update) => {
+                                try {
+                                    await t.onRecheck(update);
+                                }
+                                catch {
+                                    // The app's display failing never fails the turn, and the wait line stays, so the shopper still hears one.
+                                    return;
+                                }
+                                // The re-check's line, once the app showed it, is the turn's acknowledgement: no wait line follows it,
+                                // however long the reads run.
+                                if (update.phase === 'started' && update.text) {
+                                    ack?.cancel();
+                                    t.dropWaitLine?.();
+                                    t.acked = true;
+                                }
+                            },
+                        }
+                        : {}),
+                    ...(t.onFreshness
+                        ? {
+                            onFreshness: async (update) => {
+                                try {
+                                    await t.onFreshness(update);
+                                }
+                                catch {
+                                    // The app's display failing never fails the turn.
+                                }
+                            },
+                        }
+                        : {}),
                     ...(t.onText || writtenText
                         ? {
                             onSegment: async ({ text, conversationId }) => {
@@ -2331,7 +2393,7 @@ export function buyTool(options) {
         const own = options ?? {};
         if (typeof own !== 'object')
             throw new TypeError('Pass the turn options as an object, or leave them out.');
-        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', 'onMerchantStatus', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', 'onMerchantStatus', 'onStoreCheck', 'onRecheck', 'onFreshness', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
             if (own[key] !== undefined && typeof own[key] !== 'function')
                 throw new TypeError(`Pass ${key} to the turn as a function, or leave it out.`);
         }
@@ -2416,6 +2478,9 @@ export function buyTool(options) {
             onFound: own.onFound ?? o.onFound,
             onAvailability: own.onAvailability ?? o.onAvailability,
             onMerchantStatus: own.onMerchantStatus ?? o.onMerchantStatus,
+            onStoreCheck: own.onStoreCheck ?? o.onStoreCheck,
+            onRecheck: own.onRecheck ?? o.onRecheck,
+            onFreshness: own.onFreshness ?? o.onFreshness,
             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/card-size.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The shopper's size on a product card, as Agentcard sends it on a shoe or a garment it read at the store for the size the
+ * shopper named: the size asked for, the store's own label for it, and whether the store has it in stock. `available` is
+ * null when no read answered, and the card then says nothing of the size: an app never shows a size as in stock that
+ * Agentcard did not read. `line` is the words to show under the price, or null when there is nothing to say.
+ */
+export interface BuyCardSize {
+    /** The size the shopper asked for, as they read it: `men's 10.5`, `EU 44`, `size M`. */
+    requested: string;
+    /** The store's own label for that size (`10.5`, `M 10 / W 11.5`), or null when the store does not sell it. */
+    label: string | null;
+    /** True when the store has it in stock, false when it does not sell it or sold out of it, null when unread. */
+    available: boolean | null;
+    /** `men's 10.5 in stock` or `No men's 10.5 here`; null when `available` is null. */
+    line: string | null;
+}
+/** `shopper_size` as Agentcard sent it, or null when it sent none or a shape this version cannot read. */
+export declare function cardSizeOf(v: unknown): BuyCardSize | null;
+/** `{ shopper_size }` when Agentcard sent one, else nothing: a card with no size carries no field. */
+export declare function cardSizeField(v: Record<string, unknown>): {
+    shopper_size?: BuyCardSize;
+};

package/dist/card-size.js

@@ -0,0 +1,23 @@
+/**
+ * The shopper's size on a product card, as Agentcard sends it on a shoe or a garment it read at the store for the size the
+ * shopper named: the size asked for, the store's own label for it, and whether the store has it in stock. `available` is
+ * null when no read answered, and the card then says nothing of the size: an app never shows a size as in stock that
+ * Agentcard did not read. `line` is the words to show under the price, or null when there is nothing to say.
+ */
+/** `shopper_size` as Agentcard sent it, or null when it sent none or a shape this version cannot read. */
+export function cardSizeOf(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const r = v;
+    if (typeof r.requested !== 'string' || !r.requested.trim())
+        return null;
+    const available = r.available === true ? true : r.available === false ? false : null;
+    const label = typeof r.label === 'string' && r.label.trim() ? r.label : null;
+    const line = available === true ? `${r.requested} in stock` : available === false ? `No ${r.requested} here` : null;
+    return { requested: r.requested, label, available, line };
+}
+/** `{ shopper_size }` when Agentcard sent one, else nothing: a card with no size carries no field. */
+export function cardSizeField(v) {
+    const size = cardSizeOf(v.shopper_size);
+    return size ? { shopper_size: size } : {};
+}

package/dist/client.d.ts

@@ -8,9 +8,11 @@
  * @agent-cards/sdk (packages/checkout/src/buy.ts: turnOf, buyError), and the
  * token cache follows its client (packages/checkout/src/client.ts accessToken).
  */
+import { type BuyTrip } from './trip.js';
 import { type BuyPlan } from './plan.js';
 import { type BuyMerchantStatusUpdate, type BuySearchStatus } from './search-status.js';
 import { type BuyFulfilledBy } from './fulfilled-by.js';
+import { type BuyCardSize } from './card-size.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. */
@@ -93,6 +95,26 @@ export interface BuyAvailabilityUpdate {
         availability: BuyAvailability;
     }>;
 }
+/**
+ * One store behind one card of a running turn, as Agentcard asks the store itself for its price and stock: `checking` until
+ * the store answers, then `confirmed` (with the store's own price in `priceCents` when it gave one), `sold_out` (the store
+ * leaves the card) or `unconfirmed` (the store gave no stock answer; the card keeps the catalog's word for it). Show
+ * "checking <storeName>…" on the card until its store answers.
+ *
+ * Agentcard checks at most eight stores a turn, in the order the cards show, and each store once, under the first card that
+ * lists it: a later card that lists the same store, and a store past the eighth, hear no update and keep the catalog's word.
+ */
+export interface BuyStoreCheckUpdate {
+    conversationId: string;
+    /** The card's catalog `id`. */
+    cardId: string;
+    /** The store's website, such as `walmart.com`. */
+    store: string;
+    /** The store as a shopper reads it, such as `Walmart`. */
+    storeName: string;
+    state: 'checking' | 'confirmed' | 'sold_out' | 'unconfirmed';
+    priceCents: number | null;
+}
 /** How many products a running turn found so far, and how many of them it shows: "8 of 23 shown". */
 export interface BuyFoundUpdate {
     conversationId: string;
@@ -174,6 +196,52 @@ export interface BuyStreamHandlers {
      * follow one store, keep the updates `isMerchantStatusAt(update, 'walmart.com')` accepts. The answer's `search` holds every store.
      */
     onMerchantStatus?: (update: BuyMerchantStatusUpdate) => void | Promise<void>;
+    /**
+     * Agentcard reads the shopper's quotes again: on their return after a gap, or before a yes to a price older than its
+     * window. Comes with `phase: 'started'`, the line to show at once and every item `checking`, then `phase: 'finished'` with
+     * the answer to show and every item's result. A changed price is a question: the turn's reply asks it and nothing is booked.
+     */
+    onRecheck?: (update: BuyRecheck) => void | Promise<void>;
+    /** One item's answer as its read lands, so its status moves from checking to confirmed, changed or gone. */
+    onFreshness?: (update: BuyFreshness) => void | Promise<void>;
+    /** A store behind a card, while Agentcard checks its price and stock and once it answers: up to eight stores a turn, each under its first card. */
+    onStoreCheck?: (update: BuyStoreCheckUpdate) => void | Promise<void>;
+}
+/** Whether a quote read again still stands: `same` price, a `changed` one, or `gone` from the seller. */
+export type BuyFreshnessState = 'same' | 'changed' | 'gone';
+/** One quote after it was read again. Amounts are in the currency's smallest unit. */
+export interface BuyFreshness {
+    conversationId: string | null;
+    ref: string;
+    kind: 'flight' | 'event_ticket' | 'hotel' | 'rental_car' | 'restaurant_table' | 'store_cart';
+    name: string;
+    /** Who sells it, where the name does not say: a store's name. Null for a trip's item. */
+    seller: string | null;
+    freshness: BuyFreshnessState;
+    /** The quiet status to show beside the item: `confirmed`, `changed` or `gone`. */
+    status: 'confirmed' | 'changed' | 'gone';
+    /** The status in words: `Confirmed`, `Now $239.00`, `Sold out`. */
+    text: string;
+    previousCents: number | null;
+    amountCents: number | null;
+    currency: string | null;
+    /** When the read saw this price, ISO 8601. */
+    checkedAt: string;
+}
+/** A re-check of the shopper's quotes, as it starts and as it ends. */
+export interface BuyRecheck {
+    conversationId: string | null;
+    phase: 'started' | 'finished';
+    /** `return`: the shopper came back after a gap. `commit`: a yes to prices older than their window. */
+    reason: 'return' | 'commit';
+    /** The line to show: what is being read again when it starts, the answer when it ends. Null when no read answered. */
+    text: string | null;
+    /** At the start, each item with `status: 'checking'`; at the end, each item that answered. */
+    items: Array<Pick<BuyFreshness, 'ref' | 'kind' | 'name' | 'seller' | 'text'> & Omit<Partial<BuyFreshness>, 'status'> & {
+        status: 'checking' | BuyFreshness['status'];
+    }>;
+    /** Items whose read did not answer: they keep their old price, and the checkout's own amount check still holds. */
+    unread: string[];
 }
 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. */
@@ -429,6 +497,18 @@ export interface BuyFlightItinerary {
         arrivalAt: string | null;
         cabinClasses: Array<string | null>;
     }>;
+    /** Who the price covers, when it covers more than one passenger: `priceCents` is then the whole party's. Absent for one passenger and from an older API. */
+    party?: BuyFlightParty;
+}
+/**
+ * A flight price for a party. `totalCents` is the price for every passenger together, the same as the card's `priceCents`.
+ * `perPassengerCents` is each passenger's share, adults first, when Agentcard knows it; absent when the fares differ by age.
+ */
+export interface BuyFlightParty {
+    adults: number;
+    children: number;
+    totalCents: number;
+    perPassengerCents?: number[];
 }
 export interface BuyCatalogItem {
     flight?: BuyFlightItinerary;
@@ -452,8 +532,18 @@ 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;
+    /**
+     * Whether the product ships to the shopper's country: `yes` or `no` when the store lists the countries it ships to and
+     * Agentcard knows where the shopper is, `unknown` otherwise and from an older API. Agentcard never leaves a product out for
+     * it, and ranks a `no` behind the products that match the ask as well; an app may filter on it.
+     */
+    ships_to_you: 'yes' | 'no' | 'unknown';
+    /** A short note for a product that ranks down for where it ships ("ships from the UK", "price in £"), or null. */
+    ships_note: string | null;
     /** 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 size the shopper named, as the store's read of this product found it (BuyCardSize); absent when none was asked or read. */
+    shopper_size?: BuyCardSize;
 }
 /**
  * The products the last search found. `presented` is true when this answer's reply presents them: the
@@ -664,6 +754,8 @@ export interface BuyConversation {
     last_checkout: BuyLastCheckout | null;
     orders: BuyOrder[];
     carts: BuyCart[];
+    /** A trip being planned: each background search's status and results, flights first; null for any other conversation (trip.ts). */
+    trip: BuyTrip | null;
     /**
      * The reply Agentcard wrote since the shopper's last message, once no turn runs: the answer a call that ended with
      * `turn_timeout` never got. Null while a turn runs, when no reply was written since, and on an older API.

package/dist/client.js

@@ -8,12 +8,15 @@
  * @agent-cards/sdk (packages/checkout/src/buy.ts: turnOf, buyError), and the
  * token cache follows its client (packages/checkout/src/client.ts accessToken).
  */
+import { tripOf } from './trip.js';
 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 { cardSizeField } from './card-size.js';
 import { listenToAgentcard } from './listen.js';
 import { messageInChat } from './shopper-message.js';
+const STORE_CHECK_STATES = new Set(['checking', 'confirmed', 'sold_out', 'unconfirmed']);
 /**
  * The words this SDK shows for a step whatever Agentcard's own line says, so every app reads the same line. `searching_wider`
  * comes when a search across every store has shown no product for a while and keeps running; its products still come as cards.
@@ -22,7 +25,7 @@ export const STATUS_WORDING = Object.freeze({
     searching_wider: 'Checking more stores for this…',
 });
 /** The handlers that ask Agentcard to stream a turn. */
-const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability', 'onReplyWritten', 'onMerchantStatus'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability', 'onReplyWritten', 'onMerchantStatus', 'onRecheck', 'onFreshness', 'onStoreCheck'];
 const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -107,6 +110,45 @@ export class AgentcardApiError extends Error {
 }
 const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const QUOTE_KINDS = new Set(['flight', 'event_ticket', 'hotel', 'rental_car', 'restaurant_table', 'store_cart']);
+const FRESHNESS = new Set(['same', 'changed', 'gone']);
+const FRESH_STATUS = { same: 'confirmed', changed: 'changed', gone: 'gone' };
+/** One item of a `freshness` event or a finished `recheck`, or null when it is not one. */
+function freshnessOf(data, conversationId) {
+    const ref = str(data.ref);
+    const kind = str(data.kind);
+    const name = str(data.name);
+    const freshness = str(data.freshness);
+    if (!ref || !kind || !QUOTE_KINDS.has(kind) || !name || !freshness || !FRESHNESS.has(freshness))
+        return null;
+    return {
+        conversationId, ref, kind: kind, name, seller: str(data.seller),
+        freshness: freshness, status: FRESH_STATUS[freshness], text: str(data.text) ?? '',
+        previousCents: num(data.previous_cents), amountCents: num(data.amount_cents), currency: str(data.currency), checkedAt: str(data.checked_at) ?? '',
+    };
+}
+/** A `recheck` event as the app reads it. */
+function recheckOf(data, conversationId) {
+    const items = (Array.isArray(data.items) ? data.items : []).flatMap((raw) => {
+        if (!raw || typeof raw !== 'object')
+            return [];
+        const i = raw;
+        const done = freshnessOf(i, conversationId);
+        if (done)
+            return [done];
+        const ref = str(i.ref);
+        const kind = str(i.kind);
+        const name = str(i.name);
+        // Only a started re-check's item is still checking: a finished one this version cannot read is left out.
+        if (data.phase !== 'started' || !ref || !kind || !QUOTE_KINDS.has(kind) || !name)
+            return [];
+        return [{ ref, kind: kind, name, seller: str(i.seller), text: str(i.text) ?? '', status: 'checking' }];
+    });
+    return {
+        conversationId, phase: data.phase, reason: data.reason === 'commit' ? 'commit' : 'return',
+        text: str(data.text), items, unread: Array.isArray(data.unread) ? data.unread.filter((u) => typeof u === 'string') : [],
+    };
+}
 const bool = (v) => (typeof v === 'boolean' ? v : null);
 /**
  * A product page's address: an absolute http or https URL, serialized the way
@@ -240,8 +282,18 @@ function flightOf(value) {
                 departureAt: str(leg.departureAt), arrivalAt: str(leg.arrivalAt),
                 cabinClasses: Array.isArray(leg.cabinClasses) ? leg.cabinClasses.map(str) : [] };
         }),
+        ...partyOf(value.party),
     };
 }
+function partyOf(value) {
+    if (!isRecord(value))
+        return {};
+    const adults = num(value.adults), children = num(value.children), totalCents = num(value.totalCents);
+    if (adults === null || children === null || totalCents === null || adults + children < 2)
+        return {};
+    const each = Array.isArray(value.perPassengerCents) ? value.perPassengerCents.map(num) : null;
+    return { party: { adults, children, totalCents, ...(each && each.length === adults + children && each.every((c) => c !== null) ? { perPassengerCents: each } : {}) } };
+}
 function catalogOf(v) {
     if (!isRecord(v))
         return null;
@@ -265,7 +317,10 @@ function catalogItemsOf(v) {
             store: storeOf(i.store),
             url: pageUrl(i.url),
             ...availabilityField(i),
+            ships_to_you: i.ships_to_you === 'yes' || i.ships_to_you === 'no' ? i.ships_to_you : 'unknown',
+            ships_note: str(i.ships_note),
             ...fulfilledByField(i),
+            ...cardSizeField(i),
         };
     }) : [];
 }
@@ -404,6 +459,7 @@ function conversationOf(body) {
         })) : [],
         carts: cartsOf(body.carts),
         latest_reply: latestReplyOf(body.latest_reply),
+        trip: tripOf(body.trip),
         raw: body,
     };
 }
@@ -523,7 +579,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`, `venue_availability` and `merchant` goes to its handler
+ * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment`, `reply_written`, `cart`, `venue_availability`, `merchant` and `store_check` 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.
@@ -608,6 +664,14 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             else if (event === 'ack' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onAck) {
                 deliver(() => stream.onAck({ conversationId: named, text: data.text }));
             }
+            else if (event === 'recheck' && stream.onRecheck && (data.phase === 'started' || data.phase === 'finished')) {
+                const recheck = recheckOf(data, named);
+                deliver(() => stream.onRecheck(recheck));
+            }
+            else if (event === 'freshness' && stream.onFreshness && freshnessOf(data, named)) {
+                const one = freshnessOf(data, named);
+                deliver(() => stream.onFreshness(one));
+            }
             else if (event === 'venue_availability' && stream.onAvailability && str(data.conversation_id) && Array.isArray(data.items)) {
                 const items = data.items.filter(isRecord).flatMap((i) => {
                     const id = str(i.id);
@@ -617,6 +681,18 @@ async function readStreamedTurn(res, stream, timeoutMs) {
                 if (items.length)
                     deliver(() => stream.onAvailability({ conversationId: data.conversation_id, items }));
             }
+            else if (event === 'store_check' && stream.onStoreCheck && str(data.conversation_id) && isRecord(data.item)) {
+                const i = data.item;
+                const cardId = str(i.id);
+                const store = str(i.store);
+                if (cardId && store && typeof i.state === 'string' && STORE_CHECK_STATES.has(i.state)) {
+                    const update = {
+                        conversationId: data.conversation_id, cardId, store, storeName: str(i.store_name) ?? store,
+                        state: i.state, priceCents: typeof i.price_cents === 'number' ? i.price_cents : null,
+                    };
+                    deliver(() => stream.onStoreCheck(update));
+                }
+            }
             else if (event === 'merchant' && stream.onMerchantStatus) {
                 const update = merchantStatusOf(data);
                 if (update)

package/dist/definition.js

@@ -45,7 +45,7 @@ export const BUY_TOOL_RULES = [
     'Never tell the shopper what has not happened yet or where things stand inside, such as "nothing\'s been charged yet", "your order isn\'t placed yet" or "the address isn\'t locked in", even when `reply` says it: ask for what is needed instead, such as "should it ship to 1 ferry plz?".',
     'When `next_action` is `store_login`, `add_card` or `approve`, the message that asks for it is one short line and nothing else, even when `reply` says more, such as "sign in to doordash to place your order", "add your card to place the order" or "approve the payment to place your order (up to $19.02)": no recap of the cart, the address or the price, nothing about tax, delivery, shipping, a hold or what was charged, no word on when the link runs out, and never a request to tell you once it is done. On `approve`, put the cart\'s `max_charge` in the parentheses when it is set, and no other amount. Only when the shopper\'s last message picked what went in the cart does a line about the cart come first, as its own message; after an address, a phone number, a yes or a saved card, the ask is the whole reply.',
     'When `yes_carried` is set, the shopper already said yes to this cart, or picked it (`yes_carried.picked`), and Agentcard went ahead on it once they finished the step outside the chat, so never ask for their yes again: ask only for the step `next_action` names. When `yes_carried.total_changed` is true, that one short line opens with the new total, the one price it names beside `max_charge`, such as "it\'s $17.89 with fees and tax now. approve the payment to place your order (up to $19.02)".',
-    'When `next_action` is `confirm`, ask in one short message: the items, one total, and to say yes to place it, such as "1 carolina black socks pack from walmart, about $9.57. say yes to place it". Leave out the fees one by one, the hold, and the address unless the shopper just changed it.',
+    'When `next_action` is `confirm`, ask in one short message: the items, each at its price before fees as the cart lists it, saying so when that is not the price its card showed, the total said as "with fees", and to say yes to place it, such as "1 carolina black socks pack from walmart, $9.34. $9.57 with fees. say yes to place it". Never give the total as an item\'s price. Leave out the fees one by one, the hold, and the address unless the shopper just changed it.',
     'Every line you write reaches the shopper, a line before you call this tool too: write to them as "you", never about "the shopper" or "the user", and never say what you are about to do with this tool, such as "I\'ll add them now".',
     'Say as fact only what the result shows: never promise what a store will do later, such as confirm a size when the order goes through.',
     'Never tell the shopper to remove, delete or replace a card or to change a setting, even when `reply` says to.',
@@ -54,7 +54,7 @@ export const BUY_TOOL_RULES = [
     'Write every sentence in your own style, casing included, even where `reply` is written another way.',
     "When the shopper asks what you can do or which stores you shop at, answer without calling this tool and with no line saying you are looking: one message that names at most four stores plus the kinds of things you can do, such as food delivery and restaurant reservations, then one that asks what they need. Every shopper can buy from Amazon, Walmart, Target, Best Buy and thousands more stores, so name those four and 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 the four read as the whole list, never say \"plenty more\", \"many more\" or \"most online stores\", and never give a number of stores. Name no other store unless a result showed it.",
     "Never tell the shopper you can't render or show Markdown, a table or other formatting, and never say you keep to plain text: how your words look is your app's to decide.",
-    'Each paragraph you write reaches the shopper as its own message: give each one job and keep it under about 20 words. On a cart turn, write the confirmation and the one next step, such as "added a little cheeseburger from five guys, about $12.17 before delivery and tax" and then "next, sign in to doordash with the link so i can place it": one total, never a price breakdown your app\'s cart already shows (an app that shows no cart lists each line with its price) and never a fee by its name, rate or formula, such as an order fee, card processing or 2.9% + $0.30, even when `reply` or `fee_lines` names it, unless the shopper asks what the fees are, no promise to show the final total later, and nothing about passkeys, master passwords or Agentcard not seeing the card number unless the shopper asks.',
+    'Each paragraph you write reaches the shopper as its own message: give each one job and keep it under about 20 words. On a cart turn, write the confirmation and the one next step, such as "added a little cheeseburger from five guys, $11.88, about $12.17 with fees before delivery and tax" and then "next, sign in to doordash with the link so i can place it": each item at its price before fees as the cart lists it, saying so when that is not the price its card showed, and one total said as "with fees", never the total as an item\'s price, never a price breakdown your app\'s cart already shows (an app that shows no cart lists each line with its price) and never a fee by its name, rate or formula, such as an order fee, card processing or 2.9% + $0.30, even when `reply` or `fee_lines` names it, unless the shopper asks what the fees are, no promise to show the final total later, and nothing about passkeys, master passwords or Agentcard not seeing the card number unless the shopper asks.',
     'Never listing products again is for offering choices: when you confirm what is in the cart, name each line by its item, such as "1 Dawn Ultra dish soap, 38 oz", never "the one you picked, shown in the card".',
     'When you list options or choices for the shopper, such as sizes, breads, times, or stores no card shows, write one per line, each starting with "• ", in the same paragraph as the line that asks which one, so the question and its choices reach the shopper as one message. When the result has `choice`, list every value it holds that way, with its extra price, such as "• Gluten-free bread (+$2.46)", even when `reply` names them inside a sentence. The products and stores the cards show are still never listed again.',
     'Say how long a link works only when the shopper asks, with `link_expires_in`, such as "it works for about 24 hours", never as a raw date and time or in UTC, such as `approval_expires_at` holds; when `link_expires_in` is null, say nothing about when it runs out.',

package/dist/events.d.ts

@@ -3,7 +3,7 @@
  * name. The stream (`agentcard.listen`) and a webhook endpoint carry the same types, with the same
  * envelope and the same ids. A test holds this list to the backend's catalog.
  */
-export declare const AGENTCARD_EVENT_TYPES: readonly ['card.created', 'card.updated', 'card.closed', 'cardholder.created', 'cardholder.updated', 'transaction.authorized', 'transaction.declined', 'transaction.cleared', 'transaction.voided', 'balance.low', 'cardholder_onboarding_session.completed', 'platform_connect_session.completed', 'merchant.connected', 'order.placed', 'order.confirmed', 'order.failed', 'order.updated', 'purchase.message', 'connection.created', 'connected_card.updated', 'vault.card_stored', 'vault.session_linked', 'vault.session_card_picked', 'vault.payment_permission.updated', 'action.confirmed', 'action.done', 'checkout_authorization.approved', 'checkout_authorization.submitted', 'checkout_authorization.declined', 'checkout_authorization.cancelled', 'checkout_authorization.expired', 'checkout_authorization.duplicate_charge', 'checkout_authorization.refused', 'checkout_authorization.watched', 'checkout_authorization.amount_mismatch', 'checkout_authorization.settled', 'checkout_authorization.settlement_unconfirmed', 'checkout_authorization.outcome_reported', 'card_flow.started', 'card_flow.failed', 'transfer.approved', 'transfer.initiated', 'transfer.completed', 'transfer.failed', 'transfer.released', 'wallet.funded', 'user_wallet.funding_detected', 'user_wallet.funded', 'wallet.balance.low', 'recovery.requested', 'recovery.completed', 'recovery.rejected', 'wallet.withdrawal.initiated', 'wallet.withdrawal.completed', 'wallet.withdrawal.failed', 'identity.verification.updated', 'approval.requested', 'reward.earned', 'reward.reversed', 'wallet_link.opened'];
+export declare const AGENTCARD_EVENT_TYPES: readonly ['card.created', 'card.updated', 'card.closed', 'cardholder.created', 'cardholder.updated', 'transaction.authorized', 'transaction.declined', 'transaction.cleared', 'transaction.voided', 'balance.low', 'cardholder_onboarding_session.completed', 'platform_connect_session.completed', 'merchant.connected', 'order.placed', 'order.confirmed', 'order.failed', 'order.updated', 'purchase.message', 'connection.created', 'connected_card.updated', 'vault.card_stored', 'vault.session_linked', 'vault.session_card_picked', 'vault.payment_permission.updated', 'action.confirmed', 'action.done', 'checkout_authorization.approved', 'checkout_authorization.submitted', 'checkout_authorization.declined', 'checkout_authorization.cancelled', 'checkout_authorization.expired', 'checkout_authorization.duplicate_charge', 'checkout_authorization.refused', 'checkout_authorization.watched', 'checkout_authorization.amount_mismatch', 'checkout_authorization.settled', 'checkout_authorization.settlement_unconfirmed', 'checkout_authorization.outcome_reported', 'card_flow.started', 'card_flow.failed', 'transfer.approved', 'transfer.initiated', 'transfer.completed', 'transfer.failed', 'transfer.released', 'wallet.funded', 'user_wallet.funding_detected', 'user_wallet.funded', 'wallet.balance.low', 'recovery.requested', 'recovery.completed', 'recovery.rejected', 'wallet.withdrawal.initiated', 'wallet.withdrawal.completed', 'wallet.withdrawal.failed', 'identity.verification.updated', 'approval.requested', 'reward.earned', 'reward.reversed', 'wallet_link.opened', 'plan.updated', 'plan.item.updated'];
 /** One event type Agentcard sends. A type Agentcard adds later still reads as its own name. */
 export type AgentcardEventType = (typeof AGENTCARD_EVENT_TYPES)[number];
 /** Whether a filter entry names something Agentcard sends: an event type, a family such as `order.*`, or `*`. */

package/dist/events.js

@@ -64,6 +64,8 @@ export const AGENTCARD_EVENT_TYPES = [
     'reward.earned',
     'reward.reversed',
     'wallet_link.opened',
+    'plan.updated',
+    'plan.item.updated',
 ];
 const KNOWN = new Set(AGENTCARD_EVENT_TYPES);
 const FAMILIES = new Set(AGENTCARD_EVENT_TYPES.map((t) => `${t.split('.')[0]}.*`));

package/dist/index.d.ts

@@ -4,13 +4,13 @@ export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type
 export { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderStep, type OrderPathStep, type OrderStepState, type ArrivalTextOptions, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
 export { searchAt, isMerchantStatusAt, merchantStatusLine, searchStatusLines, type BuySearchStatus, type BuyMerchantStatus, type BuyMerchantSearchStatus, type BuyMerchantStatusUpdate, } from './search-status.js';
-export { 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, STATUS_WORDING, 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 { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyStoreCheckUpdate, type BuyFoundUpdate, type BuyTurnStatus, STATUS_WORDING, type BuySegmentUpdate, type BuyRecheck, type BuyFreshness, type BuyFreshnessState, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyCartDiscount, type BuyCartHold, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyFlightParty, type BuyPaymentSource, type BuyConversation, type BuyLatestReply, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyCodeRequest, type BuyChoiceGroup, type BuyChoiceDelivery, type BuyChoiceOption, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
 export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolAvailability, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
 export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION, type AckForOptions } from './ack.js';
 export { directCall, isProductAsk, type DirectCall, type DirectContext, type DirectReason } from './direct.js';
-export { forModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolGrandTotal, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
+export { forModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, type BuyToolModelView, type BuyToolModelCart, type BuyToolGrandTotal, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
 export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice, type ReplyAsWrittenOptions } from './texting.js';
 export { appInstructions, APP_INSTRUCTIONS_VERSION, type AppInstructionsOptions } from './app-instructions.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';
@@ -21,4 +21,6 @@ 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 { tripOf, type BuyTrip, type TripLane, type TripLaneName, type TripLaneResult, type TripLaneStatus } from './trip.js';
 export { fulfilledByLine, fulfilledByOf, type BuyFulfilledBy, type BuyFulfilledByKind } from './fulfilled-by.js';
+export { cardSizeOf, type BuyCardSize } from './card-size.js';

package/dist/index.js

@@ -10,7 +10,7 @@ export { toMessages, messageStream, typingDelay, } from './messages.js';
 export { buyTool, nextStepPrompt, productAction, } from './buy-tool.js';
 export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION } from './ack.js';
 export { directCall, isProductAsk } from './direct.js';
-export { forModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, } from './model-view.js';
+export { forModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, } from './model-view.js';
 export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice } from './texting.js';
 export { appInstructions, APP_INSTRUCTIONS_VERSION } from './app-instructions.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
@@ -20,4 +20,6 @@ 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 { tripOf } from './trip.js';
 export { fulfilledByLine, fulfilledByOf } from './fulfilled-by.js';
+export { cardSizeOf } from './card-size.js';

package/dist/model-view.d.ts

@@ -7,7 +7,7 @@
  * `product_links_sent` for the products' store pages, and `link_sent` on each
  * store and `store_links_sent` for the pages of the stores to pick from.
  */
-import type { BuyCart, BuyNextAction } from './client.js';
+import type { BuyCart, BuyFlightParty, BuyNextAction } from './client.js';
 import type { BuyToolProduct, BuyToolResult, BuyToolStatus, BuyToolStore } from './buy-tool.js';
 export interface BuyToolModelCart {
     store: string;
@@ -208,7 +208,15 @@ export declare function productPrice(product: {
     priceCents: number | null;
     currency: string | null;
     priceFrom?: true;
+    flight?: {
+        party?: BuyFlightParty;
+    };
 }): string | null;
+/**
+ * Who a party's flight price covers, as every app shows it after the price: `for 2`, or `for 2 adults and 1 child` when
+ * children fly. `$1,610 for 2` is the price of both seats together.
+ */
+export declare function flightPartyWords(party: BuyFlightParty): string;
 export declare function money(minor: number | null | undefined, currency: string | null | undefined): string | null;
 /**
  * The products the model reads: the first twenty that keep a name and a store

package/dist/model-view.js

@@ -110,8 +110,19 @@ function currencyFormat(currency) {
  */
 export function productPrice(product) {
     const price = money(product.priceCents, product.currency);
+    if (price !== null && product.flight?.party)
+        return `${price} ${flightPartyWords(product.flight.party)}`;
     return price !== null && product.priceFrom ? `from ${price}` : price;
 }
+/**
+ * Who a party's flight price covers, as every app shows it after the price: `for 2`, or `for 2 adults and 1 child` when
+ * children fly. `$1,610 for 2` is the price of both seats together.
+ */
+export function flightPartyWords(party) {
+    if (party.children === 0)
+        return `for ${party.adults}`;
+    return `for ${party.adults} adult${party.adults === 1 ? '' : 's'} and ${party.children} ${party.children === 1 ? 'child' : 'children'}`;
+}
 export function money(minor, currency) {
     if (typeof minor !== 'number' || !Number.isFinite(minor))
         return null;

package/dist/trip.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A trip Agentcard is planning, as a conversation read carries it (`BuyConversation.trip`): the place, the dates and the
+ * party, and each search Agentcard runs for it in the background, flights first. An app shows each lane as its results
+ * arrive and shows `checking` beside a lane until `done`; it never presents a lane's results as the full list before then.
+ * `fulfilled_by` on a result names who the shopper books with ("Korean Air", "Marriott"), when Agentcard knows it.
+ */
+export type TripLaneName = 'flights' | 'hotels' | 'car' | 'activities' | 'payment';
+export type TripLaneStatus = 'waiting' | 'queued' | 'searching' | 'confirmed' | 'no_results' | 'failed' | 'timed_out' | 'cancelled';
+export interface TripLaneResult {
+    product_id: string;
+    title: string;
+    price_cents: number | null;
+    currency: string | null;
+    fulfilled_by: {
+        name: string;
+        kind: string;
+    } | null;
+}
+export interface TripLane {
+    lane: TripLaneName;
+    status: TripLaneStatus;
+    /** False while the lane waits, queues or searches. */
+    done: boolean;
+    /** The quiet line to show beside the lane until it is done ("still checking hotels…"); null once it is. */
+    checking: string | null;
+    /** Why the lane waits or how it ended, in a word ("needs_origin"), or null. */
+    why: string | null;
+    results: number;
+    /** The lane's results, ordered by what the shopper said matters, at most 8. */
+    items: TripLaneResult[];
+    /** The lane's last answer to a stated preference: re-ranked, searched again narrowly, or both, and why. */
+    decision: {
+        action: 'rerank' | 'narrow' | 'both';
+        why: string[];
+    } | null;
+    /** Hotels: false when the picked flight lands on another day than these hotels were searched for. */
+    fits_flight?: boolean | null;
+    /** The card check: true when the shopper's card pays without stopping at checkout. */
+    ready?: boolean;
+}
+export interface BuyTrip {
+    place: string | null;
+    check_in: string | null;
+    check_out: string | null;
+    travelers: number | null;
+    origin: string | null;
+    lanes: TripLane[];
+}
+/** The trip a conversation read carries, or null when it plans none or the API is older. */
+export declare function tripOf(value: unknown): BuyTrip | null;

package/dist/trip.js

@@ -0,0 +1,31 @@
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const LANES = ['flights', 'hotels', 'car', 'activities', 'payment'];
+const STATUSES = ['waiting', 'queued', 'searching', 'confirmed', 'no_results', 'failed', 'timed_out', 'cancelled'];
+const ACTIONS = ['rerank', 'narrow', 'both'];
+const oneOf = (allowed, v) => (typeof v === 'string' && allowed.includes(v) ? v : null);
+/** The trip a conversation read carries, or null when it plans none or the API is older. */
+export function tripOf(value) {
+    if (!isRecord(value) || !Array.isArray(value.lanes))
+        return null;
+    return {
+        place: str(value.place), check_in: str(value.check_in), check_out: str(value.check_out), travelers: num(value.travelers), origin: str(value.origin),
+        // A lane this SDK does not know (a newer API's) is left out, and a status it does not know reads as still searching.
+        lanes: value.lanes.filter(isRecord).filter((l) => oneOf(LANES, l.lane) !== null).map((l) => ({
+            lane: oneOf(LANES, l.lane),
+            status: oneOf(STATUSES, l.status) ?? 'searching',
+            done: l.done === true,
+            checking: l.done === true ? null : str(l.checking),
+            why: str(l.why),
+            results: num(l.results) ?? 0,
+            items: Array.isArray(l.items) ? l.items.filter(isRecord).map((i) => ({
+                product_id: str(i.product_id) ?? '', title: str(i.title) ?? '', price_cents: num(i.price_cents), currency: str(i.currency),
+                fulfilled_by: isRecord(i.fulfilled_by) && str(i.fulfilled_by.name) ? { name: str(i.fulfilled_by.name), kind: str(i.fulfilled_by.kind) ?? 'seller' } : null,
+            })) : [],
+            decision: isRecord(l.decision) && oneOf(ACTIONS, l.decision.action) ? { action: oneOf(ACTIONS, l.decision.action), why: Array.isArray(l.decision.why) ? l.decision.why.filter((w) => typeof w === 'string') : [] } : null,
+            ...('fits_flight' in l ? { fits_flight: typeof l.fits_flight === 'boolean' ? l.fits_flight : null } : {}),
+            ...('ready' in l ? { ready: l.ready === true } : {}),
+        })),
+    };
+}

package/package.json

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