@agent-cards/commerce-sdk 0.11.0 → 0.14.0

package/dist/client.d.ts

@@ -44,20 +44,118 @@ export interface BuyCatalogUpdate {
     catalog: BuyCatalog;
     /** When the search ran, as the answer's `catalog.as_of` names it: the same search in the answer has the same value. */
     asOf: string | null;
+    /** How many of the products found are in `catalog.items`, the cards to show. Null when Agentcard sent no count. */
+    shown: number | null;
+    /** How many distinct products the turn's searches found so far. Null when Agentcard sent no count. */
+    found: number | null;
+    /** The products found past the cards, in the order they were found, to show on "show more" with no new search. */
+    more: BuyCatalog['items'];
 }
-/** Called while a purchase turn runs. Passing either one asks Agentcard to stream the turn. */
+/** How many products a running turn found so far, and how many of them it shows: "8 of 23 shown". */
+export interface BuyFoundUpdate {
+    conversationId: string;
+    shown: number;
+    found: number;
+}
+/**
+ * What a running turn is doing, the moment a step starts: `text` is a short line to show in place of loading dots, such as
+ * `searching Target and Walmart` or `adding it to your cart`, and `step` names the step for an app that writes its own,
+ * such as `searching`, `adding_to_cart` or `store_checkout`. No status comes for a turn that only writes its reply.
+ */
+export interface BuyTurnStatus {
+    conversationId: string | null;
+    step: string;
+    text: 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;
+    text: string;
+}
+/** The carts on the table the moment a running turn builds or changes one, before the message that announces it. */
+export interface BuyCartUpdate {
+    conversationId: string;
+    /** The cart a confirm would place, as the answer's `cart` names it, or null when none would be. */
+    cart: BuyCart | null;
+    /** Every cart on the table, oldest first, as the answer's `carts`. */
+    carts: BuyCart[];
+}
+/**
+ * A piece of a message while Agentcard writes it. A piece can hold words Agentcard drops before the message is done, such
+ * as a line that only says it is looking, so show the pieces as a draft and replace them with each `onSegment` message.
+ */
+export interface BuyDeltaUpdate {
+    conversationId: string | null;
+    text: string;
+}
+/**
+ * Called while a purchase turn runs. Passing any one asks Agentcard to stream the turn. `onCatalog`, `onSegment`,
+ * `onCart` and `onDelta` hear their events one at a time, in the order Agentcard sent them, each once the one before it
+ * settled, so a piece of the next message never reaches the app before the message ahead of it. The client waits for
+ * the last of them before it hands back the turn's answer.
+ */
 export interface BuyStreamHandlers {
     onProgress?: (progress: BuyProgress) => void;
-    /** The client waits for what this returns before it hands back the turn's answer. */
+    /** Each step the turn starts, as a line to show while the shopper waits. */
+    onStatus?: (status: BuyTurnStatus) => void;
+    /** How many products the turn found, each time the count grows. */
+    onFound?: (update: BuyFoundUpdate) => void | Promise<void>;
     onCatalog?: (update: BuyCatalogUpdate) => void | Promise<void>;
+    /** Each message Agentcard writes, the moment it is written. */
+    onSegment?: (update: BuySegmentUpdate) => void | Promise<void>;
+    /** The carts, each time the turn builds or changes one. */
+    onCart?: (update: BuyCartUpdate) => void | Promise<void>;
+    /** Each piece of a message as Agentcard writes it. Passing it asks Agentcard for the pieces (`?stream=deltas`). */
+    onDelta?: (update: BuyDeltaUpdate) => void | Promise<void>;
 }
 export declare const DEFAULT_BASE_URL = "https://api.agentcard.sh";
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
 export declare const BUY_TURN_TIMEOUT_MS = 130000;
+/** The W3C trace context a `POST /buy` carries, so the backend's spans join the caller's trace. */
+export interface TraceContext {
+    traceparent: string;
+    tracestate?: string;
+}
+/** The part of `@opentelemetry/api` the client calls: pass the module itself as `otel`. */
+export interface OtelApi {
+    trace: {
+        getTracer(name: string): OtelTracer;
+    };
+    context: {
+        active(): unknown;
+    };
+    propagation: {
+        inject(context: unknown, carrier: Record<string, string>): void;
+    };
+}
+interface OtelTracer {
+    startActiveSpan<T>(name: string, options: {
+        kind?: number;
+        attributes?: Record<string, string | boolean>;
+    }, fn: (span: OtelSpan) => T): T;
+}
+interface OtelSpan {
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    end(): void;
+}
+/**
+ * How the client finds the trace a `POST /buy` belongs to. `otel` is `@opentelemetry/api`: by default the client
+ * loads it when the app installed it, and `false` turns that off. `traceContext` names the trace by hand, for an app
+ * without OpenTelemetry: return its `traceparent`, or nothing to send none. The active OpenTelemetry context wins.
+ */
+export interface AgentcardTraceOptions {
+    otel?: OtelApi | false;
+    traceContext?: () => TraceContext | string | null | undefined;
+}
 /** A company's client credentials, or one shopper's own access token. */
 export type AgentcardClientOptions = {
     baseUrl?: string;
     fetch?: FetchLike;
+    trace?: AgentcardTraceOptions;
 } & ({
     clientId: string;
     clientSecret: string;
@@ -91,6 +189,8 @@ export interface BuyRequest {
     confirm?: string | true;
     /** Continue the shopper's newest open conversation instead of starting one. */
     resume?: true;
+    /** The conversation a confirm of a cart hash belongs to, in place of `resume`. */
+    conversation_id?: string;
     /** Drop the cart on the table and start a new order. */
     new_order?: true;
     /**
@@ -117,8 +217,23 @@ export interface BuyStore {
 export interface BuyCartLine {
     name: string;
     qty: number;
+    /** One unit's price, as the store lists it. */
     priceCents?: number;
+    /**
+     * What the line costs: its price with every add-on, times its quantity, before the store's own fees.
+     * The lines' totals add up to the cart's `subtotalCents`. Null when its price is unknown.
+     */
+    lineTotalCents: number | null;
+    /** The choices made on the line, by the store's names ("Carnitas", "Extra Guacamole"). Empty when none. */
+    options: string[];
+    /** The variant the line is, by the store's name ("Birthday (Medium)"), or null when the store names none. */
+    variant: string | null;
     product_id: string | null;
+    /**
+     * The id of the product card this line is, as `BuyProduct.ref` names it: a shown product whose `ref`
+     * (else `id`) equals it is in the cart. Null from an older API.
+     */
+    ref: string | null;
     /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
     url: string | null;
 }
@@ -138,7 +253,8 @@ export interface BuyCart {
     items: BuyCartLine[];
     /** The items alone, or null from an older API. */
     subtotalCents: number | null;
-    serviceFeesCents: number;
+    serviceFeesCents: number | null;
+    serviceFeesStatus?: 'known' | 'pending' | 'unknown';
     /** The store's own fee and tax lines inside `serviceFeesCents`, or null when the store itemized none. */
     merchantFeeLines: BuyCartFeeLine[] | null;
     tipCents: number;
@@ -172,9 +288,16 @@ export interface BuyCatalogItem {
     ref: string | null;
     name: string | null;
     priceCents: number | null;
+    /** True when `priceCents` is a "from" price: the lowest price of a product priced by a required choice, such as a burger's patty count or a drink's size. */
+    price_from?: true;
     /** The ISO 4217 code the store prices the product in, or null when Agentcard sent none. */
     currency: string | null;
     image_url: string | null;
+    /**
+     * Every photo of the product Agentcard sent, `image_url` first, each once, at most eight. One entry when the
+     * product has one photo, and none when it has none. An older API sends one photo at most.
+     */
+    image_urls: string[];
     store: BuyStore | null;
     /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
     url: string | null;
@@ -209,7 +332,7 @@ export interface BuyStoreChoice {
     eta_minutes: number | null;
     image_url: string | null;
 }
-/** The stores an answer's reply presents to choose from, at most three, in the order the reply names them. */
+/** The stores an answer's reply presents to choose from, at most eight, in the order the reply names them. */
 export interface BuyStores {
     merchant: string;
     merchant_name: string;
@@ -236,6 +359,15 @@ export interface BuyPaymentSource {
  * not know reads as null.
  */
 export type BuyNextAction = 'shipping_details' | 'guest_details' | 'store_login' | 'add_card' | 'confirm' | 'verification_code' | 'approve';
+/**
+ * A cart the store's checkout is still building after an answer went out, at `store`, since `started_at`: its cart and
+ * total reach the shopper as a message of their own (purchase.message `cart_ready`), and only the shopper's yes to that
+ * total confirms it.
+ */
+export interface BuyCartBuilding {
+    store: string;
+    started_at: string;
+}
 /** One turn's answer, every field read for its type; a field an older API does not send reads as null. */
 export interface BuyTurn {
     conversation_id: string;
@@ -273,6 +405,8 @@ export interface BuyTurn {
     stores: BuyStores | null;
     /** The store this turn's `pick.store_id` named, or an answer such as `the second one` picked; null without one. */
     store_pick: BuyStorePick | null;
+    /** The cart the store's checkout is still building after this answer; null when none is, and on an older API. */
+    cart_building: BuyCartBuilding | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -307,6 +441,8 @@ export interface BuyConversation {
     conversation_id: string;
     status: 'open' | 'closed';
     turn_in_progress: boolean;
+    /** The cart the store's checkout is still building on this conversation; null when none is, and on an older API. */
+    cart_building: BuyCartBuilding | null;
     last_checkout: BuyLastCheckout | null;
     orders: BuyOrder[];
     carts: BuyCart[];
@@ -342,6 +478,8 @@ export declare class AgentcardApiError extends Error {
 }
 /** A turn as Agentcard answers it. */
 export declare function turnOf(body: Record<string, unknown>): BuyTurn;
+/** A cart being built, as an answer, a refusal or the conversation read names it. */
+export declare function cartBuildingOf(value: unknown): BuyCartBuilding | null;
 /** The client every shopper's buy tool shares. Build one per set of credentials and keep it. */
 export declare class AgentcardClient {
     readonly baseUrl: string;
@@ -354,6 +492,7 @@ export declare class AgentcardClient {
     /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
     private readonly inbox;
     private readonly deliveredIds;
+    private readonly trace;
     constructor(options: AgentcardClientOptions);
     /** True when the client buys for many shoppers with a company's credentials; false under one shopper's own token. */
     get company(): boolean;
@@ -394,6 +533,17 @@ export declare class AgentcardClient {
      * shopper: the listener and the buy tool share one client in one process.
      */
     delivered(externalUserId: string, message: ShopperMessage): void;
+    /**
+     * Notes that your agent answers `message` with a turn of its own (`buy.nextStep`) instead of posting
+     * its `text`, so the shopper never reads that text: `delivered` skips it from now on, and no later
+     * `buy.turn` hands it to the model as words the shopper read. `buy.nextStep` calls it.
+     */
+    answered(externalUserId: string, message: ShopperMessage): void;
+    /**
+     * Takes back `answered` for a message your agent's own turn could not answer (`BuyToolTurn.release` calls it): once you
+     * post its text after all, `delivered` keeps it, and a later `buy.turn` hands it to the model as words the shopper read.
+     */
+    unanswered(externalUserId: string, message: ShopperMessage): void;
     /**
      * The messages kept for this shopper, oldest first: each one that reached their chat and that no
      * history `turn.messages` read has held yet. `buy.turn` reads them when it opens.
@@ -409,3 +559,4 @@ export declare class AgentcardClient {
     private renewAfter;
     private exchange;
 }
+export {};

package/dist/client.js

@@ -10,6 +10,8 @@
  */
 import { isRecord } from './verify.js';
 import { listenToAgentcard } from './listen.js';
+/** The handlers that ask Agentcard to stream a turn. */
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onCart', 'onDelta'];
 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. */
@@ -24,6 +26,37 @@ const DELIVERED_PER_SHOPPER = 20;
 const DELIVERED_SHOPPERS = 10_000;
 /** The event ids the client remembers taking in, so a message delivered twice reaches the model once. */
 const DELIVERED_IDS_KEPT = 10_000;
+/** `@opentelemetry/api`, loaded once, only when the app installed it: the package depends on nothing. */
+const OTEL_API = '@opentelemetry/api';
+let otelLoaded = null;
+function loadOtel() {
+    otelLoaded ??= import(/* webpackIgnore: true */ /* @vite-ignore */ OTEL_API).then((m) => (m.trace && m.propagation && m.context ? m : m.default?.trace ? m.default : null), () => null);
+    return otelLoaded;
+}
+/** The `traceparent` and `tracestate` headers for one call: the active span's, else the app's own, else none. */
+function traceHeaders(otel, own) {
+    const carrier = {};
+    if (otel) {
+        try {
+            otel.propagation.inject(otel.context.active(), carrier);
+        }
+        catch { /* A broken propagator never stops a purchase. */ }
+        if (str(carrier.traceparent))
+            return pickTrace(carrier);
+    }
+    let given;
+    try {
+        given = own?.();
+    }
+    catch { /* An app's own trace lookup that throws sends no trace. */ }
+    const ctx = typeof given === 'string' ? { traceparent: given } : given;
+    // Only a well-formed W3C traceparent goes out: anything else would break the header or the backend's parse.
+    return isRecord(ctx) && TRACEPARENT.test(String(ctx.traceparent)) ? pickTrace(ctx) : {};
+}
+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 };
 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
@@ -76,6 +109,30 @@ function pageUrl(v) {
         return null;
     }
 }
+/** The most photos one product carries. */
+const IMAGES_MAX = 8;
+/**
+ * A product's photos: `main` first, then each https address in `list`, in its order, each once, at most
+ * IMAGES_MAX. A value that is no https address, or that names a user before its host, is left out.
+ */
+function imagesOf(main, list) {
+    // The main photo passes the same check as the others: an https address without credentials. It stays as `imageUrl` spells
+    // it, so the list still starts with that address, and a later copy of it is skipped by its normalized form.
+    const mainPage = pageUrl(main);
+    const ok = !!main && !!mainPage && mainPage.startsWith('https:');
+    const out = ok ? [main] : [];
+    const seen = new Set(ok ? [mainPage] : []);
+    for (const v of Array.isArray(list) ? list : []) {
+        if (out.length >= IMAGES_MAX)
+            break;
+        const page = pageUrl(v);
+        if (page && page.startsWith('https:') && !seen.has(page)) {
+            seen.add(page);
+            out.push(page);
+        }
+    }
+    return out;
+}
 function storeOf(v) {
     if (!isRecord(v) || !str(v.id))
         return null;
@@ -87,6 +144,13 @@ 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;
 }
+function feesOf(v) {
+    const amount = num(v.serviceFeesCents);
+    const status = v.merchantFeesPending === true || v.serviceFeesStatus === 'pending' ? 'pending'
+        : (v.serviceFeesStatus === undefined || v.serviceFeesStatus === 'known')
+            && amount !== null && Number.isSafeInteger(amount) && amount >= 0 ? 'known' : 'unknown';
+    return { serviceFeesCents: status === 'known' ? amount : null, serviceFeesStatus: status };
+}
 function cartOf(v) {
     if (!isRecord(v) || !str(v.hash) || !str(v.merchant))
         return null;
@@ -94,15 +158,24 @@ function cartOf(v) {
         merchant: v.merchant,
         merchant_name: str(v.merchant_name) ?? v.merchant,
         store: storeOf(v.store),
-        items: Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => ({
-            name: str(i.name) ?? '',
-            qty: num(i.qty) ?? 1,
-            ...(num(i.priceCents) !== null ? { priceCents: i.priceCents } : {}),
-            product_id: str(i.product_id),
-            url: pageUrl(i.url),
-        })) : [],
+        items: Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => {
+            const qty = num(i.qty) ?? 1;
+            const price = num(i.priceCents);
+            return {
+                name: str(i.name) ?? '',
+                qty,
+                ...(price !== null ? { priceCents: price } : {}),
+                // An older API sends no line total: the line's price times its quantity is it.
+                lineTotalCents: num(i.lineTotalCents) ?? (price !== null ? price * qty : null),
+                options: Array.isArray(i.options) ? i.options.filter((o) => typeof o === 'string' && o.trim() !== '') : [],
+                variant: str(i.variant),
+                product_id: str(i.product_id),
+                ref: str(i.ref),
+                url: pageUrl(i.url),
+            };
+        }) : [],
         subtotalCents: num(v.subtotalCents),
-        serviceFeesCents: num(v.serviceFeesCents) ?? 0,
+        ...feesOf(v),
         merchantFeeLines: feeLinesOf(v.merchantFeeLines),
         tipCents: num(v.tipCents) ?? 0,
         totalCents: num(v.totalCents) ?? 0,
@@ -131,21 +204,31 @@ function flightOf(value) {
 function catalogOf(v) {
     if (!isRecord(v))
         return null;
-    const items = Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => {
+    const items = catalogItemsOf(v.items);
+    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
+}
+/** A catalog block's products, as `items` or `more` lists them. */
+function catalogItemsOf(v) {
+    return Array.isArray(v) ? v.filter(isRecord).map((i) => {
         const flight = flightOf(i.flight);
         return {
             id: str(i.id) ?? '',
             ref: str(i.ref),
             name: str(i.name),
             priceCents: num(i.priceCents),
+            ...(i.price_from === true && num(i.priceCents) !== null ? { price_from: true } : {}),
             currency: str(i.currency),
             image_url: str(i.image_url),
+            image_urls: imagesOf(str(i.image_url), i.image_urls),
             ...(flight ? { flight } : {}),
             store: storeOf(i.store),
             url: pageUrl(i.url),
         };
     }) : [];
-    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
+}
+/** A count Agentcard sent: a whole number, never negative. Null otherwise. */
+function countOf(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : null;
 }
 /** The stores an answer presents: each one with an id and a name, and no block when none has both. */
 function storesOf(v) {
@@ -194,15 +277,21 @@ export function turnOf(body) {
         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),
         raw: body,
     };
 }
+/** A cart being built, as an answer, a refusal or the conversation read names it. */
+export function cartBuildingOf(value) {
+    return isRecord(value) && str(value.store) ? { store: value.store, started_at: str(value.started_at) ?? '' } : null;
+}
 function conversationOf(body) {
     const last = isRecord(body.last_checkout) ? body.last_checkout : null;
     return {
         conversation_id: str(body.conversation_id) ?? '',
         status: body.status === 'closed' ? 'closed' : 'open',
         turn_in_progress: body.turn_in_progress === true,
+        cart_building: cartBuildingOf(body.cart_building),
         last_checkout: last ? {
             at: str(last.at) ?? '',
             merchant: str(last.merchant) ?? '',
@@ -335,14 +424,21 @@ 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` and `catalog` goes to its handler on the way. A stream that
- * breaks or ends before its envelope, once it named the conversation, reads as a turn past its budget
+ * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment` and `cart` 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.
  */
 async function readStreamedTurn(res, stream, timeoutMs) {
     let envelope = null;
     let conversationId = null;
-    const delivering = [];
+    // The catalog, segment, cart and delta handlers run one after another, in the order their events arrived, so an app
+    // never shows a message above the cards it names, nor a piece of the next message before the message ahead of it. The
+    // stream is read on meanwhile, and the answer waits for the last one. A handler that throws costs only itself.
+    let delivering = Promise.resolve();
+    const deliver = (hand) => {
+        delivering = delivering.then(() => hand()).catch(() => { });
+    };
     let failure = null;
     try {
         await eachEvent(res, (event, text) => {
@@ -350,6 +446,8 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             if (!data)
                 return;
             conversationId = str(data.conversation_id) ?? conversationId;
+            // The conversation this event belongs to: its own, or the one an earlier event of the same turn named.
+            const named = conversationId;
             if (event === 'envelope') {
                 envelope = data;
                 return true;
@@ -362,19 +460,59 @@ async function readStreamedTurn(res, stream, timeoutMs) {
                     // The app's display failing never fails the turn.
                 }
             }
-            else if (event === 'catalog' && stream.onCatalog && str(data.conversation_id)) {
+            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 });
+                }
+                catch {
+                    // The app's display failing never fails the turn.
+                }
+            }
+            else if (event === 'delta' && typeof data.text === 'string' && data.text !== '' && stream.onDelta) {
+                deliver(() => stream.onDelta({ conversationId: named, text: data.text }));
+            }
+            else if (event === 'catalog' && (stream.onCatalog || stream.onFound) && str(data.conversation_id)) {
                 const catalog = catalogOf(data.catalog);
                 if (!catalog || catalog.items.length === 0)
                     return;
-                const asOf = isRecord(data.catalog) ? str(data.catalog.as_of) : null;
-                delivering.push(Promise.resolve().then(() => stream.onCatalog({ conversationId: data.conversation_id, catalog, asOf })).catch(() => { }));
+                const block = data.catalog;
+                const asOf = str(block.as_of);
+                const shown = countOf(block.shown);
+                const found = countOf(block.found);
+                const update = { conversationId: data.conversation_id, catalog, asOf, shown, found, more: catalogItemsOf(block.more) };
+                // The count follows the cards it counts, so an app never shows "8 of 23" above no cards, and it settles before the
+                // next event, so a later count never lands before an earlier one. A card display that throws never costs the count.
+                deliver(async () => {
+                    try {
+                        await stream.onCatalog?.(update);
+                    }
+                    catch {
+                        // The app's display failing never fails the turn.
+                    }
+                    if (shown !== null && found !== null && found >= shown)
+                        await stream.onFound?.({ conversationId: update.conversationId, shown, found });
+                });
+            }
+            else if (event === 'find' && stream.onFound && str(data.conversation_id)) {
+                // Find mode's count from the product index: the cards it shows of the products it found.
+                const shown = countOf(data.shown);
+                const found = countOf(data.found);
+                if (shown !== null && found !== null && found >= shown)
+                    deliver(() => stream.onFound({ conversationId: data.conversation_id, shown, found }));
+            }
+            else if (event === 'segment' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onSegment) {
+                deliver(() => stream.onSegment({ conversationId: named, text: data.text }));
+            }
+            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));
             }
         });
     }
     catch (error) {
         failure = error;
     }
-    await Promise.all(delivering);
+    await delivering;
     const answered = envelope;
     if (answered) {
         const { http_status: httpStatus, ...body } = answered;
@@ -398,6 +536,7 @@ export class AgentcardClient {
     /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
     inbox = new Map();
     deliveredIds = new Set();
+    trace;
     constructor(options) {
         const o = (options ?? {});
         const hasCredentials = o.clientId !== undefined || o.clientSecret !== undefined;
@@ -416,6 +555,7 @@ export class AgentcardClient {
         this.baseUrl = (str(o.baseUrl) ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         this.credentials = hasCredentials ? { clientId: o.clientId, clientSecret: o.clientSecret } : null;
         this.shopperToken = hasCredentials ? null : o.accessToken;
+        this.trace = isRecord(o.trace) ? o.trace : {};
     }
     /** True when the client buys for many shoppers with a company's credentials; false under one shopper's own token. */
     get company() {
@@ -450,10 +590,39 @@ export class AgentcardClient {
         if (!isRecord(body))
             throw new TypeError('Pass the purchase request as an object, such as { ask: "two AA battery packs" }.');
         this.checkShopper({ externalUserId: body.external_user_id, userId: body.user_id });
-        const streamed = !!stream && (typeof stream.onProgress === 'function' || typeof stream.onCatalog === 'function');
-        // A streamed turn keeps the soft budget a JSON turn has, so it answers within BUY_TURN_TIMEOUT_MS too.
-        const path = streamed ? '/buy?stream=1&soft_timeout=1' : '/buy';
-        return turnOf(await this.call('POST', path, body, BUY_TURN_TIMEOUT_MS, streamed ? stream : undefined));
+        const streamed = !!stream && STREAM_HANDLERS.some((name) => typeof stream[name] === 'function');
+        // A streamed turn keeps the soft budget a JSON turn has, so it answers within BUY_TURN_TIMEOUT_MS too. The pieces of
+        // each message go out only to a caller that asks for them.
+        const path = !streamed ? '/buy' : typeof stream.onDelta === 'function' ? '/buy?stream=deltas&soft_timeout=1' : '/buy?stream=1&soft_timeout=1';
+        const otel = this.trace.otel === false ? null : this.trace.otel ?? await loadOtel();
+        const run = async () => {
+            const headers = traceHeaders(otel, this.trace.traceContext);
+            return turnOf(await this.call('POST', path, body, BUY_TURN_TIMEOUT_MS, streamed ? stream : undefined, headers));
+        };
+        if (!otel)
+            return run();
+        // One `sdk.buy` span per call, a client span (kind 2) the backend's `buy.request` hangs under. It names the
+        // conversation and how the call ended, never what the shopper said.
+        const attributes = { 'agentcard.streamed': streamed };
+        const conversationId = str(body.conversation_id);
+        if (conversationId)
+            attributes['agentcard.conversation_id'] = conversationId;
+        return otel.trace.getTracer('commerce-sdk').startActiveSpan('sdk.buy', { kind: 2, attributes }, async (span) => {
+            try {
+                const turn = await run();
+                if (turn.conversation_id)
+                    span.setAttribute('agentcard.conversation_id', turn.conversation_id);
+                span.setAttribute('agentcard.buy_status', turn.status);
+                return turn;
+            }
+            catch (error) {
+                span.setStatus({ code: 2, message: error instanceof AgentcardApiError ? error.code : 'error' });
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
     }
     /** One read of a conversation: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
     async conversation(conversationId, who = {}) {
@@ -516,6 +685,37 @@ export class AgentcardClient {
         if (this.inbox.size > DELIVERED_SHOPPERS)
             this.inbox.delete(this.inbox.keys().next().value);
     }
+    /**
+     * Notes that your agent answers `message` with a turn of its own (`buy.nextStep`) instead of posting
+     * its `text`, so the shopper never reads that text: `delivered` skips it from now on, and no later
+     * `buy.turn` hands it to the model as words the shopper read. `buy.nextStep` calls it.
+     */
+    answered(externalUserId, message) {
+        if (!str(externalUserId))
+            throw new TypeError('Pass externalUserId: your own id for the shopper the message is for.');
+        if (!isRecord(message))
+            throw new TypeError('Pass the message onMessage got.');
+        if (str(message.eventId)) {
+            this.deliveredIds.add(message.eventId);
+            if (this.deliveredIds.size > DELIVERED_IDS_KEPT)
+                this.deliveredIds.delete(this.deliveredIds.values().next().value);
+        }
+        const kept = this.inbox.get(externalUserId);
+        if (kept)
+            this.forgetMessages(externalUserId, kept.filter((m) => m === message || (!!message.eventId && m.eventId === message.eventId)));
+    }
+    /**
+     * Takes back `answered` for a message your agent's own turn could not answer (`BuyToolTurn.release` calls it): once you
+     * post its text after all, `delivered` keeps it, and a later `buy.turn` hands it to the model as words the shopper read.
+     */
+    unanswered(externalUserId, message) {
+        if (!str(externalUserId))
+            throw new TypeError('Pass externalUserId: your own id for the shopper the message is for.');
+        if (!isRecord(message))
+            throw new TypeError('Pass the message onMessage got.');
+        if (str(message.eventId))
+            this.deliveredIds.delete(message.eventId);
+    }
     /**
      * The messages kept for this shopper, oldest first: each one that reached their chat and that no
      * history `turn.messages` read has held yet. `buy.turn` reads them when it opens.
@@ -546,10 +746,10 @@ export class AgentcardClient {
             throw new TypeError('Name the shopper once: externalUserId, your own id for them, or userId, the Agentcard user id.');
         }
     }
-    async call(method, path, body, timeoutMs, stream) {
+    async call(method, path, body, timeoutMs, stream, extra = {}) {
         let token = await this.bearer();
         for (let attempt = 0;; attempt++) {
-            const answer = await this.send(method, path, token, body, timeoutMs, stream);
+            const answer = await this.send(method, path, token, body, timeoutMs, stream, extra);
             if (answer.status === 401 && attempt === 0 && this.credentials) {
                 token = await this.renewAfter(token);
                 continue;
@@ -567,12 +767,13 @@ export class AgentcardClient {
             throw errorOf(answer.status, answer.body);
         }
     }
-    async send(method, path, token, body, timeoutMs, stream) {
+    async send(method, path, token, body, timeoutMs, stream, extra = {}) {
         let res;
         try {
             res = await this.fetchFn(`${this.baseUrl}${path}`, {
                 method,
                 headers: {
+                    ...extra,
                     authorization: `Bearer ${token}`,
                     accept: stream ? 'text/event-stream, application/json' : 'application/json',
                     ...(body !== undefined ? { 'content-type': 'application/json' } : {}),