@agent-cards/commerce-sdk 0.18.7 → 0.18.8

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.81";
 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.81";
 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/client.d.ts

@@ -109,6 +109,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;

package/dist/client.js

@@ -14,6 +14,13 @@ import { isRecord } from './verify.js';
 import { failedPartyOf, fulfilledByField } from './fulfilled-by.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']);
@@ -554,7 +561,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,8 +3,8 @@ export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, ty
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
 export { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderStep, type OrderPathStep, type OrderStepState, type ArrivalTextOptions, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { 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 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';

package/dist/index.js

@@ -3,8 +3,8 @@ 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';

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.8",
   "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",