@kavchat/core 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxsave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @kavchat/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared engine behind every Kavchat SDK: text normalization for 10 languages, matching a typed question to a
+script (keywords, titles, typo tolerance), the conversation state machine and the UI texts. It has no dependencies
+and does no network calls.
+
+You normally do not install it directly. It comes with the SDKs:
+
+```sh
+yarn add @kavchat/widget          # website
+yarn add @kavchat/react-native    # React Native, with or without Expo
+```
+
+The same behavior is ported to Dart, Swift and Kotlin; `test-vectors/` holds the shared cases every port must pass.
+
+Kavchat is a scripted customer-support chat for websites and apps: https://kavchat.com · Docs: https://kavchat.com/docs
+
+License: MIT

package/dist/index.d.mts

@@ -0,0 +1,311 @@
+/**
+ * מבנה התוכן שהשרת מפרסם ושכל לקוח (ווידג'ט, React Native, Flutter, iOS, Android) מריץ
+ * זהה ל-ClientRelease במפרט ה-OpenAPI
+ */
+type BotAction = {
+    type: 'step';
+    stepId: string;
+} | {
+    type: 'goto';
+    stepId: string;
+    scriptId?: string;
+} | {
+    type: 'contact';
+} | {
+    type: 'screen';
+    screen: string;
+    targetId?: string;
+} | {
+    type: 'link';
+    url: string;
+} | {
+    type: 'script';
+    scriptId: string;
+};
+interface BotButton {
+    id: string;
+    label: string;
+    action: BotAction | null;
+}
+interface BotStep {
+    id: string;
+    text: string;
+    imageUrl?: string;
+    keywords: string[];
+    buttons: BotButton[];
+}
+interface BotScriptContent {
+    name: string;
+    keywords: string[];
+    contactTopicId?: string;
+    rootStepId: string;
+    steps: BotStep[];
+}
+interface BotScript {
+    id: string;
+    kind: 'opening' | 'topic';
+    sortOrder: number;
+    content: BotScriptContent;
+}
+interface BotSettings {
+    botName: string;
+    avatarText: string;
+    avatarImageUrl: string | null;
+    subtitle: string;
+    primaryColor: string;
+    position: 'start' | 'end';
+    contactTopics: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** false בתוכנית החינמית: הסמל "Powered by Kavchat" חייב להופיע */
+    removeBranding?: boolean;
+    /** true כשבעל סביבת העבודה הפעיל תשובות AI (פרימיום, על המפתח שלו). שואלים את /ai/answer רק כשאין התאמה */
+    aiAnswers?: boolean;
+}
+type ClientRelease = {
+    enabled: false;
+} | {
+    enabled: true;
+    version: number;
+    locale: string;
+    settings: BotSettings;
+    openingScriptId: string;
+    scripts: BotScript[];
+};
+
+/**
+ * נרמול טקסט לכל השפות הנתמכות, בלי ביטויים עם \p{...}, כי Hermes הישן לא תומך בהם
+ *
+ * - אותיות קטנות, הסרת ניקוד וטעמים (עברית), תשכיל (ערבית) וסימני הטעמה לטיניים (é → e)
+ * - אותיות סופיות בעברית (ם → מ), צורות אליף בערבית (أ → ا), ё → е, ß → ss
+ * - מילות קישור לכל שפה, והסרת תחיליות בעברית (ו, ה, ב...) ובערבית (ال, و, ب...)
+ *
+ * הפורטים ל-Dart, Swift ו-Kotlin חייבים לעבור את test-vectors/normalize.json
+ */
+declare const SUPPORTED_LOCALES: readonly ["he", "en", "ar", "ru", "es", "fr", "de", "pt", "it", "tr"];
+type Locale = (typeof SUPPORTED_LOCALES)[number];
+/** מנקה ומחזיר רשימת מילים */
+declare function normalizeWords(text: string): string[];
+/**
+ * מסיר תחיליות כל עוד נשארות לפחות 3 אותיות ("והתשלום" ← "תשלומ", "والدفع" ← "دفع"),
+ * ובאותיות לטיניות מסיר s של רבים ("arrives" ← "arrive"), חוץ מ-ss, us ו-is
+ */
+declare function stripPrefixes(word: string): string;
+/**
+ * מילים משמעותיות: בלי מילות קישור של שפת התוכן ושל אנגלית (משתמשים מערבבים), ואחרי הסרת תחיליות
+ */
+declare function keyTerms(text: string, locale?: string): string[];
+/** מפתח קיבוץ לשאלות דומות בדוחות */
+declare function groupKey(text: string, locale?: string): string;
+/**
+ * שגיאת כתיב אחת לכל היותר, רק במילים של 4 אותיות ומעלה:
+ * אות חסרה, אות מיותרת, אות מוחלפת, או שתי אותיות סמוכות שהתחלפו ("trakcing")
+ */
+declare function withinOneEdit(a: string, b: string): boolean;
+/** טקסט של שלב, מפוצל לבועות לפי שורה ריקה */
+declare const toBubbles: (text: string) => string[];
+
+/**
+ * התאמה של שאלה חופשית לשלב בתסריט
+ * ציון: מילה מובילה = 3, שם התסריט או כפתור שמוביל לשלב = 2, שגיאת כתיב של אות אחת = 0.5.
+ * שלב אחד עם ציון כפול מהבא = single. כמה קרובים = multi (עד 3). אין כלום = none
+ */
+type MatchReason = {
+    kind: 'keyword' | 'title' | 'typo';
+    term: string;
+};
+interface BotMatch {
+    scriptId: string;
+    stepId: string;
+    score: number;
+    reasons: MatchReason[];
+}
+interface BotMatchResult {
+    kind: 'single' | 'multi' | 'none';
+    matches: BotMatch[];
+}
+declare function matchQuestion(scripts: BotScript[], text: string, locale?: string): BotMatchResult;
+
+declare const _exports: {
+    "chat.askAnswered": string;
+    "chat.yes": string;
+    "chat.no": string;
+    "chat.thanks": string;
+    "chat.newQuestion": string;
+    "chat.back": string;
+    "chat.home": string;
+    "chat.didYouMean": string;
+    "chat.notFound": string;
+    "chat.notFoundTwice": string;
+    "chat.contactChip": string;
+    "chat.openingContact": string;
+    "chat.chooseTopic": string;
+    "chat.aiLabel": string;
+    "widget.open": string;
+    "widget.close": string;
+    "widget.placeholder": string;
+    "widget.send": string;
+    "widget.poweredBy": string;
+    "widget.offline": string;
+    "widget.loading": string;
+    "widget.unavailable": string;
+    "form.title": string;
+    "form.name": string;
+    "form.email": string;
+    "form.phone": string;
+    "form.topic": string;
+    "form.message": string;
+    "form.submit": string;
+    "form.cancel": string;
+    "form.sending": string;
+    "form.sent": string;
+    "form.error": string;
+    "form.required": string;
+    "form.contactRequired": string;
+    "form.emailInvalid": string;
+    "form.backToChat": string;
+};
+
+/**
+ * הטקסטים של משתמש הקצה: הבוט, הווידג'ט וטופס הפנייה
+ * מקור האמת הוא קובצי ה-JSON ב-i18n/, שגם Flutter, iOS ו-Android טוענים
+ */
+type UiKey = keyof typeof _exports;
+type UiTexts = Record<UiKey, string>;
+declare const UI_TEXTS: Record<string, UiTexts>;
+declare const RTL_LOCALES: string[];
+declare const isRtl: (locale: string) => boolean;
+/** הטקסטים בשפה המבוקשת, עם השלמה מאנגלית לכל מפתח חסר */
+declare function uiTexts(locale: string, overrides?: Partial<UiTexts>): UiTexts;
+declare const format: (template: string, params: Record<string, string | number>) => string;
+
+/**
+ * מנוע השיחה: פונקציות טהורות בלי ממשק
+ * כל פעולה מחזירה { state, effect }. effect הוא מה שהלקוח צריך לעשות מחוץ לצ'אט:
+ * לפתוח טופס פנייה, מסך באפליקציה או קישור.
+ * הפורטים ל-Dart, Swift ו-Kotlin חייבים לעבור את test-vectors/conversation.json
+ */
+interface BotMessage {
+    id: string;
+    from: 'bot' | 'user';
+    text: string;
+    at: number;
+    stepId?: string;
+    scriptId?: string;
+    imageUrl?: string;
+    /** תשובה שנוצרה ב-AI. הלקוח מציג לידה תווית, כדי שהמשתמש יידע שהיא לא מתסריט */
+    ai?: boolean;
+}
+type ChipKind = 'button' | 'back' | 'home' | 'yes' | 'no' | 'contact' | 'pick';
+interface BotChip {
+    id: string;
+    label: string;
+    kind: ChipKind;
+    action?: BotAction | null;
+    prefill?: string;
+    target?: {
+        scriptId: string;
+        stepId: string;
+    };
+}
+interface BotPosition {
+    scriptId: string;
+    stepId: string;
+}
+interface BotPathEntry {
+    scriptId: string;
+    stepId: string;
+    via: 'start' | 'button' | 'text' | 'back' | 'home';
+    at: string;
+}
+type BotOutcome = 'open' | 'answered' | 'contact';
+interface BotState {
+    scripts: Record<string, BotScript>;
+    openingId: string;
+    locale: string;
+    userName: string;
+    messages: BotMessage[];
+    chips: BotChip[];
+    position: BotPosition | null;
+    history: BotPosition[];
+    path: BotPathEntry[];
+    unmatched: {
+        text: string;
+        at: string;
+    }[];
+    misses: number;
+    outcome: BotOutcome;
+    lastScriptId: string | null;
+    lastMatch: BotMatchResult | null;
+    /** מונה פנימי למזהי הודעות, כדי שהמנוע יישאר דטרמיניסטי */
+    seq: number;
+}
+interface TranscriptEntry {
+    from: 'bot' | 'user';
+    text: string;
+    stepId?: string;
+    at: string;
+}
+type BotEffect = {
+    type: 'contact';
+    contactTopicId: string | null;
+    scriptId: string | null;
+    prefill: string;
+    transcript: TranscriptEntry[];
+} | Extract<BotAction, {
+    type: 'screen';
+} | {
+    type: 'link';
+}>;
+interface BotResult {
+    state: BotState;
+    effect?: BotEffect;
+}
+/** שעון ומחולל זמן ניתנים להחלפה, כדי שהבדיקות יהיו דטרמיניסטיות */
+interface EngineOptions {
+    now?: () => number;
+    texts?: Partial<UiTexts>;
+}
+declare function configureEngine(opts: EngineOptions): void;
+declare function transcriptOf(state: BotState): TranscriptEntry[];
+declare function startConversation(opts: {
+    scripts: BotScript[];
+    openingScriptId: string;
+    locale?: string;
+    userName?: string;
+}): BotState;
+declare function pressChip(state: BotState, chip: BotChip): BotResult;
+declare function sendText(state: BotState, rawText: string): BotResult;
+/** אורך השאלה המרבי שנשלח ל-/ai/answer */
+declare const AI_QUESTION_MAX = 300;
+/** אורך התשובה המרבי שמוצג. השרת כבר חותך ל-600 */
+declare const AI_ANSWER_MAX = 600;
+/**
+ * השאלה לשליחה ל-/ai/answer, או null כשהטקסט ריק או שתסריט עונה עליו.
+ * הלקוח קורא לזה רק כש-settings.aiAnswers דלוק
+ */
+declare function aiQuestion(state: BotState, rawText: string): string | null;
+/** מה מציגים בזמן שמחכים לתשובת AI: ההודעה של המשתמש, בלי כפתורים */
+declare function pendingQuestion(state: BotState, rawText: string): BotState;
+/**
+ * תשובת AI לשאלה שאין לה תסריט. נקרא על המצב שלפני השאלה, במקום sendText.
+ * הדיווח לשרת זהה ל-sendText: השאלה נרשמת ב-unmatched.
+ * תשובה ריקה מחזירה בדיוק את sendText, כלומר את הודעת "לא נמצא" הרגילה
+ */
+declare function answerWithAi(state: BotState, rawText: string, answer: string | null | undefined, scriptId?: string | null): BotResult;
+/** הדיווח לשרת (POST /v1/client/:pk/events). שולחים את כל המסלול בכל פעם */
+declare function eventsPayload(state: BotState, sessionId: string, releaseVersion: number, startedAt: string): {
+    sessionId: string;
+    releaseVersion: number;
+    startedAt: string;
+    outcome: BotOutcome;
+    path: BotPathEntry[];
+    unmatched: {
+        text: string;
+        at: string;
+    }[];
+};
+
+export { AI_ANSWER_MAX, AI_QUESTION_MAX, RTL_LOCALES, SUPPORTED_LOCALES, UI_TEXTS, aiQuestion, answerWithAi, configureEngine, eventsPayload, format, groupKey, isRtl, keyTerms, matchQuestion, normalizeWords, pendingQuestion, pressChip, sendText, startConversation, stripPrefixes, toBubbles, transcriptOf, uiTexts, withinOneEdit };
+export type { BotAction, BotButton, BotChip, BotEffect, BotMatch, BotMatchResult, BotMessage, BotOutcome, BotPathEntry, BotPosition, BotResult, BotScript, BotScriptContent, BotSettings, BotState, BotStep, ChipKind, ClientRelease, EngineOptions, Locale, MatchReason, TranscriptEntry, UiKey, UiTexts };

package/dist/index.d.ts

@@ -0,0 +1,311 @@
+/**
+ * מבנה התוכן שהשרת מפרסם ושכל לקוח (ווידג'ט, React Native, Flutter, iOS, Android) מריץ
+ * זהה ל-ClientRelease במפרט ה-OpenAPI
+ */
+type BotAction = {
+    type: 'step';
+    stepId: string;
+} | {
+    type: 'goto';
+    stepId: string;
+    scriptId?: string;
+} | {
+    type: 'contact';
+} | {
+    type: 'screen';
+    screen: string;
+    targetId?: string;
+} | {
+    type: 'link';
+    url: string;
+} | {
+    type: 'script';
+    scriptId: string;
+};
+interface BotButton {
+    id: string;
+    label: string;
+    action: BotAction | null;
+}
+interface BotStep {
+    id: string;
+    text: string;
+    imageUrl?: string;
+    keywords: string[];
+    buttons: BotButton[];
+}
+interface BotScriptContent {
+    name: string;
+    keywords: string[];
+    contactTopicId?: string;
+    rootStepId: string;
+    steps: BotStep[];
+}
+interface BotScript {
+    id: string;
+    kind: 'opening' | 'topic';
+    sortOrder: number;
+    content: BotScriptContent;
+}
+interface BotSettings {
+    botName: string;
+    avatarText: string;
+    avatarImageUrl: string | null;
+    subtitle: string;
+    primaryColor: string;
+    position: 'start' | 'end';
+    contactTopics: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** false בתוכנית החינמית: הסמל "Powered by Kavchat" חייב להופיע */
+    removeBranding?: boolean;
+    /** true כשבעל סביבת העבודה הפעיל תשובות AI (פרימיום, על המפתח שלו). שואלים את /ai/answer רק כשאין התאמה */
+    aiAnswers?: boolean;
+}
+type ClientRelease = {
+    enabled: false;
+} | {
+    enabled: true;
+    version: number;
+    locale: string;
+    settings: BotSettings;
+    openingScriptId: string;
+    scripts: BotScript[];
+};
+
+/**
+ * נרמול טקסט לכל השפות הנתמכות, בלי ביטויים עם \p{...}, כי Hermes הישן לא תומך בהם
+ *
+ * - אותיות קטנות, הסרת ניקוד וטעמים (עברית), תשכיל (ערבית) וסימני הטעמה לטיניים (é → e)
+ * - אותיות סופיות בעברית (ם → מ), צורות אליף בערבית (أ → ا), ё → е, ß → ss
+ * - מילות קישור לכל שפה, והסרת תחיליות בעברית (ו, ה, ב...) ובערבית (ال, و, ب...)
+ *
+ * הפורטים ל-Dart, Swift ו-Kotlin חייבים לעבור את test-vectors/normalize.json
+ */
+declare const SUPPORTED_LOCALES: readonly ["he", "en", "ar", "ru", "es", "fr", "de", "pt", "it", "tr"];
+type Locale = (typeof SUPPORTED_LOCALES)[number];
+/** מנקה ומחזיר רשימת מילים */
+declare function normalizeWords(text: string): string[];
+/**
+ * מסיר תחיליות כל עוד נשארות לפחות 3 אותיות ("והתשלום" ← "תשלומ", "والدفع" ← "دفع"),
+ * ובאותיות לטיניות מסיר s של רבים ("arrives" ← "arrive"), חוץ מ-ss, us ו-is
+ */
+declare function stripPrefixes(word: string): string;
+/**
+ * מילים משמעותיות: בלי מילות קישור של שפת התוכן ושל אנגלית (משתמשים מערבבים), ואחרי הסרת תחיליות
+ */
+declare function keyTerms(text: string, locale?: string): string[];
+/** מפתח קיבוץ לשאלות דומות בדוחות */
+declare function groupKey(text: string, locale?: string): string;
+/**
+ * שגיאת כתיב אחת לכל היותר, רק במילים של 4 אותיות ומעלה:
+ * אות חסרה, אות מיותרת, אות מוחלפת, או שתי אותיות סמוכות שהתחלפו ("trakcing")
+ */
+declare function withinOneEdit(a: string, b: string): boolean;
+/** טקסט של שלב, מפוצל לבועות לפי שורה ריקה */
+declare const toBubbles: (text: string) => string[];
+
+/**
+ * התאמה של שאלה חופשית לשלב בתסריט
+ * ציון: מילה מובילה = 3, שם התסריט או כפתור שמוביל לשלב = 2, שגיאת כתיב של אות אחת = 0.5.
+ * שלב אחד עם ציון כפול מהבא = single. כמה קרובים = multi (עד 3). אין כלום = none
+ */
+type MatchReason = {
+    kind: 'keyword' | 'title' | 'typo';
+    term: string;
+};
+interface BotMatch {
+    scriptId: string;
+    stepId: string;
+    score: number;
+    reasons: MatchReason[];
+}
+interface BotMatchResult {
+    kind: 'single' | 'multi' | 'none';
+    matches: BotMatch[];
+}
+declare function matchQuestion(scripts: BotScript[], text: string, locale?: string): BotMatchResult;
+
+declare const _exports: {
+    "chat.askAnswered": string;
+    "chat.yes": string;
+    "chat.no": string;
+    "chat.thanks": string;
+    "chat.newQuestion": string;
+    "chat.back": string;
+    "chat.home": string;
+    "chat.didYouMean": string;
+    "chat.notFound": string;
+    "chat.notFoundTwice": string;
+    "chat.contactChip": string;
+    "chat.openingContact": string;
+    "chat.chooseTopic": string;
+    "chat.aiLabel": string;
+    "widget.open": string;
+    "widget.close": string;
+    "widget.placeholder": string;
+    "widget.send": string;
+    "widget.poweredBy": string;
+    "widget.offline": string;
+    "widget.loading": string;
+    "widget.unavailable": string;
+    "form.title": string;
+    "form.name": string;
+    "form.email": string;
+    "form.phone": string;
+    "form.topic": string;
+    "form.message": string;
+    "form.submit": string;
+    "form.cancel": string;
+    "form.sending": string;
+    "form.sent": string;
+    "form.error": string;
+    "form.required": string;
+    "form.contactRequired": string;
+    "form.emailInvalid": string;
+    "form.backToChat": string;
+};
+
+/**
+ * הטקסטים של משתמש הקצה: הבוט, הווידג'ט וטופס הפנייה
+ * מקור האמת הוא קובצי ה-JSON ב-i18n/, שגם Flutter, iOS ו-Android טוענים
+ */
+type UiKey = keyof typeof _exports;
+type UiTexts = Record<UiKey, string>;
+declare const UI_TEXTS: Record<string, UiTexts>;
+declare const RTL_LOCALES: string[];
+declare const isRtl: (locale: string) => boolean;
+/** הטקסטים בשפה המבוקשת, עם השלמה מאנגלית לכל מפתח חסר */
+declare function uiTexts(locale: string, overrides?: Partial<UiTexts>): UiTexts;
+declare const format: (template: string, params: Record<string, string | number>) => string;
+
+/**
+ * מנוע השיחה: פונקציות טהורות בלי ממשק
+ * כל פעולה מחזירה { state, effect }. effect הוא מה שהלקוח צריך לעשות מחוץ לצ'אט:
+ * לפתוח טופס פנייה, מסך באפליקציה או קישור.
+ * הפורטים ל-Dart, Swift ו-Kotlin חייבים לעבור את test-vectors/conversation.json
+ */
+interface BotMessage {
+    id: string;
+    from: 'bot' | 'user';
+    text: string;
+    at: number;
+    stepId?: string;
+    scriptId?: string;
+    imageUrl?: string;
+    /** תשובה שנוצרה ב-AI. הלקוח מציג לידה תווית, כדי שהמשתמש יידע שהיא לא מתסריט */
+    ai?: boolean;
+}
+type ChipKind = 'button' | 'back' | 'home' | 'yes' | 'no' | 'contact' | 'pick';
+interface BotChip {
+    id: string;
+    label: string;
+    kind: ChipKind;
+    action?: BotAction | null;
+    prefill?: string;
+    target?: {
+        scriptId: string;
+        stepId: string;
+    };
+}
+interface BotPosition {
+    scriptId: string;
+    stepId: string;
+}
+interface BotPathEntry {
+    scriptId: string;
+    stepId: string;
+    via: 'start' | 'button' | 'text' | 'back' | 'home';
+    at: string;
+}
+type BotOutcome = 'open' | 'answered' | 'contact';
+interface BotState {
+    scripts: Record<string, BotScript>;
+    openingId: string;
+    locale: string;
+    userName: string;
+    messages: BotMessage[];
+    chips: BotChip[];
+    position: BotPosition | null;
+    history: BotPosition[];
+    path: BotPathEntry[];
+    unmatched: {
+        text: string;
+        at: string;
+    }[];
+    misses: number;
+    outcome: BotOutcome;
+    lastScriptId: string | null;
+    lastMatch: BotMatchResult | null;
+    /** מונה פנימי למזהי הודעות, כדי שהמנוע יישאר דטרמיניסטי */
+    seq: number;
+}
+interface TranscriptEntry {
+    from: 'bot' | 'user';
+    text: string;
+    stepId?: string;
+    at: string;
+}
+type BotEffect = {
+    type: 'contact';
+    contactTopicId: string | null;
+    scriptId: string | null;
+    prefill: string;
+    transcript: TranscriptEntry[];
+} | Extract<BotAction, {
+    type: 'screen';
+} | {
+    type: 'link';
+}>;
+interface BotResult {
+    state: BotState;
+    effect?: BotEffect;
+}
+/** שעון ומחולל זמן ניתנים להחלפה, כדי שהבדיקות יהיו דטרמיניסטיות */
+interface EngineOptions {
+    now?: () => number;
+    texts?: Partial<UiTexts>;
+}
+declare function configureEngine(opts: EngineOptions): void;
+declare function transcriptOf(state: BotState): TranscriptEntry[];
+declare function startConversation(opts: {
+    scripts: BotScript[];
+    openingScriptId: string;
+    locale?: string;
+    userName?: string;
+}): BotState;
+declare function pressChip(state: BotState, chip: BotChip): BotResult;
+declare function sendText(state: BotState, rawText: string): BotResult;
+/** אורך השאלה המרבי שנשלח ל-/ai/answer */
+declare const AI_QUESTION_MAX = 300;
+/** אורך התשובה המרבי שמוצג. השרת כבר חותך ל-600 */
+declare const AI_ANSWER_MAX = 600;
+/**
+ * השאלה לשליחה ל-/ai/answer, או null כשהטקסט ריק או שתסריט עונה עליו.
+ * הלקוח קורא לזה רק כש-settings.aiAnswers דלוק
+ */
+declare function aiQuestion(state: BotState, rawText: string): string | null;
+/** מה מציגים בזמן שמחכים לתשובת AI: ההודעה של המשתמש, בלי כפתורים */
+declare function pendingQuestion(state: BotState, rawText: string): BotState;
+/**
+ * תשובת AI לשאלה שאין לה תסריט. נקרא על המצב שלפני השאלה, במקום sendText.
+ * הדיווח לשרת זהה ל-sendText: השאלה נרשמת ב-unmatched.
+ * תשובה ריקה מחזירה בדיוק את sendText, כלומר את הודעת "לא נמצא" הרגילה
+ */
+declare function answerWithAi(state: BotState, rawText: string, answer: string | null | undefined, scriptId?: string | null): BotResult;
+/** הדיווח לשרת (POST /v1/client/:pk/events). שולחים את כל המסלול בכל פעם */
+declare function eventsPayload(state: BotState, sessionId: string, releaseVersion: number, startedAt: string): {
+    sessionId: string;
+    releaseVersion: number;
+    startedAt: string;
+    outcome: BotOutcome;
+    path: BotPathEntry[];
+    unmatched: {
+        text: string;
+        at: string;
+    }[];
+};
+
+export { AI_ANSWER_MAX, AI_QUESTION_MAX, RTL_LOCALES, SUPPORTED_LOCALES, UI_TEXTS, aiQuestion, answerWithAi, configureEngine, eventsPayload, format, groupKey, isRtl, keyTerms, matchQuestion, normalizeWords, pendingQuestion, pressChip, sendText, startConversation, stripPrefixes, toBubbles, transcriptOf, uiTexts, withinOneEdit };
+export type { BotAction, BotButton, BotChip, BotEffect, BotMatch, BotMatchResult, BotMessage, BotOutcome, BotPathEntry, BotPosition, BotResult, BotScript, BotScriptContent, BotSettings, BotState, BotStep, ChipKind, ClientRelease, EngineOptions, Locale, MatchReason, TranscriptEntry, UiKey, UiTexts };