@agent-cards/commerce-sdk 0.11.0 → 0.13.0

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,61 @@ 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) })),
+        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 > 0 ? money(cart.serviceFeesCents, cart.currency) : null,
         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,12 +216,15 @@ 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,
         link_sent: result.link_sent === true,
         links_sent: result.link_sent === true
@@ -184,6 +242,25 @@ 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.
+ *
+ * ```ts
+ * replyAsWritten(result); // 'found two at Amazon. want the first one?'
+ * ```
+ */
+export function replyAsWritten(result) {
+    // 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();
+    return agentcards && view.status === 'needs_input' && reply !== '' ? reply : null;
+}
 /**
  * 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

@@ -12,6 +12,15 @@ import { type PurchaseFacts, type PurchaseMessageKind } from './message.js';
 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.13.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": [