@agent-cards/commerce-sdk 0.15.0 → 0.16.0

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.15.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",