@agent-cards/commerce-sdk 0.18.8 → 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.81";
+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.81";
+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. */
@@ -429,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;
@@ -454,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,6 +12,7 @@ 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';
 /**
@@ -240,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;
@@ -266,6 +277,7 @@ function catalogItemsOf(v) {
             url: pageUrl(i.url),
             ...availabilityField(i),
             ...fulfilledByField(i),
+            ...cardSizeField(i),
         };
     }) : [];
 }

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 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

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

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