jsfe 1.4.1 → 1.5.0

package/README.md

@@ -342,6 +342,31 @@ const body = buildAiRequest(
   - `mergeTextParameters` adds a text model's free-text parameters only when the text model chose
     the same flow. The classifier's enum and boolean values always win.
 
+**Flow helpers — `jsfe/helpers`:**
+The functions the bundled system flows (`ask-choice`, `collect-input`, `authenticate-user`…) call from
+expressions, so every host runs the same ones. Pure: no credentials, no network. The engine does not
+register them by itself; a host lists them among its approved functions:
+
+```javascript
+import { STANDARD_FUNCTIONS } from 'jsfe/helpers';
+
+const engine = new WorkflowEngine(logger, aiCallback, flows, tools,
+  { ...STANDARD_FUNCTIONS, sendSMSOTP, sendEmail /* the host's own, credentialed functions */ });
+```
+
+- Reading answers: `matchesChoice`, `pickChoice`, `isAnswer`, `isAgentRequest`, `isOtherRequest`,
+  `isSpelledFragment`, `isAmountAnswer`, `amountInAnswer`, `readEmail`, `readPhone`,
+  `readInternationalPhone`, `readIdentifier`, `normalizeAndFindCapture`, and `matchInputs` (which of a
+  form's inputs an answer fills; ties between inputs of the same form are returned for the flow to ask).
+- Saying values: `amountToSpeech`, `dateToWords`, `last4`, `maskEmail`, `urlToSpeech`,
+  `textWithUrlToSpeech`, `anythingElse`, `goodbye`.
+- Checks: `validateDigits`, `validatePhone`, `validateEmail`, `validateCardNumber`,
+  `validateExpiration`, and `validateOTP(code, container)`, which accepts a code whose SHA-256 matches
+  `container.otpHash` within 10 minutes of `container.otpTimestamp` and leaves the reason for a refusal
+  in `container.otpFailure` (`missing`, `expired` or `mismatch`). Sending the code is the host's job.
+- Session-aware helpers read only the cargo a caller passes: `callerTextNumber`, `textDestination`,
+  `callerIsInternational`.
+
 **Alternative AI Services:**
 You can integrate any AI service (Claude, Gemini, local LLMs, etc.) by implementing this same interface. The engine only requires a function that takes system instructions and user input, then returns an AI response.
 

package/dist/helpers/amount-to-speech.d.ts

@@ -0,0 +1,6 @@
+/**
+ * An amount for a reply: spoken in words on voice ("Fifty Dollars and Twenty Five Cents", "Cincuenta dólares…"), written
+ * as '$1,500.00' on text. amountToSpeech; pure, part of jsfe/helpers.
+ */
+export function amountToSpeech(amount: any, language?: string, voice?: boolean): string;
+//# sourceMappingURL=amount-to-speech.d.ts.map

package/dist/helpers/amount-to-speech.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount-to-speech.d.ts","sourceRoot":"","sources":["../../src/helpers/amount-to-speech.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wFA4MC"}

package/dist/helpers/amount-to-speech.js

@@ -0,0 +1,195 @@
+/**
+ * An amount for a reply: spoken in words on voice ("Fifty Dollars and Twenty Five Cents", "Cincuenta dólares…"), written
+ * as '$1,500.00' on text. amountToSpeech; pure, part of jsfe/helpers.
+ */
+export function amountToSpeech(amount, language = 'en', voice = true) {
+    try {
+        if (!voice) {
+            // Written: '$1,500.00' (it was the bare number, '1500.00', in every text reply).
+            const n = typeof amount === 'number' ? amount : parseFloat(String(amount).replace(/[^-0-9.]/g, ''));
+            return isNaN(n) ? String(amount) : (n < 0 ? '-' : '') + '$' + Math.abs(n).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+        }
+        if (!language) {
+            language = 'en';
+        }
+        if (language === 'en') {
+            const units = ["", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine", "Ten", "Eleven", "Twelve", "Thirteen", "Fourteen", "Fifteen", "Sixteen", "Seventeen", "Eighteen", "Nineteen"];
+            const tens = ["", "", "Twenty", "Thirty", "Forty", "Fifty", "Sixty", "Seventy", "Eighty", "Ninety"];
+            const scales = ["", "Thousand", "Million", "Billion"];
+            function convertSmallNumber(num) {
+                let words = "";
+                if (num >= 100) {
+                    words += units[Math.floor(num / 100)] + " Hundred ";
+                    num %= 100;
+                }
+                if (num >= 20) {
+                    words += tens[Math.floor(num / 10)] + (num % 10 !== 0 ? " " + units[num % 10] : "") + " ";
+                }
+                else if (num > 0) {
+                    words += units[num] + " ";
+                }
+                return words;
+            }
+            // 0. Validate and normalize input
+            if (typeof amount === 'string') {
+                amount = amount.replace(/[^-0-9.]/g, ''); // Keep the minus sign!
+            }
+            const numAmount = parseFloat(amount);
+            if (isNaN(numAmount)) {
+                return "Invalid amount";
+            }
+            if (Math.abs(numAmount) >= 1000000000000) {
+                return "Amount exceeds 999 Billion limit";
+            }
+            // 1. Handle "Negative" prefix and work with absolute value
+            const isNegative = numAmount < 0;
+            let absoluteAmount = Math.abs(numAmount);
+            // 2. Split Dollars and Cents
+            const parts = absoluteAmount.toFixed(2).split(".");
+            let dollarVal = parseInt(parts[0]);
+            let centVal = parseInt(parts[1]);
+            // 3. Process Dollars
+            let dollarWords = "";
+            if (dollarVal === 0) {
+                dollarWords = "Zero";
+            }
+            else {
+                let scaleIdx = 0;
+                while (dollarVal > 0) {
+                    let chunk = dollarVal % 1000;
+                    if (chunk > 0) {
+                        dollarWords = convertSmallNumber(chunk) + scales[scaleIdx] + " " + dollarWords;
+                    }
+                    dollarVal = Math.floor(dollarVal / 1000);
+                    scaleIdx++;
+                }
+            }
+            // 4. Formatting for TTS
+            const dLabel = (parseInt(parts[0]) === 1) ? "Dollar" : "Dollars";
+            const cLabel = (centVal === 1) ? "Cent" : "Cents";
+            let finalSpeech = (isNegative ? "Negative " : "") + dollarWords.trim() + " " + dLabel;
+            if (centVal > 0) {
+                const centWords = convertSmallNumber(centVal);
+                finalSpeech += " and " + centWords.trim() + " " + cLabel;
+            }
+            return finalSpeech.replace(/\s+/g, ' ');
+        }
+        else if (language === 'es') {
+            // Spanish implementation
+            const basics = ["", "Un", "Dos", "Tres", "Cuatro", "Cinco", "Seis", "Siete", "Ocho", "Nueve", "Diez", "Once", "Doce", "Trece", "Catorce", "Quince", "Dieciséis", "Diecisiete", "Dieciocho", "Diecinueve", "Veinte", "Veintiún", "Veintidós", "Veintitrés", "Veinticuatro", "Veinticinco", "Veintiséis", "Veintisiete", "Veintiocho", "Veintinueve"];
+            const tens = ["", "", "Veinte", "Treinta", "Cuarenta", "Cincuenta", "Sesenta", "Setenta", "Ochenta", "Noventa"];
+            const hundreds = ["", "Ciento", "Doscientos", "Trescientos", "Cuatrocientos", "Quinientos", "Seiscientos", "Setecientos", "Ochocientos", "Novecientos"];
+            function convertGroup(n) {
+                let output = "";
+                if (n === 100)
+                    return "Cien";
+                if (n >= 100) {
+                    output += hundreds[Math.floor(n / 100)] + " ";
+                    n %= 100;
+                }
+                if (n === 0 && output.length > 0)
+                    return output.trim();
+                if (n === 0)
+                    return "";
+                if (n < 30) {
+                    output += basics[n];
+                }
+                else {
+                    output += tens[Math.floor(n / 10)];
+                    if ((n % 10) > 0) {
+                        output += " y " + basics[n % 10];
+                    }
+                }
+                return output.trim();
+            }
+            if (typeof amount === 'string') {
+                amount = amount.replace(/[^-0-9.]/g, '');
+            }
+            const numAmount = parseFloat(amount);
+            if (isNaN(numAmount)) {
+                return "Cantidad no válida";
+            }
+            if (Math.abs(numAmount) >= 1000000000000) {
+                return "Cantidad excede el límite de 999 billones";
+            }
+            const isNegative = numAmount < 0;
+            let absoluteAmount = Math.abs(numAmount);
+            const parts = absoluteAmount.toFixed(2).split(".");
+            let dollarVal = parseInt(parts[0]);
+            let centVal = parseInt(parts[1]);
+            let dollarWords = "";
+            if (dollarVal === 0) {
+                dollarWords = "Cero";
+            }
+            else if (dollarVal === 1) {
+                dollarWords = "Un";
+            }
+            else {
+                let scaleIdx = 0;
+                let tempDollars = dollarVal;
+                let accumulated = "";
+                while (tempDollars > 0) {
+                    let chunk = tempDollars % 1000;
+                    if (chunk > 0) {
+                        let chunkText = convertGroup(chunk);
+                        if (scaleIdx === 0) {
+                            accumulated = chunkText + " " + accumulated;
+                        }
+                        else if (scaleIdx === 1) {
+                            // Thousands
+                            if (chunk === 1) {
+                                accumulated = "Mil " + accumulated;
+                            }
+                            else {
+                                accumulated = chunkText + " Mil " + accumulated;
+                            }
+                        }
+                        else if (scaleIdx === 2) {
+                            // Millions
+                            if (chunk === 1) {
+                                accumulated = "Un Millón " + accumulated;
+                            }
+                            else {
+                                accumulated = chunkText + " Millones " + accumulated;
+                            }
+                        }
+                        else if (scaleIdx === 3) {
+                            // Billions
+                            if (chunk === 1) {
+                                accumulated = "Un Billón " + accumulated;
+                            }
+                            else {
+                                accumulated = chunkText + " Billones " + accumulated;
+                            }
+                        }
+                    }
+                    tempDollars = Math.floor(tempDollars / 1000);
+                    scaleIdx++;
+                }
+                dollarWords = accumulated.trim();
+            }
+            const dLabel = (parseInt(parts[0]) === 1) ? "Dólar" : "Dólares";
+            const cLabel = (centVal === 1) ? "Centavo" : "Centavos";
+            // Add "de" for exact millions/billions
+            if (dollarWords.endsWith("Millón") || dollarWords.endsWith("Millones") || dollarWords.endsWith("Billón") || dollarWords.endsWith("Billones")) {
+                dollarWords += " de";
+            }
+            let finalSpeech = (isNegative ? "Negativo " : "") + dollarWords + " " + dLabel;
+            if (centVal > 0) {
+                let centWords = "";
+                if (centVal === 1)
+                    centWords = "Un";
+                else
+                    centWords = convertGroup(centVal);
+                finalSpeech += " con " + centWords + " " + cLabel;
+            }
+            return finalSpeech.replace(/\s+/g, ' ').trim();
+        }
+        else {
+            return `Language ${language} not supported for amount to speech conversion`;
+        }
+    }
+    catch (error) {
+        return `Error converting amount to speech: ${error.message}`;
+    }
+}

package/dist/helpers/answer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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: any, kind: any, extra?: any[]): boolean;
+/** 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: any): boolean;
+/** Whether the answer is (part of) a spelled address — letters said one at a time, or a spelled symbol. */
+export function isSpelledFragment(input: any): boolean;
+/**
+ * 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: any, kind: any): boolean;
+/**
+ * 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: any): boolean;
+/**
+ * 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: any): number;
+/**
+ * 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: any, choices: any, acceptOther: any): any;
+export namespace ANSWER_WORDS {
+    let yes: string[];
+    let no: string[];
+    let agent: string[];
+    let exit: string[];
+    let text: string[];
+}
+export const CONFIRM_WORDS: string[];
+//# sourceMappingURL=answer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/helpers/answer.js"],"names":[],"mappings":"AAyIA;;;GAGG;AACH,wEAgBC;AAED,+HAA+H;AAC/H,oDAIC;AAcD,2GAA2G;AAC3G,uDAGC;AAOD;;;;;GAKG;AACH,+DAUC;AAKD;;;;GAIG;AACH,oDAEC;AAiBD;;;;;;GAMG;AACH,mDA6BC;AAUD;;;;;;;;;GASG;AACH,6EAyGC;;;;;;;;AAjWD,qCAKiD"}