@agent-cards/commerce-sdk 0.18.5 → 0.18.7

package/dist/client.js

@@ -8,11 +8,14 @@
  * @agent-cards/sdk (packages/checkout/src/buy.ts: turnOf, buyError), and the
  * token cache follows its client (packages/checkout/src/client.ts accessToken).
  */
+import { planOf } from './plan.js';
+import { merchantStatusOf, searchOf } from './search-status.js';
 import { isRecord } from './verify.js';
+import { failedPartyOf, fulfilledByField } from './fulfilled-by.js';
 import { listenToAgentcard } from './listen.js';
 import { messageInChat } from './shopper-message.js';
 /** The handlers that ask Agentcard to stream a turn. */
-const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability', 'onReplyWritten'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability', 'onReplyWritten', 'onMerchantStatus'];
 const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -58,6 +61,15 @@ const TRACEPARENT = /^[\da-f]{2}-[\da-f]{32}-[\da-f]{16}-[\da-f]{2}$/;
 // A tracestate is printable ASCII of at most 512 characters (W3C); any other value is left off, so it can never stop a purchase.
 const TRACESTATE = /^[\x20-\x7e]{1,512}$/;
 const pickTrace = (c) => typeof c.tracestate === 'string' && TRACESTATE.test(c.tracestate) ? { traceparent: c.traceparent, tracestate: c.tracestate } : { traceparent: c.traceparent };
+/** An answer's code request, from its `browser_checkout` when that checkout waits on a wallet's code; null otherwise. */
+export function codeRequestOf(value) {
+    if (!isRecord(value) || value.status !== 'needs_code' || !str(value.store) || !isRecord(value.code))
+        return null;
+    const { wallet, channel, destination } = value.code;
+    if ((wallet !== 'link' && wallet !== 'shop_pay') || (channel !== 'text' && channel !== 'email'))
+        return null;
+    return { store: value.store, wallet, channel, destination: str(destination) };
+}
 const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'store_login', 'add_card', 'confirm', 'verification_code', 'approve']);
 /**
  * A refusal, or a failure to reach Agentcard. `code` is the API's own
@@ -145,6 +157,23 @@ function feeLinesOf(v) {
     const lines = v.filter(isRecord).flatMap((f) => (str(f.label) && num(f.amountCents) !== null ? [{ label: f.label, amountCents: f.amountCents }] : []));
     return lines.length ? lines : null;
 }
+const HOLD_REASONS = new Set(['flight', 'hotel', 'checkout_estimate']);
+function holdOf(v) {
+    if (!isRecord(v) || typeof v.reason !== 'string' || !HOLD_REASONS.has(v.reason))
+        return null;
+    const amount = num(v.amountCents);
+    return amount !== null && amount > 0 ? { amountCents: amount, reason: v.reason } : null;
+}
+function discountsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter(isRecord).flatMap((d) => {
+        const amount = num(d.amountCents);
+        if (!str(d.label) || amount === null || !(amount < 0))
+            return [];
+        return [d.kind === 'coupon' ? { label: d.label, amountCents: amount, kind: 'coupon', code: str(d.code) } : { label: d.label, amountCents: amount, kind: 'discount', code: null }];
+    });
+}
 function feesOf(v) {
     const amount = num(v.serviceFeesCents);
     const status = v.merchantFeesPending === true || v.serviceFeesStatus === 'pending' ? 'pending'
@@ -173,16 +202,20 @@ function cartOf(v) {
                 product_id: str(i.product_id),
                 ref: str(i.ref),
                 url: pageUrl(i.url),
+                ...fulfilledByField(i),
             };
         }) : [],
         subtotalCents: num(v.subtotalCents),
         ...feesOf(v),
         merchantFeeLines: feeLinesOf(v.merchantFeeLines),
+        discounts: discountsOf(v.discounts),
+        pricing: v.pricing === true,
         tipCents: num(v.tipCents) ?? 0,
         totalCents: num(v.totalCents) ?? 0,
         totalIsEstimate: v.totalIsEstimate === true,
         currency: str(v.currency),
         approvedCeilingCents: num(v.approvedCeilingCents),
+        hold: holdOf(v.hold),
         hash: v.hash,
     };
 }
@@ -225,6 +258,7 @@ function catalogItemsOf(v) {
             store: storeOf(i.store),
             url: pageUrl(i.url),
             ...availabilityField(i),
+            ...fulfilledByField(i),
         };
     }) : [];
 }
@@ -285,6 +319,7 @@ export function turnOf(body) {
         approval_url: str(body.approval_url),
         charge_status: str(body.charge_status),
         error_code: str(body.error_code),
+        fulfilled_by: failedPartyOf(body.placements),
         authorization_id: str(body.authorization_id),
         merchant_total_cents: num(body.merchant_total_cents),
         merchant_currency: str(body.merchant_currency),
@@ -297,11 +332,14 @@ export function turnOf(body) {
         store_login_expires_at: str(body.store_login_expires_at),
         store_login_merchant_name: str(body.store_login_merchant_name),
         next_action: typeof body.next_action === 'string' && NEXT_ACTIONS.has(body.next_action) ? body.next_action : null,
+        code_request: codeRequestOf(body.browser_checkout),
         pick: isRecord(body.pick) && str(body.pick.product_id) ? { product_id: body.pick.product_id, ref: str(body.pick.ref), in_cart: body.pick.in_cart === true } : null,
         stores: storesOf(body.stores),
         store_pick: isRecord(body.store_pick) && str(body.store_pick.store_id) ? { store_id: body.store_pick.store_id, name: str(body.store_pick.name), selected: body.store_pick.selected === true } : null,
         cart_building: cartBuildingOf(body.cart_building),
         choice: choiceOf(body.choice),
+        plan: planOf(body.plan),
+        search: searchOf(body.search),
         raw: body,
     };
 }
@@ -358,9 +396,23 @@ function conversationOf(body) {
             placed_at: str(o.placed_at),
         })) : [],
         carts: cartsOf(body.carts),
+        latest_reply: latestReplyOf(body.latest_reply),
         raw: body,
     };
 }
+/** The reply a conversation read hands back, or null when it names no text. */
+function latestReplyOf(value) {
+    if (!isRecord(value) || !str(value.text)?.trim())
+        return null;
+    const messages = Array.isArray(value.messages) ? value.messages.filter((m) => typeof m === 'string' && m.trim() !== '') : [];
+    return {
+        message_id: str(value.message_id) ?? '',
+        text: value.text,
+        messages: messages.length > 0 ? messages : [value.text],
+        catalog: catalogOf(value.catalog),
+        created_at: str(value.created_at),
+    };
+}
 /** An error code as the API spells one: lower-case words joined by underscores. */
 const CODE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
 /**
@@ -464,7 +516,7 @@ async function eachEvent(res, onEvent) {
 }
 /**
  * A streamed purchase turn, read to its `envelope`: the same answer a JSON turn returns, with its
- * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment`, `reply_written`, `cart` and `venue_availability` goes to its handler
+ * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment`, `reply_written`, `cart`, `venue_availability` and `merchant` goes to its handler
  * on the way, and any other event, such as a `ping` or a `tool`, is read past. A stream that breaks or
  * ends before its envelope, once it named the conversation, reads as a turn past its budget
  * (`turn_timeout`), so the tool reads the conversation for what the turn left instead of losing it.
@@ -558,6 +610,11 @@ async function readStreamedTurn(res, stream, timeoutMs) {
                 if (items.length)
                     deliver(() => stream.onAvailability({ conversationId: data.conversation_id, items }));
             }
+            else if (event === 'merchant' && stream.onMerchantStatus) {
+                const update = merchantStatusOf(data);
+                if (update)
+                    deliver(() => stream.onMerchantStatus(update));
+            }
             else if (event === 'cart' && stream.onCart && str(data.conversation_id)) {
                 const update = { conversationId: data.conversation_id, cart: cartOf(data.cart), carts: cartsOf(data.carts) };
                 deliver(() => stream.onCart(update));

package/dist/definition.js

@@ -52,7 +52,8 @@ export const BUY_TOOL_RULES = [
     'Name each link by what it is for, from `next_action`: the link to add a card, to sign in to the store, or to approve the payment.',
     'Within a step, ask for one detail per message, such as the delivery address before the name for the label.',
     '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 and Best Buy, so name those, and no other store unless a result showed it.",
+    "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.',
     '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.',

package/dist/direct.d.ts

@@ -36,6 +36,14 @@ export interface DirectContext {
         productId: string | null;
         name: string;
     }>;
+    /**
+     * Every product card an earlier answer of this conversation showed, each once, newest first. A card's tap whose name no card
+     * of `tappable` holds is read against these, so a tap on a card two answers back still sends its `product_id`.
+     */
+    shownBefore?: ReadonlyArray<{
+        productId: string | null;
+        name: string;
+    }>;
     /** The stores Agentcard's last answer showed, with the `store_id` a pick sends. */
     stores?: ReadonlyArray<{
         storeId: string;

package/dist/direct.js

@@ -185,14 +185,25 @@ function pickOf(raw, bare, context) {
         if (named.length > 1)
             return call({});
     }
+    // A tap on a card an earlier answer showed, after an answer that showed no cards: it is read against every card shown before.
+    const tapNow = byName.length === 0 ? tappedName(raw) : null;
+    if (tapNow !== null) {
+        const before = (context.shownBefore ?? []).filter((product) => product.productId && [nameWords(tapNow), nameWords(`the ${tapNow}`)].includes(nameWords(product.name)));
+        if (before.length > 0)
+            return call(new Set(before.map((product) => product.productId)).size === 1 ? { product_id: before[0].productId } : {});
+    }
     if (byName.length > 0) {
         // A card's tap names the product whole, `I'll take the Burrito Bowl ($15.15)`: the product of exactly that name is the pick,
         // never the Burrito whose one word it shares, and a tap that names no product here (a card this list does not hold), or two
         // alike, sends none, so Agentcard reads the words against every card it showed.
         const tap = tappedName(raw);
         if (tap !== null) {
-            const exact = byName.filter((product) => [nameWords(tap), nameWords(`the ${tap}`)].includes(nameWords(product.name)));
-            return call(exact.length === 1 ? { product_id: exact[0].productId } : {});
+            const named = (cards) => cards.filter((product) => [nameWords(tap), nameWords(`the ${tap}`)].includes(nameWords(product.name)));
+            const exact = named(byName);
+            // A tap on a card an earlier answer showed names a card of no newer list: it is read against every card shown before.
+            const before = exact.length === 0 ? named(context.shownBefore ?? []).filter((product) => product.productId) : [];
+            const card = exact.length === 1 ? exact[0] : exact.length === 0 && new Set(before.map((product) => product.productId)).size === 1 ? before[0] : null;
+            return call(card ? { product_id: card.productId } : {});
         }
         // A product's whole name inside the message: `I want the KODAK AA Alkaline Batteries (24 Pack)`.
         const said = nameWords(raw);

package/dist/fulfilled-by.d.ts

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

package/dist/fulfilled-by.js

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

package/dist/index.d.ts

@@ -3,17 +3,22 @@ export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, ty
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
 export { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderStep, type OrderPathStep, type OrderStepState, type ArrivalTextOptions, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyChoiceGroup, type BuyChoiceDelivery, type BuyChoiceOption, } from './client.js';
+export { searchAt, isMerchantStatusAt, type BuySearchStatus, type BuyMerchantStatus, type BuyMerchantSearchStatus, type BuyMerchantStatusUpdate, } from './search-status.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyCartDiscount, type BuyCartHold, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLatestReply, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyCodeRequest, type BuyChoiceGroup, type BuyChoiceDelivery, type BuyChoiceOption, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
 export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolAvailability, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
 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, forModelError, stepAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.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 { 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';
 export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, type AgentcardEventType, } from './events.js';
 export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS, type TurnStream, type TurnStreamOptions } from './turn-stream.js';
 export { TURN_RECOVERY_ON, isTurnId, type TurnEvent, type TurnRecord, type TurnRecordStore } from './turn-record.js';
+export type { BuyLateResults, BuyStoreWait } from './store-wait.js';
+export { planOf, type BuyPlan, type BuyPlanItem, type BuyPlanItemState, type BuyPlanStatus } from './plan.js';
+export { fulfilledByLine, fulfilledByOf, type BuyFulfilledBy, type BuyFulfilledByKind } from './fulfilled-by.js';

package/dist/index.js

@@ -3,17 +3,21 @@ export { readPurchaseMessage, } from './message.js';
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, } from './shopper-message.js';
 export { ORDER_STEPS, updateOrder, arrivalText, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, } from './handler.js';
+export { searchAt, isMerchantStatusAt, } from './search-status.js';
 export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, typingDelay, } from './messages.js';
 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, forModelError, stepAsWritten, withoutCardList, stripLinks, } from './model-view.js';
+export { forModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, } 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';
 export { listenToAgentcard, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, } from './events.js';
 export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS } from './turn-stream.js';
 export { TURN_RECOVERY_ON, isTurnId } from './turn-record.js';
+export { planOf } from './plan.js';
+export { fulfilledByLine, fulfilledByOf } from './fulfilled-by.js';

package/dist/message.d.ts

@@ -10,6 +10,7 @@ import { type AgentcardEvent } from './verify.js';
  * - `order_failed`: the order failed after the approval, and nothing more happens for that approval.
  * - `order_not_placed_yet`: the shopper approved, and the order is not placed yet.
  * - `order_unconfirmed`: the store's reply to the order was lost, so the order may exist; Agentcard is confirming it.
+ * - `order_placing`: the shopper approved, and Agentcard is placing the order now; one of the order kinds above follows.
  * - `approval_expiring`: the approval link expires soon; `text` carries the link.
  * - `approval_expired`: the approval expired before the shopper answered, and nothing was charged.
  * - `approval_declined`: the shopper declined the approval, and nothing was charged.
@@ -25,7 +26,7 @@ import { type AgentcardEvent } from './verify.js';
  * - `cart_needs_input`: that checkout asks the shopper something first, such as a size, a delivery address, a sign-in to the store or an approval of the most the order can cost.
  * - `cart_failed`: that checkout built no cart, and nothing was ordered or charged.
  */
-export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'approval_expiring' | 'approval_expired' | 'approval_declined' | 'payment_declined' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle' | 'card_added' | 'store_connected' | 'store_connect_failed' | 'store_connect_expired' | 'cart_ready' | 'cart_needs_input' | 'cart_failed';
+export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'order_placing' | 'approval_expiring' | 'approval_expired' | 'approval_declined' | 'payment_declined' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle' | 'card_added' | 'store_connected' | 'store_connect_failed' | 'store_connect_expired' | 'cart_ready' | 'cart_needs_input' | 'cart_failed';
 /** The message's values one by one, for a company that writes its own copy. A fact that does not apply is absent. */
 export interface PurchaseFacts {
     merchantName?: string;

package/dist/model-view.d.ts

@@ -7,14 +7,15 @@
  * `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 { BuyNextAction } from './client.js';
+import type { BuyCart, BuyNextAction } from './client.js';
 import type { BuyToolProduct, BuyToolResult, BuyToolStatus, BuyToolStore } from './buy-tool.js';
 export interface BuyToolModelCart {
     store: string;
     /**
      * `price` is one unit's; `line_total` is what the line costs with its add-ons and quantity, and the
      * lines' totals add up before `fees`. `options` are the choices made on the line and `variant` the
-     * variant it is. `product_id` is the id the line's product carries in `products`, or null.
+     * variant it is. `product_id` is the id the line's product carries in `products`, or null. `fulfilled_by` is who
+     * sells or books the line where that is not the store, such as `via StubHub`; absent when Agentcard named none.
      */
     items: Array<{
         product_id: string | null;
@@ -24,6 +25,7 @@ export interface BuyToolModelCart {
         line_total: string | null;
         options: string[];
         variant: string | null;
+        fulfilled_by?: string;
     }>;
     fees: string | null;
     fees_status?: 'known' | 'pending' | 'unknown';
@@ -32,6 +34,19 @@ export interface BuyToolModelCart {
         label: string;
         amount: string;
     }>;
+    /**
+     * The discounts and coupons inside `total`, each negative, which `fee_lines` also lists: show them as money taken off,
+     * never add them to `total` again. `code` names a coupon's code. Absent when the cart has none.
+     */
+    discounts?: Array<{
+        label: string;
+        amount: string;
+        amount_cents: number;
+        kind: 'discount' | 'coupon';
+        code: string | null;
+    }>;
+    /** True while the store's checkout prices this cart, several stores at once included, so `total` is not its price yet; absent once it is priced. */
+    pricing?: true;
     tip: string | null;
     total: string;
     /** True when the store has not priced its fees and tax yet: `total` is an estimate, never the final amount. */
@@ -40,6 +55,16 @@ export interface BuyToolModelCart {
     total_leaves_out: string | null;
     /** The most the shopper's card can be held for this cart: above `total` at a store that prices its final at checkout, `total` itself for a flight, which holds exactly that; else null. */
     max_charge: string | null;
+    /**
+     * Why the card is held for `max_charge`: `flight` or `hotel` for a booking's hold on the card, which the shopper sees
+     * on their statement, and `checkout_estimate` for the headroom over a store's total, released unused. Show a hold line
+     * for `flight` and `hotel` alone. Absent when nothing is held.
+     */
+    hold?: {
+        amount: string;
+        amount_cents: number;
+        reason: 'flight' | 'hotel' | 'checkout_estimate';
+    };
 }
 export interface BuyToolModelProduct {
     /** What the model passes as `product_id` when the shopper picks this product: Agentcard's ref, never a link. Null when there is none. */
@@ -60,6 +85,22 @@ export interface BuyToolModelStore {
     /** True when the shopper holds this store's page, which `sendLink` delivered beside the reply. */
     link_sent: boolean;
 }
+/**
+ * What every store cart on the table adds up to, in one currency: the stores' totals summed in minor units, each store's
+ * tip, fees and tax counted once as its `total` counts them. `is_estimate` is true when any store's total is an estimate,
+ * and `leaves_out` names what the estimated totals leave out together; null when every store priced its cart.
+ */
+export interface BuyToolGrandTotal {
+    amount: string;
+    /** The sum in the currency's minor unit, such as cents. */
+    amount_cents: number;
+    /** The ISO 4217 code, upper case, or null when Agentcard named none for these carts. */
+    currency: string | null;
+    is_estimate: boolean;
+    leaves_out: string | null;
+    /** How many store carts this total adds up. */
+    stores: number;
+}
 /** The buy tool's answer as the model reads it. */
 export interface BuyToolModelView {
     status: BuyToolStatus;
@@ -78,6 +119,8 @@ export interface BuyToolModelView {
     cart: BuyToolModelCart | null;
     /** Every cart on the table, the newest last, when the shopper is buying from more than one store. */
     carts: BuyToolModelCart[];
+    /** What the carts add up to, one entry per currency, in the order the carts first name it; empty when no cart is on the table. */
+    grand_totals: BuyToolGrandTotal[];
     products: BuyToolModelProduct[];
     approval_expires_at: string | null;
     /**
@@ -197,6 +240,11 @@ export declare function cardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'ur
  * and a place's card is where the shopper reads whether it has room.
  */
 export declare function productCardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'url' | 'flight' | 'availability'>): string | null;
+/**
+ * The carts' grand totals, one per currency, summed from each cart's `totalCents`, which already holds its tip, fees and
+ * tax: a display string is never parsed. Carts in two currencies are never added together.
+ */
+export declare function grandTotals(carts: readonly BuyCart[]): BuyToolGrandTotal[];
 /** How long until `iso`, from `now`, as the shopper reads it: `about 24 hours`, `about 15 minutes`, `no longer`, or null. */
 export declare function expiresIn(iso: string | null | undefined, now?: number): string | null;
 /**
@@ -243,9 +291,11 @@ export interface ShownCard {
  * points at a number the list gave (`the dishwand in #8`), a sentence that goes on to more of the list (`other 6-packs
  * are ...`, `there's also ...`) and names a card, and, past the one or two products a reply recommends in words, each
  * further sentence that names another card. A list written on one line goes the same way, item by item (inlineList),
- * and so does a list line written without a bullet, whole, up to the question on it. What is left is the reply around
- * the list, such as `found these at amazon.` and `which one do you want?`. A reply whose cards went out names none of
- * them twice over. A list that keeps an item for a product no card shows keeps its lead-in, and the two read as one
+ * and so does a list line written without a bullet, whole, up to the question on it. The lines set in under a list
+ * line that goes, its details such as `  - ships from London`, go with it, and once the list went, a sentence that only
+ * points back at it, `both are priced in foreign currency`, goes when the cards show another number than it counts.
+ * What is left is the reply around the list, such as `found these at amazon.` and `which one do you want?`. A reply
+ * whose cards went out names none of them twice over. A list that keeps an item for a product no card shows keeps its lead-in, and the two read as one
  * message (toMessages), so the shopper never reads `two options came in under $20:` on its own.
  *
  * Each card is its name, or its name and its price as the model reads it (`{ name, price: '$22.89' }`): with the price,