jsfe 1.4.2 → 1.5.0

package/dist/helpers/matches-choice.js

@@ -0,0 +1,61 @@
+/**
+ * Strict word-aware option matching for flow CASE conditions (APPROVED_FUNCTIONS.matchesChoice) —
+ * replaces the substring `.some(choice => input.includes(choice))` idiom, whose false positives broke
+ * branch routing ('si' inside "imposible"/"así" matched YES, prod-observed 2026-08-09).
+ *
+ * Rules (deliberately NO fuzzy/prefix matching):
+ *  - single-word choice: exact word membership
+ *  - multi-word choice: exact word-sequence containment
+ *  - plurals/inflections: enumerate them explicitly in the choice list
+ *  - a keypad key (one digit, * or #) matches ONLY an answer that is exactly that key, never a key
+ *    inside a longer answer (owner rule): "I made payments by 1," at "press 1 to pay" charged the full
+ *    amount due on dev, 2026-10-14
+ *  - an ELONGATED word the user typed is forgiven (2026-10-01): a repeated vowel or any letter typed
+ *    3+ times collapses — "Sii" matches 'si', "nadaaaa" 'nada', "yesss" 'yes'. A typed "Sii" at the
+ *    authentication retry menu ended the conversation in contact-support. Only the user's word is
+ *    collapsed, and only against an option word with no doubled letter of its own. Measured on a
+ *    week of prod prompts (scratch replay, 98 option lists × 23,692 prompts):
+ *      · collapsing BOTH sides: rejected — 'all' → 'al' made "servicio al cliente" (138 turns) pick
+ *        the "all" option, and 'mm' → 'm' made "I'm" a filler;
+ *      · collapsing every doubled letter of the user's word: rejected — "mess" matched Spanish
+ *        'mes' and "Mall" 'mal'. A doubled consonant is real spelling, so "okk" stays unmatched.
+ *
+ * Zero imports, so scripts/tests/matches-choice.mjs runs the real implementation.
+ */
+export function matchesChoice(input, choices) {
+    if (!input || !Array.isArray(choices)) {
+        return false;
+    }
+    // One tokenizer for both sides: letters/digits/'*' are word chars, everything
+    // else (commas, ¿?¡!, periods) separates — so callers need no pre-normalization.
+    const tokenize = (s) => String(s).toLowerCase().split(/[^\p{L}\p{N}*]+/u).filter(Boolean);
+    // Elongation, not spelling: a repeated VOWEL, or any letter typed 3+ times. A doubled consonant
+    // is real spelling too often ("mess" would become Spanish 'mes', "Mall" 'mal').
+    const collapse = (word) => word.replace(/([aeiouáéíóúü])\1+/gu, '$1').replace(/(\p{L})\1{2,}/gu, '$1');
+    const hasDoubledLetter = (word) => /(\p{L})\1/u.test(word);
+    const words = tokenize(input);
+    const collapsedWords = words.map(collapse);
+    const sameWord = (i, choiceWord) => words[i] === choiceWord
+        || (!hasDoubledLetter(choiceWord) && collapsedWords[i] === choiceWord);
+    return choices.some(choice => {
+        const choiceWords = tokenize(choice);
+        if (/^[0-9*#]$/.test(String(choice).trim())) {
+            return String(input).replace(/^[\s.,;:!?¿¡'"]+|[\s.,;:!?¿¡'"]+$/g, '') === String(choice).trim();
+        }
+        else if (choiceWords.length === 0) {
+            return false;
+        }
+        else {
+            // a single word, or a multi-word entry ('thank you', 'por favor') as a consecutive run
+            for (let i = 0; i <= words.length - choiceWords.length; i++) {
+                if (choiceWords.every((c, j) => sameWord(i + j, c))) {
+                    return true;
+                }
+                else {
+                    // no run starting here
+                }
+            }
+            return false;
+        }
+    });
+}

package/dist/helpers/otp-check.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @param {{otpHash?: string|null, otpTimestamp?: number|null}} stored  the container's pending code
+ * @param {string} providedHash  sha256 of what the customer entered
+ * @param {number} now
+ * @returns {{ok: boolean, failure: null|'missing'|'expired'|'mismatch'}}
+ */
+export function checkOtp(stored: {
+    otpHash?: string | null;
+    otpTimestamp?: number | null;
+}, providedHash: string, now: number): {
+    ok: boolean;
+    failure: null | "missing" | "expired" | "mismatch";
+};
+/** A destination for a log line: the last 4 digits of a phone, or the domain of an email. */
+export function maskDestination(to: any): string;
+/**
+ * A flow's code check (validateOTP): hashes what the customer entered (SHA-256, the hash the code senders store in
+ * container.otpHash) and checks it with checkOtp. Accepted: the pending code is cleared and container.otpVerified /
+ * otpVerifiedAt are set. Expired: the code is cleared (it can never be accepted again). Every refusal leaves its reason
+ * in container.otpFailure ('missing' | 'expired' | 'mismatch'). Uses the platform's Web Crypto, so it needs no host.
+ */
+export function validateOTP(otp: any, container: any): Promise<boolean>;
+/**
+ * Is this one-time code accepted — and if not, WHY? (validateOTP)
+ *
+ * validateOTP returns a boolean, which every flow condition depends on. Until 2026-10-05 the reason
+ * a code was refused was lost: an EXPIRED code (which validateOTP also clears) and a wrong one
+ * both read as "That code didn't match. Let's try again." — and the flow asked again for a code
+ * that could no longer exist. A WhatsApp customer looped for 19 minutes on
+ * exactly that (2026-10-05). The reason now rides on the container as `otpFailure`, so the
+ * flow can send a fresh code for 'expired' / 'missing' and re-ask only on 'mismatch'.
+ *
+ * Pure, no imports. Tested by scripts/tests/otp-check.mjs in CI.
+ */
+export const OTP_EXPIRY_MS: number;
+//# sourceMappingURL=otp-check.d.ts.map

package/dist/helpers/otp-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otp-check.d.ts","sourceRoot":"","sources":["../../src/helpers/otp-check.js"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,iCALW;IAAC,OAAO,CAAC,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,GAAC,IAAI,CAAA;CAAC,gBACnD,MAAM,OACN,MAAM,GACJ;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,IAAI,GAAC,SAAS,GAAC,SAAS,GAAC,UAAU,CAAA;CAAC,CAYvE;AAED,6FAA6F;AAC7F,iDAQC;AAED;;;;;GAKG;AACH,wEAsBC;AAxED;;;;;;;;;;;GAWG;AAEH,mCAA4C"}

package/dist/helpers/otp-check.js

@@ -0,0 +1,75 @@
+/**
+ * Is this one-time code accepted — and if not, WHY? (validateOTP)
+ *
+ * validateOTP returns a boolean, which every flow condition depends on. Until 2026-10-05 the reason
+ * a code was refused was lost: an EXPIRED code (which validateOTP also clears) and a wrong one
+ * both read as "That code didn't match. Let's try again." — and the flow asked again for a code
+ * that could no longer exist. A WhatsApp customer looped for 19 minutes on
+ * exactly that (2026-10-05). The reason now rides on the container as `otpFailure`, so the
+ * flow can send a fresh code for 'expired' / 'missing' and re-ask only on 'mismatch'.
+ *
+ * Pure, no imports. Tested by scripts/tests/otp-check.mjs in CI.
+ */
+export const OTP_EXPIRY_MS = 10 * 60 * 1000;
+/**
+ * @param {{otpHash?: string|null, otpTimestamp?: number|null}} stored  the container's pending code
+ * @param {string} providedHash  sha256 of what the customer entered
+ * @param {number} now
+ * @returns {{ok: boolean, failure: null|'missing'|'expired'|'mismatch'}}
+ */
+export function checkOtp(stored, providedHash, now) {
+    if (!stored || !stored.otpHash || !stored.otpTimestamp) {
+        return { ok: false, failure: 'missing' };
+    }
+    else if (now - stored.otpTimestamp > OTP_EXPIRY_MS) {
+        return { ok: false, failure: 'expired' };
+    }
+    else if (providedHash !== stored.otpHash) {
+        return { ok: false, failure: 'mismatch' };
+    }
+    else {
+        return { ok: true, failure: null };
+    }
+}
+/** A destination for a log line: the last 4 digits of a phone, or the domain of an email. */
+export function maskDestination(to) {
+    const s = String(to || '');
+    if (s.includes('@')) {
+        return `…@${s.split('@').pop()}`;
+    }
+    else {
+        const digits = s.replace(/\D/g, '');
+        return digits ? `…${digits.slice(-4)}` : '(none)';
+    }
+}
+/**
+ * A flow's code check (validateOTP): hashes what the customer entered (SHA-256, the hash the code senders store in
+ * container.otpHash) and checks it with checkOtp. Accepted: the pending code is cleared and container.otpVerified /
+ * otpVerifiedAt are set. Expired: the code is cleared (it can never be accepted again). Every refusal leaves its reason
+ * in container.otpFailure ('missing' | 'expired' | 'mismatch'). Uses the platform's Web Crypto, so it needs no host.
+ */
+export async function validateOTP(otp, container) {
+    const bytes = new TextEncoder().encode(String(otp ?? ''));
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    const providedHash = Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, '0')).join('');
+    const verdict = checkOtp(container, providedHash, Date.now());
+    if (verdict.ok) {
+        container.otpHash = null;
+        container.otpTimestamp = null;
+        delete container.otpFailure;
+        container.otpVerified = true;
+        container.otpVerifiedAt = Date.now();
+        return true;
+    }
+    else if (verdict.failure === 'expired') {
+        container.otpHash = null;
+        container.otpTimestamp = null;
+        container.otpVerified = false;
+        container.otpFailure = 'expired';
+        return false;
+    }
+    else {
+        container.otpFailure = verdict.failure;
+        return false;
+    }
+}

package/dist/helpers/phrases.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sentences the flows say in many places, written once and addressed to the customer by name when the session knows it
+ * (APPROVED_FUNCTIONS anythingElse, goodbye). Before it, one flow set's closing question was typed into 30 English and 30
+ * Spanish SAYs, none of them using the name the account lookup had found. Part of jsfe/helpers; zero imports.
+ */
+/** A name as said to the customer: trimmed; an all-capitals name (as account systems store it) in title case. */
+export function sayName(name: any): string;
+/** The closing question after a task is done, in the turn's language ('en' when there is none), with the name if known. */
+export function anythingElse(lang: any, name: any): any;
+/** The parting wish when a conversation ends, in the turn's language, with the name if known. */
+export function goodbye(lang: any, name: any): any;
+//# sourceMappingURL=phrases.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"phrases.d.ts","sourceRoot":"","sources":["../../src/helpers/phrases.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iHAAiH;AACjH,2CAOC;AAWD,2HAA2H;AAC3H,wDAEC;AAED,iGAAiG;AACjG,mDAEC"}

package/dist/helpers/phrases.js

@@ -0,0 +1,31 @@
+/**
+ * Sentences the flows say in many places, written once and addressed to the customer by name when the session knows it
+ * (APPROVED_FUNCTIONS anythingElse, goodbye). Before it, one flow set's closing question was typed into 30 English and 30
+ * Spanish SAYs, none of them using the name the account lookup had found. Part of jsfe/helpers; zero imports.
+ */
+/** A name as said to the customer: trimmed; an all-capitals name (as account systems store it) in title case. */
+export function sayName(name) {
+    const n = String(name ?? '').trim();
+    if (n && n === n.toUpperCase() && /[A-ZÁÉÍÓÚÑ]/.test(n)) {
+        return n.toLowerCase().replace(/(^|[\s'-])(\p{L})/gu, (m, sep, ch) => sep + ch.toUpperCase());
+    }
+    else {
+        return n;
+    }
+}
+const ANYTHING_ELSE = {
+    en: (n) => (n ? `Is there anything else I can help you with, ${n}?` : 'Is there anything else I can help you with?'),
+    es: (n) => (n ? `¿Hay algo más en lo que pueda ayudarle, ${n}?` : '¿Hay algo más en lo que pueda ayudarle?'),
+};
+const GOODBYE = {
+    en: (n) => (n ? `Have a great day, ${n}!` : 'Have a great day!'),
+    es: (n) => (n ? `¡Que tenga un buen día, ${n}!` : '¡Que tenga un buen día!'),
+};
+/** The closing question after a task is done, in the turn's language ('en' when there is none), with the name if known. */
+export function anythingElse(lang, name) {
+    return (ANYTHING_ELSE[lang] || ANYTHING_ELSE.en)(sayName(name));
+}
+/** The parting wish when a conversation ends, in the turn's language, with the name if known. */
+export function goodbye(lang, name) {
+    return (GOODBYE[lang] || GOODBYE.en)(sayName(name));
+}

package/dist/helpers/url-speech.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A URL said aloud (urlToSpeech, textWithUrlToSpeech): protocol, query and fragment dropped, "www." dropped, dots,
+ * slashes, dashes and underscores as words, in English or Spanish. Pure; part of jsfe/helpers.
+ */
+export function urlToSpeech(url: any, language?: string): string;
+/** Every URL in a text said aloud. */
+export function textWithUrlToSpeech(text: any, language?: string): any;
+//# sourceMappingURL=url-speech.d.ts.map

package/dist/helpers/url-speech.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-speech.d.ts","sourceRoot":"","sources":["../../src/helpers/url-speech.js"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iEAaC;AAED,sCAAsC;AACtC,uEAMC"}

package/dist/helpers/url-speech.js

@@ -0,0 +1,28 @@
+/**
+ * A URL said aloud (urlToSpeech, textWithUrlToSpeech): protocol, query and fragment dropped, "www." dropped, dots,
+ * slashes, dashes and underscores as words, in English or Spanish. Pure; part of jsfe/helpers.
+ */
+export function urlToSpeech(url, language = 'en') {
+    if (!url || typeof url !== 'string') {
+        return '';
+    }
+    else {
+        const words = language === 'es'
+            ? { dot: 'punto', slash: 'diagonal', dash: 'guión', underscore: 'guión bajo' }
+            : { dot: 'dot', slash: 'slash', dash: 'dash', underscore: 'underscore' };
+        const bare = url.replace(/^https?:\/\//i, '').replace(/\?.*$/, '').replace(/#.*$/, '').replace(/\/+$/, '');
+        const slashIdx = bare.indexOf('/');
+        const domain = (slashIdx >= 0 ? bare.substring(0, slashIdx) : bare).replace(/^www\./i, '').replace(/\./g, ` ${words.dot} `);
+        const path = (slashIdx >= 0 ? bare.substring(slashIdx) : '').replace(/\//g, ` ${words.slash} `).replace(/-/g, ` ${words.dash} `).replace(/_/g, ` ${words.underscore} `);
+        return (domain + ' ' + path).replace(/\s+/g, ' ').trim();
+    }
+}
+/** Every URL in a text said aloud. */
+export function textWithUrlToSpeech(text, language = 'en') {
+    if (!text || typeof text !== 'string') {
+        return text;
+    }
+    else {
+        return text.replace(/https?:\/\/[^\s]+/gi, (url) => urlToSpeech(url, language));
+    }
+}

package/dist/helpers/validators.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shape checks flows call in conditions (validateDigits, validatePhone, validateEmail). Pure; part of jsfe/helpers.
+ */
+/** Only digits, and between minDigits and maxDigits of them. */
+export function validateDigits(input: any, minDigits: any, maxDigits: any): boolean;
+/**
+ * A US phone number (10 digits, or 11 starting with 1), or with acceptInternational any 11–15 digits. String() first:
+ * a flow can hand over a number (an all-digit answer evaluated to Number).
+ */
+export function validatePhone(phone: any, acceptInternational?: boolean): boolean;
+/** Something@something.tld, no spaces. */
+export function validateEmail(email: any): boolean;
+//# sourceMappingURL=validators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/helpers/validators.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gEAAgE;AAChE,oFAMC;AAED;;;GAGG;AACH,kFASC;AAED,0CAA0C;AAC1C,mDAEC"}

package/dist/helpers/validators.js

@@ -0,0 +1,32 @@
+/**
+ * Shape checks flows call in conditions (validateDigits, validatePhone, validateEmail). Pure; part of jsfe/helpers.
+ */
+/** Only digits, and between minDigits and maxDigits of them. */
+export function validateDigits(input, minDigits, maxDigits) {
+    if (!/^\d+$/.test(input)) {
+        return false;
+    }
+    else {
+        return input.length >= minDigits && input.length <= maxDigits; // as the host had it: a Number input has no length
+    }
+}
+/**
+ * A US phone number (10 digits, or 11 starting with 1), or with acceptInternational any 11–15 digits. String() first:
+ * a flow can hand over a number (an all-digit answer evaluated to Number).
+ */
+export function validatePhone(phone, acceptInternational = false) {
+    const cleaned = String(phone ?? '').replace(/\D/g, '');
+    if (cleaned.length === 10 || (cleaned.length === 11 && cleaned.startsWith('1'))) {
+        return true;
+    }
+    else if (acceptInternational && cleaned.length >= 11 && cleaned.length <= 15) {
+        return true;
+    }
+    else {
+        return false;
+    }
+}
+/** Something@something.tld, no spaces. */
+export function validateEmail(email) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(email ?? ''));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsfe",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "TypeScript workflow engine for conversational/automation apps: multi-flow orchestration, interrupt/resume, stack-based control, robust errors, and flexible tool/REST integration.",
   "license": "MIT",
   "author": "Ron Pinkas",
@@ -18,6 +18,10 @@
     "./host": {
       "types": "./dist/host/index.d.ts",
       "import": "./dist/host/index.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers/index.d.ts",
+      "import": "./dist/helpers/index.js"
     }
   },
   "main": "./dist/index.js",