@agent-cards/commerce-sdk 0.19.0 → 0.19.1

package/dist/basket.d.ts

@@ -1,6 +1,6 @@
 /**
  * A basket on a purchase answer: the carts at several sellers that one approval pays, each seller charging the card
- * separately for no more than its line. `approval_url` is the one link the shopper approves on while the basket waits for
+ * separately for exactly its line, or up to its hold for a store that charges its final amount (`held`). `approval_url` is the one link the shopper approves on while the basket waits for
  * that approval or pays under it. Null on an answer with no basket, and on an older API.
  *
  * A basket whose stores reach their payment step after this answer has no link yet: the link then arrives as a
@@ -17,15 +17,26 @@ export interface BuyBasketLine {
     /** The seller as the shopper knows it: the store or the airline. */
     seller: string;
     status: BuyBasketLineStatus;
+    /** The seller's cart total, the amount to show for this line. */
     total_cents: number;
-    /** The most this seller may charge: its total_cents, since a seller is paid exactly the amount the shopper approved. */
+    /**
+     * The most this seller may charge. It equals total_cents for a seller that quotes its final price: that seller is paid
+     * exactly the amount the shopper approved. A store that charges its final amount when the order is placed holds the
+     * card above its total, and cap_cents is that hold.
+     */
     cap_cents: number;
+    /**
+     * True when cap_cents is above total_cents: show the total and the hold beside it, as in "Walmart $100.00, card held up
+     * to $125.00, you pay only the final amount".
+     */
+    held: boolean;
 }
 export interface BuyBasket {
     id: string;
     status: BuyBasketStatus;
+    /** The sum of the sellers' cart totals, the amount the shopper approves. */
     total_cents: number;
-    /** The most every seller together may charge: total_cents, the sum of what each seller is paid. */
+    /** The most every seller together may charge: total_cents, plus the hold above each held line's total. */
     cap_cents: number;
     currency: string;
     approval_url: string | null;

package/dist/basket.js

@@ -15,7 +15,9 @@ export function basketOf(v) {
     for (const l of v.lines) {
         if (!isRecord(l) || typeof l.seller !== 'string' || typeof l.status !== 'string' || !LINE_STATUSES.has(l.status) || !whole(l.total_cents) || !whole(l.cap_cents))
             return null;
-        lines.push({ seller: l.seller, status: l.status, total_cents: l.total_cents, cap_cents: l.cap_cents });
+        if (l.cap_cents < l.total_cents)
+            return null;
+        lines.push({ seller: l.seller, status: l.status, total_cents: l.total_cents, cap_cents: l.cap_cents, held: l.cap_cents > l.total_cents });
     }
     return { id: v.id, status: v.status, total_cents: v.total_cents, cap_cents: v.cap_cents, currency: v.currency,
         approval_url: typeof v.approval_url === 'string' ? v.approval_url : null, expires_at: v.expires_at, lines };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatureReason, type AgentcardEvent, type VerifyOptions, } from './verify.js';
 export { shopperLocationOf, type ShopperLocation, type ShopperShipTo, type BuyShopperLocation } from './shopper-location.js';
-export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.js';
+export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, type CardRefusal, } from './message.js';
 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';

package/dist/message.d.ts

@@ -59,6 +59,25 @@ export interface PurchaseFacts {
     validUntil?: string;
     /** 1 for a cart's first nudge, 2 for its second. */
     nudgeNumber?: number;
+    /**
+     * On an `order_failed` whose card the store's payment processor refused after the approval: why it refused the card,
+     * and whether any money moved, so your app can show the reason without reading `reason`'s words.
+     */
+    cardRefusal?: CardRefusal;
+    /** The one step that moves the purchase on: `add_card`, with the add-a-card link in `cardLinkUrl`. */
+    nextAction?: 'add_card' | (string & {});
+    /**
+     * When `cardLinkUrl` stops working, as an ISO 8601 timestamp, on a message that stays true after it does (`order_failed`):
+     * past it, ask Agentcard for a new link instead of sending this one.
+     */
+    cardLinkExpiresAt?: string;
+}
+/** Why a store's payment processor refused the shopper's card, and whether any money moved. */
+export interface CardRefusal {
+    /** `incorrect_number`, `insufficient_funds`, `expired_card`, `incorrect_cvc`, or `card_declined` for any other refusal. */
+    reason: 'incorrect_number' | 'insufficient_funds' | 'expired_card' | 'incorrect_cvc' | 'card_declined' | (string & {});
+    /** `none`: nothing was charged. `unknown`: Agentcard has no confirmation yet either way. */
+    charged: 'none' | 'unknown' | (string & {});
 }
 /** A `purchase.message` event, read. */
 export interface PurchaseMessage {

package/dist/message.js

@@ -18,6 +18,8 @@ const STRING_FACTS = [
     ['card_link_url', 'cardLinkUrl'],
     ['retry_until', 'retryUntil'],
     ['valid_until', 'validUntil'],
+    ['next_action', 'nextAction'],
+    ['card_link_expires_at', 'cardLinkExpiresAt'],
 ];
 const NUMBER_FACTS = [
     ['total_cents', 'totalCents'],
@@ -39,6 +41,10 @@ function readFacts(raw) {
         if (typeof value === 'number' && Number.isFinite(value))
             facts[name] = value;
     }
+    const refusal = raw.card_refusal;
+    if (isRecord(refusal) && typeof refusal.reason === 'string' && refusal.reason !== '') {
+        facts.cardRefusal = { reason: refusal.reason, charged: typeof refusal.charged === 'string' && refusal.charged !== '' ? refusal.charged : 'unknown' };
+    }
     return facts;
 }
 function requiredString(data, field) {

package/dist/model-view.d.ts

@@ -194,9 +194,11 @@ export declare function stripLinks(text: string): string;
  * one. A line that pointed at a link ends as a sentence when the answer sent the shopper what it pointed at, a product or a
  * store card or a step's link, and goes when it sent none, so the reply never promises what the shopper does not get. 2026-10-27, chat.opencommerce.sh:
  * "here's the stool on Wayfair:" reached the shopper with nothing after it. The page of a card the answer sent, `pages`,
- * stays as written.
+ * stays as written. A line that points at a step link the answer hands the app, `stepLinks`, keeps its words as a sentence
+ * whether or not the tool sent it: the app sends that link itself. 2026-11-05, a company's app with no sendLink: Marshalls'
+ * one-line sign-in ask went whole, and the app read an empty reply beside the sign-in link.
  */
-export declare function replyWithoutLinks(reply: string, sent: boolean, pages?: readonly (string | null | undefined)[]): string;
+export declare function replyWithoutLinks(reply: string, sent: boolean, pages?: readonly (string | null | undefined)[], stepLinks?: readonly string[]): string;
 /**
  * An amount in its currency's minor unit, as the model reads it: the currency's own minor units place the
  * decimal point, so 1331 is $13.31 in USD, CA$13.31 in CAD and ¥1,331 in JPY. An amount whose currency

package/dist/model-view.js

@@ -4,6 +4,8 @@ import { GONE, LINK_WORD_LINKS, MARKDOWN_IMAGE, holdStorePages, namesOnlyALink,
 import { withoutEmptyMarks } from './list-marks.js';
 /** 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']);
+/** The links an answer hands over for a step the shopper takes: the add-card, approval and store sign-in links. */
+const STEP_LINKS = new Set(['vault', 'approval', 'store_login']);
 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 up to eight, so this cap holds only for an older answer. */
 const MAX_PRODUCTS = 20;
@@ -81,13 +83,15 @@ const POINTS_AT_LINK = /^([^\n]*?\S)[ \t]*:[ \t]*(?:\n[ \t]*)?<?(?:https?:\/\/|(
  * one. A line that pointed at a link ends as a sentence when the answer sent the shopper what it pointed at, a product or a
  * store card or a step's link, and goes when it sent none, so the reply never promises what the shopper does not get. 2026-10-27, chat.opencommerce.sh:
  * "here's the stool on Wayfair:" reached the shopper with nothing after it. The page of a card the answer sent, `pages`,
- * stays as written.
+ * stays as written. A line that points at a step link the answer hands the app, `stepLinks`, keeps its words as a sentence
+ * whether or not the tool sent it: the app sends that link itself. 2026-11-05, a company's app with no sendLink: Marshalls'
+ * one-line sign-in ask went whole, and the app read an empty reply beside the sign-in link.
  */
-export function replyWithoutLinks(reply, sent, pages = []) {
+export function replyWithoutLinks(reply, sent, pages = [], stepLinks = []) {
     // A card's own store page stays where the reply wrote it (store-pages.ts), and a line whose words only named a link goes with it.
     // A bold label keeps its colon outside the bold (`**Photo:** <address>` reads `**Photo**: <address>`), so it reads as a label.
     const { text, restore } = holdStorePages(String(reply ?? '').replace(/(\*\*|__)([^*_\n]+?):\1/g, '$1$2$1:'), pages);
-    return restore(stripLinks(withoutGoneLines(text.replace(POINTS_AT_LINK, (_line, lead) => (sent && !namesOnlyALink(lead) ? `${lead}.` : GONE)))));
+    return restore(stripLinks(withoutGoneLines(text.replace(POINTS_AT_LINK, (line, lead) => ((sent || stepLinks.some((url) => line.includes(url))) && !namesOnlyALink(lead) ? `${lead}.` : GONE)))));
 }
 /** A currency's minor units as Intl knows them: 2 for USD and CAD, 0 for JPY. */
 function minorUnits(format) {
@@ -313,7 +317,7 @@ export function forModel(result) {
                 question: result.choice.question === null ? null : stripLinks(result.choice.question),
                 groups: result.choice.groups.map((group) => ({ name: stripLinks(group.name), required: group.required, options: group.options.map((option) => `${stripLinks(option.label)}${option.price_delta_cents ? ` (+$${(option.price_delta_cents / 100).toFixed(2)})` : ''}`) })),
             } } : {}),
-        reply: replyWithoutLinks(result.reply, products.some(held) || stores.some(heldStore) || result.link_sent === true, [...products.filter(held).map((product) => product.url), ...stores.filter(heldStore).map((store) => store.url)]),
+        reply: replyWithoutLinks(result.reply, products.some(held) || stores.some(heldStore) || result.link_sent === true, [...products.filter(held).map((product) => product.url), ...stores.filter(heldStore).map((store) => store.url)], (result.links ?? []).flatMap((link) => (STEP_LINKS.has(link.kind) && typeof link.url === 'string' && link.url !== '' ? [link.url] : []))),
         cart: result.cart ? cartView(result.cart, result.cart_building?.store) : null,
         carts: (result.carts ?? []).map((cart) => cartView(cart, result.cart_building?.store)),
         products: products.map((product) => ({ product_id: pickId(product), name: stripLinks(product.name), store: stripLinks(product.store ?? ''), price: productPrice(product), link_sent: held(product) })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Give your agent one tool that buys for your shoppers at real stores, and post each purchase update Agentcard sends into the shopper's chat, over a connection your server opens or a webhook endpoint.",
   "homepage": "https://opencommerce.sh",
   "type": "module",