@agent-cards/commerce-sdk 0.18.7 → 0.18.9

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.80";
+export declare const VOICE_VERSION = "0.2.82";
 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.80";
+export const VOICE_VERSION = "0.2.82";
 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,6 +31,7 @@
  * 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 { BuyFulfilledBy } from './fulfilled-by.js';
@@ -97,6 +98,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.
@@ -186,6 +189,8 @@ export interface BuyToolProduct {
     availability?: BuyAvailability;
     /** 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 {

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 } : {}), ...(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.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}$/;
@@ -279,6 +279,7 @@ function productsOfCatalog(catalog) {
         linkSent: false,
         ...(item.availability ? { availability: item.availability } : {}),
         ...(item.fulfilled_by ? { fulfilledBy: item.fulfilled_by } : {}),
+        ...(item.shopper_size ? { shopperSize: item.shopper_size } : {}),
     }));
 }
 /** The stores an answer presents, as the tool reads them. */

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

@@ -11,6 +11,7 @@
 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. */
@@ -109,6 +110,11 @@ export interface BuyTurnStatus {
     step: string;
     text: string;
 }
+/**
+ * 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.
+ */
+export declare const STATUS_WORDING: Readonly<Record<string, string>>;
 /** One message Agentcard finished writing while the turn runs, links included, as the answer's `messages` then holds it. */
 export interface BuySegmentUpdate {
     conversationId: string | null;
@@ -424,6 +430,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;
@@ -449,6 +467,8 @@ export interface BuyCatalogItem {
     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 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

package/dist/client.js

@@ -12,8 +12,16 @@ 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';
+/**
+ * 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.
+ */
+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 PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
@@ -233,8 +241,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;
@@ -259,6 +277,7 @@ function catalogItemsOf(v) {
             url: pageUrl(i.url),
             ...availabilityField(i),
             ...fulfilledByField(i),
+            ...cardSizeField(i),
         };
     }) : [];
 }
@@ -554,7 +573,7 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             }
             else if (event === 'status' && typeof data.text === 'string' && data.text.trim() !== '' && typeof data.step === 'string' && stream.onStatus) {
                 try {
-                    stream.onStatus({ conversationId: named, step: data.step, text: data.text });
+                    stream.onStatus({ conversationId: named, step: data.step, text: Object.hasOwn(STATUS_WORDING, data.step) ? STATUS_WORDING[data.step] : data.text });
                 }
                 catch {
                     // The app's display failing never fails the turn.

package/dist/index.d.ts

@@ -3,14 +3,14 @@ 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 { 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 { 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 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';
@@ -22,3 +22,4 @@ export { TURN_RECOVERY_ON, isTurnId, type TurnEvent, type TurnRecord, type TurnR
 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';
+export { cardSizeOf, type BuyCardSize } from './card-size.js';

package/dist/index.js

@@ -3,14 +3,14 @@ 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 { searchAt, isMerchantStatusAt, merchantStatusLine, searchStatusLines, } from './search-status.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, STATUS_WORDING, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, typingDelay, } from './messages.js';
 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';
@@ -21,3 +21,4 @@ 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';
+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/search-status.d.ts

@@ -12,8 +12,10 @@
  * - `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.
+ * - `unavailable`: Agentcard could not reach the store this turn. Show it only for a store the shopper named, with
+ *   `merchantStatusLine`, and leave a store they did not name out.
  */
-export type BuyMerchantSearchStatus = 'searching' | 'confirmed' | 'recently_confirmed' | 'no_results' | 'timed_out' | 'confirmation_unavailable' | 'failed';
+export type BuyMerchantSearchStatus = 'searching' | 'confirmed' | 'recently_confirmed' | 'no_results' | 'timed_out' | 'confirmation_unavailable' | 'failed' | 'unavailable';
 /** 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`. */
@@ -70,3 +72,11 @@ export declare function merchantStatusOf(data: Record<string, unknown>): BuyMerc
 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;
+/**
+ * The line to show the shopper for one store's status, or null for none. A store the shopper named (`named`, by its domain, id
+ * or name) that reads `unavailable` reads `still loading Walmart`; every other store and status reads nothing, so a store
+ * the shopper did not name drops out quietly while other stores fill the answer.
+ */
+export declare function merchantStatusLine(store: BuyMerchantStatus | BuyMerchantStatusUpdate, named: string | readonly string[]): string | null;
+/** Every line `merchantStatusLine` gives for the turn's stores, in the order their searches started; none when `search` is null. */
+export declare function searchStatusLines(search: BuySearchStatus | null, named: string | readonly string[]): string[];

package/dist/search-status.js

@@ -2,7 +2,7 @@
  * 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 MERCHANT_STATUSES = new Set(['searching', 'confirmed', 'recently_confirmed', 'no_results', 'timed_out', 'confirmation_unavailable', 'failed', 'unavailable']);
 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);
@@ -76,3 +76,23 @@ export function isMerchantStatusAt(update, store) {
     const want = storeKey(store);
     return storeKey(update.merchant) === want || storeKey(update.merchantName) === want;
 }
+/** Whether a store, as a line or an update carries it, is one of the stores you name, as `searchAt` matches them. */
+function isNamed(store, named) {
+    const name = 'merchant_name' in store ? store.merchant_name : store.merchantName;
+    const keys = new Set([storeKey(store.merchant), storeKey(name)]);
+    return (typeof named === 'string' ? [named] : named).some((n) => keys.has(storeKey(n)));
+}
+/**
+ * The line to show the shopper for one store's status, or null for none. A store the shopper named (`named`, by its domain, id
+ * or name) that reads `unavailable` reads `still loading Walmart`; every other store and status reads nothing, so a store
+ * the shopper did not name drops out quietly while other stores fill the answer.
+ */
+export function merchantStatusLine(store, named) {
+    if (store.status !== 'unavailable' || !isNamed(store, named))
+        return null;
+    return `still loading ${'merchant_name' in store ? store.merchant_name : store.merchantName}`;
+}
+/** Every line `merchantStatusLine` gives for the turn's stores, in the order their searches started; none when `search` is null. */
+export function searchStatusLines(search, named) {
+    return (search?.merchants ?? []).flatMap((m) => merchantStatusLine(m, named) ?? []);
+}

package/package.json

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