@agent-cards/commerce-sdk 0.14.0 → 0.16.0

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;

package/dist/texting.js

@@ -0,0 +1,347 @@
+import { forModel, replyAsWritten as replyWithoutCardList } from './model-view.js';
+/** The mark every list line starts with. */
+const BULLET = '• ';
+/** A line that is a list item: `- `, `* `, `• `, `1. ` or `1) `, then text. The number, when it has one, is group 2. */
+const MARKED = /^(\s*)(?:[-*•]|(\d{1,2})[.)])\s+(?=\S)/;
+/** A line that leads into a list: it ends with a colon or a question mark, as `which bread do you want?` does. */
+const LEAD = /[:?]["')\]]*$/;
+/** A line indented under a list item, such as a description under its name: two spaces or a tab, then text. */
+const CONTINUATION = /^(?: {2,}|\t)\S/;
+/**
+ * A word whose period ends no sentence: a title or a short form such as `St.`, `Dr.`, `vs.` or `e.g.`, or initials
+ * such as `J.` or `U.S.`, so the word after it keeps its capital ("St. Louis", "Dr. Pepper").
+ */
+const ABBREVIATIONS = new Set(['st', 'dr', 'mr', 'mrs', 'ms', 'jr', 'sr', 'mt', 'ft', 'vs', 'e.g', 'i.e', 'etc']);
+const INITIALS = /^(?:[A-Za-z]\.)*[A-Z]$/;
+/** `No.` stands for a number before a digit, as in `No. 7`; anywhere else it is the answer "no" and ends its sentence. */
+const NUMBER_SIGN = /^no$/i;
+const DIGIT_NEXT = /^\s*\d/;
+/**
+ * True when `word`, read up to the period after it and the text `after` that period, is an abbreviation or initials
+ * rather than a sentence's last word.
+ */
+function isAbbreviation(word, after) {
+    const bare = word.replace(/^[^\p{L}]+/u, '');
+    if (NUMBER_SIGN.test(bare))
+        return DIGIT_NEXT.test(after);
+    return ABBREVIATIONS.has(bare.toLowerCase()) || INITIALS.test(bare);
+}
+/** At most this many characters and words make a line short enough to be a choice written on its own, with no marker. */
+const OPTION_CHARACTERS = 60;
+const OPTION_WORDS = 8;
+/**
+ * A line that is one choice written on its own, as a list of breads or times is written with no marker: short, and not
+ * the end of a sentence (`.`, `!`, `?`, `:` or `;`), so a line of prose never reads as one.
+ */
+function isOption(line) {
+    const text = line.trim();
+    return text !== '' && text.length <= OPTION_CHARACTERS && text.split(/\s+/).length <= OPTION_WORDS && !/[.!?:;]$/.test(text) && !MARKED.test(line);
+}
+/** The text with every list written as bullet lines, read by `options`. */
+function bulletLists(text, options = {}) {
+    const lines = text.split('\n');
+    // A marked list: two or more item lines, with only blank lines and lines indented under an item between them. An
+    // indented line, such as `  the chef's pick` under `- Sourdough`, stays as written under its item's bullet.
+    for (let start = 0; start < lines.length; start += 1) {
+        if (!MARKED.test(lines[start]))
+            continue;
+        const items = [start];
+        let end = start + 1;
+        while (end < lines.length) {
+            if (MARKED.test(lines[end]))
+                items.push(end);
+            else if (lines[end].trim() !== '' && !CONTINUATION.test(lines[end]))
+                break;
+            end += 1;
+        }
+        start = items[items.length - 1];
+        // One marked line is not a list, so it stays as written.
+        if (items.length < 2)
+            continue;
+        const numbered = items.some((i) => MARKED.exec(lines[i])[2] !== undefined);
+        if (numbered && options.keepNumbers?.(items.map((i) => lines[i].replace(MARKED, ''))))
+            continue;
+        for (const i of items)
+            lines[i] = lines[i].replace(MARKED, (_, indent) => `${indent}${BULLET}`);
+    }
+    // Choices with no marker: two or more short lines in a row right after a line that leads into them, such as the
+    // breads after `which bread do you want?`. Blank lines may sit between the lead and the first choice.
+    const runFrom = (first) => {
+        let end = first;
+        while (end < lines.length && isOption(lines[end]))
+            end += 1;
+        if (end - first < 2)
+            return;
+        for (let i = first; i < end; i += 1)
+            lines[i] = BULLET + lines[i].trim();
+    };
+    const nextWithWords = (from) => {
+        let i = from;
+        while (i < lines.length && lines[i].trim() === '')
+            i += 1;
+        return i;
+    };
+    if (options.leadIn)
+        runFrom(nextWithWords(0));
+    for (let i = 0; i < lines.length; i += 1) {
+        if (LEAD.test(lines[i].trim()))
+            runFrom(nextWithWords(i + 1));
+    }
+    return lines.join('\n');
+}
+/**
+ * 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 function asBullets(text) {
+    return bulletLists(text);
+}
+/**
+ * The text with the capital that opens each sentence after its first lowercased. A capital after an abbreviation or
+ * initials, such as `St. Louis` or `J. Crew`, is a name and stays.
+ */
+function sentenceStarts(text) {
+    let out = '';
+    let from = 0;
+    // The capital is looked ahead, never consumed, so `vs. Mt. Bachelor` reads `Mt.` as a word of its own.
+    for (const match of text.matchAll(/(\S*)([.!?])\s+(?=[A-Z][a-z])/g)) {
+        const at = match.index + match[0].length;
+        if (match[2] === '.' && isAbbreviation(match[1], text.slice(match.index + match[1].length + 1)))
+            continue;
+        out += text.slice(from, at) + text[at].toLowerCase();
+        from = at + 1;
+    }
+    return out + text.slice(from);
+}
+/** Each line in the texting style: the work of `textingStyle` on text whose lists are bullets already. */
+function styleLines(text) {
+    return text
+        .split('\n')
+        .map((raw) => {
+        const item = MARKED.test(raw);
+        const line = raw
+            .replace(/^\s*#{1,6}\s+/, '')
+            // A markdown marker on a line of its own goes; a bullet stays.
+            .replace(/^(\s*)[-*]\s+/, '$1')
+            .replace(/\*\*(.+?)\*\*|__(.+?)__/g, (_, a, b) => a ?? b ?? '')
+            .replace(/\s+[—–-]\s+/g, ', ')
+            .replace(/\s*—\s*/g, ', ')
+            .replace(/\bI(?=('(m|ll|ve|d))?\b)/g, 'i');
+        const marker = /^\s*(?:\d+[.)]\s+|•\s+)?/.exec(line)?.[0] ?? '';
+        const rest = sentenceStarts(line.slice(marker.length));
+        // A list line keeps its first word as written: it is usually a name, such as a product's or a store's. So does a
+        // line that opens with an abbreviation, such as `Mt. Hood`.
+        const opening = /^(\S*)\./.exec(rest);
+        return marker + (item || (opening !== null && isAbbreviation(opening[1], rest.slice(opening[0].length))) ? rest : rest.replace(/^([A-Z])(?=[a-z])/, (letter) => letter.toLowerCase()));
+    })
+        .join('\n')
+        .trim();
+}
+/**
+ * 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 function textingStyle(text) {
+    return styleLines(bulletLists(text));
+}
+/** A text's words, lowercased, letters and digits only. */
+function wordsOf(text) {
+    return text.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((word) => word !== '');
+}
+/**
+ * True when a list item names one of `names`, by the first four words of the name: two of them, and most of them, in
+ * the item, or the name's one word as the item's first.
+ */
+function namesOne(item, names) {
+    const said = wordsOf(item);
+    const set = new Set(said);
+    return names.some((name) => {
+        const head = name.slice(0, 4);
+        if (head.length === 1)
+            return said[0] === head[0];
+        const hits = head.filter((word) => set.has(word)).length;
+        return hits >= Math.max(2, Math.ceil(head.length * 0.6));
+    });
+}
+/**
+ * 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 function replyAsWritten(result, options = {}) {
+    const reply = replyWithoutCardList(result);
+    if (reply === null)
+        return null;
+    const view = forModel(result);
+    const names = [...view.products.map((product) => product.name), ...view.stores.map((store) => store.name)].map(wordsOf).filter((name) => name.length > 0);
+    const bulleted = withChoice(bulletLists(reply, { keepNumbers: (items) => items.some((item) => namesOne(item, names)) }), result.choice ?? null);
+    return (options.textingStyle ? styleLines(bulleted) : bulleted) || 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 function messageForShopper(text, leadIn, texting) {
+    const bulleted = bulletLists(text, { leadIn, keepNumbers: () => true });
+    return texting ? styleLines(bulleted) : bulleted;
+}
+/** True when a message ends in a colon or a question mark, so a list that opens the next one belongs to it. */
+export function leadsIntoList(text) {
+    return LEAD.test(text.trim());
+}
+/** A label as plain words: lowercase letters and digits, one space between words. */
+const plainLabel = (text) => text.toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+/** A value's extra price as a shopper reads it after the value: ` (+$2.46)`, nothing when it is free or not known. */
+const extraPrice = (cents) => (cents && cents > 0 ? ` (+$${(cents / 100).toFixed(2)})` : '');
+/**
+ * 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 function choiceLines(choice) {
+    const groups = choice.groups.filter((group) => group.options.length > 0);
+    return groups
+        .flatMap((group) => [
+        ...(groups.length > 1 && group.name ? [`${group.name}:`] : []),
+        ...group.options.map((option) => `${BULLET}${option.label}${extraPrice(option.price_delta_cents)}`),
+    ])
+        .join('\n');
+}
+/** A value's extra price as its line names it: "2.46" for 246 cents; null when it is free or not known. */
+const priceWords = (cents) => (cents && cents > 0 ? (cents / 100).toFixed(2) : null);
+/**
+ * How `text` lists the choice's values: each value's own line (a list marker before it allowed), the values no line holds, and
+ * the lines of priced values that leave their extra price out. A line belongs to the one value whose label it opens with, the
+ * longest such label, so `• 7.5` is the line of 7.5 and never of 7.
+ */
+function choiceListing(text, choice) {
+    const raw = text.split('\n');
+    // Short lines in a row after a question are a list too (bulletLists), whether or not they carry a marker.
+    const read = bulletLists(text, { keepNumbers: () => true }).split('\n');
+    const lines = raw.map((line) => plainLabel(line.replace(MARKED, '')));
+    const options = choice.groups.flatMap((group, g) => group.options.map((option) => ({ group: g, option, label: plainLabel(option.label), price: priceWords(option.price_delta_cents) })));
+    const owner = lines.map((line, n) => {
+        const marked = MARKED.test(read[n] ?? raw[n]);
+        let best = -1;
+        options.forEach((option, i) => {
+            // A list line may say more after its value (a price, a note); a line of prose that only opens with a value is no list
+            // line. An unmarked line that is the value alone, or the value and its price, is one.
+            const listLine = marked || line === option.label || (!!option.price && line === `${option.label} ${plainLabel(option.price)}`);
+            if (option.label && listLine && (line === option.label || line.startsWith(`${option.label} `)) && (best < 0 || option.label.length > options[best].label.length))
+                best = i;
+        });
+        return best;
+    });
+    const unpriced = [];
+    options.forEach((option, i) => {
+        const line = owner.indexOf(i);
+        if (line >= 0 && option.price && !raw[line].includes(option.price))
+            unpriced.push({ line, price: option.price });
+    });
+    const lastLine = Math.max(-1, ...owner.map((o, line) => (o >= 0 ? line : -1)));
+    // Each value no line holds goes after the last listed value of its own group; a group none of whose values is listed follows
+    // the whole list, led by its name when the choice has more than one group.
+    const insertions = [];
+    let missing = 0;
+    choice.groups.forEach((group, g) => {
+        const absent = options.filter((option, i) => option.group === g && !owner.includes(i));
+        if (!absent.length)
+            return;
+        missing += absent.length;
+        const bullets = absent.map(({ option }) => `${BULLET}${option.label}${extraPrice(option.price_delta_cents)}`);
+        const own = Math.max(-1, ...owner.map((o, line) => (o >= 0 && options[o].group === g ? line : -1)));
+        insertions.push(own >= 0 ? { after: own, lines: bullets } : { after: lastLine, lines: [...(choice.groups.length > 1 && group.name ? [`${group.name}:`] : []), ...bullets] });
+    });
+    return { missing, lastLine, insertions, unpriced };
+}
+/** True when every value of the choice has a line of its own in `text`, each priced one naming its extra price. */
+function listsChoiceWithPrices(text, choice) {
+    const listing = choiceListing(text, choice);
+    return listing.missing === 0 && listing.unpriced.length === 0;
+}
+/**
+ * The text less a bracket that holds nothing but the choice's values, such as a store's "(Size: 3 oz, 4.375 oz, 8.375 oz)":
+ * the values go under the question instead, so the shopper never reads them twice. A bracket whose values follow anything but a
+ * group's name, such as "(Choose up to 2: Garlic, Herb)", keeps what it says about the choice and stays.
+ */
+function withoutInlineValues(text, choice) {
+    const labels = new Set(choice.groups.flatMap((group) => group.options.map((option) => plainLabel(option.label))));
+    const groupNames = new Set(choice.groups.map((group) => plainLabel(group.name)));
+    return text.replace(/\s*\(([^()\n]*)\)/g, (whole, inside) => {
+        const parts = inside.split(/;\s*/).map((part) => /^([^:,]{1,40}):\s*(.*)$/.exec(part) ?? [part, null, part]);
+        if (parts.some(([, lead]) => lead != null && !groupNames.has(plainLabel(lead))))
+            return whole;
+        const values = parts.flatMap(([, , rest]) => (rest ?? '').split(/,\s*(?:or\s+|and\s+)?|\s+(?:or|and)\s+/))
+            .map((value) => value.trim()).filter((value) => value !== '' && value !== '…' && value !== '...');
+        return values.length >= 2 && values.every((value) => labels.has(plainLabel(value))) ? '' : whole;
+    });
+}
+/**
+ * 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 function withChoice(text, choice) {
+    if (!choice || !choice.groups.some((group) => group.options.length > 0))
+        return text;
+    const listing = choiceListing(text, choice);
+    if (listing.lastLine >= 0) {
+        // Some values have their line already: a priced one that leaves its price out gets it at the line's end, and the values
+        // no line holds follow the last listed value of their own group, so the list is whole and none is read twice.
+        if (!listing.missing && !listing.unpriced.length)
+            return text;
+        const listed = text.split('\n');
+        for (const { line, price } of listing.unpriced)
+            listed[line] = `${listed[line].trimEnd()} (+$${price})`;
+        // From the bottom up, so each insertion leaves the lines above it where they were; at one place, in the groups' order.
+        for (const { after, lines } of [...listing.insertions].reverse().sort((x, y) => y.after - x.after))
+            listed.splice(after + 1, 0, ...lines);
+        return listed.join('\n');
+    }
+    const lines = withoutInlineValues(text, choice).split('\n');
+    const question = choice.question?.trim();
+    let at = question ? lines.findIndex((line) => line.includes(question)) : -1;
+    for (let i = lines.length - 1; at < 0 && i >= 0; i -= 1)
+        if (lines[i].includes('?'))
+            at = i;
+    if (at < 0)
+        at = lines.length - 1;
+    lines.splice(at + 1, 0, choiceLines(choice));
+    return lines.join('\n');
+}
+/** True when the shopper's messages already list every value of the choice one per line, each priced one with its extra price. */
+export function messagesListChoice(messages, choice) {
+    return listsChoiceWithPrices(messages.map((message) => bulletLists(message, { leadIn: true, keepNumbers: () => true })).join('\n'), choice);
+}

package/package.json

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