@kavchat/react-native 0.0.2 → 0.0.3

package/README.md

@@ -147,6 +147,44 @@ If your app is Hebrew or Arabic, set RTL once in your app as usual (`I18nManager
 
 The free plan shows "Powered by Kavchat" under the chat (linking to kavchat.com); paid plans hide it automatically.
 
+## Live chat with a representative
+
+Nothing to set up for the basic flow. When live chat is on in the dashboard (`liveChat.enabled` in the release), the chat
+behaves like the website widget (contract: `docs/live-chat-protocol.md`):
+
+- **Option:** "Talk to a representative" is added before "Talk to our team" only after `GET /live/availability` says open
+  (cached 30 s, checked again on tap). Otherwise only the contact form, with a line for `closed` (and when the team is back)
+  or `no_agents`; `quota` and `disabled` show the form without explanation.
+- **Request form** (`view: 'liveForm'`): guests leave an email or a phone, name and first message optional, department choice when
+  more than one is open; identified users (`userToken`) skip contact details. Not accepted: the contact form opens with what was typed.
+- **Waiting / chat** (`view: 'live'`): countdown to `queueDeadline`, "Leave a message instead", "End chat", agent name, typing
+  (sent at most every 3 s), transfers, plain text only. When the wait ends, the chat becomes a request (a sync after the deadline
+  catches it even if the stream missed it).
+- **Transport:** SSE with a single-use stream ticket, read through `XMLHttpRequest` progress events (or `fetch` with
+  `body.getReader()`), long-poll fallback (`POST /live/sync` with `wait`) when no streaming transport exists, after `live_busy`,
+  or after 3 failed streams. Reconnect with 1-30 s backoff and +-30% jitter, then sync after `lastSeq`. Order and dedupe by `seq`
+  (the shared reducer in `@kavchat/core`), client message ids for idempotent retries, pending and failed bubbles (tap to retry).
+- **Lifecycle:** the stream closes when `AppState` is `background` and catches up on `active`. The credential (`lvc_...`, up to
+  12 hours) is kept in `secureStorage` (default: `storage`) and restores an ongoing chat after an app restart. It is never put in a
+  URL or a log. Switching user drops it.
+- **No push notifications in v1:** messages arrive only while the app is open.
+
+```tsx
+import * as SecureStore from 'expo-secure-store';
+const safe = (k: string) => k.replace(/[^A-Za-z0-9._-]/g, '_'); // SecureStore key charset
+const secureStorage = {
+  getItem: (k: string) => SecureStore.getItemAsync(safe(k)),
+  setItem: (k: string, v: string) => SecureStore.setItemAsync(safe(k), v),
+  removeItem: (k: string) => SecureStore.deleteItemAsync(safe(k)),
+};
+
+<KavchatProvider publicKey="pk_live_..." secureStorage={secureStorage} livePage="checkout" onEvent={(e) => e.type === 'live' && console.log(e.phase)}>
+
+const { openLive, livePhase } = useKavchat(); // your own "chat with us" button
+```
+
+UI texts are the `live.*` keys of `@kavchat/core` (11 languages), the same as the website widget.
+
 ## AI answers (Premium)
 
 Nothing to configure in the app. When the workspace owner turns on AI answers in the dashboard (Premium, with the

package/lib/controller.d.ts

@@ -2,6 +2,9 @@ import type { BotChip, BotEffect, BotState, UiTexts } from '@kavchat/core';
 import { EnabledRelease, FetchLike } from './api';
 import { KavchatScreen } from './screens';
 import { StorageAdapter } from './storage';
+import { LiveDepartmentAvailability, LiveUnavailableReason } from './live/api';
+import { LivePhase, LiveSnapshot, LiveTiming } from './live/session';
+import type { StreamOpener } from './live/sse';
 /**
  * הבקר: טעינת הגרסה עם ETag ומטמון, שמירת השיחה, דיווח לשרת ופניות
  * קוד TypeScript רגיל בלי React Native, כדי שאפשר יהיה לבדוק אותו ב-Node.
@@ -9,11 +12,13 @@ import { StorageAdapter } from './storage';
  */
 export declare const DEFAULT_API = "https://api.kavchat.com";
 export declare const BRANDING_URL = "https://kavchat.com";
+/** טופס פנייה (contact) או טופס הבקשה לנציג (live) */
 export type ContactEffect = Extract<BotEffect, {
-    type: 'contact';
+    type: 'contact' | 'live';
 }>;
 export type KavchatStatus = 'loading' | 'ready' | 'unavailable';
-export type KavchatView = 'chat' | 'form' | 'sent';
+/** live: צ'אט עם נציג (המתנה, שיחה, או המצב הסופי) */
+export type KavchatView = 'chat' | 'form' | 'sent' | 'live' | 'liveForm';
 export type KavchatEvent = {
     type: 'ready';
     version: number;
@@ -28,7 +33,25 @@ export type KavchatEvent = {
     type: 'ticket';
     id: string;
     number: number;
+}
+/** צ'אט עם נציג: queued, active, closed, ticket, replaced או expired */
+ | {
+    type: 'live';
+    phase: LivePhase;
 };
+/** האם להציע "צ'אט עם נציג" בטופס הפנייה, ואם לא, למה */
+export interface LiveOffer {
+    /** בודקים עכשיו את /live/availability */
+    checking: boolean;
+    open: boolean;
+    /** closed ו-no_agents מוצגים כשורת הסבר. quota ו-disabled: רק הטופס, בלי הסבר */
+    reason: LiveUnavailableReason | null;
+    /** המחלקות הפתוחות. יותר מאחת: המשתמש בוחר */
+    departments: LiveDepartmentAvailability[];
+    /** כש-reason הוא closed: מתי הצוות זמין שוב */
+    nextOpenAt: string | null;
+}
+export declare const AVAILABILITY_CACHE_MS = 30000;
 export interface KavchatSnapshot {
     status: KavchatStatus;
     release: EnabledRelease | null;
@@ -48,6 +71,18 @@ export interface KavchatSnapshot {
     reason?: string;
     identified: boolean;
     userName?: string;
+    /** liveChat.enabled בגרסה: רק אז מציעים צ'אט עם נציג */
+    liveEnabled: boolean;
+    liveOffer: LiveOffer | null;
+    /** הצ'אט עם הנציג, אם התחיל */
+    live: LiveSnapshot | null;
+    /** מה שהמשתמש כבר כתב בטופס הבקשה לנציג, כשאין מי שיענה וחוזרים לטופס הפנייה */
+    contactPrefill: {
+        name?: string;
+        email?: string;
+        phone?: string;
+        message?: string;
+    } | null;
 }
 export interface ControllerOptions {
     publicKey: string;
@@ -69,6 +104,21 @@ export interface ControllerOptions {
     reportDelayMs?: number;
     sessionMaxAgeMs?: number;
     now?: () => number;
+    /**
+     * אחסון לקרדנשל של הצ'אט עם נציג (lvc_...). מומלץ אחסון מאובטח, למשל expo-secure-store.
+     * ברירת מחדל: storage
+     */
+    secureStorage?: StorageAdapter;
+    /** שם המסך שנשלח עם הבקשה לנציג (page), למשל 'checkout' */
+    livePage?: string;
+    /** להחלפה בבדיקות */
+    liveTiming?: Partial<LiveTiming>;
+    /** להחלפה בבדיקות. null: רק long-poll */
+    streamOpener?: StreamOpener | null;
+    random?: () => number;
+}
+export interface LiveRequestFields extends Partial<ContactFields> {
+    departmentId?: string;
 }
 export interface ContactFields {
     name?: string;
@@ -81,6 +131,16 @@ export declare class KavchatController {
     private opts;
     private api;
     private store;
+    private secure;
+    private liveCfg;
+    private liveSession;
+    private liveTried;
+    private livePhase;
+    /** נוצרים פעם אחת לכל ניסיון של המשתמש, ומשמשים לכל ניסיון חוזר */
+    private liveRequestId;
+    private liveMessageClientId;
+    private availability;
+    private foreground;
     private snap;
     private listeners;
     private session;
@@ -97,6 +157,8 @@ export declare class KavchatController {
     ready: Promise<void>;
     /** מתממש כשניסיון רישום המסכים האחרון הסתיים. בשביל בדיקות */
     screensSync: Promise<void>;
+    /** מתממש כשניסיון שחזור הצ'אט עם הנציג הסתיים. בשביל בדיקות */
+    liveRestore: Promise<void>;
     constructor(options: ControllerOptions);
     subscribe: (listener: () => void) => () => void;
     getSnapshot: () => KavchatSnapshot;
@@ -130,6 +192,11 @@ export declare class KavchatController {
      */
     private run;
     private setConversation;
+    /**
+     * הכפתורים להצגה: כמו במנוע, ועם "שיחה עם נציג" לפני "פנייה לצוות" כשיש נציג זמין עכשיו
+     * (liveChat.enabled בגרסה, ו-/live/availability אמר open)
+     */
+    chips(): BotChip[];
     private afterAction;
     private handleEffect;
     /** פתיחת הטופס מכפתור מחוץ לתסריט */
@@ -140,6 +207,38 @@ export declare class KavchatController {
     private scheduleReport;
     /** שולח את המסלול עכשיו. קוראים לזה גם כשהאפליקציה עוברת לרקע */
     flush(): Promise<boolean>;
+    private liveOptions;
+    private onLive;
+    /** אחרי הפעלה מחדש: חוזרים לשיחה שעוד פתוחה, אם הקרדנשל בתוקף */
+    private restoreLive;
+    /**
+     * בודק אם אפשר להציע צ'אט עם נציג. נקרא כשטופס הפנייה נפתח. התשובה נשמרת 30 שניות.
+     * בלי liveChat.enabled בגרסה לא שואלים בכלל
+     */
+    checkLiveAvailability(force?: boolean): Promise<void>;
+    private availabilityInflight;
+    private fetchAvailability;
+    /**
+     * לחיצה על "שיחה עם נציג" (הכפתור שלפני "פנייה לצוות", או openLive מהאפליקציה):
+     * בודקים זמינות שוב. יש נציג: טופס הבקשה (view liveForm). אין: טופס הפנייה עם שורת הסבר
+     */
+    openLive(effect?: ContactEffect): Promise<void>;
+    /**
+     * שליחת טופס הבקשה לנציג. אורח חייב להשאיר מייל או טלפון, ההודעה אופציונלית.
+     * מחזיר הודעת שגיאה בשפת הממשק, או null. כשאין מי שיענה: טופס הפנייה עם מה שנכתב ושורת הסבר (liveOffer.reason)
+     */
+    requestLive(fields?: LiveRequestFields): Promise<string | null>;
+    /** מחזיר הודעת שגיאה בשפת הממשק (ואז הטקסט נשאר בשדה), או null */
+    liveSend(text: string): string | null;
+    liveRetry(clientId: string): void;
+    /** נקרא בכל שינוי בשדה הטקסט של הצ'אט עם הנציג */
+    liveTyping(text: string): void;
+    liveLeaveMessage(text?: string): Promise<boolean>;
+    liveEnd(): Promise<boolean>;
+    /** "חזרה לעוזר" אחרי שהצ'אט עם הנציג הסתיים. שיחה פתוחה לא נסגרת מכאן */
+    closeLive(): boolean;
+    /** האפליקציה ברקע: הזרם נסגר. בחזרה: השלמה לפי seq וזרם חדש. אין התראות push בגרסה הזו */
+    setForeground(active: boolean): void;
     dispose(): void;
     private now;
     private emit;

package/lib/controller.js

@@ -1,8 +1,10 @@
-import { aiQuestion, answerWithAi, configureEngine, eventsPayload, isRtl, pendingQuestion, pressChip, sendText, startConversation, transcriptOf, uiTexts, } from '@kavchat/core';
+import { aiQuestion, answerWithAi, configureEngine, eventsPayload, isRtl, pendingQuestion, pressChip, sendText, startConversation, transcriptOf, uiTexts, withLiveChip, LIVE_AVAILABILITY_TTL_MS, } from '@kavchat/core';
 import { fetchRelease, postAiAnswer, postEvents, postScreens, postTicket } from './api';
 import { SCREENS_MAX_AGE_MS, normalizeScreens, screensFingerprint, screensKey } from './screens';
 import { memoryStorage, randomId, readJson, releaseKey, sessionKey, userFingerprint, writeJson, } from './storage';
 import { pickLocale, safeUrl, ticketError, validateTicket } from './text';
+import { liveApi } from './live/api';
+import { LiveSession, liveKey, requestHandoff } from './live/session';
 /**
  * הבקר: טעינת הגרסה עם ETag ומטמון, שמירת השיחה, דיווח לשרת ופניות
  * קוד TypeScript רגיל בלי React Native, כדי שאפשר יהיה לבדוק אותו ב-Node.
@@ -10,8 +12,41 @@ import { pickLocale, safeUrl, ticketError, validateTicket } from './text';
  */
 export const DEFAULT_API = 'https://api.kavchat.com';
 export const BRANDING_URL = 'https://kavchat.com';
+export const AVAILABILITY_CACHE_MS = LIVE_AVAILABILITY_TTL_MS;
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function liveConfig(release) {
+    const lc = release ? release.liveChat : undefined;
+    return lc && typeof lc === 'object' && lc.enabled === true ? lc : null;
+}
+function offerFrom(a) {
+    const open = a.enabled === true && a.open === true;
+    const reason = open ? null : a.reason ?? null;
+    return {
+        checking: false,
+        open,
+        reason,
+        departments: open ? (a.departments ?? []).filter((d) => d.open) : [],
+        nextOpenAt: reason === 'closed' ? earliest(a.departments) : null,
+    };
+}
+function earliest(deps) {
+    let best = null;
+    for (const d of deps ?? []) {
+        if (d.nextOpenAt && (!best || Date.parse(d.nextOpenAt) < Date.parse(best)))
+            best = d.nextOpenAt;
+    }
+    return best;
+}
 export class KavchatController {
     constructor(options) {
+        this.liveSession = null;
+        this.liveTried = false;
+        this.livePhase = null;
+        /** נוצרים פעם אחת לכל ניסיון של המשתמש, ומשמשים לכל ניסיון חוזר */
+        this.liveRequestId = null;
+        this.liveMessageClientId = null;
+        this.availability = null;
+        this.foreground = true;
         this.listeners = new Set();
         this.session = null;
         this.loadSeq = 0;
@@ -27,6 +62,8 @@ export class KavchatController {
         this.ready = Promise.resolve();
         /** מתממש כשניסיון רישום המסכים האחרון הסתיים. בשביל בדיקות */
         this.screensSync = Promise.resolve();
+        /** מתממש כשניסיון שחזור הצ'אט עם הנציג הסתיים. בשביל בדיקות */
+        this.liveRestore = Promise.resolve();
         // ---------- מנוי, בשביל useSyncExternalStore ----------
         this.subscribe = (listener) => {
             this.listeners.add(listener);
@@ -35,6 +72,7 @@ export class KavchatController {
             };
         };
         this.getSnapshot = () => this.snap;
+        this.availabilityInflight = null;
         if (!options || !options.publicKey)
             throw new Error('Kavchat: publicKey is required');
         this.opts = { ...options };
@@ -45,6 +83,8 @@ export class KavchatController {
             getToken: () => this.opts.userToken || undefined,
             fetch: options.fetch,
         };
+        this.secure = options.secureStorage ?? this.store;
+        this.liveCfg = { ...this.api, getLocale: () => this.snap.locale };
         this.screens = normalizeScreens(options.screens);
         const locale = pickLocale(options.locale, options.deviceLocale, 'en');
         this.snap = {
@@ -61,6 +101,10 @@ export class KavchatController {
             ticketNumber: null,
             identified: !!options.userToken,
             userName: options.userName,
+            liveEnabled: false,
+            liveOffer: null,
+            live: null,
+            contactPrefill: null,
         };
     }
     update(patch) {
@@ -131,7 +175,8 @@ export class KavchatController {
         let view = this.snap.view;
         if (changed || !conversation) {
             conversation = await this.restoreSession(release, user);
-            view = 'chat';
+            // צ'אט פתוח עם נציג נשאר על המסך גם כשהגרסה מתחלפת
+            view = this.liveSession ? 'live' : 'chat';
         }
         this.update({
             status: 'ready',
@@ -146,8 +191,11 @@ export class KavchatController {
             reason: undefined,
             identified: !!this.opts.userToken,
             userName: this.opts.userName,
+            liveEnabled: !!liveConfig(release),
         });
         this.emit({ type: 'ready', version: release.version, offline });
+        if (!this.liveTried)
+            this.liveRestore = this.restoreLive();
     }
     async restoreSession(release, user) {
         const saved = await readJson(this.store, sessionKey(this.opts.publicKey));
@@ -170,6 +218,17 @@ export class KavchatController {
         if (token === this.opts.userToken && name === this.opts.userName)
             return this.ready;
         this.flush();
+        if (userFingerprint(token) !== userFingerprint(this.opts.userToken)) {
+            // שיחה עם נציג של משתמש אחד לא ממשיכה אצל אחר
+            this.liveSession?.forget();
+            this.liveSession = null;
+            this.liveTried = false;
+            this.livePhase = null;
+            this.liveRequestId = null;
+            this.liveMessageClientId = null;
+            this.availability = null;
+            this.update({ live: null, liveOffer: null, view: this.snap.view === 'live' ? 'chat' : this.snap.view });
+        }
         this.opts.userToken = token;
         this.opts.userName = name;
         return this.load();
@@ -298,6 +357,17 @@ export class KavchatController {
             void writeJson(this.store, sessionKey(this.opts.publicKey), this.session);
         }
         this.update({ conversation: state, ...extra });
+        // כפתור "פנייה לצוות" על המסך: בודקים (עם מטמון של 30 שניות) אם להוסיף לפניו "שיחה עם נציג"
+        if (state.chips.some((c) => c.kind === 'contact'))
+            void this.checkLiveAvailability();
+    }
+    /**
+     * הכפתורים להצגה: כמו במנוע, ועם "שיחה עם נציג" לפני "פנייה לצוות" כשיש נציג זמין עכשיו
+     * (liveChat.enabled בגרסה, ו-/live/availability אמר open)
+     */
+    chips() {
+        const chips = this.snap.conversation?.chips ?? [];
+        return this.snap.liveEnabled && this.snap.liveOffer?.open ? withLiveChip(chips, this.snap.texts['live.talk']) : chips;
     }
     afterAction(r) {
         this.setConversation(r.state);
@@ -307,8 +377,12 @@ export class KavchatController {
     }
     handleEffect(effect) {
         this.emit({ type: 'effect', effect });
-        if (effect.type === 'contact') {
-            this.update({ view: 'form', contact: effect, ticketNumber: null });
+        if (effect.type === 'live') {
+            void this.openLive(effect);
+        }
+        else if (effect.type === 'contact') {
+            this.update({ view: 'form', contact: effect, ticketNumber: null, contactPrefill: null });
+            void this.checkLiveAvailability();
         }
         else if (effect.type === 'link') {
             // רק https ו-tel. כל פרוטוקול אחר מהתסריט נחסם
@@ -326,6 +400,7 @@ export class KavchatController {
         this.update({
             view: 'form',
             ticketNumber: null,
+            contactPrefill: null,
             contact: {
                 type: 'contact',
                 contactTopicId: null,
@@ -334,6 +409,7 @@ export class KavchatController {
                 transcript: state ? transcriptOf(state) : [],
             },
         });
+        void this.checkLiveAvailability();
     }
     backToChat() {
         this.update({ view: 'chat', contact: null, ticketNumber: null });
@@ -393,10 +469,263 @@ export class KavchatController {
             return ok;
         });
     }
+    // ---------- צ'אט עם נציג ----------
+    liveOptions() {
+        return {
+            api: this.liveCfg,
+            store: this.secure,
+            storageKey: liveKey(this.opts.publicKey),
+            user: userFingerprint(this.opts.userToken),
+            opener: this.opts.streamOpener,
+            timing: this.opts.liveTiming,
+            random: this.opts.random,
+            now: this.opts.now,
+            onChange: (snap) => {
+                // רק הסשן הנוכחי מעדכן את המסך
+                if (this.liveSession && this.liveSession.getSnapshot() === snap)
+                    this.onLive(snap);
+            },
+        };
+    }
+    onLive(snap) {
+        this.update({ live: snap });
+        if (snap.phase !== this.livePhase) {
+            this.livePhase = snap.phase;
+            this.emit({ type: 'live', phase: snap.phase });
+        }
+    }
+    /** אחרי הפעלה מחדש: חוזרים לשיחה שעוד פתוחה, אם הקרדנשל בתוקף */
+    async restoreLive() {
+        if (this.liveTried || this.liveSession)
+            return;
+        this.liveTried = true;
+        const user = userFingerprint(this.opts.userToken);
+        const s = await LiveSession.restore(this.liveOptions());
+        if (!s)
+            return;
+        if (this.disposed || this.liveSession || user !== userFingerprint(this.opts.userToken)) {
+            s.dispose();
+            return;
+        }
+        this.liveSession = s;
+        if (!this.foreground)
+            s.pause();
+        this.livePhase = null;
+        this.update({ view: 'live' });
+        this.onLive(s.getSnapshot());
+    }
+    /**
+     * בודק אם אפשר להציע צ'אט עם נציג. נקרא כשטופס הפנייה נפתח. התשובה נשמרת 30 שניות.
+     * בלי liveChat.enabled בגרסה לא שואלים בכלל
+     */
+    checkLiveAvailability(force = false) {
+        if (!liveConfig(this.snap.release)) {
+            if (this.snap.liveOffer)
+                this.update({ liveOffer: null });
+            return Promise.resolve();
+        }
+        const cached = this.availability;
+        if (!force && cached && this.now() - cached.at < AVAILABILITY_CACHE_MS) {
+            if (this.snap.liveOffer?.checking || !this.snap.liveOffer)
+                this.update({ liveOffer: offerFrom(cached.value) });
+            return Promise.resolve();
+        }
+        // בקשה אחת בכל פעם: הכפתורים, הטופס והלחיצה על הכפתור מחכים לאותה תשובה
+        if (!this.availabilityInflight || force) {
+            this.availabilityInflight = this.fetchAvailability().finally(() => {
+                this.availabilityInflight = null;
+            });
+        }
+        return this.availabilityInflight;
+    }
+    async fetchAvailability() {
+        // עד שהתשובה מגיעה נשארת ההצעה הקודמת, כדי שהכפתור לא יהבהב
+        if (!this.snap.liveOffer)
+            this.update({ liveOffer: { checking: true, open: false, reason: null, departments: [], nextOpenAt: null } });
+        const r = await liveApi.availability(this.liveCfg);
+        if (this.disposed)
+            return;
+        if (!r.ok) {
+            // לא ידוע: מציגים רק את הטופס, בלי הסבר
+            this.update({ liveOffer: { checking: false, open: false, reason: null, departments: [], nextOpenAt: null } });
+            return;
+        }
+        this.availability = { at: this.now(), value: r.data };
+        this.update({ liveOffer: offerFrom(r.data) });
+    }
+    /**
+     * לחיצה על "שיחה עם נציג" (הכפתור שלפני "פנייה לצוות", או openLive מהאפליקציה):
+     * בודקים זמינות שוב. יש נציג: טופס הבקשה (view liveForm). אין: טופס הפנייה עם שורת הסבר
+     */
+    async openLive(effect) {
+        const state = this.snap.conversation;
+        const e = effect ?? {
+            type: 'live',
+            contactTopicId: null,
+            scriptId: state?.lastScriptId ?? null,
+            prefill: '',
+            transcript: state ? transcriptOf(state) : [],
+        };
+        if (this.liveSession && !this.liveSession.isFinal()) {
+            this.update({ view: 'live' });
+            return;
+        }
+        await this.checkLiveAvailability();
+        if (this.disposed)
+            return;
+        const open = !!this.snap.liveOffer?.open;
+        this.update({ view: open ? 'liveForm' : 'form', contact: e, ticketNumber: null, contactPrefill: null });
+    }
+    /**
+     * שליחת טופס הבקשה לנציג. אורח חייב להשאיר מייל או טלפון, ההודעה אופציונלית.
+     * מחזיר הודעת שגיאה בשפת הממשק, או null. כשאין מי שיענה: טופס הפנייה עם מה שנכתב ושורת הסבר (liveOffer.reason)
+     */
+    async requestLive(fields = {}) {
+        const t = this.snap.texts;
+        if (this.liveSession && !this.liveSession.isFinal()) {
+            this.update({ view: 'live' });
+            return null;
+        }
+        const trim = (v) => (v ?? '').trim() || undefined;
+        const email = trim(fields.email);
+        const phone = trim(fields.phone);
+        const message = trim(fields.message);
+        const identified = !!this.opts.userToken;
+        if (!email && !phone && !identified)
+            return t['form.contactRequired'];
+        if (email && !EMAIL_RE.test(email))
+            return t['form.emailInvalid'];
+        if (message && message.length > 2000)
+            return this.snap.texts['live.tooLong'];
+        this.liveRequestId ?? (this.liveRequestId = randomId(22));
+        if (message)
+            this.liveMessageClientId ?? (this.liveMessageClientId = randomId(22));
+        const effect = this.snap.contact;
+        const bot = this.snap.conversation;
+        const transcript = (effect?.transcript ?? (bot ? transcriptOf(bot) : []))
+            .slice(-200)
+            .map((x) => ({ from: x.from, text: String(x.text).slice(0, 1000), at: x.at }));
+        const departments = this.snap.liveOffer?.departments ?? [];
+        const body = {
+            requestId: this.liveRequestId,
+            sessionId: this.session?.id,
+            identityToken: this.opts.userToken || undefined,
+            name: trim(fields.name),
+            email,
+            phone,
+            // ברירת מחדל: המחלקה הפתוחה הראשונה
+            departmentId: trim(fields.departmentId) ?? departments[0]?.id,
+            topicId: trim(fields.topicId) ?? (effect?.contactTopicId || undefined),
+            message,
+            messageClientId: message ? this.liveMessageClientId ?? undefined : undefined,
+            page: this.opts.livePage || undefined,
+            transcript,
+        };
+        const r = await requestHandoff(this.liveCfg, body, this.opts.liveTiming, this.opts.random);
+        if (this.disposed)
+            return null;
+        if (!r.ok) {
+            if (r.code === 'ticket_contact_required')
+                return t['form.contactRequired'];
+            if (r.code === 'email_invalid')
+                return t['form.emailInvalid'];
+            if (r.code === 'live_message_too_long')
+                return this.snap.texts['live.tooLong'];
+            if (r.code === 'live_conversation_open')
+                return t['live.elsewhere'];
+            if (r.code === 'network')
+                return t['form.error'];
+            return r.message || t['form.error'];
+        }
+        this.liveRequestId = null;
+        this.liveMessageClientId = null;
+        if (!r.data.accepted) {
+            // אין מי שיענה עכשיו: טופס הפנייה הרגיל עם מה שכבר נכתב ושורת הסבר
+            const cached = this.availability?.value;
+            this.availability = null;
+            this.update({
+                view: 'form',
+                contact: effect ? { ...effect, type: 'contact' } : effect,
+                contactPrefill: { name: trim(fields.name), email, phone, message },
+                liveOffer: {
+                    checking: false,
+                    open: false,
+                    reason: r.data.reason,
+                    departments: [],
+                    nextOpenAt: r.data.reason === 'closed' ? earliest(cached?.departments) : null,
+                },
+            });
+            return null;
+        }
+        void this.flush();
+        const s = await LiveSession.start(this.liveOptions(), r.data);
+        if (this.disposed) {
+            s.dispose();
+            return null;
+        }
+        this.liveSession?.dispose();
+        this.liveSession = s;
+        this.liveTried = true;
+        if (!this.foreground)
+            s.pause();
+        this.livePhase = null;
+        this.update({ view: 'live' });
+        this.onLive(s.getSnapshot());
+        return null;
+    }
+    /** מחזיר הודעת שגיאה בשפת הממשק (ואז הטקסט נשאר בשדה), או null */
+    liveSend(text) {
+        const s = this.liveSession;
+        if (!s)
+            return null;
+        const code = s.send(text);
+        if (code === 'live_message_too_long')
+            return this.snap.texts['live.tooLong'];
+        return null;
+    }
+    liveRetry(clientId) {
+        this.liveSession?.retry(clientId);
+    }
+    /** נקרא בכל שינוי בשדה הטקסט של הצ'אט עם הנציג */
+    liveTyping(text) {
+        this.liveSession?.typing(text);
+    }
+    liveLeaveMessage(text) {
+        return this.liveSession ? this.liveSession.leaveMessage(text) : Promise.resolve(false);
+    }
+    liveEnd() {
+        return this.liveSession ? this.liveSession.endChat() : Promise.resolve(false);
+    }
+    /** "חזרה לעוזר" אחרי שהצ'אט עם הנציג הסתיים. שיחה פתוחה לא נסגרת מכאן */
+    closeLive() {
+        const s = this.liveSession;
+        if (s && !s.isFinal())
+            return false;
+        s?.dispose();
+        this.liveSession = null;
+        this.livePhase = null;
+        this.update({ live: null, view: 'chat', contact: null, liveOffer: null });
+        return true;
+    }
+    /** האפליקציה ברקע: הזרם נסגר. בחזרה: השלמה לפי seq וזרם חדש. אין התראות push בגרסה הזו */
+    setForeground(active) {
+        if (this.foreground === active)
+            return;
+        this.foreground = active;
+        const s = this.liveSession;
+        if (!s)
+            return;
+        if (active)
+            void s.resume();
+        else
+            s.pause();
+    }
     dispose() {
         if (this.disposed)
             return;
         void this.flush();
+        this.liveSession?.dispose();
+        this.liveSession = null;
         this.disposed = true;
         this.listeners.clear();
     }

package/lib/index.d.ts

@@ -5,7 +5,10 @@ export type { KavchatChatProps } from './ui/KavchatChat';
 export { KavchatLauncher } from './ui/KavchatLauncher';
 export type { KavchatLauncherProps } from './ui/KavchatLauncher';
 export { KavchatController, DEFAULT_API, BRANDING_URL } from './controller';
-export type { ControllerOptions, ContactFields, KavchatEvent, KavchatSnapshot, KavchatStatus, KavchatView } from './controller';
+export type { ControllerOptions, ContactFields, KavchatEvent, KavchatSnapshot, KavchatStatus, KavchatView, LiveOffer, LiveRequestFields } from './controller';
+export type { LiveConversation, LiveEvent, LiveState, LiveUnavailableReason } from './live/api';
+export type { LiveConnection, LivePending, LivePhase, LiveSnapshot } from './live/session';
+export type { StreamOpener } from './live/sse';
 export { memoryStorage, defaultStorage } from './storage';
 export type { StorageAdapter } from './storage';
 export { themeFor } from './theme';