@agent-cards/commerce-sdk 0.14.0 → 0.16.0

package/dist/model-view.js

@@ -1,3 +1,4 @@
+import { SENTENCE_END, lastSentenceStart } from './sentences.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']);
 const MODEL_STATUSES = new Set(['needs_input', 'needs_card', 'approval_sent', 'placing', 'order_placed', 'declined']);
@@ -59,6 +60,24 @@ export function stripLinks(text) {
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
+/**
+ * A line that points at a link with a colon, the link after it on the same line or alone on the next: `here's the stool on
+ * Wayfair: https://www.wayfair.com/...`, one in angle brackets, or a bare address with a path or query (`vault.agentcard.sh?token=...`,
+ * never a bare `www.walmart.com`, which stripLinks keeps as the store's name). Every such
+ * link comes out of what the shopper reads (stripLinks), and the colon would then point at nothing. A Markdown link is not one:
+ * stripLinks keeps its label, which the shopper reads after the colon. A question mark that ends the sentence is not a query,
+ * as HOST_PATH reads it (`Buy from: glossier.com?`), and a page whose path ends in a bracket keeps it (`stool_(oak)`).
+ */
+const POINTS_AT_LINK = /^([^\n]*?\S)[ \t]*:[ \t]*(?:\n[ \t]*)?<?(?:https?:\/\/|(?:www\.)?(?:[\p{L}\p{N}-]+\.)+\p{L}{2,}(?:[/#]|\?(?![.,;:!?]*(?:[\s<>"'`)\]]|$))))[^\s<>"'`\]]*>?[ \t]*[.!]?[ \t]*$/gimu;
+/**
+ * Agentcard's reply as the shopper and the model read it, with every link taken out (stripLinks) and no line left pointing at
+ * 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.
+ */
+export function replyWithoutLinks(reply, sent) {
+    return stripLinks(String(reply ?? '').replace(POINTS_AT_LINK, (_line, lead) => (sent ? `${lead}.` : '')));
+}
 /** A currency's minor units as Intl knows them: 2 for USD and CAD, 0 for JPY. */
 function minorUnits(format) {
     return format.resolvedOptions().maximumFractionDigits ?? 0;
@@ -135,13 +154,14 @@ export function cardKey(product) {
 }
 /**
  * The key of the card a product gets, or null when it gets none: a product with a page at its store,
- * or a flight option, which has no page, with an id a pick takes. A flight's card is how the shopper
- * taps the flight they want (2026-10-20: three flights listed in text, and no card to tap).
+ * or a flight option or a place to book, which can have no page, with an id a pick takes. A flight's card
+ * is how the shopper taps the flight they want (2026-10-20: three flights listed in text, and no card to tap),
+ * and a place's card is where the shopper reads whether it has room.
  */
 export function productCardKey(product) {
     if (typeof product.url === 'string' && product.url !== '')
         return cardKey(product);
-    return product.flight ? pickId(product) : null;
+    return product.flight || product.availability ? pickId(product) : null;
 }
 function cartView(cart) {
     return {
@@ -218,7 +238,11 @@ export function forModel(result) {
         status,
         next_action: result.next_action ?? null,
         ...(result.cart_building ? { cart_building: { store: stripLinks(result.cart_building.store) } } : {}),
-        reply: stripLinks(result.reply),
+        ...(result.choice ? { choice: {
+                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),
         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: productPrice(product), link_sent: held(product) })),
@@ -242,8 +266,73 @@ export function forModel(result) {
         store_pick: result.store_pick && stripLinks(result.store_pick.store_id) === result.store_pick.store_id
             ? { store_id: result.store_pick.store_id, selected: result.store_pick.selected === true }
             : null,
+        ...(yesCarriedView(result) ? { yes_carried: yesCarriedView(result) } : {}),
     };
 }
+/** The yes an answer went ahead on, as the model reads it, or null. */
+function yesCarriedView(result) {
+    const yes = result.yes_carried;
+    if (!yes || typeof yes.said_yes_to_cents !== 'number' || typeof yes.total_cents !== 'number')
+        return null;
+    const said = money(yes.said_yes_to_cents, yes.currency);
+    const total = money(yes.total_cents, yes.currency);
+    return said && total ? { said_yes_to: said, total, total_changed: yes.said_yes_to_cents !== yes.total_cents, ...(yes.picked === true ? { picked: true } : {}) } : null;
+}
+/** The link each step's ask goes with. */
+const STEP_LINK = { add_card: 'vault', approve: 'approval', store_login: 'store_login' };
+/** The items of a cart in one line, such as `1 Chicken Salad` or `2 tacos and 1 horchata`. */
+function itemsLine(cart) {
+    const lines = cart.items.map((line) => `${line.qty} ${line.name}`);
+    return lines.length <= 1 ? (lines[0] ?? '') : `${lines.slice(0, -1).join(', ')} and ${lines[lines.length - 1]}`;
+}
+/** A cart's total as the shopper reads it: `$17.43`, or `about $15.90 before tax and shipping or delivery` for an estimate. */
+function totalLine(cart) {
+    if (!cart.total_is_estimate)
+        return cart.total;
+    const before = cart.total_leaves_out ? ` before ${cart.total_leaves_out.replace(/,.*$/, '')}` : '';
+    return `about ${cart.total}${before}`;
+}
+/**
+ * The fixed short line for an answer whose next step is a link the shopper already holds: `add your card to place the
+ * order`, `sign in to DoorDash to place your order`, or `approve the payment to place your order (up to $19.02)`, with
+ * the most the shopper can be charged in the parentheses when the cart names it. After the shopper's own words put the
+ * cart together, a line about the cart comes first, as its own message. After a yes the turn carried past a step outside
+ * the chat, a total that changed opens the ask: `it's $17.89 with fees and tax now. approve the payment ...`. Null for any
+ * other answer, when the link did not go out, when the shopper already read Agentcard's own ask through `onText`, when a
+ * card or approval step has no cart to place, and when the answer also showed products.
+ */
+export function stepAsWritten(result) {
+    if (result.shopper_already_read_reply === true || result.link_sent !== true)
+        return null;
+    const next = result.next_action ?? '';
+    const kind = STEP_LINK[next];
+    const link = kind ? (result.links ?? []).find((l) => l.kind === kind && typeof l.url === 'string' && l.url !== '') : undefined;
+    if (!kind || !link)
+        return null;
+    const view = forModel(result);
+    const cart = view.cart;
+    // The line is about placing an order: an answer with no cart to place, such as the card link the shopper asked for while
+    // browsing, or one that also showed products the reply talks about, is the model's to word.
+    if ((!cart && next !== 'store_login') || view.products.length > 0)
+        return null;
+    const store = stripLinks(link.store ?? '') || cart?.store || 'the store';
+    const ask = next === 'add_card'
+        ? 'add your card to place the order'
+        : next === 'store_login'
+            ? `sign in to ${store} to place your order`
+            : `approve the payment to place your order${cart?.max_charge ? ` (up to ${cart.max_charge})` : ''}`;
+    const yes = view.yes_carried;
+    if (yes?.total_changed && cart) {
+        const total = cart.total_is_estimate ? `about ${cart.total}` : `${cart.total} with fees and tax`;
+        return `it's ${total} now. ${ask}`;
+    }
+    // Only the shopper's own words that built the cart get a line about it first; after a yes or a saved card, the ask is the whole message.
+    const agentcards = typeof result.envelope?.reply === 'string' && result.envelope.reply === result.reply;
+    if (agentcards && result.confirm_sent !== true && !yes && cart && cart.items.length > 0 && next !== 'approve') {
+        return `${itemsLine(cart)} from ${cart.store}, ${totalLine(cart)}\n\n${ask}`;
+    }
+    return ask;
+}
 /**
  * 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
@@ -252,6 +341,8 @@ export function forModel(result) {
  * 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.
  * Null as well once the shopper read the reply through `onText` (`shopper_already_read_reply`).
+ * An answer whose next step is a link the call handed over reads as that step's fixed short line
+ * instead (`stepAsWritten`), whoever wrote the reply.
  *
  * ```ts
  * replyAsWritten(result); // 'found two at Amazon. want the first one?'
@@ -261,13 +352,20 @@ export function replyAsWritten(result) {
     // The shopper already read every message of it through onText: handing it out again would say it twice.
     if (result.shopper_already_read_reply === true)
         return null;
+    // A step whose link the shopper already holds is asked for in the same short line every time, with no model.
+    const step = stepAsWritten(result);
+    if (step !== null)
+        return step;
     // 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();
     if (!agentcards || view.status !== 'needs_input' || reply === '')
         return null;
-    const cards = [...view.products.filter((product) => product.link_sent).map((product) => product.name), ...view.stores.filter((store) => store.link_sent).map((store) => store.name)];
+    const cards = [
+        ...view.products.filter((product) => product.link_sent).map((product) => ({ name: product.name, price: product.price })),
+        ...view.stores.filter((store) => store.link_sent).map((store) => ({ name: store.name })),
+    ];
     // A reply with nothing left once the cards' list comes out is your model's to word.
     return withoutCardList(reply, cards) || null;
 }
@@ -277,6 +375,15 @@ const LIST_ITEM = /^\s*(?:[-*•]|\d{1,2}[.)])\s+/;
 const PRICE = /[$£€]\s?\d/;
 /** The place a sentence points at in a numbered list, such as `#8` or `number 3`, where `a #2 Phillips head` names a kind of thing. */
 const LIST_NUMBER = /(?<!\ba )(?<!\ban )(?:#(\d{1,2})\b|\bnumber (\d{1,2})\b)/i;
+/**
+ * A sentence that goes on to more of the list rather than recommending: `other 6-packs are ...`, `other options include ...`,
+ * `there's also ...`, `you could also ...`. One that names a card is the list, whatever the reply recommended before it.
+ */
+const MORE_OF_LIST = /^[\s*_"'(]*(?:(?:and|plus|but|or)\s+)?(?:others?\b[^.!?:]{0,40}?\b(?:are|is|include|includes|would be)\b|there(?:'s|’s|\s+is|\s+are)\s+also\b|(?:you|we)\s+(?:could|can|might)\s+also\b)/i;
+/** An amount a text gives after a currency sign, such as `$22.89` or `¥1,331`. */
+const AMOUNT = /[$£€¥]\s?(\d{1,3}(?:,\d{3})+|\d+)(\.\d+)?/g;
+/** Words that tell no product from another: a card's brand or its distinctive words are never one of these. */
+const FILLER = new Set(['the', 'and', 'with', 'for', 'from', 'of', 'by', 'in', 'on', 'to', 'or', 'at', 'an', 'new', 'pack', 'count', 'set', 'each', 'size']);
 /** A unit a size or a count is written in, so `10 ft`, `10-ft` and `10ft` read as one word. */
 const UNIT = /(\d)[\s-]+(ft|feet|foot|inch|inches|oz|fl|ml|l|g|kg|lb|lbs|gb|tb|mb|w|mah|v|cm|mm|m|pack|pk|ct|count|pcs|pieces)\b/gi;
 /**
@@ -286,6 +393,8 @@ const UNIT = /(\d)[\s-]+(ft|feet|foot|inch|inches|oz|fl|ml|l|g|kg|lb|lbs|gb|tb|m
 const SAME_UNIT = new Map([['feet', 'ft'], ['foot', 'ft'], ['in', ''], ['inch', ''], ['inches', ''], ['pk', 'pack'], ['ct', 'pack'], ['count', 'pack'], ['pcs', 'pack'], ['pieces', 'pack'], ['lbs', 'lb']]);
 /** A size or a count written as one word, such as `24pack` or `10ft`. */
 const SIZE = /^(\d+)(\p{L}+)$/u;
+/** A size in inches, however a text writes it: `10 inch`, `10-inches`, `10in`, `10 in`. */
+const INCHES = /(\d+)\s*-?\s*(?:inch(?:es)?|in)\b/gi;
 /** A text's words, lowercased, letters and digits only, with markdown's bold marks gone and a size written as one word. */
 function wordsOf(text) {
     return text
@@ -295,29 +404,115 @@ function wordsOf(text) {
         .filter((word) => word !== '')
         .map((word) => word.replace(SIZE, (whole, count, unit) => `${count}${SAME_UNIT.get(unit) ?? unit}`));
 }
+/** An amount in hundredths, so `$26.46`, `from $26.46` and `26.46` all read 2646, and `¥1,331` reads 133100. */
+function hundredths(whole, fraction) {
+    return Math.round(Number(`${whole.replace(/,/g, '')}${fraction ?? ''}`) * 100);
+}
+/** The amounts a text gives after a currency sign, in hundredths. */
+function amountsIn(text) {
+    return new Set([...text.matchAll(AMOUNT)].map((match) => hundredths(match[1], match[2])));
+}
 /**
- * The card a text names, by the first six words of the card's name: at least two of them, and most of them, in the
- * text. Null when it names none. A name of one word never counts in prose, where a generic word such as `soap` would.
- * A size or a count among those words has to be in the text too, so the 3ft cable's line never reads as the 10ft card.
+ * The sizes among a text's words, by unit: `10ft` and `3ft` are two sizes in feet, `24pack` a count. Inches come from
+ * the text itself, because `wordsOf` leaves `10 inch` as the bare `10`, so the 10 inch skillet reads as one size in
+ * inches and the 12 inch one as another.
  */
-function cardNamed(text, cards, inList) {
-    const said = new Set(wordsOf(text));
-    for (const [index, name] of cards.entries()) {
-        const head = name.slice(0, 6);
-        if (!head.every((word) => !/\d/.test(word) || said.has(word)))
-            continue;
-        const hits = head.filter((word) => said.has(word)).length;
-        if (head.length === 1 ? inList && hits === 1 : hits >= Math.max(2, Math.ceil(head.length * 0.6)))
-            return index;
+function sizesOf(words, text) {
+    const sizes = new Map();
+    for (const word of words) {
+        const [, count, unit] = /^(\d+)(\p{L}+)$/u.exec(word) ?? [];
+        if (count && unit)
+            sizes.set(unit, (sizes.get(unit) ?? new Set()).add(count));
     }
-    return null;
+    for (const [, count] of text.matchAll(INCHES))
+        sizes.set('inch', (sizes.get('inch') ?? new Set()).add(count));
+    return sizes;
+}
+function readCards(shown) {
+    const named = shown
+        .map((card) => (typeof card === 'string' ? { name: card, price: null } : { name: String(card?.name ?? ''), price: card?.price ?? null }))
+        .map((card) => ({ name: card.name, words: wordsOf(card.name), price: card.price }))
+        .filter((card) => card.words.length > 0);
+    const holders = new Map();
+    for (const card of named)
+        for (const word of new Set(card.words))
+            holders.set(word, (holders.get(word) ?? 0) + 1);
+    const telling = (word) => word.length >= 3 && !/\d/.test(word) && !FILLER.has(word);
+    return named.map(({ name, words, price }) => {
+        const brand = words.find((word) => /\p{L}/u.test(word) && word.length >= 2 && !FILLER.has(word)) ?? null;
+        const amount = typeof price === 'string' ? /(\d{1,3}(?:,\d{3})+|\d+)(\.\d+)?/.exec(price) : null;
+        return {
+            words,
+            head: words.slice(0, 6),
+            brand,
+            marks: new Set([...(brand ? [brand] : []), ...words.filter((word) => telling(word) && (holders.get(word) ?? 0) <= Math.max(1, named.length / 2))]),
+            price: amount ? hundredths(amount[1], amount[2]) : null,
+            sizes: sizesOf(words, name),
+        };
+    });
+}
+/**
+ * The cards a text names, by their indexes; empty when it names none. A text names a card in one of three ways:
+ *
+ * - By the first six words of the card's name: at least two of them, and most of them, in the text. A name of one word
+ *   never counts in prose, where a generic word such as `soap` would. A size or a count among those words has to be in
+ *   the text too, so the 3ft cable's line never reads as the 10ft card.
+ * - By the card's exact price with its brand or another word that tells it apart: `Planet Oat Extra Creamy ($22.89)`
+ *   names the card `Planet Oat Extra Creamy Oatmilk, 32 Fl Oz (Pack of 6)` at $22.89. A price alone, as on a line of
+ *   sizes, names nothing.
+ * - By its brand and two more of its first six words, when the text gives no price or gives the card's.
+ *
+ * The last two take a short name a reply writes for a long title, and neither counts when the text gives a size the card
+ * has in another number, such as 3ft for its 10ft. A text that gives prices, none of them the card's, names it only by
+ * the first six words, so a line for a product no card shows keeps its place beside the card of its brand.
+ * 2026-10-27, "Oat milk, shelf stable, a 6 pack": "Planet Oat Extra Creamy ($22.89)" shares too few of its title's first
+ * six words to match by them alone.
+ */
+function cardsNamed(text, cards, inList) {
+    const words = wordsOf(text);
+    // Each word with how often the text says it, so a name of one word twice over, `Miu Miu`, counts twice.
+    const said = new Map();
+    for (const word of words)
+        said.set(word, (said.get(word) ?? 0) + 1);
+    const amounts = amountsIn(text);
+    const sizes = sizesOf(words, text);
+    const found = [...cards.entries()].flatMap(([index, card]) => {
+        const { head } = card;
+        const shared = head.filter((word) => said.has(word));
+        const hit = new Set(shared);
+        if (head.every((word) => !/\d/.test(word) || said.has(word))) {
+            if (head.length === 1 ? inList && shared.length === 1 : shared.length >= Math.max(2, Math.ceil(head.length * 0.6)))
+                return [{ index, hit }];
+        }
+        const otherSize = [...card.sizes].some(([unit, counts]) => sizes.has(unit) && ![...counts].some((count) => sizes.get(unit).has(count)));
+        if (otherSize)
+            return [];
+        const ownPrice = card.price !== null && amounts.has(card.price);
+        if (ownPrice && [...card.marks].some((word) => said.has(word)))
+            return [{ index, hit }];
+        const otherPrice = amounts.size > 0 && !ownPrice;
+        const more = new Set(head.filter((word) => word !== card.brand && word.length >= 2 && !FILLER.has(word) && said.has(word)));
+        return !otherPrice && card.brand !== null && said.has(card.brand) && more.size >= 2 ? [{ index, hit }] : [];
+    });
+    // Cards whose names share their words read as several products where the text names one, as three Kirkland Signature
+    // Organic milks do for `Kirkland Signature Organic Almond Milk`: a card the text names in nothing but another card's
+    // words, each said once, is that card's mention, and counts for no product of its own. A text that says those words
+    // again names both products, as `Diamond Walnut Pieces ($5.99) and Diamond Walnut Pieces Halves ($7.99)` does.
+    const saidOnce = (hit) => [...hit].every((word) => said.get(word) === 1);
+    return found
+        .filter(({ hit }) => hit.size === 0 || !saidOnce(hit) || !found.some((other) => other.hit.size > hit.size && [...hit].every((word) => other.hit.has(word))))
+        .map(({ index }) => index);
 }
 /**
  * Agentcard's reply without the list its cards already show the shopper: each list line that names a product or
  * store whose card went out, the line that led into that list (`here are a few:`, `other choices:`), a sentence that
- * points at a number the list gave (`the dishwand in #8`), and, past the one or two products a reply recommends in
- * words, each further sentence that names another card. What is left is the reply around the list, such as `found
- * these at amazon.` and `which one do you want?`. A reply whose cards went out names none of them twice over.
+ * points at a number the list gave (`the dishwand in #8`), a sentence that goes on to more of the list (`other 6-packs
+ * are ...`, `there's also ...`) and names a card, and, past the one or two products a reply recommends in words, each
+ * further sentence that names another card. What is left is the reply around the list, such as `found these at
+ * amazon.` and `which one do you want?`. A reply whose cards went out names none of them twice over.
+ *
+ * Each card is its name, or its name and its price as the model reads it (`{ name, price: '$22.89' }`): with the price,
+ * a reply's short name for the product, such as `Planet Oat Extra Creamy ($22.89)`, reads as its card (cardsNamed).
  *
  * ```ts
  * withoutCardList('Two I'd suggest:\n- Duracell AA, 24 pack, $20.78\n\nWhich one?', ['Duracell AA Batteries, 24 Count']);
@@ -325,18 +520,18 @@ function cardNamed(text, cards, inList) {
  * ```
  */
 export function withoutCardList(reply, cardNames) {
-    const cards = cardNames.map(wordsOf).filter((name) => name.length > 0);
+    const cards = readCards(cardNames);
     if (cards.length === 0)
         return reply.trim();
     // A text that opens with a card's name and gives its price is a list line, as a reply writes one without a bullet.
     const opensCard = (text) => {
         const words = wordsOf(text);
-        return PRICE.test(text) && cards.some((name) => name.length >= 2 && name.slice(0, 3).every((word, i) => words[i] === word));
+        return PRICE.test(text) && cards.some((card) => card.words.length >= 2 && card.words.slice(0, 3).every((word, i) => words[i] === word));
     };
     const lines = reply.split('\n');
     const kind = lines.map((line) => {
         if (LIST_ITEM.test(line))
-            return cardNamed(line.replace(LIST_ITEM, ''), cards, true) !== null ? 'item' : 'kept';
+            return cardsNamed(line.replace(LIST_ITEM, ''), cards, true).length > 0 ? 'item' : 'kept';
         return opensCard(line) ? 'named' : 'kept';
     });
     const dropped = kind.map((of) => of !== 'kept');
@@ -363,21 +558,26 @@ export function withoutCardList(reply, cardNames) {
         // `Other choices:`. A list that keeps a line, for a product no card shows, keeps its lead too.
         const list = listAfter(i);
         if (text.trim().endsWith(':') && list.length > 0 && list.every(Boolean))
-            text = text.trim().replace(/(?:^|(?<=[.!?])\s+)[^.!?]*:$/, '');
-        const sentences = text.split(/(?<=[.!?])\s+/).filter((sentence) => {
+            text = text.trim().slice(0, lastSentenceStart(text.trim())).trimEnd();
+        const sentences = text.split(SENTENCE_END).filter((sentence) => {
             const place = LIST_NUMBER.exec(sentence);
             if (place && numbers.has(Number(place[1] ?? place[2])))
                 return false;
-            const card = cardNamed(sentence, cards, false);
+            const found = cardsNamed(sentence, cards, false);
             // A list line written without a bullet keeps the sentences its card does not say, such as the question after it.
             if (kind[i] === 'named')
-                return card === null && !opensCard(sentence);
-            if (card === null || named.has(card))
+                return found.length === 0 && !opensCard(sentence);
+            if (found.length === 0)
                 return true;
+            // `other 6-packs are ...` and `there's also ...` recommend nothing: they are the list again, in a sentence.
+            if (MORE_OF_LIST.test(sentence))
+                return false;
+            const fresh = found.filter((card) => !named.has(card));
             // A reply recommends one or two products in words; a sentence that names a third is the list again.
-            if (named.size >= 2)
+            if (named.size + fresh.length > 2)
                 return false;
-            named.add(card);
+            for (const card of fresh)
+                named.add(card);
             return true;
         });
         if (kind[i] === 'named' && sentences.length === 0)

package/dist/order.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 declare const ORDER_STEPS: readonly ['placed', 'confirmed', 'preparing', 'on_the_way', 'delivered'];
+/** One step a tracker draws. */
+export type OrderPathStep = (typeof ORDER_STEPS)[number];
+/** Where an order is: one of `ORDER_STEPS`, or `canceled` or `failed`, which end it before `delivered`. */
+export type OrderStep = OrderPathStep | 'canceled' | 'failed';
+/** One step of the tracker: the order went past it (`done`), is at it (`current`), or has not reached it (`upcoming`). */
+export interface OrderStepState {
+    step: OrderPathStep;
+    /** The step's name as the tracker writes it, such as "Preparing". */
+    label: string;
+    state: 'done' | 'current' | 'upcoming';
+}
+/**
+ * An order as a tracker shows it. Every message about one order carries the same `orderId`, so an app
+ * keeps one tracker per `orderId` and passes each new message's order through `updateOrder`. A value
+ * Agentcard did not send is null; the package never guesses one.
+ */
+export interface ShopperOrder {
+    /** The store's id for the order, the same on every message about it. Null on a failure that placed no order. */
+    orderId: string | null;
+    /** The service the order went through, such as "DoorDash" or "Walmart". Null for an order across several retailers. */
+    merchantName: string | null;
+    /** The place the order comes from, such as the restaurant on DoorDash, when Agentcard names it. Show `merchantName` without it. */
+    storeName: string | null;
+    step: OrderStep;
+    /** The step's name as the tracker writes it: "Placed", "Accepted", "Preparing", "On the way", "Delivered", "Canceled" or "Failed". */
+    label: string;
+    /** The steps of `ORDER_STEPS` in order, each `done`, `current` or `upcoming`. After `canceled` or `failed` none is `current`. */
+    steps: OrderStepState[];
+    /** The store's own line for where the order is, such as "Preparing your order". */
+    title: string | null;
+    /** The store's own sentence under it, such as "Mendocino Farms is preparing your order." */
+    detail: string | null;
+    /** The earliest and the latest arrival the store estimates, as ISO 8601 timestamps. */
+    arrival: {
+        earliest: string | null;
+        latest: string | null;
+    } | null;
+    /** The delivery window the retailer quoted, in its own words, such as "Sat, Sep 6 - Tue, Sep 9". */
+    deliveryWindow: string | null;
+    /** The total in the currency's minor unit: 1789 is $17.89. */
+    totalCents: number | null;
+    /** The three-letter currency code, lowercase. */
+    currency: string | null;
+    /** The retailer's own order number, as on its confirmation, when it differs from `orderId`. */
+    retailerOrderId: string | null;
+    /** When the order was delivered, as an ISO 8601 timestamp. */
+    deliveredAt: string | null;
+    /** Why the order was canceled or failed, in the store's or Agentcard's words. */
+    reason: string | null;
+    /** When the order reached this step, as an ISO 8601 timestamp. */
+    updatedAt: string;
+}
+/** The step an `order.updated` stage reads as, or null for a stage the package does not know. */
+export declare function orderStepOf(stage: string | null | undefined): OrderStep | null;
+/** The values a message names about its order, as the package reads them. */
+export interface OrderFields {
+    orderId?: string;
+    merchantName?: string;
+    storeName?: string;
+    step: OrderStep;
+    /** For a canceled order, the step it was at before. */
+    reached?: OrderStep | null;
+    title?: string;
+    detail?: string;
+    arrivalEarliest?: string;
+    arrivalLatest?: string;
+    deliveryWindow?: string;
+    totalCents?: number;
+    currency?: string;
+    retailerOrderId?: string;
+    deliveredAt?: string;
+    reason?: string;
+    updatedAt: string;
+}
+/** The order a message describes, from the values it names. */
+export declare function orderFrom(fields: OrderFields): ShopperOrder;
+/**
+ * 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 declare function updateOrder(previous: ShopperOrder | null | undefined, next: ShopperOrder): ShopperOrder;
+export interface ArrivalTextOptions {
+    /** The shopper's IANA time zone, such as `America/Los_Angeles`. Default: the runtime's own. */
+    timeZone?: string;
+    /** The locale the times are written in. Default: `en-US`. */
+    locale?: string;
+    /** Unix milliseconds that count as now, to tell a time today from one on another day. Default: the system clock. */
+    now?: number;
+}
+/**
+ * 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 declare function arrivalText(order: Pick<ShopperOrder, 'step' | 'arrival' | 'deliveryWindow' | 'deliveredAt'>, options?: ArrivalTextOptions): string | null;

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;
+}