@agent-cards/commerce-sdk 0.18.15 → 0.18.16

package/README.md

@@ -886,6 +886,7 @@ The facts are `merchantName`, `totalCents`, `currency`, `cardBrand`, `cardLast4`
 | `cart_ready` | The store's checkout built the cart an answer named as still being built (`cart_building`). `text` gives the store's own total, and nothing is paid until the shopper says yes to it. |
 | `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. Their reply continues the cart. |
 | `cart_failed` | That checkout built no cart, and nothing was ordered or charged. |
+| `basket_approval` | Every store in a basket reached its payment step after the answer to the shopper's yes. `text` carries the one approval link for every seller, and each store charges separately. |
 
 Agentcard can add a kind later. A kind your code does not know still carries `text`, ready to send as is.
 

package/dist/basket.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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
+ * 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
+ * `basket_approval` purchase message.
+ */
+export type BuyBasketStatus = 'collecting' | 'awaiting_approval' | 'approved' | 'settling' | 'done' | 'expired' | 'declined';
+/**
+ * Where one seller's line stands: `parking` on its way to the store's payment step, `parked` there and in the approval,
+ * `left_out` asking its own approval, `approved`, `sent` (the card went to the store), `charged`, `needs_input` (the store
+ * asks more than the approval covers, and asks its own approval at the new total), `failed`, `released`.
+ */
+export type BuyBasketLineStatus = 'parking' | 'parked' | 'left_out' | 'approved' | 'sent' | 'charged' | 'needs_input' | 'failed' | 'released';
+export interface BuyBasketLine {
+    /** The seller as the shopper knows it: the store or the airline. */
+    seller: string;
+    status: BuyBasketLineStatus;
+    total_cents: number;
+    /** The most this seller may charge: its total_cents, since a seller is paid exactly the amount the shopper approved. */
+    cap_cents: number;
+}
+export interface BuyBasket {
+    id: string;
+    status: BuyBasketStatus;
+    total_cents: number;
+    /** The most every seller together may charge: total_cents, the sum of what each seller is paid. */
+    cap_cents: number;
+    currency: string;
+    approval_url: string | null;
+    expires_at: string;
+    lines: BuyBasketLine[];
+}
+/** The basket an answer carries, or null when it carries none, or one with a status or a line this version cannot read. */
+export declare function basketOf(v: unknown): BuyBasket | null;

package/dist/basket.js

@@ -0,0 +1,22 @@
+const BASKET_STATUSES = new Set(['collecting', 'awaiting_approval', 'approved', 'settling', 'done', 'expired', 'declined']);
+const LINE_STATUSES = new Set(['parking', 'parked', 'left_out', 'approved', 'sent', 'charged', 'needs_input', 'failed', 'released']);
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const whole = (v) => typeof v === 'number' && Number.isSafeInteger(v);
+/** The basket an answer carries, or null when it carries none, or one with a status or a line this version cannot read. */
+export function basketOf(v) {
+    if (!isRecord(v) || typeof v.id !== 'string' || typeof v.status !== 'string' || !Array.isArray(v.lines))
+        return null;
+    if (!whole(v.total_cents) || !whole(v.cap_cents) || typeof v.currency !== 'string' || typeof v.expires_at !== 'string')
+        return null;
+    if (!BASKET_STATUSES.has(v.status))
+        return null;
+    const lines = [];
+    // Every line or none: an app never shows fewer sellers than the approval covers.
+    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 });
+    }
+    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/buy-tool.d.ts

@@ -33,6 +33,7 @@
  */
 import type { BuyCardSize } from './card-size.js';
 import type { BuyPlan } from './plan.js';
+import type { BuyBasket } from './basket.js';
 import type { BuyMerchantStatusUpdate, BuySearchStatus } from './search-status.js';
 import { type BuyGroupsUpdate } from './search-groups.js';
 import type { BuyFreshness, BuyRecheck, BuyStoreCheckUpdate } from './client.js';
@@ -259,6 +260,8 @@ export interface BuyToolResult {
     cart_building?: BuyCartBuilding | null;
     /** The checkout plan the answer started or moved, such as a trip's flight, hotel and car with each one's state; null when none. */
     plan?: BuyPlan | null;
+    /** The basket the yes parked its carts into: one approval link for every seller, and each seller's line; null when none. */
+    basket?: BuyBasket | null;
     /** Every store the answer's searches asked and where each stands (`searchAt` narrows it to one store); null when it searched none. */
     search?: BuySearchStatus | null;
     /**

package/dist/buy-tool.js

@@ -337,6 +337,7 @@ function answerOf(turn) {
         choice: turn.choice ?? null,
         code_request: turn.code_request ?? null,
         plan: turn.plan ?? null,
+        basket: turn.basket ?? null,
         search: turn.search ?? null,
         envelope: turn.raw,
     };
@@ -372,6 +373,18 @@ function onlyNextStepLinks(result, next) {
     const links = result.links.filter((link) => (link.kind === 'vault' ? next === 'add_card' : link.kind === 'approval' ? next === 'approve' : true));
     return links.length === result.links.length ? result : { ...result, links };
 }
+/**
+ * The answer whose step is the approval it carries: an approval Agentcard already sent is the step the
+ * shopper takes now, so an answer that names another step names `approve` instead. The link is the one way
+ * to that approval, and the other step held it back and left the shopper with an address question and no
+ * link until the approval was about to expire (2026-11-04, an Amazon cart). An answer that names no step
+ * keeps naming none, as it always did.
+ */
+function approvalIsTheStep(result) {
+    if (result.status !== 'approval_sent' || !result.next_action || result.next_action === 'approve')
+        return result;
+    return result.links.some((link) => link.kind === 'approval') ? { ...result, next_action: 'approve' } : result;
+}
 /**
  * The answer's `messages`, read once its `reply` is final: the messages Agentcard sent while the reply
  * is still Agentcard's own, else the reply the tool wrote, each cut at its blank lines.
@@ -448,7 +461,8 @@ function askingForNamedStep(result, next) {
 }
 /** A purchase answer, read for its status. A status Agentcard adds later reads as `needs_input`. */
 function resultOfTurn(turn) {
-    return askingForNamedStep(onlyNextStepLinks(resultOfStatus(turn), turn.next_action), turn.next_action);
+    const sent = approvalIsTheStep(resultOfStatus(turn));
+    return askingForNamedStep(onlyNextStepLinks(sent, sent.next_action), sent.next_action);
 }
 /** A purchase answer, read for its status, with every link the answer carries. */
 function resultOfStatus(turn) {
@@ -456,6 +470,12 @@ function resultOfStatus(turn) {
     const card = needsCardOf(turn, answer);
     if (card)
         return card;
+    // A basket awaiting its one approval: that link is the step, for every seller at once, whatever the answer's status.
+    const basket = turn.basket;
+    if (basket && basket.status === 'awaiting_approval' && basket.approval_url) {
+        return { ...answer, status: 'approval_sent', next_action: 'approve', approval_expires_at: basket.expires_at,
+            links: [...answer.links, approvalLink(basket.approval_url, basket.expires_at, null)] };
+    }
     switch (turn.status) {
         case 'order_placed':
         case 'partially_placed':

package/dist/client.d.ts

@@ -10,6 +10,7 @@
  */
 import { type BuyTrip } from './trip.js';
 import { type BuyPlan } from './plan.js';
+import { type BuyBasket } from './basket.js';
 import { type BuyMerchantStatusUpdate, type BuySearchStatus } from './search-status.js';
 import { type BuyGroup, type BuyGroupsUpdate } from './search-groups.js';
 import { type BuyFulfilledBy } from './fulfilled-by.js';
@@ -731,6 +732,8 @@ export interface BuyTurn {
     choice: BuyChoice | null;
     /** The checkout plan this answer's yes started or moved, with each item's state; null when none, and on an older API. */
     plan: BuyPlan | null;
+    /** The basket this answer's yes parked its carts into, with its one approval link and each seller's line; null when none, and on an older API. */
+    basket: BuyBasket | null;
     /** Every store the turn searched and where each stands; null for a turn that searched none, and on an older API. */
     search: BuySearchStatus | null;
     /** The answer as Agentcard sent it. */

package/dist/client.js

@@ -10,6 +10,7 @@
  */
 import { tripOf } from './trip.js';
 import { planOf } from './plan.js';
+import { basketOf } from './basket.js';
 import { merchantStatusOf, searchOf } from './search-status.js';
 import { groupListOf, groupOf, groupsOf } from './search-groups.js';
 import { isRecord } from './verify.js';
@@ -405,6 +406,7 @@ export function turnOf(body) {
         cart_building: cartBuildingOf(body.cart_building),
         choice: choiceOf(body.choice),
         plan: planOf(body.plan),
+        basket: basketOf(body.basket),
         search: searchOf(body.search),
         raw: body,
     };

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS, type TurnStream, type Tu
 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 { basketOf, type BuyBasket, type BuyBasketLine, type BuyBasketLineStatus, type BuyBasketStatus } from './basket.js';
 export { tripOf, type BuyTrip, type TripLane, type TripLaneName, type TripLaneResult, type TripLaneStatus } from './trip.js';
 export { fulfilledByLine, fulfilledByOf, type BuyFulfilledBy, type BuyFulfilledByKind } from './fulfilled-by.js';
 export { cardSizeOf, type BuyCardSize } from './card-size.js';

package/dist/index.js

@@ -22,6 +22,7 @@ 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 { basketOf } from './basket.js';
 export { tripOf } from './trip.js';
 export { fulfilledByLine, fulfilledByOf } from './fulfilled-by.js';
 export { cardSizeOf } from './card-size.js';

package/dist/message.d.ts

@@ -25,8 +25,9 @@ import { type AgentcardEvent } from './verify.js';
  * - `cart_ready`: the store's checkout built the cart an answer named as still being built (`cart_building`), at the store's own total. Nothing is paid until the shopper says yes to it.
  * - `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.
+ * - `basket_approval`: every store in a basket reached its payment step after the answer to the shopper's yes; `text` carries the one approval link for every seller, and each store charges separately.
  */
-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';
+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' | 'basket_approval';
 /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.18.15",
+  "version": "0.18.16",
   "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",