@kavchat/core 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -1,144 +1,3 @@
-/**
- * מבנה התוכן שהשרת מפרסם ושכל לקוח (ווידג'ט, 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
- * - מילות קישור לכל שפה, והסרת תחיליות בעברית (ו, ה, ב...) ובערבית (ال, و, ب...)
- * - תאית ושאר הכתבים בלי רווחים בין מילים (לאו, חמרית, בורמזית, יפנית וסינית): ראו isSpacelessScript
- *
- * הפורטים ל-Dart, Swift ו-Kotlin חייבים לעבור את test-vectors/normalize.json
- */
-declare const SUPPORTED_LOCALES: readonly ["he", "en", "ar", "ru", "es", "fr", "de", "pt", "it", "tr", "th"];
-type Locale = (typeof SUPPORTED_LOCALES)[number];
-/**
- * מילה שיש בה תו מכתב בלי רווחים. מילות מפתח כאלה מותאמות כתת-מחרוזת של השאלה, ולא כמילה שלמה (ראו match.ts)
- */
-declare function isSpacelessScript(word: string): boolean;
-/** מנקה ומחזיר רשימת מילים */
-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
- *
- * כתבים בלי רווחים (תאית, לאו, חמרית, בורמזית, יפנית, סינית): "ใบเสร็จอยู่ที่ไหน" היא מילה אחת בעיני normalizeWords,
- * ולכן השוואת מילים שלמות לא תמצא בה את "ใบเสร็จ". מילת מפתח, שם תסריט או כפתור שיש בהם תו מכתב כזה
- * מותאמים כתת-מחרוזת של כל השאלה המנורמלת, אחרי חיבור המילים בלי רווחים (משתמשים מוסיפים רווחים באמצע).
- * המשקלות זהים (3 ו-2). בתוך שלב, מונח שמוכל במונח ארוך יותר שנמצא, עם משקל שווה או גבוה, לא נספר שוב.
- * אין סובלנות לשגיאות כתיב בכתבים האלה: השאלה היא רצף אחד בלי גבולות מילים, ושינוי של סימן אחד
- * (למשל טון: ข้าว ו-ข่าว) הוא מילה אחרת. שגיאה של אות אחת בתת-מחרוזת קצרה הייתה מתאימה כמעט לכל שאלה
- */
-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;
@@ -177,6 +36,34 @@ declare const _exports: {
     "form.contactRequired": string;
     "form.emailInvalid": string;
     "form.backToChat": string;
+    "live.talk": string;
+    "live.intro": string;
+    "live.department": string;
+    "live.message": string;
+    "live.start": string;
+    "live.connecting": string;
+    "live.waiting": string;
+    "live.waitingLeft": string;
+    "live.leave": string;
+    "live.end": string;
+    "live.joined": string;
+    "live.with": string;
+    "live.agent": string;
+    "live.typing": string;
+    "live.ended": string;
+    "live.ticket": string;
+    "live.timeout": string;
+    "live.number": string;
+    "live.closed": string;
+    "live.closedUntil": string;
+    "live.busy": string;
+    "live.failed": string;
+    "live.back": string;
+    "live.reconnecting": string;
+    "live.tooLong": string;
+    "live.elsewhere": string;
+    "live.replaced": string;
+    "live.placeholder": string;
 };
 
 /**
@@ -192,6 +79,34 @@ 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;
 
+/**
+ * התאמה של שאלה חופשית לשלב בתסריט
+ * ציון: מילה מובילה = 3, שם התסריט או כפתור שמוביל לשלב = 2, שגיאת כתיב של אות אחת = 0.5.
+ * שלב אחד עם ציון כפול מהבא = single. כמה קרובים = multi (עד 3). אין כלום = none
+ *
+ * כתבים בלי רווחים (תאית, לאו, חמרית, בורמזית, יפנית, סינית): "ใบเสร็จอยู่ที่ไหน" היא מילה אחת בעיני normalizeWords,
+ * ולכן השוואת מילים שלמות לא תמצא בה את "ใบเสร็จ". מילת מפתח, שם תסריט או כפתור שיש בהם תו מכתב כזה
+ * מותאמים כתת-מחרוזת של כל השאלה המנורמלת, אחרי חיבור המילים בלי רווחים (משתמשים מוסיפים רווחים באמצע).
+ * המשקלות זהים (3 ו-2). בתוך שלב, מונח שמוכל במונח ארוך יותר שנמצא, עם משקל שווה או גבוה, לא נספר שוב.
+ * אין סובלנות לשגיאות כתיב בכתבים האלה: השאלה היא רצף אחד בלי גבולות מילים, ושינוי של סימן אחד
+ * (למשל טון: ข้าว ו-ข่าว) הוא מילה אחרת. שגיאה של אות אחת בתת-מחרוזת קצרה הייתה מתאימה כמעט לכל שאלה
+ */
+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;
+
 /**
  * מנוע השיחה: פונקציות טהורות בלי ממשק
  * כל פעולה מחזירה { state, effect }. effect הוא מה שהלקוח צריך לעשות מחוץ לצ'אט:
@@ -209,7 +124,8 @@ interface BotMessage {
     /** תשובה שנוצרה ב-AI. הלקוח מציג לידה תווית, כדי שהמשתמש יידע שהיא לא מתסריט */
     ai?: boolean;
 }
-type ChipKind = 'button' | 'back' | 'home' | 'yes' | 'no' | 'contact' | 'pick';
+/** live: "שיחה עם נציג". המנוע לא יוצר אותו בעצמו; הלקוח מוסיף אותו עם withLiveChip כשיש נציג זמין */
+type ChipKind = 'button' | 'back' | 'home' | 'yes' | 'no' | 'contact' | 'pick' | 'live';
 interface BotChip {
     id: string;
     label: string;
@@ -260,7 +176,7 @@ interface TranscriptEntry {
     at: string;
 }
 type BotEffect = {
-    type: 'contact';
+    type: 'contact' | 'live';
     contactTopicId: string | null;
     scriptId: string | null;
     prefill: string;
@@ -319,5 +235,256 @@ declare function eventsPayload(state: BotState, sessionId: string, releaseVersio
     }[];
 };
 
-export { AI_ANSWER_MAX, AI_QUESTION_MAX, RTL_LOCALES, SUPPORTED_LOCALES, UI_TEXTS, aiQuestion, answerWithAi, configureEngine, eventsPayload, format, groupKey, isRtl, isSpacelessScript, 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 };
+/**
+ * צד המבקר בצ'אט עם נציג: פונקציות טהורות בלי רשת ובלי ממשק.
+ * החוזה המלא: docs/live-chat-protocol.md. הרשת (SSE, סנכרון, ניסיונות חוזרים) נשארת בכל לקוח,
+ * אבל הסדר, הסינון הכפול, ההודעות שבדרך והטקסטים שמוצגים נקבעים כאן, כדי שכל הפורטים יתנהגו אותו דבר.
+ * הפורטים ל-Dart, Swift ו-Kotlin חייבים לעבור את test-vectors/live.json
+ */
+type LiveState = 'queued' | 'active' | 'closed' | 'ticket';
+type LiveUnavailableReason = 'disabled' | 'closed' | 'no_agents' | 'quota';
+/** liveChat בגרסה שפורסמה. open הוא רק רמז מרגע הטעינה */
+interface LiveChatRelease {
+    enabled: boolean;
+    open: boolean;
+    departments: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+interface LiveAvailability {
+    enabled: boolean;
+    open: boolean;
+    reason: LiveUnavailableReason | null;
+    waitSeconds: number;
+    departments: Array<{
+        id: string;
+        name: string;
+        open: boolean;
+        reason: LiveUnavailableReason | null;
+        nextOpenAt?: string | null;
+    }>;
+}
+interface LiveConversation {
+    id: string;
+    state: LiveState;
+    departmentId?: string;
+    agent?: {
+        name?: string;
+    } | null;
+    queueDeadline?: string | null;
+    closeReason?: 'agent' | 'visitor' | 'expired' | null;
+    ticket?: {
+        number: number | null;
+        reason?: string;
+    } | null;
+    lastSeq: number;
+    credentialExpiresAt: string;
+}
+interface LiveEvent {
+    seq: number;
+    type: string;
+    author: {
+        kind: 'visitor' | 'agent' | 'system';
+        name?: string;
+    };
+    text?: string | null;
+    data?: Record<string, unknown> | null;
+    clientId?: string | null;
+    at: string;
+}
+/** הודעה של המבקר שעוד לא אושרה בשרת */
+interface LivePending {
+    clientId: string;
+    text: string;
+    at: string;
+    status: 'sending' | 'failed';
+}
+interface LiveChat {
+    conversation: LiveConversation;
+    /** ממוינים לפי seq, בלי כפילויות */
+    events: LiveEvent[];
+    /** ה-seq הגבוה ביותר שהוחל. נשלח כ-after בסנכרון ובחיבור מחדש */
+    lastSeq: number;
+    pending: LivePending[];
+}
+/** שורה אחת לתצוגה */
+interface LiveLine {
+    key: string;
+    kind: 'visitor' | 'agent' | 'system';
+    text: string;
+    name?: string;
+    status?: 'sending' | 'failed';
+    clientId?: string;
+}
+declare const LIVE_MESSAGE_MAX = 2000;
+/** שליחת "מקליד" לכל היותר פעם ב-3 שניות */
+declare const LIVE_TYPING_INTERVAL_MS = 3000;
+/** "מקליד" של הנציג נעלם אחרי 6 שניות בלי עדכון */
+declare const LIVE_TYPING_HIDE_MS = 6000;
+/** כמה זמן תשובת /live/availability תקפה */
+declare const LIVE_AVAILABILITY_TTL_MS = 30000;
+declare const isLiveFinal: (state: LiveState | undefined) => state is "closed" | "ticket";
+declare const isLiveClientId: (id: unknown) => id is string;
+/**
+ * השהיה לפני ניסיון מספר attempt (מ-0): 1, 2, 4, 8, 16, 30 שניות, ועוד רעש אקראי של 30% לכל כיוון.
+ * random מוזרק כדי שהבדיקות יהיו דטרמיניסטיות
+ */
+declare function liveBackoff(attempt: number, random?: () => number): number;
+declare function liveStart(conversation: LiveConversation): LiveChat;
+/**
+ * אובייקט השיחה הוא מקור האמת למצב. היחיד שלא מקבלים: חזרה ממצב סופי למצב פתוח,
+ * או אובייקט של שיחה אחרת
+ */
+declare function liveApplyConversation(chat: LiveChat, conversation: LiveConversation | null | undefined): LiveChat;
+/**
+ * אירוע מהזרם, מסנכרון או מתשובה לפקודה: מתעלמים מ-seq שכבר ידוע, מכניסים לפי seq,
+ * ולא מחכים ל-seq חסר. הודעה עם clientId מחליפה את הבועה "נשלח" שלה.
+ * אירועי מעבר (agent.joined, conversation.closed, conversation.ticket) מעדכנים גם את המצב,
+ * למקרה שאובייקט השיחה המעודכן עוד לא הגיע
+ */
+declare function liveApplyEvent(chat: LiveChat, event: LiveEvent | null | undefined): LiveChat;
+/** תשובה של POST /live/sync: קודם אובייקט השיחה, אחר כך האירועים לפי הסדר */
+declare function liveApplySync(chat: LiveChat, sync: {
+    conversation?: LiveConversation | null;
+    events?: LiveEvent[] | null;
+}): LiveChat;
+/** הודעה חדשה של המבקר מוצגת מיד כ"נשלח". אותו clientId פעמיים, או כזה שכבר אושר, לא נוסף */
+declare function liveAddPending(chat: LiveChat, clientId: string, text: string, at: string): LiveChat;
+declare function liveSetPending(chat: LiveChat, clientId: string, status: LivePending['status'] | null): LiveChat;
+/** מה מציגים: האירועים שהמבקר רואה, ואחריהם ההודעות שבדרך. סוגים לא מוכרים לא מוצגים */
+declare function liveLines(chat: LiveChat, t: UiTexts): LiveLine[];
+/** שניות שנשארו עד שהשיחה בתור הופכת לפנייה. null כשאין מועד או שהשיחה לא בתור */
+declare function liveWaitLeft(conversation: LiveConversation, now: number): number | null;
+/** 105 -> "1:45" */
+declare const liveClock: (seconds: number) => string;
+/** שורת המצב שמעל השיחה */
+declare function liveStatus(conversation: LiveConversation, t: UiTexts, now: number): string;
+/**
+ * למה אין נציג, לשורה שמעל טופס הפנייה. closed ו-no_agents מקבלים הסבר; quota ו-disabled לא (הטופס מוצג בלי הסבר).
+ * time: מתי חוזרים, כבר מעוצב בשפת הממשק (אם ידוע)
+ */
+declare function liveUnavailableText(reason: LiveUnavailableReason | null | undefined, t: UiTexts, time?: string | null): string;
+/**
+ * מוסיף "שיחה עם נציג" לפני "פנייה לצוות", עם אותו טקסט מוכן. הלקוח קורא לזה רק כש-liveChat.enabled
+ * ו-/live/availability אמר open
+ */
+declare function withLiveChip(chips: BotChip[], label: string): BotChip[];
+
+/**
+ * מבנה התוכן שהשרת מפרסם ושכל לקוח (ווידג'ט, 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[];
+    /** חסר בשרת ישן: אז אין "שיחה עם נציג" */
+    liveChat?: LiveChatRelease;
+};
+
+/**
+ * נרמול טקסט לכל השפות הנתמכות, בלי ביטויים עם \p{...}, כי Hermes הישן לא תומך בהם
+ *
+ * - אותיות קטנות, הסרת ניקוד וטעמים (עברית), תשכיל (ערבית) וסימני הטעמה לטיניים (é → e)
+ * - אותיות סופיות בעברית (ם → מ), צורות אליף בערבית (أ → ا), ё → е, ß → ss
+ * - מילות קישור לכל שפה, והסרת תחיליות בעברית (ו, ה, ב...) ובערבית (ال, و, ب...)
+ * - תאית ושאר הכתבים בלי רווחים בין מילים (לאו, חמרית, בורמזית, יפנית וסינית): ראו isSpacelessScript
+ *
+ * הפורטים ל-Dart, Swift ו-Kotlin חייבים לעבור את test-vectors/normalize.json
+ */
+declare const SUPPORTED_LOCALES: readonly ["he", "en", "ar", "ru", "es", "fr", "de", "pt", "it", "tr", "th"];
+type Locale = (typeof SUPPORTED_LOCALES)[number];
+/**
+ * מילה שיש בה תו מכתב בלי רווחים. מילות מפתח כאלה מותאמות כתת-מחרוזת של השאלה, ולא כמילה שלמה (ראו match.ts)
+ */
+declare function isSpacelessScript(word: string): boolean;
+/** מנקה ומחזיר רשימת מילים */
+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[];
+
+export { AI_ANSWER_MAX, AI_QUESTION_MAX, LIVE_AVAILABILITY_TTL_MS, LIVE_MESSAGE_MAX, LIVE_TYPING_HIDE_MS, LIVE_TYPING_INTERVAL_MS, RTL_LOCALES, SUPPORTED_LOCALES, UI_TEXTS, aiQuestion, answerWithAi, configureEngine, eventsPayload, format, groupKey, isLiveClientId, isLiveFinal, isRtl, isSpacelessScript, keyTerms, liveAddPending, liveApplyConversation, liveApplyEvent, liveApplySync, liveBackoff, liveClock, liveLines, liveSetPending, liveStart, liveStatus, liveUnavailableText, liveWaitLeft, matchQuestion, normalizeWords, pendingQuestion, pressChip, sendText, startConversation, stripPrefixes, toBubbles, transcriptOf, uiTexts, withLiveChip, withinOneEdit };
+export type { BotAction, BotButton, BotChip, BotEffect, BotMatch, BotMatchResult, BotMessage, BotOutcome, BotPathEntry, BotPosition, BotResult, BotScript, BotScriptContent, BotSettings, BotState, BotStep, ChipKind, ClientRelease, EngineOptions, LiveAvailability, LiveChat, LiveChatRelease, LiveConversation, LiveEvent, LiveLine, LivePending, LiveState, LiveUnavailableReason, Locale, MatchReason, TranscriptEntry, UiKey, UiTexts };