@agent-cards/commerce-sdk 0.11.0 → 0.14.0

package/dist/model-view.d.ts

@@ -11,12 +11,22 @@ import type { 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.
+     */
     items: Array<{
+        product_id: string | null;
         name: string;
         qty: number;
         price: string | null;
+        line_total: string | null;
+        options: string[];
+        variant: string | null;
     }>;
     fees: string | null;
+    fees_status?: 'known' | 'pending' | 'unknown';
     /** The store's own fee and tax lines inside `fees`, by the store's labels. Empty when it itemized none. */
     fee_lines: Array<{
         label: string;
@@ -26,6 +36,8 @@ export interface BuyToolModelCart {
     total: string;
     /** True when the store has not priced its fees and tax yet: `total` is an estimate, never the final amount. */
     total_is_estimate: boolean;
+    /** What an estimated `total` leaves out, in words the model can repeat; null when the store priced the cart. */
+    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;
 }
@@ -53,6 +65,13 @@ export interface BuyToolModelView {
     status: BuyToolStatus;
     /** The one thing to ask the shopper for in this message, or null when nothing waits on them. Never ask for a later step. */
     next_action: BuyNextAction | null;
+    /**
+     * The store whose checkout is still building the cart this answer named, absent when none is: its cart and total reach the
+     * shopper in a message from Agentcard, and only the shopper's yes to that total confirms it.
+     */
+    cart_building?: {
+        store: string;
+    };
     /** Agentcard's answer for the shopper, with every link taken out. */
     reply: string;
     /** The newest cart on the table. */
@@ -61,9 +80,18 @@ export interface BuyToolModelView {
     carts: BuyToolModelCart[];
     products: BuyToolModelProduct[];
     approval_expires_at: string | null;
+    /**
+     * How long the newest link this answer sent (Vault, approval or store login) still works, in words the
+     * shopper reads, such as `about 24 hours` or `about 15 minutes`; `no longer` once it ran out; null when
+     * Agentcard named no expiry. Read when the answer came back, so the model never reckons it from a timestamp.
+     */
+    link_expires_in: string | null;
+    /** True when the shopper need not reply to this answer, as when Agentcard places the order on its own. False beside a step `next_action` names, whose ask is one short line. */
     shopper_need_not_reply: boolean;
     /** True when the shopper already got a message this turn saying their request is being worked on, so the reply opens with no acknowledgement of its own. */
     shopper_already_told_looking: boolean;
+    /** True when the shopper already read `reply`, every message of it, as Agentcard wrote it, so the answer adds only what it leaves out. */
+    shopper_already_read_reply: boolean;
     /** True when the shopper already has the link this answer needed. */
     link_sent: boolean;
     /**
@@ -99,6 +127,15 @@ export declare function stripLinks(text: string): string;
  * decimal point, so 1331 is $13.31 in USD, CA$13.31 in CAD and ¥1,331 in JPY. An amount whose currency
  * Agentcard did not name shows with no symbol, because a dollar sign on it could be wrong.
  */
+/**
+ * A product's price as the shopper reads it: `$12.99`, or `from $10.69` for a product priced by a
+ * required choice (a size, a patty count), whose base price is often $0. Null when Agentcard named none.
+ */
+export declare function productPrice(product: {
+    priceCents: number | null;
+    currency: string | null;
+    priceFrom?: true;
+}): string | null;
 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
@@ -129,6 +166,8 @@ export declare function cardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'ur
  * taps the flight they want (2026-10-20: three flights listed in text, and no card to tap).
  */
 export declare function productCardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'url' | 'flight'>): string | null;
+/** 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;
 /**
  * The model's view of one answer: the status, Agentcard's reply, the newest
  * cart and every cart on the table, the products by id, name and price, and
@@ -136,6 +175,33 @@ export declare function productCardKey(product: Pick<BuyToolProduct, 'id' | 'ref
  * reads as `needs_input`.
  */
 export declare function forModel(result: BuyToolResult): BuyToolModelView;
+/**
+ * Agentcard's reply, ready for the shopper as written, when the answer only asks them something: a
+ * `needs_input` answer with a reply, such as a product list, a size or a store to pick, or a cart's
+ * total and the ask for their yes. The reply comes with every link taken out, as the model reads it.
+ * Null for any other answer, which your model puts in its own words, and for a line the tool wrote
+ * itself for your model, such as the note that the cart changed or a `nextStep` turn's ask for the
+ * shopper's yes: only the reply Agentcard sent, as `envelope` holds it, is written for the shopper.
+ * Null as well once the shopper read the reply through `onText` (`shopper_already_read_reply`).
+ *
+ * ```ts
+ * replyAsWritten(result); // 'found two at Amazon. want the first one?'
+ * ```
+ */
+export declare function replyAsWritten(result: BuyToolResult): string | null;
+/**
+ * Agentcard's reply without the list its cards already show the shopper: each list line that names a product or
+ * store whose card went out, the line that led into that list (`here are a few:`, `other choices:`), a sentence that
+ * points at a number the list gave (`the dishwand in #8`), and, past the one or two products a reply recommends in
+ * words, each further sentence that names another card. 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.
+ *
+ * ```ts
+ * withoutCardList('Two I'd suggest:\n- Duracell AA, 24 pack, $20.78\n\nWhich one?', ['Duracell AA Batteries, 24 Count']);
+ * // 'Which one?'
+ * ```
+ */
+export declare function withoutCardList(reply: string, cardNames: readonly string[]): string;
 /**
  * A thrown error as the model may read it: the same message with every link
  * taken out, and the original error on `cause` for your logs. A TypeError

package/dist/model-view.js

@@ -1,5 +1,7 @@
+/** The steps the shopper takes on a page a link opens: the message that asks for one is one short line. */
+const STEP_ACTIONS = new Set(['store_login', 'add_card', 'approve']);
 const MODEL_STATUSES = new Set(['needs_input', 'needs_card', 'approval_sent', 'placing', 'order_placed', 'declined']);
-/** At most twenty products reach the model. Agentcard's /buy answer lists three, so this cap holds only for an older answer. */
+/** At most twenty products reach the model. Agentcard's /buy answer lists up to eight, so this cap holds only for an older answer. */
 const MAX_PRODUCTS = 20;
 const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
 const SCHEME_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"'`)\]]*/gi;
@@ -82,6 +84,14 @@ function currencyFormat(currency) {
  * decimal point, so 1331 is $13.31 in USD, CA$13.31 in CAD and ¥1,331 in JPY. An amount whose currency
  * Agentcard did not name shows with no symbol, because a dollar sign on it could be wrong.
  */
+/**
+ * A product's price as the shopper reads it: `$12.99`, or `from $10.69` for a product priced by a
+ * required choice (a size, a patty count), whose base price is often $0. Null when Agentcard named none.
+ */
+export function productPrice(product) {
+    const price = money(product.priceCents, product.currency);
+    return price !== null && product.priceFrom ? `from ${price}` : price;
+}
 export function money(minor, currency) {
     if (typeof minor !== 'number' || !Number.isFinite(minor))
         return null;
@@ -136,16 +146,62 @@ export function productCardKey(product) {
 function cartView(cart) {
     return {
         store: stripLinks(cart.store?.name ?? cart.merchant_name) || stripLinks(cart.merchant),
-        items: cart.items.map((line) => ({ name: stripLinks(line.name), qty: line.qty, price: money(line.priceCents, cart.currency) })),
-        fees: cart.serviceFeesCents > 0 ? money(cart.serviceFeesCents, cart.currency) : null,
+        items: cart.items.map((line) => ({
+            product_id: pickId({ id: line.product_id ?? '', ref: line.ref ?? null }),
+            name: stripLinks(line.name),
+            qty: line.qty,
+            // A $0 listed price on a line that costs something is the base of an item priced by its
+            // required choice, such as a burger's patty count: one unit at its configuration then reads
+            // the line's own cost over its quantity, never $0 (2026-10-20: "1× Cheeseburger $0.00" under
+            // a $10.69 total). Any other line keeps its listed price beside line_total.
+            price: money(line.priceCents === 0 && typeof line.lineTotalCents === 'number' && line.lineTotalCents > 0 && line.qty > 0 ? Math.round(line.lineTotalCents / line.qty) : line.priceCents, cart.currency),
+            line_total: money(line.lineTotalCents ?? (typeof line.priceCents === 'number' ? line.priceCents * line.qty : null), cart.currency),
+            options: (line.options ?? []).map(stripLinks).filter((o) => o !== ''),
+            variant: line.variant ? stripLinks(line.variant) || null : null,
+        })),
+        fees: cart.serviceFeesCents !== null && cart.serviceFeesCents > 0 ? money(cart.serviceFeesCents, cart.currency) : null,
+        fees_status: cart.serviceFeesStatus,
         fee_lines: (cart.merchantFeeLines ?? []).map((line) => ({ label: stripLinks(line.label), amount: money(line.amountCents, cart.currency) })),
         tip: cart.tipCents > 0 ? money(cart.tipCents, cart.currency) : null,
         total: money(cart.totalCents, cart.currency) ?? money(0, cart.currency),
         total_is_estimate: cart.totalIsEstimate === true,
+        // 2026-10-21, swarm-bigbox-a10: an estimate read "about $18.41 total with tax and shipping" to the shopper. The words
+        // ride beside the flag, so the model never has to guess which side of the total tax and shipping sit on.
+        total_leaves_out: cart.totalIsEstimate === true ? leftOut(cart.merchantFeeLines ?? []) : null,
         // Agentcard names a ceiling equal to the total only for a hold of exactly the total, as a flight's.
         max_charge: typeof cart.approvedCeilingCents === 'number' && cart.approvedCeilingCents > 0 && cart.approvedCeilingCents >= cart.totalCents ? money(cart.approvedCeilingCents, cart.currency) : null,
     };
 }
+/** What an estimated total leaves out: tax, and shipping or delivery, less what the store's own fee lines already carry
+ *  (a 1-800-Flowers estimate holds its Florist Delivery and Sales Tax). Null when the lines carry both. */
+function leftOut(lines) {
+    const parts = [];
+    if (!lines.some((l) => /\btax\b/i.test(l.label)))
+        parts.push('tax');
+    if (!lines.some((l) => /\b(?:deliver(?:y|ies)?|shipping)\b/i.test(l.label)))
+        parts.push('shipping or delivery');
+    return parts.length ? `${parts.join(' and ')}, which the store adds at checkout` : null;
+}
+/** How long until `iso`, from `now`, as the shopper reads it: `about 24 hours`, `about 15 minutes`, `no longer`, or null. */
+export function expiresIn(iso, now = Date.now()) {
+    const at = typeof iso === 'string' ? Date.parse(iso) : NaN;
+    if (!Number.isFinite(at))
+        return null;
+    if (at <= now)
+        return 'no longer';
+    const minutes = Math.max(1, Math.round((at - now) / 60_000));
+    if (minutes < 90)
+        return `about ${minutes} minute${minutes === 1 ? '' : 's'}`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 48)
+        return `about ${hours} hours`;
+    return `about ${Math.round(hours / 24)} days`;
+}
+/** The expiry of the newest Vault, approval or store login link an answer carries, else its approval's. */
+function linkExpiry(result) {
+    const timed = (result.links ?? []).filter((link) => (link.kind === 'vault' || link.kind === 'approval' || link.kind === 'store_login') && typeof link.expiresAt === 'string');
+    return timed.length > 0 ? timed[timed.length - 1].expiresAt : (result.approval_expires_at ?? null);
+}
 /**
  * The model's view of one answer: the status, Agentcard's reply, the newest
  * cart and every cart on the table, the products by id, name and price, and
@@ -161,13 +217,17 @@ export function forModel(result) {
     return {
         status,
         next_action: result.next_action ?? null,
+        ...(result.cart_building ? { cart_building: { store: stripLinks(result.cart_building.store) } } : {}),
         reply: stripLinks(result.reply),
         cart: result.cart ? cartView(result.cart) : null,
         carts: (result.carts ?? []).map(cartView),
-        products: products.map((product) => ({ product_id: pickId(product), name: stripLinks(product.name), store: stripLinks(product.store ?? ''), price: money(product.priceCents, product.currency), link_sent: held(product) })),
+        products: products.map((product) => ({ product_id: pickId(product), name: stripLinks(product.name), store: stripLinks(product.store ?? ''), price: productPrice(product), link_sent: held(product) })),
         approval_expires_at: typeof result.approval_expires_at === 'string' ? stripLinks(result.approval_expires_at) || null : null,
-        shopper_need_not_reply: result.shopper_need_not_reply === true,
+        link_expires_in: expiresIn(linkExpiry(result)),
+        // A step's ask is one short line: an approval Agentcard places on its own needs no "no need to reply" beside it.
+        shopper_need_not_reply: result.shopper_need_not_reply === true && !STEP_ACTIONS.has(result.next_action ?? ''),
         shopper_already_told_looking: result.shopper_already_told_looking === true,
+        shopper_already_read_reply: result.shopper_already_read_reply === true,
         link_sent: result.link_sent === true,
         links_sent: result.link_sent === true
             ? [...new Set((result.links ?? []).map((link) => link.kind).filter((kind) => kind === 'vault' || kind === 'approval' || kind === 'store_login'))]
@@ -184,6 +244,148 @@ export function forModel(result) {
             : null,
     };
 }
+/**
+ * Agentcard's reply, ready for the shopper as written, when the answer only asks them something: a
+ * `needs_input` answer with a reply, such as a product list, a size or a store to pick, or a cart's
+ * total and the ask for their yes. The reply comes with every link taken out, as the model reads it.
+ * Null for any other answer, which your model puts in its own words, and for a line the tool wrote
+ * itself for your model, such as the note that the cart changed or a `nextStep` turn's ask for the
+ * shopper's yes: only the reply Agentcard sent, as `envelope` holds it, is written for the shopper.
+ * Null as well once the shopper read the reply through `onText` (`shopper_already_read_reply`).
+ *
+ * ```ts
+ * replyAsWritten(result); // 'found two at Amazon. want the first one?'
+ * ```
+ */
+export function replyAsWritten(result) {
+    // The shopper already read every message of it through onText: handing it out again would say it twice.
+    if (result.shopper_already_read_reply === true)
+        return null;
+    // The tool's own lines tell the model what to say, so only Agentcard's reply, unchanged, goes out as is.
+    const agentcards = typeof result.envelope?.reply === 'string' && result.envelope.reply === result.reply;
+    const view = forModel(result);
+    const reply = view.reply.trim();
+    if (!agentcards || view.status !== 'needs_input' || reply === '')
+        return null;
+    const cards = [...view.products.filter((product) => product.link_sent).map((product) => product.name), ...view.stores.filter((store) => store.link_sent).map((store) => store.name)];
+    // A reply with nothing left once the cards' list comes out is your model's to word.
+    return withoutCardList(reply, cards) || null;
+}
+/** A line that opens a list: `- `, `* `, `• `, `1. ` or `1) `. */
+const LIST_ITEM = /^\s*(?:[-*•]|\d{1,2}[.)])\s+/;
+/** A price, in any of the currencies a store writes one in. */
+const PRICE = /[$£€]\s?\d/;
+/** The place a sentence points at in a numbered list, such as `#8` or `number 3`, where `a #2 Phillips head` names a kind of thing. */
+const LIST_NUMBER = /(?<!\ba )(?<!\ban )(?:#(\d{1,2})\b|\bnumber (\d{1,2})\b)/i;
+/** A unit a size or a count is written in, so `10 ft`, `10-ft` and `10ft` read as one word. */
+const UNIT = /(\d)[\s-]+(ft|feet|foot|inch|inches|oz|fl|ml|l|g|kg|lb|lbs|gb|tb|mb|w|mah|v|cm|mm|m|pack|pk|ct|count|pcs|pieces)\b/gi;
+/**
+ * A size one text spells one way and a card's name another, so `24 pack` reads as the card's `24 Count`. Inches lose
+ * their unit, so `41 in black` reads as the card's `41` and `10 in` as its `10in`: `in` is a word as often as a unit.
+ */
+const SAME_UNIT = new Map([['feet', 'ft'], ['foot', 'ft'], ['in', ''], ['inch', ''], ['inches', ''], ['pk', 'pack'], ['ct', 'pack'], ['count', 'pack'], ['pcs', 'pack'], ['pieces', 'pack'], ['lbs', 'lb']]);
+/** A size or a count written as one word, such as `24pack` or `10ft`. */
+const SIZE = /^(\d+)(\p{L}+)$/u;
+/** A text's words, lowercased, letters and digits only, with markdown's bold marks gone and a size written as one word. */
+function wordsOf(text) {
+    return text
+        .toLowerCase()
+        .replace(UNIT, '$1$2')
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((word) => word !== '')
+        .map((word) => word.replace(SIZE, (whole, count, unit) => `${count}${SAME_UNIT.get(unit) ?? unit}`));
+}
+/**
+ * The card a text names, by the first six words of the card's name: at least two of them, and most of them, in the
+ * text. Null when it names none. A name of one word never counts in prose, where a generic word such as `soap` would.
+ * A size or a count among those words has to be in the text too, so the 3ft cable's line never reads as the 10ft card.
+ */
+function cardNamed(text, cards, inList) {
+    const said = new Set(wordsOf(text));
+    for (const [index, name] of cards.entries()) {
+        const head = name.slice(0, 6);
+        if (!head.every((word) => !/\d/.test(word) || said.has(word)))
+            continue;
+        const hits = head.filter((word) => said.has(word)).length;
+        if (head.length === 1 ? inList && hits === 1 : hits >= Math.max(2, Math.ceil(head.length * 0.6)))
+            return index;
+    }
+    return null;
+}
+/**
+ * Agentcard's reply without the list its cards already show the shopper: each list line that names a product or
+ * store whose card went out, the line that led into that list (`here are a few:`, `other choices:`), a sentence that
+ * points at a number the list gave (`the dishwand in #8`), and, past the one or two products a reply recommends in
+ * words, each further sentence that names another card. 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.
+ *
+ * ```ts
+ * withoutCardList('Two I'd suggest:\n- Duracell AA, 24 pack, $20.78\n\nWhich one?', ['Duracell AA Batteries, 24 Count']);
+ * // 'Which one?'
+ * ```
+ */
+export function withoutCardList(reply, cardNames) {
+    const cards = cardNames.map(wordsOf).filter((name) => name.length > 0);
+    if (cards.length === 0)
+        return reply.trim();
+    // A text that opens with a card's name and gives its price is a list line, as a reply writes one without a bullet.
+    const opensCard = (text) => {
+        const words = wordsOf(text);
+        return PRICE.test(text) && cards.some((name) => name.length >= 2 && name.slice(0, 3).every((word, i) => words[i] === word));
+    };
+    const lines = reply.split('\n');
+    const kind = lines.map((line) => {
+        if (LIST_ITEM.test(line))
+            return cardNamed(line.replace(LIST_ITEM, ''), cards, true) !== null ? 'item' : 'kept';
+        return opensCard(line) ? 'named' : 'kept';
+    });
+    const dropped = kind.map((of) => of !== 'kept');
+    // The numbers the dropped list gave, so a number of a product's own, `a #2 Phillips head`, keeps its sentence.
+    const numbers = new Set(lines.flatMap((line, i) => (dropped[i] ? [Number(/^\s*(\d{1,2})[.)]\s/.exec(line)?.[1])] : [])).filter((number) => Number.isInteger(number)));
+    // The list a line leads into: the lines from the next one with words on it to the first that is not a list line, so a
+    // question on the line after the last item, `Which one?`, is no part of the list.
+    const listAfter = (line) => {
+        const start = lines.findIndex((after, j) => j > line && after.trim() !== '');
+        if (start === -1)
+            return [];
+        let end = start;
+        while (end < lines.length && (LIST_ITEM.test(lines[end]) || kind[end] === 'named'))
+            end += 1;
+        return dropped.slice(start, end);
+    };
+    const named = new Set();
+    const kept = [];
+    lines.forEach((line, i) => {
+        if (kind[i] === 'item')
+            return;
+        let text = line;
+        // The line that leads into a list whose every line went loses the sentence that leads in: `Two I'd suggest:` or
+        // `Other choices:`. A list that keeps a line, for a product no card shows, keeps its lead too.
+        const list = listAfter(i);
+        if (text.trim().endsWith(':') && list.length > 0 && list.every(Boolean))
+            text = text.trim().replace(/(?:^|(?<=[.!?])\s+)[^.!?]*:$/, '');
+        const sentences = text.split(/(?<=[.!?])\s+/).filter((sentence) => {
+            const place = LIST_NUMBER.exec(sentence);
+            if (place && numbers.has(Number(place[1] ?? place[2])))
+                return false;
+            const card = cardNamed(sentence, cards, false);
+            // A list line written without a bullet keeps the sentences its card does not say, such as the question after it.
+            if (kind[i] === 'named')
+                return card === null && !opensCard(sentence);
+            if (card === null || named.has(card))
+                return true;
+            // A reply recommends one or two products in words; a sentence that names a third is the list again.
+            if (named.size >= 2)
+                return false;
+            named.add(card);
+            return true;
+        });
+        if (kind[i] === 'named' && sentences.length === 0)
+            return;
+        kept.push(sentences.join(' ').trimEnd());
+    });
+    return kept.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
 /**
  * A thrown error as the model may read it: the same message with every link
  * taken out, and the original error on `cause` for your logs. A TypeError

package/dist/shopper-message.d.ts

@@ -9,9 +9,18 @@ import { type PurchaseFacts, type PurchaseMessageKind } from './message.js';
  * The event types that carry a message for a shopper. Subscribe your endpoint to each by name:
  * a catch-all `*` alone does not turn `purchase.message` on.
  */
-export declare const SHOPPER_EVENT_TYPES: readonly ["purchase.message", "order.confirmed", "order.updated"];
+export declare const SHOPPER_EVENT_TYPES: readonly ['purchase.message', 'order.confirmed', 'order.updated'];
 /** One of the event types that carry a message for a shopper. */
 export type ShopperEventType = (typeof SHOPPER_EVENT_TYPES)[number];
+/**
+ * The kinds after which your agent takes the next step on its own, as a turn of its own, instead of
+ * posting `text` and waiting for the shopper's "ok": the shopper saved a card (`card_added`), signed in
+ * to the store (`store_connected`), or declined the approval (`approval_declined`), outside the chat.
+ * `buy.nextStep(message)` opens that turn. Every other kind's `text` is the whole message: post it as is.
+ */
+export declare const NEXT_STEP_KINDS: readonly ['card_added', 'store_connected', 'approval_declined'];
+/** A kind after which the agent takes the next step on its own. */
+export type NextStepKind = (typeof NEXT_STEP_KINDS)[number];
 /**
  * The delivery stage of an order, as `order.updated` names it. A stage Agentcard adds later reads
  * as its own name.
@@ -65,6 +74,12 @@ export interface ShopperMessage {
     /** For your agent: the facts of what happened, marked as written by the system and not typed by the shopper. */
     note: string;
     facts: ShopperFacts;
+    /**
+     * True when the message ends a step the shopper took outside the chat, one of `NEXT_STEP_KINDS`:
+     * open `buy.nextStep(message)` and let your model take the next step, such as the card ask or the
+     * cart's total and a request for their yes, instead of posting `text`. False for every other message.
+     */
+    advances: boolean;
     /** The OAuth client id of the app the shopper connected through, when the event names it. */
     clientId: string | null;
     /** False for a sandbox event. */

package/dist/shopper-message.js

@@ -10,6 +10,14 @@ import { readPurchaseMessage } from './message.js';
  * a catch-all `*` alone does not turn `purchase.message` on.
  */
 export const SHOPPER_EVENT_TYPES = ['purchase.message', 'order.confirmed', 'order.updated'];
+/**
+ * The kinds after which your agent takes the next step on its own, as a turn of its own, instead of
+ * posting `text` and waiting for the shopper's "ok": the shopper saved a card (`card_added`), signed in
+ * to the store (`store_connected`), or declined the approval (`approval_declined`), outside the chat.
+ * `buy.nextStep(message)` opens that turn. Every other kind's `text` is the whole message: post it as is.
+ */
+export const NEXT_STEP_KINDS = ['card_added', 'store_connected', 'approval_declined'];
+const NEXT_STEP = new Set(NEXT_STEP_KINDS);
 const SYSTEM_LINE = 'This note was generated by the system, not typed by the user.';
 function text(value, max = 200) {
     if (typeof value !== 'string')
@@ -103,6 +111,7 @@ function readOrderConfirmed(event) {
     return {
         ...base,
         kind: 'order_confirmed',
+        advances: false,
         text: `${who}${retailerOrderId ? `, order number ${retailerOrderId}` : ''}.${deliveryWindow ? ` Expected delivery: ${deliveryWindow}.` : ''}`,
         note: `[event: the store accepted this user's order${store ? ` at ${store}` : ''} on its side, outside this conversation.` +
             `${retailerOrderId ? ` The store's order number is ${retailerOrderId}.` : ''}` +
@@ -128,6 +137,7 @@ function readOrderUpdated(event) {
     return {
         ...base,
         kind: 'order_updated',
+        advances: false,
         text: message,
         note: `[event: this user's order${store ? ` at ${store}` : ''} moved to the stage ${status}` +
             `${previous ? ` from ${previous}` : ''}, outside this conversation.` +
@@ -163,6 +173,7 @@ export function readShopperMessage(event) {
         ...message,
         type: 'purchase.message',
         conversationId: id(event.data.conversation_id) ?? null,
+        advances: NEXT_STEP.has(message.kind),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.11.0",
+  "version": "0.14.0",
   "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.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
     }
   },
   "files": [
@@ -36,6 +40,14 @@
     "webhooks",
     "purchases"
   ],
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=18"
   },