jsfe 1.4.1 → 1.5.0

package/dist/helpers/answer.js

@@ -0,0 +1,409 @@
+/**
+ * The platform's answer vocabulary, ONE place for every flow set (APPROVED_FUNCTIONS isAnswer, isAgentRequest, isOtherRequest,
+ * isAmountAnswer, pickChoice). Before it, the YES / NO / AGENT / EXIT / TEXT words were copied by hand into system, ai-ar and Shopify
+ * flows and had drifted: four AGENT lists (25, 21, 15 and 12 words), nine YES lists, and a Shopify search that
+ * matched AGENT words as substrings, so "olive oil" and "televisor inteligente" went to an agent (review 2026-10-13).
+ *
+ * Words match whole words or word runs (matchesChoice), never substrings. Keypad conventions are platform-wide:
+ * 0 is an agent, * is exit.
+ *
+ * Part of jsfe/helpers; imports only its sibling matches-choice.js.
+ */
+import { matchesChoice } from './matches-choice.js';
+export const ANSWER_WORDS = {
+    yes: ['yes', 'yeah', 'yea', 'yep', 'yup', 'sure', 'ok', 'okay', 'okey', 'please', 'of course', 'correct', 'right', 'go ahead',
+        'alright', 'all right', 'absolutely', 'definitely', 'certainly', 'sounds good', "that's fine", 'that is fine', 'fine',
+        "that's ok", "that's okay", "that's right", 'that is right', "that's correct", 'that works', 'agree', 'i agree', 'agreed',
+        'approve', 'i approve', 'approved', 'confirm', 'i confirm', 'confirmed', 'proceed', 'do it', 'perfect', 'exactly', 'i do',
+        'si', 'sí', 'claro', 'claro que sí', 'claro que si', 'seguro', 'por favor', 'correcto', 'está bien', 'esta bien', 'de acuerdo',
+        'estoy de acuerdo', 'dale', 'por supuesto', 'bueno', 'confirmo', 'confirmado', 'apruebo', 'aprobado', 'adelante', 'hazlo',
+        'procede', 'perfecto', 'exacto', 'eso es', 'así es', 'asi es',
+        // agreeing to what the question offers: "Sí, quiero continuar" to "diga SÍ para continuar" (replay of prod, 2026-10-14).
+        // A bare "I want" / "quiero" is never a confirmation (owner decision 2026-10-15): "Quiero pagar" at the express offer,
+        // which charges on its YES, was a YES because 'pagar' is that choice's own word.
+        'continue', 'i want to continue', 'go on', 'go ahead please', 'please do', 'yes i do',
+        'sí quiero', 'si quiero', 'continuar', 'quiero continuar', 'seguir', 'sigue', 'continúe', 'continue por favor',
+        'proceder', 'procedo', 'procede por favor', 'proceda', 'proceda por favor', 'sí proceda', 'si proceda'],
+    no: ['no', 'nope', 'nah', 'no thanks', 'no thank you', 'not now', 'not today', 'no gracias', 'ahora no', 'hoy no'],
+    agent: ['live agent', 'agent', 'agents', 'representative', 'rep', 'human', 'operator', 'manager', 'supervisor', 'someone',
+        'somebody', 'real person', 'a person', 'customer service', 'support', 'agente', 'agentes', 'gente', 'representante',
+        'humano', 'operador', 'operadora', 'gerente', 'alguien', 'persona', 'servicio al cliente', 'al cliente', 'servicio',
+        'recepcionista', 'recepcion', 'recepción'],
+    exit: ['exit', 'quit', 'abort', 'salir', 'cancel', 'cancelar'],
+    text: ['text', 'texto', 'sms', 'message', 'mensaje', 'text me', 'by text', 'por texto', 'mensaje de texto', 'whatsapp',
+        'escríbeme', 'escribeme'],
+};
+// The ONLY words that confirm a choice that charges or cancels (`exact`), besides the choice's own words and keys; courtesy
+// around them is allowed (owner decision 2026-10-15: "clear charge confirmation exclusively"). Left out on purpose:
+// acknowledgements ("ok", "está bien", "fine", "sounds good", "perfecto": "I heard you", not "charge me"), "bueno" (the
+// Mexican phone "hello?"), courtesy alone ("please", "por favor"), words that are questions once ASR drops the "?"
+// ("right", "seguro", "exactly", "así es"), and agreeing to continue ("continue", "continuar").
+export const CONFIRM_WORDS = ['yes', 'yeah', 'yep', 'yup', 'sure', 'of course', 'absolutely', 'definitely', 'confirm', 'i confirm',
+    'confirmed', 'approve', 'i approve', 'approved', 'agree', 'i agree', 'agreed', 'proceed', 'go ahead', 'go ahead please', 'do it',
+    'correct', "that's correct", 'that is correct', "that's right", 'that is right', 'yes i do',
+    'si', 'sí', 'claro', 'claro que sí', 'claro que si', 'por supuesto', 'confirmo', 'confirmado', 'apruebo', 'aprobado', 'adelante',
+    'dale', 'hazlo', 'procede', 'proceda', 'proceder', 'procedo', 'sí proceda', 'si proceda', 'correcto', 'de acuerdo',
+    'estoy de acuerdo', 'sí quiero', 'si quiero'];
+// Acknowledgements: never a confirmation of an `exact` choice on their own, but said beside one ("Sí, está bien", "Yes,
+// okay") they change nothing, like courtesy. Beside an exact choice's own words, a CONFIRM word is the same ("Yes, the
+// full balance").
+// AGENT words that also mean something else inside a sentence ("quiero pagar mi servicio", "someone else will pay"): they
+// ask for a person only as the whole answer (AGENT_ONLY), never from inside one.
+const AGENT_AMBIGUOUS = new Set(['servicio', 'support', 'someone', 'somebody', 'alguien', 'persona', 'a person', 'gente', 'al cliente']);
+// A word that negates what follows it in its clause ("not sure", "no quiero un agente").
+const NEGATIONS = ['no', 'not', 'nope', 'nah', 'never', 'dont', 'doesnt', 'didnt', 'cant', 'cannot', 'wont', 'nunca', 'ni',
+    'tampoco', 'jamas', 'jamás'];
+// Phrases that hold a negation word but agree ("no problem", "why not").
+const AGREEING = /\b(no problem|no worries|no hay problema|no te preocupes|why not|por que no|por qué no)\b/g;
+const DEFERRAL = /\b(later|tomorrow|next week|not now|not today|another time|mañana|manana|después|despues|luego|otro día|otro dia|ahora no|hoy no)\b/;
+const AGENT_ONLY = /^(?:(?:i want|i need|i would like|id like|can i|could i|let me|please|quiero|necesito|puedo|por favor)\s+)*(?:(?:to\s+)?(?:talk|speak|hablar|comunicarme)\s+(?:to|with|con)\s+)?(?:a|an|un|una|el|la)?\s*(?:live agent|agent|representative|rep|human|operator|real person|a person|person|someone|somebody|customer service|agente|representante|humano|operador|operadora|persona|alguien|servicio al cliente|gerente|manager|supervisor)(?:\s+(?:please|por favor))?$/;
+// Accents are not meaning here (owner 2026-10-16): text callers type "direccion" for "dirección", "si" for "sí". Both
+// sides of every comparison pass through normalize, so a word list matches with or without them; ñ is kept.
+const plainVowels = (s) => s.replace(/[áàâä]/g, 'a').replace(/[éèêë]/g, 'e').replace(/[íìîï]/g, 'i').replace(/[óòôö]/g, 'o').replace(/[úùûü]/g, 'u');
+/** Unescapes what the engine escaped, lowercases, drops punctuation but keeps * @ ., and drops accents (not ñ). */
+const normalize = (s) => plainVowels(String(s ?? '').replace(/\\(['"\\])/g, '$1').toLowerCase().replace(/[^\w\s*@.áéíóúüñàâäèêëìîïòôöùû]+/g, ''))
+    .replace(AGREEING, ' ').replace(/\s+/g, ' ').trim();
+const NEGATION_SET = new Set(NEGATIONS.map(plainVowels));
+const hasNegation = (s) => String(s).split(' ').some((t) => NEGATION_SET.has(t));
+// Said around an answer without changing it: politeness, filler, a form of address.
+const COURTESY = ['please', 'por favor', 'thanks', 'thank you', 'thank you so much', 'thanks a lot', 'gracias', 'muchas gracias', 'um', 'umm', 'uh', 'uhm',
+    'hmm', 'oh', 'ah', 'well', 'so', 'like', 'este', 'pues', "ma'am", 'maam', 'madam', 'sir', 'miss', 'señor', 'senor', 'señora',
+    'senora', 'señorita', 'senorita', 'mija', 'mijo'].map(normalize).map((w) => w.split(' '));
+// A bare thanks at a yes/no question is a graceful acceptance (owner decision 2026-10-16): YES, but only at a choice keyed
+// 'yes' that does not charge or cancel (pickChoice). "No, gracias" stays NO; isAnswer(…, 'yes') takes thanks only as a
+// caller's extra.
+const THANKS = ['thanks', 'thank you', 'thank you so much', 'thanks a lot', 'gracias', 'muchas gracias'];
+const ACKNOWLEDGEMENTS = ['ok', 'okay', 'okey', 'está bien', 'esta bien', 'bueno', 'fine', "that's fine", 'alright', 'all right',
+    'perfect', 'perfecto', 'sounds good', 'great', 'excelente', 'muy bien'].map(normalize).map((w) => w.split(' '));
+const CONFIRM_FILLER = CONFIRM_WORDS.map(normalize).map((w) => w.split(' '));
+// articles and possessives in front of an exact choice's own words ("Yes, the full balance", "Sí, el saldo completo")
+const ARTICLES = ['the', 'my', 'el', 'la', 'mi'].map((w) => [w]);
+const YES_SET = new Set(ANSWER_WORDS.yes.map(normalize));
+const collapse = (w) => w.replace(/([aeiouáéíóúü])\1+/g, '$1').replace(/(\p{L})\1{2,}/gu, '$1');
+/**
+ * Whether the answer, with courtesy around it removed (please / thanks / gracias, um, uh, ma'am, señora…), holds NOTHING but
+ * words from `words` — at least one of them. A YES that acts must be the whole answer (owner rule, 2026-10-14): "Yeah, sure,
+ * thank you" and "Sí, claro, por favor" are YES; "yes, pay it" and "I made payments by 1" are not.
+ */
+function onlyAffirmative(b, words, needOne = true, filler = []) {
+    if (!words.length && needOne) {
+        return false;
+    }
+    else {
+        // words to match
+    }
+    const tk = String(b).replace(/\./g, ' ').split(' ').filter(Boolean);
+    const own = words.map(normalize).filter(Boolean).map((w) => w.split(' '));
+    const at = (i, phrase) => phrase.every((w, j) => tk[i + j] === w || (!/(\p{L})\1/u.test(w) && collapse(tk[i + j] || '') === w));
+    let i = 0;
+    let saw = false;
+    while (i < tk.length) {
+        const yes = own.filter((p) => at(i, p)).sort((x, y) => y.length - x.length)[0];
+        const courtesy = yes ? null : [...COURTESY, ...filler].filter((p) => at(i, p)).sort((x, y) => y.length - x.length)[0];
+        if (yes) {
+            i += yes.length;
+            saw = true;
+        }
+        else if (courtesy) {
+            i += courtesy.length;
+        }
+        else {
+            return false;
+        }
+    }
+    return saw || !needOne;
+}
+/**
+ * Whether the answer is the keypad key `key` with nothing around it but courtesy ("1 please", "um 2", "2 gracias") and,
+ * when `yesOk`, a YES word ("yes 1", "sí, 1"). Owner decision 2026-10-15: "Yes 1" at "tell me the product number" was
+ * missed. Anything else around the key ("no 1", "1 or 2", "I paid 1 already") is not that key.
+ */
+function keyWithOnlyCourtesy(b, key, yesOk) {
+    const tk = String(b).replace(/\./g, ' ').split(' ').filter(Boolean);
+    const at = tk.reduce((acc, t, i) => (t === key ? [...acc, i] : acc), []);
+    if (at.length !== 1) {
+        return false;
+    }
+    else {
+        const rest = tk.filter((t, i) => i !== at[0]).join(' ');
+        return onlyAffirmative(rest, yesOk ? ANSWER_WORDS.yes : [], false);
+    }
+}
+/**
+ * Whether the answer is a `kind` answer ('yes' | 'no' | 'agent' | 'exit' | 'text'), with the caller's `extra` words.
+ * YES, AGENT and TEXT never match a negated answer ("not sure", "I don't want an agent"); 0 is AGENT, * is EXIT.
+ */
+export function isAnswer(input, kind, extra = []) {
+    const words = [...(ANSWER_WORDS[kind] || []), ...(Array.isArray(extra) ? extra : [])];
+    const b = normalize(input);
+    if (!b) {
+        return false;
+    }
+    else if (kind === 'agent' && b === '0') {
+        return true;
+    }
+    else if (kind === 'exit' && b === '*') {
+        return true;
+    }
+    else if ((kind === 'yes' || kind === 'agent' || kind === 'text') && hasNegation(b)) {
+        return false;
+    }
+    else if (kind === 'yes') {
+        return onlyAffirmative(b, words);
+    }
+    else {
+        return matchesChoice(b, words);
+    }
+}
+/** Whether the WHOLE answer asks for a person ("agent", "I want to talk to a representative", "0") — for free-text prompts. */
+export function isAgentRequest(input) {
+    // the period normalize() keeps for emails is not part of the answer at its ends ("Operator." on a call, 2026-10-17)
+    const b = normalize(input).replace(/^[.\s]+|[.\s]+$/g, '');
+    return b === '0' || (!hasNegation(b) && AGENT_ONLY.test(b));
+}
+// A spoken or typed number: a digit, or a number word (ASR usually writes digits, not always).
+const NUMBER_WORD = /\b(zero|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen|twenty|thirty|forty|fifty|sixty|seventy|eighty|ninety|hundred|thousand|cero|uno|una|dos|tres|cuatro|cinco|seis|siete|ocho|nueve|diez|once|doce|trece|catorce|quince|dieciséis|dieciseis|diecisiete|dieciocho|diecinueve|veinte|veinti\w+|treinta|cuarenta|cincuenta|sesenta|setenta|ochenta|noventa|cien|ciento|cientos|mil)\b/;
+const EMAIL_SHAPE = /@|\b(at|arroba|dot|punto|gmail|hotmail|yahoo|outlook|icloud|aol)\b/;
+// An address being spelled: a spelled symbol, or three or more single letters or digits of which at least two are not
+// also words ("S o n. N y underscore.", "L e, o s"). The single-letter words a, e, i, o, u, y fill ordinary sentences
+// ("quiero ver mi saldo y a la vez pagar o algo"), so they alone never make a spelling.
+const SPELLING_WORD = /\b(underscore|guion|gui[oó]n bajo|dash|hyphen)\b/;
+const isSpelling = (b) => {
+    const singles = b.split(' ').map((w) => w.replace(/[.,]$/, '')).filter((w) => /^[a-z0-9]$/.test(w));
+    return SPELLING_WORD.test(b) || (singles.length >= 3 && singles.filter((w) => !'aeiouy'.includes(w)).length >= 2);
+};
+/** Whether the answer is (part of) a spelled address — letters said one at a time, or a spelled symbol. */
+export function isSpelledFragment(input) {
+    const b = normalize(input);
+    return !/@|\b(?:at|arroba)\b/.test(b) && isSpelling(b);
+}
+const SHAPES = {
+    number: (b) => /\d/.test(b) || NUMBER_WORD.test(b),
+    email: (b) => EMAIL_SHAPE.test(b) || isSpelling(b),
+    contact: (b) => /\d/.test(b) || NUMBER_WORD.test(b) || EMAIL_SHAPE.test(b) || isSpelling(b),
+};
+/**
+ * Whether a free-text answer to a question that expects a `kind` ('number' | 'email' | 'contact') is the caller
+ * changing direction ("what's my balance?" to "how much would you like to pay?") rather than an attempt at the answer:
+ * three or more words, none of them the expected shape. Such an answer is DISPATCHed, never counted as a failed try.
+ * A short miss ("what?") is not: the asking flow re-asks it.
+ */
+export function isOtherRequest(input, kind) {
+    const b = normalize(input);
+    const shape = SHAPES[kind];
+    if (!shape) {
+        return false;
+    }
+    else if (shape(b)) {
+        return false;
+    }
+    else {
+        return b.split(' ').filter((w) => /[a-záéíóúüñ]/.test(w)).length >= 3;
+    }
+}
+// An answer that names an amount: a currency sign or word, cents, or a number with decimals.
+const AMOUNT_ANSWER = /\$|\b(dollars?|d[oó]lar(es)?|bucks?|cents?|centavos?)\b|\d[.,]\d{1,2}\b/i;
+/**
+ * Whether the answer names an amount ("$1", "1 dollar", "un dólar", "50 cents", "12.50") rather than a keypad key.
+ * Such an answer never picks a digit choice (pickChoice): "$1" said at "press 1 to pay what is due" chose FULL and
+ * the caller was offered $235.90 (2026-10-14).
+ */
+export function isAmountAnswer(input) {
+    return AMOUNT_ANSWER.test(String(input ?? '').replace(/\\(['"\\])/g, '$1'));
+}
+// A number that names something other than an amount: an account or sub-account, a card's last digits, a code, a ZIP.
+const IDENTIFIER_NUMBER = /\b(?:sub[\s-]?accounts?|accounts?|subcuentas?|cuentas?|cards?|tarjetas?|ending(?:\s+in)?|terminad[ao]s?\s+en|que\s+termina\s+en|termina\s+en|codes?|c[oó]digos?|zip(?:\s+code)?|postal|n[uú]mero|number)\s*(?:de\s+|is\s+|es\s+)?\d[\d\s-]*/gi;
+// Digits spoken one at a time ("2 4 8 6"): a card ending or a code read back, never an amount.
+const SPELLED_DIGITS = /\b\d(?:\s+\d\b){2,}/g;
+// "10 con 18 centavos", "10 dollars and 18 cents", "$10 y 18 centavos"; speech-to-text also writes "76 con50 centavos", and
+// callers say "171 con un 6 centavos" (owner 2026-10-18; a prod call went to the guru): an "un" before the cents.
+const DOLLARS_AND_CENTS = /(\d+)\s*(?:dollars?|d[oó]lar(?:es)?|bucks?)?\s*(?:and|con|y)\s*(?:un\s+)?(\d{1,2})\s*(?:cents?|centavos?)\b/i;
+// Dollars joined to two cent digits with no word for cents: "82 dollars and 50", "$82 y 50", "82 con 50". The joiner
+// makes the second number cents when the first is marked as dollars ($ or a dollar word), or always for a joiner in
+// CENTS_JOINERS (the languages that say amounts that way: Spanish "ochenta y dos con cincuenta") when two digits follow.
+// "82 dollars and 5" is $82.05; "82 and 50" is $82.50; an unmarked "82 con 5", "82 and 5" or "82 y 50" stays two numbers. An "un" before the
+// cents is allowed ("171 con un 06").
+const CENTS_JOINERS = ['con', 'and']; // 'and' too (owner 2026-10-18: "87 and 21" = $87.21)
+const DOLLARS_JOINED_CENTS = /(\$\s*)?(\d+)(\s*(?:dollars?|d[oó]lar(?:es)?|bucks?))?\s*(and|con|y)\s*(?:un\s+)?(\d{1,2})\b(?!\s*\d)/gi;
+/**
+ * The amount an answer names, or NaN when it names none or is ambiguous. Prod replay 2026-10-14: the first number in the
+ * answer was taken, so "pagar cuenta 50, ciento treinta y cuatro…" paid $50, "$10 con 18 centavos" paid $10.00 and an
+ * offer read back with "terminada en 2 4 8 6" paid $2. Numbers that name an account, card, code or ZIP, and digits spoken
+ * one by one, are not amounts; two different remaining numbers are ambiguous unless exactly one is marked as money ($,
+ * dollars, cents or decimals). "50 cents" alone is $0.50; "82 dollars and 50" and "82 con 50" are $82.50. Amounts said only in words are NaN (not parsed yet).
+ */
+export function amountInAnswer(input) {
+    const raw = String(input ?? '').replace(/\\(['"\\])/g, '$1');
+    // 1.234,56 (European) → 1234.56; 1,234.56 → 1234.56; 12,50 → 12.50
+    let t = /\d{1,3}(\.\d{3})+,\d{1,2}\b/.test(raw) ? raw.replace(/\./g, '').replace(',', '.') : raw.replace(/,(?=\d{3}\b)/g, '').replace(/(\d),(\d{1,2})\b/g, '$1.$2');
+    const dc = t.match(DOLLARS_AND_CENTS);
+    if (dc) {
+        t = t.replace(DOLLARS_AND_CENTS, () => ` $${dc[1]}.${dc[2].padStart(2, '0')} `);
+    }
+    else {
+        // no dollars-and-cents phrase
+    }
+    t = t.replace(IDENTIFIER_NUMBER, ' ').replace(SPELLED_DIGITS, ' ').replace(DOLLARS_JOINED_CENTS, (m, sign, d, word, joiner, c) => (sign || word || (CENTS_JOINERS.includes(joiner.toLowerCase()) && c.length === 2) ? ` $${d}.${c.padStart(2, '0')} ` : m));
+    const found = [...t.matchAll(/(\$\s*)?(\d+(?:\.\d{1,2})?)(\s*(?:dollars?|d[oó]lar(?:es)?|bucks?|cents?|centavos?)\b)?/gi)]
+        .map((m) => ({ v: parseFloat(m[2]), marked: !!(m[1] || m[3] || m[2].includes('.')), cents: !m[1] && /cent/i.test(m[3] || '') }));
+    const values = [...new Set(found.map((f) => f.v))];
+    let pick = null;
+    if (values.length === 1) {
+        pick = found[0];
+    }
+    else if (values.length > 1) {
+        const marked = found.filter((f) => f.marked);
+        pick = new Set(marked.map((f) => f.v)).size === 1 ? marked[0] : null;
+    }
+    else {
+        // no number at all
+    }
+    if (!pick) {
+        return NaN;
+    }
+    else {
+        // Cents alone only when nothing else was said: "76 con50 centavos" read as $0.50 (prod, 10-15).
+        return pick.cents ? (values.length === 1 ? Math.round(pick.v) / 100 : NaN) : pick.v;
+    }
+}
+// Number words a caller says for a keypad key (prod 2026-10-16 7:07 AM: "dos" at "presione 2 o diga NO" was re-asked).
+const KEY_WORDS = { cero: '0', zero: '0', uno: '1', una: '1', one: '1', dos: '2', two: '2', tres: '3', three: '3', cuatro: '4',
+    four: '4', cinco: '5', five: '5', seis: '6', six: '6', siete: '7', seven: '7', ocho: '8', eight: '8', nueve: '9', nine: '9' };
+/** The normalized answer with each number word replaced by its digit ("dos por favor" → "2 por favor"). */
+function spokenKeys(b) {
+    return String(b).replace(/\./g, ' ').split(' ').filter(Boolean).map((t) => KEY_WORDS[t] ?? t).join(' ');
+}
+/**
+ * ask-choice's matcher: the key of the choice the answer picks, '__agent', '__exit', or '' (no choice).
+ * choices: [{ key, words, negative?, neutral?, exact? }]. A key (digit, * or #) and a YES word pick a choice only as the whole
+ * answer, courtesy aside (onlyAffirmative); an `exact` choice (one that charges or cancels) treats ALL its words that way. A choice keyed 'yes' also takes ANSWER_WORDS.yes (CONFIRM_WORDS when `exact`) and, when not `exact`, a bare thanks (THANKS), and the NO-type
+ * choice (key no / decline / done / cancel, or negative: true) also takes ANSWER_WORDS.no, so callers list only their
+ * extras. A word after a negation in its clause is negated: it picks the NO-type choice; a `neutral` choice still
+ * matches unless it follows its negation within two words; any other choice is blocked and NO answers. A deferral
+ * (later, mañana) answers NO; a reply led by a bare 'no' turns YES into NO. With acceptOther, AGENT only when the
+ * whole answer is an agent request and EXIT only on exit/quit/salir/abort (cancel is an answer there).
+ */
+export function pickChoice(answer, choices, acceptOther) {
+    const raw = String(answer ?? '').replace(/\\(['"\\])/g, '$1');
+    const b = normalize(raw);
+    const pos = [];
+    const negs = [];
+    raw.split(/[,;!?]|\.\s|\s(?:but|pero)\s/i).map(normalize).forEach((clause) => {
+        const tk = clause.split(' ');
+        const k = tk.findIndex((t) => NEGATION_SET.has(t));
+        if (k < 0) {
+            pos.push(clause);
+        }
+        else {
+            pos.push(tk.slice(0, k).join(' '));
+            negs.push(tk.slice(k).join(' '));
+        }
+    });
+    const P = pos.join(' ~ ');
+    const N = negs.join(' ~ ');
+    const refused = (w) => {
+        const wt = w.split(' ');
+        return negs.some((r) => {
+            const tk = r.split(' ');
+            for (let q = 1; q < tk.length && q <= 2; q++) {
+                if (tk.slice(q, q + wt.length).join(' ') === w) {
+                    return true;
+                }
+                else {
+                    // not at this offset
+                }
+            }
+            return false;
+        });
+    };
+    const leadNo = /^(no|nope|nah|no thanks|no gracias)$/.test(normalize(raw.split(/[,;!?]|\.\s/)[0]));
+    const cs = Array.isArray(choices) ? choices.filter((c) => c && c.key) : [];
+    const isNoType = (c) => ['no', 'decline', 'done', 'cancel'].includes(c.key) || c.negative === true;
+    const noChoice = (cs.find(isNoType) || {}).key || '';
+    const deferral = DEFERRAL.test(b);
+    const amount = isAmountAnswer(raw); // an amount never picks a keypad key
+    const spoken = spokenKeys(b); // "dos", "two": a key said as a word picks what the digit would
+    let blocked = false;
+    let found = '';
+    for (const c of cs) {
+        const own = Array.isArray(c.words) ? c.words : [];
+        const all = c.key === 'yes' ? [...own, ...(c.exact === true ? CONFIRM_WORDS : ANSWER_WORDS.yes)] : (c.key === noChoice ? [...own, ...ANSWER_WORDS.no] : own);
+        // Strict words pick this choice only when they are the whole answer (onlyAffirmative): a key, a YES word, or — on an
+        // `exact` choice (one that charges or cancels) — every word. The rest (named actions: LINK, RECEIPT…) match inside it.
+        const strict = all.filter((w) => c.exact === true || /^[0-9*#]$/.test(String(w).trim()) || YES_SET.has(normalize(w)))
+            .filter((w) => !(amount && /^\d+$/.test(String(w).trim())));
+        const isKey = (w) => /^[0-9*#]$/.test(String(w).trim());
+        const keyed = (w) => isKey(w) && (matchesChoice(raw, [w]) || keyWithOnlyCourtesy(b, String(w).trim(), !isNoType(c)) || (spoken !== b && keyWithOnlyCourtesy(spoken, String(w).trim(), !isNoType(c))));
+        // A question is not a confirmation: "sure?" or "1?" never picks a choice that charges or cancels.
+        if (c.exact === true && /[?¿]/.test(raw)) {
+            // not this choice
+        }
+        else if (strict.some(keyed) || onlyAffirmative(b, [...strict.filter((w) => !isKey(w)), ...(c.key === 'yes' && c.exact !== true ? THANKS : [])], true, c.exact === true ? (c.key === 'yes' ? ACKNOWLEDGEMENTS : [...ACKNOWLEDGEMENTS, ...CONFIRM_FILLER, ...ARTICLES]) : [])) {
+            found = c.key;
+            break;
+        }
+        else {
+            // not by a strict word
+        }
+        for (const w of all.map(normalize).filter((w) => !strict.map(normalize).includes(w) && !/^[0-9*#]$/.test(w) && !(c.exact === true))) {
+            if (!w || (amount && /^\d+$/.test(w))) {
+                continue;
+            }
+            else if (c.key === noChoice || c.key === 'no' || c.negative === true || hasNegation(w)) {
+                if (matchesChoice(b, [w])) {
+                    found = c.key;
+                }
+                else {
+                    // a NO-type word matches the whole answer only
+                }
+            }
+            else if (matchesChoice(P, [w])) {
+                found = c.key;
+            }
+            else if (matchesChoice(N, [w])) {
+                if (c.neutral === true && !refused(w)) {
+                    found = c.key;
+                }
+                else {
+                    blocked = true;
+                }
+            }
+            else {
+                // not this word
+            }
+            if (found) {
+                break;
+            }
+            else {
+                // keep looking
+            }
+        }
+        if (found) {
+            break;
+        }
+        else {
+            // next choice
+        }
+    }
+    if (noChoice && deferral && found !== noChoice) {
+        return noChoice;
+    }
+    else if (found === 'yes' && leadNo && noChoice) {
+        return noChoice;
+    }
+    else if (found) {
+        return found;
+    }
+    else if (blocked && noChoice) {
+        return noChoice;
+    }
+    else if ((b === '0' && !amount) || (!hasNegation(b) && !b.includes('@') && (AGENT_ONLY.test(b) || (!acceptOther && matchesChoice(b, ANSWER_WORDS.agent.filter((w) => !AGENT_AMBIGUOUS.has(w))))))) {
+        return '__agent';
+    }
+    else if (b === '*' || (acceptOther ? /^(exit|quit|salir|abort)( please| por favor)?$/ : /^(exit|quit|salir|abort|cancel|cancelar)( please| por favor)?$/).test(b)) {
+        return '__exit';
+    }
+    else {
+        return '';
+    }
+}

package/dist/helpers/capture.d.ts

@@ -0,0 +1,5 @@
+export function normalizeAndFindCapture(userInput: any, patterns: any, warn?: () => void): {
+    variable: any;
+    value: any;
+} | null;
+//# sourceMappingURL=capture.d.ts.map

package/dist/helpers/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/helpers/capture.js"],"names":[],"mappings":"AAeA;;;SA8BC"}

package/dist/helpers/capture.js

@@ -0,0 +1,50 @@
+/**
+ * normalizeAndFindCapture (APPROVED_FUNCTIONS): the first capture pattern a free answer matches, as
+ * { variable, value } (value = the matched part) — the retry menu's "a contact in the answer retries with it" (generic-retry-with-options
+ * capture_patterns: [{ variable, regex, normalizer? }]). The normalizer is removed from the answer first
+ * (e.g. '[^0-9]' leaves the digits of "213-555-0100"). A pattern whose regex is invalid is skipped and reported
+ * through `warn`, so one bad tenant pattern cannot stop the others.
+ *
+ * A pattern may name a reader instead of a regex: { variable, reader: 'phone' | 'email' } reads the answer with
+ * readPhone / readEmail (spoken and spelled forms included).
+ *
+ * Part of jsfe/helpers; imports only its sibling contact.js.
+ */
+import { readEmail, readPhone } from './contact.js';
+const READERS = { phone: readPhone, email: readEmail };
+export function normalizeAndFindCapture(userInput, patterns, warn = () => { }) {
+    if (!Array.isArray(patterns)) {
+        return null;
+    }
+    else {
+        for (const pattern of patterns) {
+            if (pattern && READERS[pattern.reader]) {
+                const value = READERS[pattern.reader](userInput);
+                if (value) {
+                    return { variable: pattern.variable, value };
+                }
+                else {
+                    continue;
+                }
+            }
+            else {
+                // a regex pattern
+            }
+            try {
+                const value = pattern.normalizer ? String(userInput ?? '').replace(new RegExp(pattern.normalizer, 'g'), '') : String(userInput ?? '');
+                const match = new RegExp(pattern.regex).exec(value);
+                if (match) {
+                    // the matched part only: "my email is a@b.com" captures a@b.com
+                    return { variable: pattern.variable, value: match[0].trim() };
+                }
+                else {
+                    // not this pattern
+                }
+            }
+            catch (e) {
+                warn(`Invalid regex in capture pattern: ${e.message}`);
+            }
+        }
+        return null;
+    }
+}

package/dist/helpers/card-checks.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Card checks the payment flows call (validateCardNumber / validateExpiration). Pure; part of jsfe/helpers.
+ */
+/** 12–19 digits passing the Luhn checksum (catches nearly every typo, on every network). */
+export function validateCardNumber(input: any): boolean;
+/** MM and YY (two digits each), a real month, not expired, at most 20 years out. `now` is for tests. */
+export function validateExpiration(month: any, year: any, now?: Date): boolean;
+//# sourceMappingURL=card-checks.d.ts.map

package/dist/helpers/card-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-checks.d.ts","sourceRoot":"","sources":["../../src/helpers/card-checks.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH,4FAA4F;AAC5F,wDAoBC;AAED,wGAAwG;AACxG,+EAYC"}

package/dist/helpers/card-checks.js

@@ -0,0 +1,46 @@
+/**
+ * Card checks the payment flows call (validateCardNumber / validateExpiration). Pure; part of jsfe/helpers.
+ */
+/** 12–19 digits passing the Luhn checksum (catches nearly every typo, on every network). */
+export function validateCardNumber(input) {
+    const cleaned = String(input || '').replace(/\D/g, '');
+    if (cleaned.length < 12 || cleaned.length > 19) {
+        return false;
+    }
+    else {
+        let sum = 0;
+        let double = false;
+        for (let i = cleaned.length - 1; i >= 0; i--) {
+            let d = parseInt(cleaned[i], 10);
+            if (double) {
+                d *= 2;
+                if (d > 9)
+                    d -= 9;
+            }
+            else {
+                // undoubled digit
+            }
+            sum += d;
+            double = !double;
+        }
+        return sum % 10 === 0;
+    }
+}
+/** MM and YY (two digits each), a real month, not expired, at most 20 years out. `now` is for tests. */
+export function validateExpiration(month, year, now = new Date()) {
+    const m = String(month || '').replace(/\D/g, '');
+    const y = String(year || '').replace(/\D/g, '');
+    if (m.length !== 2 || y.length !== 2)
+        return false;
+    const mNum = parseInt(m, 10);
+    const yNum = parseInt(y, 10);
+    if (mNum < 1 || mNum > 12)
+        return false;
+    const curYear = now.getFullYear() % 100;
+    const curMonth = now.getMonth() + 1;
+    if (yNum < curYear)
+        return false;
+    if (yNum === curYear && mNum < curMonth)
+        return false;
+    return yNum <= curYear + 20;
+}

package/dist/helpers/contact.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The email address in the answer, lowercased, or ''. At / arroba and dot / punto may be spoken, and the name before
+ * the @ may come in several pieces ("J. A Garcia at example.com", "j u a n", "Maria jose@example.com"): every piece
+ * back to the first lead-in word ("my email is", "mi correo es") is kept and joined. On a call the address is read
+ * back for a YES / NO, so a misheard piece can be corrected; a dropped one could not. Accents are dropped from the
+ * name (an address cannot carry them), and only the last @ counts.
+ */
+export function readEmail(text: any): string;
+/** The 10-digit North American number in the answer (a leading 1 dropped), or ''. */
+export function readPhone(text: any): string;
+/**
+ * A phone number from outside the US / Canada in the answer, as its digits with the country code, or ''. With an
+ * explicit prefix ("+", "plus", "más", "00") 8-15 digits; without one 11-13 digits not starting with 1 (a card or an
+ * account number is not mistaken for one). US / Canada numbers are readPhone's. The flows say what such a number
+ * cannot be used for instead of "I didn't get that" (owner, 2026-10-14).
+ */
+export function readInternationalPhone(text: any): string;
+/** Whether the caller's own number (cargo.callerId) is from outside the US / Canada: on a call, a real caller ID. */
+export function callerIsInternational(cargo: any): boolean;
+/**
+ * What the customer identified themselves with: { kind: 'account' | 'phone' | 'international_phone' | 'email', value } or
+ * null.
+ * accountPattern (a regex source, e.g. '^5\\d{6,7}$') is the tenant's account-number shape; its digits win first.
+ */
+export function readIdentifier(text: any, accountPattern?: string): {
+    kind: string;
+    value: string;
+} | null;
+/**
+ * The last four characters of a number (card, account, phone, tracking) as said to the customer: spaced one by one on a
+ * call ("5, 4, 7, 5"), as written otherwise ("5475"). Written ~25 times inline across the flow sets before it.
+ */
+export function last4(value: any, voice: any): string;
+/**
+ * An email said back to the customer without reading all of it out. On a call: its first two characters spaced
+ * one by one and its domain ("starting with r, o, at gmail.com" / "que empieza con r, o, arroba gmail.com"): "ending
+ * in @gmail.com" alone is ambiguous on a call, and "ro***" makes the speech engine read the asterisks. Written:
+ * "ro***@gmail.com". '' for anything that is not an email.
+ */
+export function maskEmail(email: any, voice: any, lang?: string): string;
+/**
+ * The number we can text the caller at, 10 digits, or '': ONE rule for offering TEXT and for sending one. Only on a
+ * call with a sender (cargo.twilioNumber), a US / Canada caller ID, and not the number a code could not be texted to
+ * (cargo.otpUndeliverableTo). A number from another country used to be cut to its last 10 digits and offered TEXT,
+ * which then failed (dev calls from +52, 2026-10-13).
+ */
+export function callerTextNumber(cargo: any): string;
+/** Where a text to the customer can go, 10 digits or '': the verified cell, else the caller (callerTextNumber). */
+export function textDestination(cargo: any): string;
+//# sourceMappingURL=contact.d.ts.map

package/dist/helpers/contact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact.d.ts","sourceRoot":"","sources":["../../src/helpers/contact.js"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,6CAwBC;AAED,qFAAqF;AACrF,6CASC;AAED;;;;;GAKG;AACH,0DAgBC;AAED,qHAAqH;AACrH,2DAIC;AAED;;;;GAIG;AACH;;;SAmBC;AAED;;;GAGG;AACH,sDAOC;AAED;;;;;GAKG;AACH,yEAUC;AAQD;;;;;GAKG;AACH,qDAIC;AAED,mHAAmH;AACnH,oDAIC"}