@kavchat/react-native 0.0.2 → 0.0.3

package/src/controller.ts

@@ -10,6 +10,8 @@ import {
   startConversation,
   transcriptOf,
   uiTexts,
+  withLiveChip,
+  LIVE_AVAILABILITY_TTL_MS,
 } from '@kavchat/core';
 import type { BotChip, BotEffect, BotResult, BotState, UiTexts } from '@kavchat/core';
 import { AnyRelease, ApiConfig, EnabledRelease, FetchLike, TicketInput, fetchRelease, postAiAnswer, postEvents, postScreens, postTicket } from './api';
@@ -27,6 +29,9 @@ import {
   writeJson,
 } from './storage';
 import { pickLocale, safeUrl, ticketError, validateTicket } from './text';
+import { LiveAvailability, LiveApiConfig, LiveChatRelease, LiveDepartmentAvailability, LiveRequestBody, LiveUnavailableReason, liveApi } from './live/api';
+import { LivePhase, LiveSession, LiveSessionOptions, LiveSnapshot, LiveTiming, liveKey, requestHandoff } from './live/session';
+import type { StreamOpener } from './live/sse';
 
 /**
  * הבקר: טעינת הגרסה עם ETag ומטמון, שמירת השיחה, דיווח לשרת ופניות
@@ -37,15 +42,34 @@ import { pickLocale, safeUrl, ticketError, validateTicket } from './text';
 export const DEFAULT_API = 'https://api.kavchat.com';
 export const BRANDING_URL = 'https://kavchat.com';
 
-export type ContactEffect = Extract<BotEffect, { type: 'contact' }>;
+/** טופס פנייה (contact) או טופס הבקשה לנציג (live) */
+export type ContactEffect = Extract<BotEffect, { 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; offline: boolean }
   | { type: 'unavailable'; reason?: string }
   | { type: 'effect'; effect: BotEffect }
-  | { type: 'ticket'; id: string; number: number };
+  | { 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 const AVAILABILITY_CACHE_MS = LIVE_AVAILABILITY_TTL_MS;
 
 export interface KavchatSnapshot {
   status: KavchatStatus;
@@ -66,6 +90,13 @@ 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 {
@@ -88,6 +119,49 @@ 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;
+}
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function liveConfig(release: EnabledRelease | null): LiveChatRelease | null {
+  const lc = release ? (release as unknown as { liveChat?: LiveChatRelease }).liveChat : undefined;
+  return lc && typeof lc === 'object' && lc.enabled === true ? lc : null;
+}
+
+function offerFrom(a: LiveAvailability): LiveOffer {
+  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: LiveDepartmentAvailability[] | undefined): string | null {
+  let best: string | null = null;
+  for (const d of deps ?? []) {
+    if (d.nextOpenAt && (!best || Date.parse(d.nextOpenAt) < Date.parse(best))) best = d.nextOpenAt;
+  }
+  return best;
 }
 
 export interface ContactFields {
@@ -102,6 +176,16 @@ export class KavchatController {
   private opts: ControllerOptions;
   private api: ApiConfig;
   private store: StorageAdapter;
+  private secure: StorageAdapter;
+  private liveCfg: LiveApiConfig;
+  private liveSession: LiveSession | null = null;
+  private liveTried = false;
+  private livePhase: LivePhase | null = null;
+  /** נוצרים פעם אחת לכל ניסיון של המשתמש, ומשמשים לכל ניסיון חוזר */
+  private liveRequestId: string | null = null;
+  private liveMessageClientId: string | null = null;
+  private availability: { at: number; value: LiveAvailability } | null = null;
+  private foreground = true;
   private snap: KavchatSnapshot;
   private listeners = new Set<() => void>();
   private session: StoredSession | null = null;
@@ -118,6 +202,8 @@ export class KavchatController {
   ready: Promise<void> = Promise.resolve();
   /** מתממש כשניסיון רישום המסכים האחרון הסתיים. בשביל בדיקות */
   screensSync: Promise<void> = Promise.resolve();
+  /** מתממש כשניסיון שחזור הצ'אט עם הנציג הסתיים. בשביל בדיקות */
+  liveRestore: Promise<void> = Promise.resolve();
 
   constructor(options: ControllerOptions) {
     if (!options || !options.publicKey) throw new Error('Kavchat: publicKey is required');
@@ -129,6 +215,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 = {
@@ -145,6 +233,10 @@ export class KavchatController {
       ticketNumber: null,
       identified: !!options.userToken,
       userName: options.userName,
+      liveEnabled: false,
+      liveOffer: null,
+      live: null,
+      contactPrefill: null,
     };
   }
 
@@ -227,7 +319,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',
@@ -242,8 +335,10 @@ 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();
   }
 
   private async restoreSession(release: EnabledRelease, user: string): Promise<BotState | null> {
@@ -266,6 +361,17 @@ export class KavchatController {
     const name = user?.name || undefined;
     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();
@@ -392,6 +498,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(): BotChip[] {
+    const chips = this.snap.conversation?.chips ?? [];
+    return this.snap.liveEnabled && this.snap.liveOffer?.open ? withLiveChip(chips, this.snap.texts['live.talk']) : chips;
   }
 
   private afterAction(r: BotResult) {
@@ -402,8 +519,11 @@ export class KavchatController {
 
   private handleEffect(effect: BotEffect) {
     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. כל פרוטוקול אחר מהתסריט נחסם
       const href = safeUrl(effect.url, ['https', 'tel']);
@@ -419,6 +539,7 @@ export class KavchatController {
     this.update({
       view: 'form',
       ticketNumber: null,
+      contactPrefill: null,
       contact: {
         type: 'contact',
         contactTopicId: null,
@@ -427,6 +548,7 @@ export class KavchatController {
         transcript: state ? transcriptOf(state) : [],
       },
     });
+    void this.checkLiveAvailability();
   }
 
   backToChat() {
@@ -486,9 +608,252 @@ export class KavchatController {
     });
   }
 
+  // ---------- צ'אט עם נציג ----------
+
+  private liveOptions(): LiveSessionOptions {
+    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);
+      },
+    };
+  }
+
+  private onLive(snap: LiveSnapshot) {
+    this.update({ live: snap });
+    if (snap.phase !== this.livePhase) {
+      this.livePhase = snap.phase;
+      this.emit({ type: 'live', phase: snap.phase });
+    }
+  }
+
+  /** אחרי הפעלה מחדש: חוזרים לשיחה שעוד פתוחה, אם הקרדנשל בתוקף */
+  private 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): Promise<void> {
+    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;
+  }
+
+  private availabilityInflight: Promise<void> | null = null;
+
+  private async fetchAvailability(): Promise<void> {
+    // עד שהתשובה מגיעה נשארת ההצעה הקודמת, כדי שהכפתור לא יהבהב
+    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?: ContactEffect) {
+    const state = this.snap.conversation;
+    const e: ContactEffect = 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: LiveRequestFields = {}): Promise<string | null> {
+    const t = this.snap.texts;
+    if (this.liveSession && !this.liveSession.isFinal()) {
+      this.update({ view: 'live' });
+      return null;
+    }
+    const trim = (v?: string) => (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 ??= randomId(22);
+    if (message) 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: LiveRequestBody = {
+      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: string): string | null {
+    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: string) {
+    this.liveSession?.retry(clientId);
+  }
+
+  /** נקרא בכל שינוי בשדה הטקסט של הצ'אט עם הנציג */
+  liveTyping(text: string) {
+    this.liveSession?.typing(text);
+  }
+
+  liveLeaveMessage(text?: string): Promise<boolean> {
+    return this.liveSession ? this.liveSession.leaveMessage(text) : Promise.resolve(false);
+  }
+
+  liveEnd(): Promise<boolean> {
+    return this.liveSession ? this.liveSession.endChat() : Promise.resolve(false);
+  }
+
+  /** "חזרה לעוזר" אחרי שהצ'אט עם הנציג הסתיים. שיחה פתוחה לא נסגרת מכאן */
+  closeLive(): boolean {
+    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: boolean) {
+    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/src/index.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';

package/src/live/api.ts

@@ -0,0 +1,109 @@
+import type { FetchLike } from '../api';
+
+/**
+ * Client API של צ'אט עם נציג (/v1/client/{publicKey}/live), לפי docs/live-chat-protocol.md.
+ * אפליקציה לא צריכה להתחשב ב-CORS, ולכן הגוף נשלח כ-application/json והשפה ב-Accept-Language.
+ * הקרדנשל (lvc_...) עובר רק בגוף, אף פעם לא בכתובת, ולא נכתב ללוג
+ */
+
+// הטיפוסים והמכונה הטהורה משותפים לכל הלקוחות ב-@kavchat/core (src/live.ts). כאן רק הרשת
+import type { LiveAvailability, LiveConversation, LiveEvent, LiveUnavailableReason } from '@kavchat/core';
+export type { LiveAvailability, LiveChatRelease, LiveConversation, LiveEvent, LiveState, LiveUnavailableReason } from '@kavchat/core';
+
+export type LiveDepartmentAvailability = LiveAvailability['departments'][number];
+
+export interface LiveSync {
+  conversation: LiveConversation;
+  events: LiveEvent[];
+  hasMore: boolean;
+}
+
+export interface LiveAccepted {
+  accepted: true;
+  conversation: LiveConversation;
+  credential: string;
+  credentialExpiresAt: string;
+  waitSeconds: number;
+}
+
+export interface LiveUnavailable {
+  accepted: false;
+  reason: LiveUnavailableReason;
+  fallback: 'ticket';
+}
+
+export interface LiveRequestBody {
+  requestId: string;
+  credential?: string;
+  identityToken?: string;
+  departmentId?: string;
+  sessionId?: string;
+  name?: string;
+  email?: string;
+  phone?: string;
+  topicId?: string;
+  message?: string;
+  messageClientId?: string;
+  page?: string;
+  transcript?: Array<{ from: 'bot' | 'user'; text: string; at: string }>;
+}
+
+/** תוצאה של קריאה: הצלחה עם data, או קוד שגיאה. status 0 = אין רשת */
+export type LiveResult<T> = { ok: true; status: number; data: T } | { ok: false; status: number; code: string; message: string };
+
+export interface LiveApiConfig {
+  apiBase: string;
+  publicKey: string;
+  getToken: () => string | undefined;
+  getLocale: () => string;
+  fetch?: FetchLike;
+}
+
+export const liveUrl = (c: LiveApiConfig, path: string) =>
+  `${c.apiBase.replace(/\/+$/, '')}/v1/client/${encodeURIComponent(c.publicKey)}/live/${path}`;
+
+const doFetch = (c: LiveApiConfig): FetchLike => c.fetch ?? (globalThis.fetch as unknown as FetchLike);
+
+/** האם כדאי לנסות שוב: אין רשת, 5xx או 429. שאר ה-4xx סופיים */
+export const retryable = (r: { ok: boolean; status: number }) => !r.ok && (r.status === 0 || r.status === 429 || r.status >= 500);
+
+async function call<T>(c: LiveApiConfig, method: 'GET' | 'POST', path: string, body?: unknown, auth = false): Promise<LiveResult<T>> {
+  const headers: Record<string, string> = { 'Accept-Language': c.getLocale() };
+  if (method === 'POST') headers['Content-Type'] = 'application/json';
+  const token = auth ? c.getToken() : undefined;
+  if (token) headers.Authorization = `Bearer ${token}`;
+  let res: Awaited<ReturnType<FetchLike>>;
+  try {
+    res = await doFetch(c)(liveUrl(c, path), {
+      method,
+      cache: 'no-store',
+      credentials: 'omit',
+      headers,
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+  } catch {
+    return { ok: false, status: 0, code: 'network', message: '' };
+  }
+  const json = (await res.json().catch(() => null)) as { success?: boolean; data?: T; code?: string; message?: string } | null;
+  if (res.ok && json && json.success === true && json.data !== undefined) return { ok: true, status: res.status, data: json.data };
+  return { ok: false, status: res.ok ? 502 : res.status, code: String(json?.code || `http_${res.status}`), message: String(json?.message || '') };
+}
+
+export const liveApi = {
+  availability: (c: LiveApiConfig, departmentId?: string) =>
+    call<LiveAvailability>(c, 'GET', departmentId ? `availability?departmentId=${encodeURIComponent(departmentId)}` : 'availability', undefined, true),
+  request: (c: LiveApiConfig, body: LiveRequestBody) => call<LiveAccepted | LiveUnavailable>(c, 'POST', 'requests', body, true),
+  message: (c: LiveApiConfig, credential: string, clientId: string, text: string) =>
+    call<{ event: LiveEvent; duplicate?: boolean }>(c, 'POST', 'messages', { credential, clientId, text }),
+  typing: (c: LiveApiConfig, credential: string, on: boolean) => call<{ ok: true }>(c, 'POST', 'typing', { credential, on }),
+  sync: (c: LiveApiConfig, credential: string, after: number, wait = 0) =>
+    call<LiveSync>(c, 'POST', 'sync', wait > 0 ? { credential, after, wait } : { credential, after }),
+  streamTicket: (c: LiveApiConfig, credential: string) => call<{ ticket: string; expiresIn: number }>(c, 'POST', 'stream-ticket', { credential }),
+  leaveMessage: (c: LiveApiConfig, credential: string, text?: string, clientId?: string) =>
+    call<{ conversation: LiveConversation }>(c, 'POST', 'leave-message', text ? { credential, text, clientId } : { credential }),
+  end: (c: LiveApiConfig, credential: string) => call<{ conversation: LiveConversation }>(c, 'POST', 'end', { credential }),
+};
+
+/** כתובת הזרם. מכילה כרטיס חד-פעמי: לא לכתוב אותה ללוג */
+export const streamUrl = (c: LiveApiConfig, ticket: string, after: number) =>
+  `${liveUrl(c, 'stream')}?ticket=${encodeURIComponent(ticket)}&after=${Math.max(0, Math.floor(after))}`;