@agent-cards/commerce-sdk 0.16.0 → 0.18.0

package/dist/model-view.js

@@ -1,4 +1,5 @@
-import { SENTENCE_END, lastSentenceStart } from './sentences.js';
+import { SENTENCE_END, lastSentenceStart, leadsIn, withoutLeadIn } from './sentences.js';
+import { toMessages } from './messages.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']);
@@ -373,6 +374,18 @@ export function replyAsWritten(result) {
 const LIST_ITEM = /^\s*(?:[-*•]|\d{1,2}[.)])\s+/;
 /** A price, in any of the currencies a store writes one in. */
 const PRICE = /[$£€]\s?\d/;
+/**
+ * A mark that numbers or bullets an item in the middle of a line, such as the `2)` in `1) a mug; 2) a soap`, or a `•`.
+ * A number counts only in a run that goes 1, 2, 3, so a size such as `(Pack of 12) and` marks nothing.
+ */
+const INLINE_MARK = /(?<=^|[\s:;,(])(?:(\d{1,2})([.)])|•)[ \t]+/g;
+/**
+ * A sentence that asks the shopper something: a question, `let me know ...` or `tell me ...` anywhere in it, as in
+ * `amazon has the best price, so let me know how many you want.`, or one that opens with `pick ...` or `reply ...`.
+ */
+const ASKS = /\?[\s"'*_)\]]*$|\b(?:let me know|tell me)\b|^[\s*_"'(]*(?:just (?:say|tell|reply|pick)|reply|pick|choose)\b/i;
+/** A clause that turns from a product to the shopper, after a comma, a semicolon or a dash: `, which one would you like?`. */
+const ASKING_CLAUSE = /(?:[,;]|\s[-–])\s+(?=(?:(?:and|or|so|but)\s+)?(?:which|what|want|would|do|does|should|shall|can|could|how|any|let me know|tell me|just)\b)/gi;
 /** 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;
 /**
@@ -503,13 +516,123 @@ function cardsNamed(text, cards, inList) {
         .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);
 }
+/** The sentences of a text from `from` on, each with the place in the text where it starts. */
+function sentencesAt(text, from) {
+    const out = [];
+    let at = from;
+    for (const part of text.slice(from).split(SENTENCE_END)) {
+        const start = text.indexOf(part, at);
+        if (part !== '')
+            out.push({ text: part, at: start });
+        at = start + part.length;
+    }
+    return out;
+}
+/**
+ * Where the clause that asks the shopper starts in a sentence that also gives a product, as `which one would you like?`
+ * does in `2) Mini Soaps Gift Box ($58.00), which one would you like?`, or null when the sentence asks nothing apart.
+ */
+function askingClause(sentence) {
+    if (!ASKS.test(sentence))
+        return null;
+    for (const turn of sentence.matchAll(ASKING_CLAUSE)) {
+        const rest = sentence.slice(turn.index + turn[0].length);
+        if (ASKS.test(rest) && !PRICE.test(rest))
+            return turn.index + turn[0].length;
+    }
+    return null;
+}
+/** Where the sentence that holds `at` starts: right after the sentence before it, or at the line's start. */
+function sentenceStart(line, at) {
+    return lastSentenceStart(line.slice(0, at));
+}
+/**
+ * Where a list on one line stops, given where its last item starts: past that item's first period, through the
+ * sentences that only describe it, to the first that asks the shopper or names a card itself, so `8.4 Fl. Oz.` never
+ * cuts the item short. A question the item's own sentence asks after a comma, `..., which one?`, stays out of it.
+ */
+function inlineEnd(line, from, cards) {
+    const [own, ...rest] = sentencesAt(line, from);
+    const clause = own ? askingClause(own.text) : null;
+    if (own && clause !== null)
+        return own.at + clause;
+    const stop = rest.find((sentence) => ASKS.test(sentence.text) || cardsNamed(sentence.text, cards, false).length > 0);
+    return stop ? stop.at : line.length;
+}
+/**
+ * A list a reply writes on one line, mid-sentence: `i found a few options: 1) a mug ($19.00); 2) a gift set ($115.00);
+ * 3) a soap box ($58.00). which one?`. Its items are numbered `1)` or `1.`, bulleted with `•`, or set apart by `;` with
+ * each naming a card, after a colon or three of them at least. The list may open the line, `1) a mug; 2) a candle`, and
+ * ends where inlineEnd says. `lead` is where the sentence that leads into the list starts, `end` where the list stops.
+ * Null when the line holds no such list.
+ */
+function inlineList(line, cards) {
+    const marks = [...line.matchAll(INLINE_MARK)];
+    // A numbered run, 1, 2, 3, each marked the same way, or two or more bullets.
+    const run = [];
+    for (const mark of marks) {
+        if (mark[1] !== undefined && Number(mark[1]) === run.length + 1 && (run.length === 0 || run[0][2] === mark[2]))
+            run.push(mark);
+    }
+    const bullets = marks.filter((mark) => mark[1] === undefined);
+    const chosen = run.length >= 2 ? run : bullets.length >= 2 ? bullets : [];
+    if (chosen.length >= 2) {
+        const last = chosen[chosen.length - 1];
+        const end = inlineEnd(line, last.index + last[0].length, cards);
+        const items = chosen.map((mark, k) => {
+            const start = mark.index;
+            const raw = line.slice(start, k + 1 < chosen.length ? chosen[k + 1].index : end);
+            return { start, raw, body: raw.slice(mark[0].length), number: mark[1] === undefined ? null : Number(mark[1]) };
+        });
+        return { lead: sentenceStart(line, items[0].start), items, end };
+    }
+    // Parts set apart by `;` run from the colon that leads into them, found by its place rather than by sentences, so a
+    // name such as `8.4 Fl. Oz.` before the first `;` stays whole.
+    const semicolon = line.indexOf(';');
+    if (semicolon === -1)
+        return null;
+    const colon = line.lastIndexOf(':', semicolon);
+    const led = colon !== -1 && !/[?!]/.test(line.slice(colon, semicolon));
+    const opens = led ? colon + 1 : sentenceStart(line, semicolon);
+    // The list's last `;` is the last one with an item on its right and no question between, found before the list's end
+    // is, so a sentence inside an item, `The Lavender Candle ships free;`, never ends the list early, and a `;` in a
+    // question after it, `which one would you like; or should i search again?`, is no part of it. An item names a card
+    // the list has not named yet, or names one again with a price, `Travel Mug ($19.00)`; a part that names a listed
+    // card with no price is a recommendation after the list, `i'd pick Travel Mug; Lavender Candle is nicer.`, and stays.
+    let last = semicolon;
+    for (let next = line.indexOf(';', last + 1); next !== -1; next = line.indexOf(';', last + 1)) {
+        const after = line.indexOf(';', next + 1);
+        const asks = sentencesAt(line.slice(0, next), last + 1).some((sentence) => ASKS.test(sentence.text));
+        const listed = new Set(cardsNamed(line.slice(opens, next), cards, true));
+        const text = line.slice(next + 1, after === -1 ? line.length : after);
+        const part = cardsNamed(text, cards, true);
+        const item = part.some((index) => !listed.has(index)) || (part.length > 0 && PRICE.test(sentencesAt(text, 0)[0]?.text ?? ''));
+        if (asks || !item)
+            break;
+        last = next;
+    }
+    const end = inlineEnd(line, last + 1, cards);
+    const parts = line.slice(opens, end).replace(/[\s,;]+$/, '').split(';');
+    if ((!led && parts.length < 3) || !parts.every((part) => cardsNamed(part, cards, true).length > 0))
+        return null;
+    let start = opens;
+    const items = parts.map((part) => {
+        const item = { start, raw: part, body: part, number: null };
+        start += part.length + 1;
+        return item;
+    });
+    return { lead: led ? sentenceStart(line, colon) : opens, items, end };
+}
 /**
  * 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`), 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.
+ * further sentence that names another card. A list written on one line goes the same way, item by item (inlineList),
+ * and so does a list line written without a bullet, whole, up to the question on it. 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. A list that keeps an item for a product no card shows keeps its lead-in, and the two read as one
+ * message (toMessages), so the shopper never reads `two options came in under $20:` on its own.
  *
  * 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).
@@ -528,25 +651,61 @@ export function withoutCardList(reply, cardNames) {
         const words = wordsOf(text);
         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');
+    // The numbers the dropped list gave, so a number of a product's own, `a #2 Phillips head`, keeps its sentence.
+    const numbers = new Set();
+    // A list a line writes inline goes the way a list of lines does: each item that names a card, and the sentence that
+    // led into the list once every item went. An item for a product no card shows stays, with the lead, and so does a
+    // list that opens the line, `1) a mug; 2) a candle; 3) a soap box`, item by item rather than as one list line.
+    const unlisted = (line) => {
+        const list = inlineList(line, cards);
+        const gone = list?.items.map((item) => cardsNamed(item.body, cards, true).length > 0) ?? [];
+        if (!list || !gone.some(Boolean))
+            return line;
+        list.items.forEach((item, k) => {
+            if (gone[k] && item.number !== null)
+                numbers.add(item.number);
+        });
+        const after = line.slice(list.end).trimStart();
+        if (gone.every(Boolean))
+            return `${line.slice(0, list.lead).trimEnd()} ${after}`.trim();
+        const left = list.items.filter((_, k) => !gone[k]).map((item) => item.raw.trim().replace(/[\s,;]*(?:\b(?:and|or))?[\s,;]*$/i, ''));
+        const close = /[.!?]$/.test(left[left.length - 1]) ? '' : '.';
+        return [line.slice(0, list.items[0].start).trimEnd(), `${left.join('; ')}${close}`, after].filter((part) => part !== '').join(' ');
+    };
+    const lines = reply.split('\n').map(unlisted);
     const kind = lines.map((line) => {
         if (LIST_ITEM.test(line))
             return cardsNamed(line.replace(LIST_ITEM, ''), cards, true).length > 0 ? 'item' : 'kept';
         return opensCard(line) ? 'named' : 'kept';
     });
     const dropped = kind.map((of) => of !== 'kept');
-    // The numbers the dropped list gave, so a number of a product's own, `a #2 Phillips head`, keeps its sentence.
-    const numbers = new Set(lines.flatMap((line, i) => (dropped[i] ? [Number(/^\s*(\d{1,2})[.)]\s/.exec(line)?.[1])] : [])).filter((number) => Number.isInteger(number)));
+    lines.forEach((line, i) => {
+        const number = dropped[i] ? Number(/^\s*(\d{1,2})[.)]\s/.exec(line)?.[1]) : NaN;
+        if (Number.isInteger(number))
+            numbers.add(number);
+    });
     // The list a line leads into: the lines from the next one with words on it to the first that is not a list line, so a
-    // question on the line after the last item, `Which one?`, is no part of the list.
+    // question on the line after the last item, `Which one?`, is no part of the list. A blank line between two list lines
+    // is no end of it, as toMessages reads one, so a list that keeps an item past the blank keeps its lead.
+    const listLine = (j) => LIST_ITEM.test(lines[j]) || kind[j] === 'named';
     const listAfter = (line) => {
         const start = lines.findIndex((after, j) => j > line && after.trim() !== '');
         if (start === -1)
             return [];
-        let end = start;
-        while (end < lines.length && (LIST_ITEM.test(lines[end]) || kind[end] === 'named'))
-            end += 1;
-        return dropped.slice(start, end);
+        const list = [];
+        for (let j = start; j < lines.length; j += 1) {
+            if (listLine(j)) {
+                list.push(dropped[j]);
+                continue;
+            }
+            if (lines[j].trim() !== '')
+                break;
+            // A blank line: the list goes on when the next line with words on it is a list line.
+            const next = lines.findIndex((after, k) => k > j && after.trim() !== '');
+            if (next === -1 || !listLine(next))
+                break;
+        }
+        return list;
     };
     const named = new Set();
     const kept = [];
@@ -557,34 +716,44 @@ export function withoutCardList(reply, cardNames) {
         // The line that leads into a list whose every line went loses the sentence that leads in: `Two I'd suggest:` or
         // `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().slice(0, lastSentenceStart(text.trim())).trimEnd();
-        const sentences = text.split(SENTENCE_END).filter((sentence) => {
+        if (leadsIn(text) && list.length > 0 && list.every(Boolean))
+            text = withoutLeadIn(text);
+        // A list line written without a bullet goes whole, with what trails its card's price (`$16.12. amazon, and the
+        // cheapest multipack.`), up to the sentence that asks the shopper something, which stays with what follows it. A
+        // question its card's own sentence asks after a comma, `..., $16.12, want it?`, stays too.
+        let asked = false;
+        const sentences = text.split(SENTENCE_END).flatMap((sentence) => {
             const place = LIST_NUMBER.exec(sentence);
             if (place && numbers.has(Number(place[1] ?? place[2])))
-                return false;
+                return [];
             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 found.length === 0 && !opensCard(sentence);
+            if (kind[i] === 'named') {
+                const card = found.length > 0 || opensCard(sentence);
+                asked ||= ASKS.test(sentence);
+                if (!card)
+                    return asked ? [sentence] : [];
+                const clause = asked ? askingClause(sentence) : null;
+                return clause === null ? [] : [sentence.slice(clause)];
+            }
             if (found.length === 0)
-                return true;
+                return [sentence];
             // `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;
+                return [];
             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 + fresh.length > 2)
-                return false;
+                return [];
             for (const card of fresh)
                 named.add(card);
-            return true;
+            return [sentence];
         });
         if (kind[i] === 'named' && sentences.length === 0)
             return;
         kept.push(sentences.join(' ').trimEnd());
     });
-    return kept.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+    // A lead-in kept for a list that lost an item to a card goes with what is left of the list, as one message (toMessages).
+    return toMessages(kept.join('\n')).join('\n\n');
 }
 /**
  * A thrown error as the model may read it: the same message with every link

package/dist/sentences.d.ts

@@ -1,3 +1,16 @@
 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;
+/** True when `text` ends with a colon that leads into what follows it, so it never stands alone as a message. */
+export declare function leadsIn(text: string): boolean;
+/**
+ * The text less every sentence at its end that leads in with a colon, for lead-ins nothing follows: the list they led
+ * into went (its cards show it), and a colon would point at nothing. Lead-ins in a row go together, so `two things:`
+ * above `first:` leaves no colon behind. A text that leads into nothing stays as it is.
+ *
+ * ```ts
+ * withoutLeadIn('found these at amazon. two came in under $20:'); // 'found these at amazon.'
+ * withoutLeadIn('two things:\nfirst:'); // ''
+ * ```
+ */
+export declare function withoutLeadIn(text: string): string;

package/dist/sentences.js

@@ -27,3 +27,31 @@ export function lastSentenceStart(text) {
         start = end.index + end[0].length;
     return start;
 }
+/**
+ * A text that leads into what comes after it with a colon, as `two options came in under $20:` or `here are a few:` does,
+ * a closing quote or bracket allowed after the colon.
+ */
+const LEAD_IN = /:["')\]]*$/;
+/** True when `text` ends with a colon that leads into what follows it, so it never stands alone as a message. */
+export function leadsIn(text) {
+    return LEAD_IN.test(String(text ?? '').trim());
+}
+/**
+ * The text less every sentence at its end that leads in with a colon, for lead-ins nothing follows: the list they led
+ * into went (its cards show it), and a colon would point at nothing. Lead-ins in a row go together, so `two things:`
+ * above `first:` leaves no colon behind. A text that leads into nothing stays as it is.
+ *
+ * ```ts
+ * withoutLeadIn('found these at amazon. two came in under $20:'); // 'found these at amazon.'
+ * withoutLeadIn('two things:\nfirst:'); // ''
+ * ```
+ */
+export function withoutLeadIn(text) {
+    let rest = String(text ?? '').trim();
+    while (rest !== '' && leadsIn(rest)) {
+        const at = rest.lastIndexOf('\n') + 1;
+        const last = rest.slice(at);
+        rest = (rest.slice(0, at) + last.slice(0, lastSentenceStart(last))).trim();
+    }
+    return rest;
+}

package/dist/texting.d.ts

@@ -41,6 +41,8 @@ export interface ReplyAsWrittenOptions {
  * 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`).
+ * A paragraph that ends with a colon, such as `two options came in under $20:`, shares its message with the paragraph
+ * after it, and one that nothing follows loses its colon sentence, so the shopper never reads a message ending on a colon.
  *
  * ```ts
  * replyAsWritten(result); // 'which bread do you want?\n\n• Sourdough\n• Whole wheat'

package/dist/texting.js

@@ -1,4 +1,5 @@
 import { forModel, replyAsWritten as replyWithoutCardList } from './model-view.js';
+import { toMessages } from './messages.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. */
@@ -184,6 +185,8 @@ function namesOne(item, names) {
  * 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`).
+ * A paragraph that ends with a colon, such as `two options came in under $20:`, shares its message with the paragraph
+ * after it, and one that nothing follows loses its colon sentence, so the shopper never reads a message ending on a colon.
  *
  * ```ts
  * replyAsWritten(result); // 'which bread do you want?\n\n• Sourdough\n• Whole wheat'
@@ -196,7 +199,9 @@ export function replyAsWritten(result, options = {}) {
     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;
+    // Read as the shopper's chat cuts it (toMessages), so a paragraph that leads in with a colon shares its message with
+    // the one after it, and one nothing follows loses its colon sentence: no message of it ends on a colon.
+    return toMessages(options.textingStyle ? styleLines(bulleted) : bulleted).join('\n\n') || null;
 }
 /**
  * One message of Agentcard's, as `onText` hands it to the app: its lists as `• ` bullet lines and, with `texting`, in

package/package.json

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