@agent-cards/commerce-sdk 0.15.0 → 0.16.0

package/dist/order.js

@@ -0,0 +1,155 @@
+/**
+ * Where a shopper's order is, read from the messages Agentcard sends about it, for an app that draws
+ * an order tracker instead of a line of text. `readShopperMessage` puts it on `message.order`;
+ * `updateOrder` folds the next message about the same order into the one a tracker shows, and
+ * `arrivalText` writes the arrival line. No import reaches outside the package, so the browser entry
+ * carries this file too.
+ */
+/** The steps a tracker draws, left to right. An order that ends early reads `canceled` or `failed`. */
+export const ORDER_STEPS = ['placed', 'confirmed', 'preparing', 'on_the_way', 'delivered'];
+const LABELS = {
+    placed: 'Placed',
+    confirmed: 'Accepted',
+    preparing: 'Preparing',
+    on_the_way: 'On the way',
+    delivered: 'Delivered',
+    canceled: 'Canceled',
+    failed: 'Failed',
+};
+/**
+ * The step each delivery stage of `order.updated` reads as. The store accepting the order is
+ * `confirmed`; a driver being found, waiting at the store or the order being ready is `preparing`;
+ * the order picked up or nearby is `on_the_way`.
+ */
+const STAGE_STEPS = {
+    placed: 'placed',
+    confirmed: 'confirmed',
+    courier_assigned: 'preparing',
+    courier_at_store: 'preparing',
+    ready_for_pickup: 'preparing',
+    picked_up: 'on_the_way',
+    arriving: 'on_the_way',
+    delivered: 'delivered',
+    canceled: 'canceled',
+};
+/** The step an `order.updated` stage reads as, or null for a stage the package does not know. */
+export function orderStepOf(stage) {
+    return (stage && STAGE_STEPS[stage]) || null;
+}
+const RANK = { placed: 0, confirmed: 1, preparing: 2, on_the_way: 3, delivered: 4, canceled: 5, failed: 5 };
+/**
+ * The tracker's steps. An order at a step has passed every step before it. A canceled order has
+ * passed the step it was canceled at, `reached`, and a failed one passed none.
+ */
+function stepsOf(step, reached) {
+    const ended = step === 'canceled' || step === 'failed';
+    const at = ended ? (reached && reached !== 'canceled' && reached !== 'failed' ? RANK[reached] : step === 'canceled' ? 0 : -1) : RANK[step];
+    return ORDER_STEPS.map((s) => ({
+        step: s,
+        label: LABELS[s],
+        state: RANK[s] < at || (ended && RANK[s] === at) ? 'done' : RANK[s] === at ? 'current' : 'upcoming',
+    }));
+}
+/** The order a message describes, from the values it names. */
+export function orderFrom(fields) {
+    const earliest = fields.arrivalEarliest ?? null;
+    const latest = fields.arrivalLatest ?? null;
+    return {
+        orderId: fields.orderId ?? null,
+        merchantName: fields.merchantName ?? null,
+        storeName: fields.storeName ?? null,
+        step: fields.step,
+        label: LABELS[fields.step],
+        steps: stepsOf(fields.step, fields.reached ?? null),
+        title: fields.title ?? null,
+        detail: fields.detail ?? null,
+        arrival: earliest || latest ? { earliest, latest } : null,
+        deliveryWindow: fields.deliveryWindow ?? null,
+        totalCents: fields.totalCents ?? null,
+        currency: fields.currency ?? null,
+        retailerOrderId: fields.retailerOrderId ?? null,
+        deliveredAt: fields.deliveredAt ?? null,
+        reason: fields.reason ?? null,
+        updatedAt: fields.updatedAt,
+    };
+}
+/** Values that stay true of an order whatever step it reaches. */
+const LASTING = ['orderId', 'merchantName', 'storeName', 'totalCents', 'currency', 'retailerOrderId', 'deliveryWindow'];
+/**
+ * The order a tracker shows once `next` arrives, for two messages about the same order. The order
+ * never moves back a step: Agentcard delivers each message at least once and in no set order, so a
+ * late `order.confirmed` after the driver picked the order up leaves the tracker at `on_the_way`. At
+ * the same step, the message with the later `updatedAt` wins. A value the shown message lacks, such
+ * as the total `order_placed` named or the restaurant `order.updated` named, comes from the other,
+ * and so does the store's line when both are at the same step. An arrival estimate holds until the
+ * order is delivered, canceled or failed.
+ *
+ * ```ts
+ * trackers.set(order.orderId, updateOrder(trackers.get(order.orderId), order));
+ * ```
+ */
+export function updateOrder(previous, next) {
+    if (!previous)
+        return next;
+    const diff = RANK[next.step] - RANK[previous.step];
+    const newer = diff !== 0 ? diff > 0 : !(Date.parse(next.updatedAt) < Date.parse(previous.updatedAt));
+    const [shown, other] = newer ? [next, previous] : [previous, next];
+    const merged = { ...shown };
+    for (const key of LASTING)
+        if (merged[key] === null)
+            merged[key] = other[key];
+    if (shown.step === other.step) {
+        merged.title ??= other.title;
+        merged.detail ??= other.detail;
+    }
+    // An arrival estimate holds until the order arrives, whichever step quoted it.
+    if (shown.step !== 'delivered' && shown.step !== 'canceled' && shown.step !== 'failed')
+        merged.arrival ??= other.arrival;
+    return merged;
+}
+function validDate(value) {
+    if (!value)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/**
+ * The line a tracker writes under the steps about when the order arrives, in the shopper's time zone,
+ * or null when Agentcard sent no time for it:
+ *
+ * - `Arriving 12:04 – 12:22 PM` from the store's estimate, with the weekday when it is not today;
+ * - `Arriving by 12:22 PM` when the estimate names only its latest time;
+ * - `Expected Sat, Sep 6 - Tue, Sep 9` from a retailer's delivery window;
+ * - `Delivered at 12:20 PM` once delivered.
+ *
+ * A canceled or failed order has no arrival line.
+ */
+export function arrivalText(order, options = {}) {
+    const locale = options.locale ?? 'en-US';
+    const now = new Date(options.now ?? Date.now());
+    const time = (date) => {
+        const day = (d) => new Intl.DateTimeFormat(locale, { timeZone: options.timeZone, year: 'numeric', month: 'numeric', day: 'numeric' }).format(d);
+        const today = day(date) === day(now);
+        return new Intl.DateTimeFormat(locale, { timeZone: options.timeZone, hour: 'numeric', minute: '2-digit', ...(today ? {} : { weekday: 'short' }) });
+    };
+    if (order.step === 'canceled' || order.step === 'failed')
+        return null;
+    if (order.step === 'delivered') {
+        const at = validDate(order.deliveredAt);
+        return at ? `Delivered at ${time(at).format(at)}` : 'Delivered';
+    }
+    const earliest = validDate(order.arrival?.earliest);
+    const latest = validDate(order.arrival?.latest);
+    if (earliest && latest && earliest.getTime() < latest.getTime()) {
+        const format = time(earliest);
+        const range = typeof format.formatRange === 'function' ? format.formatRange(earliest, latest) : `${format.format(earliest)} – ${format.format(latest)}`;
+        return `Arriving ${range}`;
+    }
+    if (latest)
+        return `Arriving by ${time(latest).format(latest)}`;
+    if (earliest)
+        return `Arriving around ${time(earliest).format(earliest)}`;
+    if (order.deliveryWindow)
+        return `Expected ${order.deliveryWindow}`;
+    return null;
+}

package/dist/sentences.d.ts

@@ -0,0 +1,3 @@
+export declare const SENTENCE_END: RegExp;
+/** Where the last sentence of `text` begins: 0 when the text is one sentence. */
+export declare function lastSentenceStart(text: string): number;

package/dist/sentences.js

@@ -0,0 +1,29 @@
+/**
+ * Where one sentence of Agentcard's words ends and the next begins: the space after a full stop, a question mark or an
+ * exclamation mark. A stop that ends a short form or an initial ends no sentence, so `Mr. Coffee`, `Dr. Pepper`,
+ * `St. Louis`, `J. Crew`, `U.S. Polo`, `e.g. a mug`, `Acme Inc. mugs` and `No. 7` each stay in one sentence. A price
+ * (`$24.99`), a size (`8.5`) and a domain (`target.com`) carry no space after their stop, so they end none either.
+ *
+ * On 2026-10-27 a reply that led into its list with `target has two colors of the Mr. Coffee Retro Brew French Press:`
+ * reached the shopper as `target has two colors of the Mr.`: the stop after `Mr` was read as a sentence's end.
+ */
+const SHORT_FORMS = ['mr', 'mrs', 'ms', 'dr', 'st', 'jr', 'sr', 'mt', 'ft', 'vs', 'inc', 'co', 'ltd', 'e.g', 'i.e'];
+const anyCase = (word) => word.replace(/[a-z]/g, (letter) => `[${letter}${letter.toUpperCase()}]`).replace(/\./g, '\\.');
+/** What comes before a letter that is a size, not an initial: `size `, `sizes `, `in `, `and `, `or `, or another size and a comma. */
+const NOT_A_SIZE = '(?<!(?:\\b(?:[Ss]izes?|in|and|or)|\\b[A-Z]{1,3},)\\s)';
+export const SENTENCE_END = new RegExp([
+    '(?<=[.!?])',
+    `(?<!(?:^|[^\\p{L}.])(?:${SHORT_FORMS.map(anyCase).join('|')})\\.)`,
+    // An initial, or initials such as `U.S.`, written as capitals. A size, `size S.` or `in S, M and L.`, is no initial.
+    `(?<!(?:^|[^\\p{L}])${NOT_A_SIZE}(?:\\p{L}\\.)*\\p{Lu}\\.)`,
+    // `No.` stands for a number before a digit; anywhere else it is the answer "no".
+    '(?!(?<=(?:^|[^\\p{L}])[Nn][Oo]\\.)\\s+\\d)',
+    '\\s+',
+].join(''), 'u');
+/** Where the last sentence of `text` begins: 0 when the text is one sentence. */
+export function lastSentenceStart(text) {
+    let start = 0;
+    for (const end of text.matchAll(new RegExp(SENTENCE_END.source, 'gu')))
+        start = end.index + end[0].length;
+    return start;
+}

package/dist/shopper-message.d.ts

@@ -5,6 +5,7 @@
  */
 import { type AgentcardEvent } from './verify.js';
 import { type PurchaseFacts, type PurchaseMessageKind } from './message.js';
+import { type ShopperOrder } from './order.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.
@@ -36,6 +37,8 @@ export type ShopperMessageKind = PurchaseMessageKind | 'order_confirmed' | 'orde
 export interface ShopperFacts extends PurchaseFacts {
     /** The retailer's own order number, as on its confirmation and account page. */
     retailerOrderId?: string;
+    /** The place the order comes from, such as the restaurant on DoorDash, when Agentcard names it. */
+    storeName?: string;
     /** The retailer's quoted delivery window, in its own words. */
     deliveryWindow?: string;
     /** The order's delivery stage. */
@@ -74,6 +77,13 @@ 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;
+    /**
+     * Where the order is, for a message about an order a tracker can show: `order_placed`,
+     * `order_failed`, `order_confirmed`, and `order_updated` at a stage the package knows. Null for
+     * every other message. Keep one tracker per `order.orderId` and fold each new one in with
+     * `updateOrder`, so successive messages move one tracker instead of adding lines.
+     */
+    order: ShopperOrder | null;
     /**
      * 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

package/dist/shopper-message.js

@@ -5,6 +5,7 @@
  */
 import { isRecord } from './verify.js';
 import { readPurchaseMessage } from './message.js';
+import { orderFrom, orderStepOf } from './order.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.
@@ -30,6 +31,8 @@ function text(value, max = 200) {
 function id(value) {
     return typeof value === 'string' && value !== '' ? value : undefined;
 }
+/** Unix seconds as an ISO 8601 timestamp. */
+const isoOf = (created) => new Date(created * 1000).toISOString();
 function count(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
@@ -101,12 +104,18 @@ function readOrderConfirmed(event) {
     const deliveryWindow = text(data.delivery_window, 80);
     const facts = present({
         merchantName: store ?? undefined,
+        storeName: text(data.store_name, 64),
         totalCents: count(data.final_total_cents) ?? count(data.charged_cents),
         currency: text(data.currency, 8),
         orderId: id(data.order_id),
         retailerOrderId,
         deliveryWindow,
     });
+    const order = orderFrom({
+        ...facts,
+        step: 'confirmed',
+        updatedAt: text(data.confirmed_at, 40) ?? isoOf(event.created),
+    });
     const who = store ? `${store} confirmed your order` : 'The store confirmed your order';
     return {
         ...base,
@@ -117,6 +126,7 @@ function readOrderConfirmed(event) {
             `${retailerOrderId ? ` The store's order number is ${retailerOrderId}.` : ''}` +
             `${deliveryWindow ? ` The store quotes delivery ${deliveryWindow}.` : ''} ${SYSTEM_LINE}]`,
         facts,
+        order,
     };
 }
 function readOrderUpdated(event) {
@@ -134,6 +144,30 @@ function readOrderUpdated(event) {
         return null;
     const arrival = isRecord(data.estimated_arrival) ? data.estimated_arrival : {};
     const previous = text(data.previous_status, 40);
+    const facts = present({
+        merchantName: store ?? undefined,
+        storeName: text(data.store_name, 64),
+        orderId: id(data.order_id),
+        orderStatus: status,
+        previousOrderStatus: previous,
+        statusTitle,
+        arrivalEarliest: text(arrival.earliest, 40),
+        arrivalLatest: text(arrival.latest, 40),
+        deliveredAt: text(data.delivered_at, 40),
+        canceledReason,
+    });
+    const step = orderStepOf(status);
+    const order = step
+        ? orderFrom({
+            ...facts,
+            step,
+            reached: orderStepOf(previous),
+            title: statusTitle,
+            detail: text(data.status_detail, 200),
+            reason: canceledReason,
+            updatedAt: text(data.updated_at, 40) ?? isoOf(event.created),
+        })
+        : null;
     return {
         ...base,
         kind: 'order_updated',
@@ -142,17 +176,8 @@ function readOrderUpdated(event) {
         note: `[event: this user's order${store ? ` at ${store}` : ''} moved to the stage ${status}` +
             `${previous ? ` from ${previous}` : ''}, outside this conversation.` +
             `${statusTitle ? ` The store says: ${statusTitle}.` : ''}${canceledReason ? ` The store's reason: ${canceledReason}.` : ''} ${SYSTEM_LINE}]`,
-        facts: present({
-            merchantName: store ?? undefined,
-            orderId: id(data.order_id),
-            orderStatus: status,
-            previousOrderStatus: previous,
-            statusTitle,
-            arrivalEarliest: text(arrival.earliest, 40),
-            arrivalLatest: text(arrival.latest, 40),
-            deliveredAt: text(data.delivered_at, 40),
-            canceledReason,
-        }),
+        facts,
+        order,
     };
 }
 /**
@@ -174,8 +199,23 @@ export function readShopperMessage(event) {
         type: 'purchase.message',
         conversationId: id(event.data.conversation_id) ?? null,
         advances: NEXT_STEP.has(message.kind),
+        order: purchaseOrder(message.kind, message.facts, event.created),
     };
 }
+/** The order an `order_placed` or `order_failed` message describes; null for every other kind. */
+function purchaseOrder(kind, facts, created) {
+    if (kind !== 'order_placed' && kind !== 'order_failed')
+        return null;
+    return orderFrom({
+        orderId: facts.orderId,
+        merchantName: facts.merchantName,
+        totalCents: facts.totalCents,
+        currency: facts.currency,
+        step: kind === 'order_placed' ? 'placed' : 'failed',
+        reason: kind === 'order_failed' ? facts.reason : undefined,
+        updatedAt: isoOf(created),
+    });
+}
 /**
  * Whether the message stopped holding before `now` (unix milliseconds, default the system clock):
  * the link or the window its text names has closed. Drop a stale message instead of sending it.

package/dist/texting.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Agentcard's words as a chat shows them: every list as bullet lines that start with `• `, and, for an app that asks,
+ * the texting style a chat writes in. The reply a turn hands out as written (`replyAsWritten`) and each message
+ * `onText` hears come through here, so an app shows them with no formatting of its own.
+ */
+import type { BuyToolResult } from './buy-tool.js';
+import type { BuyChoice } from './client.js';
+/**
+ * The text with every list written as bullet lines that start with `• `: lines marked `- `, `* `, `• `, `1. ` or
+ * `1) `, and two or more short lines in a row that follow a line ending in `:` or `?`, such as the choices of bread
+ * after `which bread do you want?`. A list's lead-in line stays, and so does prose. One line on its own is no list.
+ *
+ * ```ts
+ * asBullets('which bread do you want?\n\nSourdough\nWhole wheat'); // 'which bread do you want?\n\n• Sourdough\n• Whole wheat'
+ * ```
+ */
+export declare function asBullets(text: string): string;
+/**
+ * The text in a chat's texting style: every list as `• ` bullet lines (`asBullets`), no other markdown (headings, bold,
+ * a lone `- ` or `* ` marker), no spaced dashes, which become commas, and lowercase at the start of each sentence and
+ * for "I". A capital inside a sentence is a name and stays, and so does an all-caps word such as "USB". A list line
+ * keeps its first word as written, since it is usually a product's or a store's name.
+ *
+ * ```ts
+ * textingStyle('Here are two — both ship today. Which one?\n- Anker cable\n- Onn cable');
+ * // 'here are two, both ship today. which one?\n• Anker cable\n• Onn cable'
+ * ```
+ */
+export declare function textingStyle(text: string): string;
+/** Options for `replyAsWritten`. */
+export interface ReplyAsWrittenOptions {
+    /** `true` writes the reply in the texting style (`textingStyle`): lowercase sentence starts, no markdown, no spaced dashes, `• ` bullets kept. */
+    textingStyle?: boolean;
+}
+/**
+ * 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 size, a bread 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, without the list of products or stores whose cards
+ * went out (`withoutCardList`), and with every list left in it as `• ` bullet lines (`asBullets`). A numbered list
+ * that names the answer's products or stores keeps its numbers, because the shopper picks from it by number ("number
+ * 6"), and Agentcard and `directCall` read that number against the list. Null for any other answer, which your model
+ * puts in its own words, for a line the tool wrote itself for your model, and once the shopper read the reply through
+ * `onText` (`shopper_already_read_reply`). `{ textingStyle: true }` hands it over in the texting style (`textingStyle`).
+ *
+ * ```ts
+ * replyAsWritten(result); // 'which bread do you want?\n\n• Sourdough\n• Whole wheat'
+ * ```
+ */
+export declare function replyAsWritten(result: BuyToolResult, options?: ReplyAsWrittenOptions): string | null;
+/**
+ * One message of Agentcard's, as `onText` hands it to the app: its lists as `• ` bullet lines and, with `texting`, in
+ * the texting style. A numbered list keeps its numbers, since a streamed message still lists the products its cards
+ * show and the shopper may pick one by its number. `leadIn` says the message before it ended in a colon or a question
+ * mark, so the choices that open this one are that question's list.
+ */
+export declare function messageForShopper(text: string, leadIn: boolean, texting: boolean): string;
+/** True when a message ends in a colon or a question mark, so a list that opens the next one belongs to it. */
+export declare function leadsIntoList(text: string): boolean;
+/**
+ * A choice's values as the shopper reads them, one `• ` line each with its extra price after it: `• Gluten-free bread
+ * (+$2.46)`. A choice of more than one group leads each group's lines with its name, as `Size:`.
+ *
+ * ```ts
+ * choiceLines(result.choice!); // '• Ciabatta\n• Sourdough\n• Gluten-free bread (+$2.46)'
+ * ```
+ */
+export declare function choiceLines(choice: BuyChoice): string;
+/**
+ * The text with the choice's values listed one per line (choiceLines) under the line that asks the question, when the text
+ * does not list them already: Agentcard's reply may name them inside a sentence, as "i can also do sourdough, whole wheat,
+ * or gluten-free bread for $2.46 more" did. A bracket that holds only the values goes, since the list replaces it. A text
+ * that asks nothing gets the list at its end. When every value already opens a line, a priced one that leaves its price out
+ * gets it at the end of its line, and the text is otherwise as it is, as it is with no choice.
+ *
+ * ```ts
+ * withChoice('which bread do you want?', result.choice); // 'which bread do you want?\n• Ciabatta\n• Sourdough'
+ * ```
+ */
+export declare function withChoice(text: string, choice: BuyChoice | null): string;
+/** True when the shopper's messages already list every value of the choice one per line, each priced one with its extra price. */
+export declare function messagesListChoice(messages: readonly string[], choice: BuyChoice): boolean;