@kavchat/react-native 0.0.1 → 0.0.3

package/src/live/session.ts

@@ -0,0 +1,784 @@
+import { StorageAdapter, randomId, readJson, writeJson } from '../storage';
+import {
+  LiveAccepted,
+  LiveApiConfig,
+  LiveConversation,
+  LiveEvent,
+  LiveRequestBody,
+  LiveResult,
+  LiveSync,
+  LiveUnavailable,
+  liveApi,
+  retryable,
+  streamUrl,
+} from './api';
+import { SseMessage, SseParser, StreamHandle, StreamOpener, defaultStreamOpener } from './sse';
+import { isLiveFinal, liveAddPending, liveApplyConversation, liveApplyEvent, liveApplySync, liveSetPending, liveStart } from '@kavchat/core';
+import type { LiveChat, LivePending } from '@kavchat/core';
+export type { LivePending } from '@kavchat/core';
+
+/**
+ * צד המבקר בצ'אט עם נציג: הזרם, חיבור מחדש עם השלמה לפי seq, שליחה אידמפוטנטית,
+ * הקלדה, מעבר לרקע ושחזור אחרי הפעלה מחדש. בלי React Native, כדי שאפשר לבדוק ב-Node.
+ * הסדר, הסינון הכפול וההודעות שבדרך: המכונה הטהורה ב-@kavchat/core (live.ts), זהה בכל הלקוחות.
+ * החוזה: docs/live-chat-protocol.md. הקרדנשל לא נכתב ללוג ולא לכתובת
+ */
+
+export type LivePhase = 'queued' | 'active' | 'closed' | 'ticket' | 'replaced' | 'expired';
+export type LiveConnection = 'connecting' | 'live' | 'polling' | 'reconnecting' | 'paused' | 'stopped';
+
+export interface LiveSnapshot {
+  phase: LivePhase;
+  /** המצב של המכונה המשותפת: מעבירים אותו ל-liveLines ו-liveStatus */
+  chat: LiveChat;
+  conversation: LiveConversation;
+  /** אירועים שהמבקר רואה, ממוינים לפי seq, בלי כפילויות */
+  events: LiveEvent[];
+  /** הודעות שעוד לא אושרו בשרת */
+  pending: LivePending[];
+  /** שם הנציג שמקליד, או null */
+  agentTyping: string | null;
+  connection: LiveConnection;
+  waitSeconds: number;
+  /** קוד השגיאה האחרונה שצריך להציג (למשל live_message_too_long), או null */
+  error: { code: string; message: string } | null;
+}
+
+export interface LiveTiming {
+  /** השהיות חיבור מחדש וניסיון חוזר: 1, 2, 4, 8, 16, 30 שניות */
+  backoffMs: number[];
+  /** רעש אקראי של 30% לכל כיוון */
+  jitter: number;
+  /** בלי שום נתון (גם לא הערת ping) זמן כזה: הפרוקסי ניתק בשקט */
+  silenceMs: number;
+  typingThrottleMs: number;
+  typingHideMs: number;
+  pollWaitSeconds: number;
+  /** הפסקה מינימלית בין שתי בקשות long-poll שחזרו מיד */
+  pollGapMs: number;
+  /** כמה זמן להשתמש ב-long-poll אחרי live_busy או כישלונות חוזרים, לפני שמנסים זרם שוב */
+  pollModeMs: number;
+  /** אחרי queueDeadline: סנכרון אחד, למקרה שהעדכון לא הגיע בזרם */
+  deadlineGraceMs: number;
+  /** השיחה עדיין queued אחרי הסנכרון (משימת השרת מאחרת): בודקים שוב במרווח הזה, עד 6 פעמים */
+  deadlineRetryMs: number;
+  sendAttempts: number;
+}
+
+export const DEFAULT_TIMING: LiveTiming = {
+  backoffMs: [1000, 2000, 4000, 8000, 16000, 30000],
+  jitter: 0.3,
+  silenceMs: 60_000,
+  typingThrottleMs: 3000,
+  typingHideMs: 6000,
+  pollWaitSeconds: 25,
+  pollGapMs: 1000,
+  pollModeMs: 120_000,
+  deadlineGraceMs: 3000,
+  deadlineRetryMs: 10_000,
+  sendAttempts: 6,
+};
+
+/** מה נשמר במכשיר כדי לחזור לשיחה אחרי הפעלה מחדש. הקרדנשל רק כאן ובזיכרון */
+export interface StoredLive {
+  credential: string;
+  expiresAt: string;
+  conversationId: string;
+  user: string;
+  waitSeconds?: number;
+}
+
+export const liveKey = (publicKey: string) => `kavchat:live:${publicKey}`;
+
+export interface LiveSessionOptions {
+  api: LiveApiConfig;
+  /** אחסון לקרדנשל. עדיף אחסון מאובטח (Keychain / Keystore) */
+  store: StorageAdapter;
+  storageKey: string;
+  /** טביעה של המשתמש המחובר, כדי לא להמשיך שיחה של משתמש אחר */
+  user: string;
+  /** null: אין זרם, רק long-poll */
+  opener?: StreamOpener | null;
+  timing?: Partial<LiveTiming>;
+  random?: () => number;
+  now?: () => number;
+  onChange?: (snapshot: LiveSnapshot) => void;
+}
+
+const FINAL: LivePhase[] = ['closed', 'ticket', 'replaced', 'expired'];
+export const isFinalPhase = (p: LivePhase) => FINAL.includes(p);
+const isOpenState = (p: LivePhase) => p === 'queued' || p === 'active';
+
+export function backoffDelay(attempt: number, t: Pick<LiveTiming, 'backoffMs' | 'jitter'>, random: () => number = Math.random): number {
+  const list = t.backoffMs.length ? t.backoffMs : [1000];
+  const base = list[Math.min(Math.max(attempt, 0), list.length - 1)];
+  return Math.max(0, Math.round(base * (1 + (random() * 2 - 1) * t.jitter)));
+}
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** בקשת נציג עם ניסיונות חוזרים על רשת, 5xx ו-429. ה-requestId זהה בכל הניסיונות */
+export async function requestHandoff(
+  api: LiveApiConfig,
+  body: LiveRequestBody,
+  timing: Partial<LiveTiming> = {},
+  random: () => number = Math.random,
+  attempts = 4,
+): Promise<LiveResult<LiveAccepted | LiveUnavailable>> {
+  const t = { ...DEFAULT_TIMING, ...timing };
+  for (let attempt = 0; ; attempt++) {
+    const r = await liveApi.request(api, body);
+    if (r.ok || !retryable(r) || attempt + 1 >= attempts) return r;
+    await sleep(backoffDelay(attempt, t, random));
+  }
+}
+
+function errorCode(body: string): string {
+  try {
+    const j = JSON.parse(body) as { code?: unknown };
+    return typeof j.code === 'string' ? j.code : '';
+  } catch {
+    return '';
+  }
+}
+
+export class LiveSession {
+  private o: LiveSessionOptions;
+  private t: LiveTiming;
+  private random: () => number;
+  private opener: StreamOpener | null;
+  private credential: string;
+  private expiresAt: string;
+  /** המצב עצמו (שיחה, אירועים, הודעות שבדרך) מנוהל על ידי המכונה הטהורה ב-@kavchat/core */
+  private chat: LiveChat;
+  /** מצבים סופיים שלא באים מהשרת: הקרדנשל הוחלף (bye replaced) או פג */
+  private override: 'replaced' | 'expired' | null = null;
+  private finished = false;
+  private agentTyping: string | null = null;
+  private connection: LiveConnection = 'connecting';
+  private waitSeconds: number;
+  private error: LiveSnapshot['error'] = null;
+  private snap: LiveSnapshot;
+
+  /** עולה בכל עצירה (רקע, סיום, dispose), כדי שלולאות ישנות ייעצרו אחרי await */
+  private gen = 0;
+  private conn: { closed: boolean; handle: StreamHandle | null } | null = null;
+  private attempt = 0;
+  private failuresWithoutReady = 0;
+  private pollUntil = 0;
+  private polling = false;
+  private paused = false;
+  private disposed = false;
+  private typingOn = false;
+  private lastTypingAt = 0;
+  private armedDeadline = '';
+  private timers: Record<'reconnect' | 'silence' | 'typing' | 'deadline' | 'expiry' | 'poll', ReturnType<typeof setTimeout> | null> = {
+    reconnect: null,
+    silence: null,
+    typing: null,
+    deadline: null,
+    expiry: null,
+    poll: null,
+  };
+
+  private get phase(): LivePhase {
+    return this.override ?? this.chat.conversation.state;
+  }
+
+  private get lastSeq() {
+    return this.chat.lastSeq;
+  }
+
+  private constructor(o: LiveSessionOptions, credential: string, expiresAt: string, waitSeconds: number, conversation: LiveConversation) {
+    this.chat = liveStart(conversation);
+    this.o = o;
+    this.t = { ...DEFAULT_TIMING, ...(o.timing ?? {}) };
+    this.random = o.random ?? Math.random;
+    this.opener = o.opener === undefined ? defaultStreamOpener : o.opener;
+    this.credential = credential;
+    this.expiresAt = expiresAt;
+    this.waitSeconds = waitSeconds;
+    this.snap = this.build();
+  }
+
+  // ---------- יצירה ----------
+
+  /** אחרי accepted: שומר את הקרדנשל, מציג המתנה ופותח את הזרם */
+  static async start(o: LiveSessionOptions, accepted: LiveAccepted): Promise<LiveSession> {
+    const s = new LiveSession(o, accepted.credential, accepted.credentialExpiresAt, accepted.waitSeconds, accepted.conversation);
+    await writeJson(o.store, o.storageKey, {
+      credential: accepted.credential,
+      expiresAt: accepted.credentialExpiresAt,
+      conversationId: accepted.conversation.id,
+      user: o.user,
+      waitSeconds: accepted.waitSeconds,
+    } satisfies StoredLive);
+    s.afterChange();
+    s.run();
+    return s;
+  }
+
+  /**
+   * אחרי הפעלה מחדש: אם יש קרדנשל בתוקף של אותו משתמש, בונה את השיחה מ-sync after 0 וממשיך.
+   * שיחה שהסתיימה בינתיים או קרדנשל שפג: מוחק ומחזיר null
+   */
+  static async restore(o: LiveSessionOptions): Promise<LiveSession | null> {
+    const saved = await readJson<StoredLive>(o.store, o.storageKey);
+    if (!saved || typeof saved.credential !== 'string' || !saved.credential) return null;
+    const now = o.now ? o.now() : Date.now();
+    const exp = Date.parse(saved.expiresAt);
+    if (saved.user !== o.user || !Number.isFinite(exp) || exp <= now) {
+      await removeKey(o.store, o.storageKey);
+      return null;
+    }
+    // עד שהסנכרון עונה: שיחה בתור עם המזהה השמור. after: 0 בונה את כל השיחה מחדש
+    const placeholder: LiveConversation = { id: String(saved.conversationId ?? ''), state: 'queued', lastSeq: 0, credentialExpiresAt: saved.expiresAt };
+    const s = new LiveSession(o, saved.credential, saved.expiresAt, saved.waitSeconds ?? 0, placeholder);
+    const ok = await s.syncAll();
+    if (s.isFinal()) {
+      s.dispose();
+      await removeKey(o.store, o.storageKey);
+      return null;
+    }
+    // רשת לא זמינה: ממשיכים עם מה שידוע, והחיבור מחדש ישלים
+    if (!ok) s.connection = 'reconnecting';
+    s.run();
+    return s;
+  }
+
+  // ---------- מצב ----------
+
+  getSnapshot = (): LiveSnapshot => this.snap;
+
+  isFinal() {
+    return isFinalPhase(this.phase);
+  }
+
+  private build(): LiveSnapshot {
+    return {
+      phase: this.phase,
+      chat: this.chat,
+      conversation: this.chat.conversation,
+      events: this.chat.events,
+      pending: this.chat.pending,
+      agentTyping: this.agentTyping,
+      connection: this.connection,
+      waitSeconds: this.waitSeconds,
+      error: this.error,
+    };
+  }
+
+  private emit() {
+    if (this.disposed) return;
+    this.snap = this.build();
+    try {
+      this.o.onChange?.(this.snap);
+    } catch (e) {
+      console.error('Kavchat: live listener failed', e);
+    }
+  }
+
+  private now() {
+    return this.o.now ? this.o.now() : Date.now();
+  }
+
+  private canRun() {
+    return !this.disposed && !this.paused && !this.isFinal();
+  }
+
+  private setConnection(c: LiveConnection) {
+    if (this.connection === c) return;
+    this.connection = c;
+    this.emit();
+  }
+
+  // ---------- החלת נתונים מהשרת ----------
+
+  /** מחליף את המצב בתוצאה של המכונה הטהורה, ומטפל בתוצאות הצדדיות: מועדים, הקלדה, סיום */
+  private setChat(next: LiveChat) {
+    if (next === this.chat || this.override) return;
+    this.chat = next;
+    this.afterChange();
+  }
+
+  private afterChange() {
+    const c = this.chat.conversation;
+    if (c.credentialExpiresAt) this.expiresAt = c.credentialExpiresAt;
+    if (c.state === 'queued') this.armDeadline(c.queueDeadline ?? undefined);
+    else this.clearTimer('deadline');
+    if (c.state !== 'active') this.agentTyping = null;
+    if (isLiveFinal(c.state) && !this.finished) this.finish();
+    this.emit();
+  }
+
+  /** אובייקט השיחה הוא מקור האמת. closed ו-ticket סופיים: המכונה לא חוזרת מהם */
+  private applyConversation(c: LiveConversation | undefined | null) {
+    this.setChat(liveApplyConversation(this.chat, c));
+  }
+
+  /** כפילות לפי seq מתעלמים, מכניסים לפי הסדר, ולא מחכים ל-seq חסר (liveApplyEvent) */
+  private applyEvent(e: LiveEvent | undefined | null) {
+    const next = liveApplyEvent(this.chat, e);
+    if (next !== this.chat && e?.type === 'message' && e.author?.kind === 'agent') this.agentTyping = null;
+    this.setChat(next);
+  }
+
+  private applySync(d: LiveSync) {
+    this.setChat(liveApplySync(this.chat, d));
+  }
+
+  /** POST /sync עד hasMore=false. false כשנכשל */
+  private async syncAll(): Promise<boolean> {
+    for (let page = 0; page < 50; page++) {
+      if (this.disposed) return false;
+      const r = await liveApi.sync(this.o.api, this.credential, this.lastSeq);
+      if (this.disposed) return false;
+      if (!r.ok) {
+        if (r.status === 401) this.expire();
+        return false;
+      }
+      this.applySync(r.data);
+      if (!r.data.hasMore || !(r.data.events ?? []).length) return true;
+    }
+    return true;
+  }
+
+  // ---------- זרם ----------
+
+  private run() {
+    this.armExpiry();
+    void this.connect();
+  }
+
+  private async connect() {
+    if (!this.canRun() || this.conn || this.polling) return;
+    if (!this.opener || this.now() < this.pollUntil) return this.poll();
+    const gen = this.gen;
+    this.setConnection(this.attempt > 0 ? 'reconnecting' : 'connecting');
+    const t = await liveApi.streamTicket(this.o.api, this.credential);
+    if (gen !== this.gen || !this.canRun() || this.conn) return;
+    if (!t.ok) return this.onStreamFailure(t.status, t.code);
+    const conn: { closed: boolean; handle: StreamHandle | null } = { closed: false, handle: null };
+    this.conn = conn;
+    const alive = () => this.conn === conn && !conn.closed;
+    const parser = new SseParser((m) => alive() && this.onMessage(m));
+    const handle = this.opener(streamUrl(this.o.api, t.data.ticket, this.lastSeq), { 'Accept-Language': this.o.api.getLocale() }, {
+      onChunk: (text) => {
+        if (!alive()) return;
+        this.armSilence();
+        parser.feed(text);
+      },
+      onError: (status, body) => {
+        if (!alive()) return;
+        this.dropStream();
+        // -1: אין זרימה בסביבה הזו. עוברים ל-long-poll לצמיתות
+        if (status === -1) this.opener = null;
+        this.onStreamFailure(status, errorCode(body));
+      },
+      onEnd: () => {
+        if (!alive()) return;
+        // השרת סוגר אחרי שעה: כמו שגיאה, חיבור מחדש עם after
+        this.dropStream();
+        this.scheduleReconnect();
+      },
+    });
+    if (!handle) {
+      if (this.conn === conn) this.conn = null;
+      this.opener = null;
+      return this.poll();
+    }
+    conn.handle = handle;
+    if (conn.closed) handle.close();
+    else this.armSilence();
+  }
+
+  private onMessage(m: SseMessage) {
+    let data: unknown;
+    try {
+      data = JSON.parse(m.data);
+    } catch {
+      return;
+    }
+    const d = data as Record<string, unknown>;
+    switch (m.event) {
+      case 'ready':
+        this.attempt = 0;
+        this.failuresWithoutReady = 0;
+        this.applyConversation(d.conversation as LiveConversation);
+        if (this.canRun()) this.setConnection('live');
+        break;
+      case 'event':
+        this.applyEvent(data as LiveEvent);
+        break;
+      case 'state':
+        this.applyConversation(data as LiveConversation);
+        break;
+      case 'typing': {
+        const on = d.on !== false;
+        const author = (d.author ?? {}) as { name?: string };
+        this.setTyping(on ? author.name || '' : null);
+        break;
+      }
+      case 'bye': {
+        const reason = String(d.reason ?? '');
+        this.dropStream();
+        if (reason === 'replaced') this.end('replaced');
+        else if (reason === 'expired' || reason === 'deleted') this.end('expired');
+        else this.scheduleReconnect();
+        break;
+      }
+      default:
+      // סוגים לא מוכרים: מתעלמים
+    }
+  }
+
+  private setTyping(name: string | null) {
+    this.clearTimer('typing');
+    this.agentTyping = this.phase === 'active' ? name : null;
+    if (this.agentTyping !== null) {
+      this.timers.typing = setTimeout(() => {
+        this.timers.typing = null;
+        this.agentTyping = null;
+        this.emit();
+      }, this.t.typingHideMs);
+    }
+    this.emit();
+  }
+
+  private onStreamFailure(status: number, code: string) {
+    if (status === 401 && code !== 'live_stream_ticket_invalid') return this.expire();
+    if (status === 503 || code === 'live_busy') {
+      this.pollUntil = this.now() + this.t.pollModeMs;
+    } else if (++this.failuresWithoutReady >= 3) {
+      // פרוקסי שחוסם זרמים: long-poll לזמן מה
+      this.failuresWithoutReady = 0;
+      this.pollUntil = this.now() + this.t.pollModeMs;
+    }
+    this.scheduleReconnect();
+  }
+
+  private scheduleReconnect() {
+    if (!this.canRun()) return;
+    this.clearTimer('reconnect');
+    this.setConnection('reconnecting');
+    const gen = this.gen;
+    const delay = backoffDelay(this.attempt++, this.t, this.random);
+    this.timers.reconnect = setTimeout(async () => {
+      this.timers.reconnect = null;
+      if (gen !== this.gen) return;
+      await this.syncAll();
+      if (gen !== this.gen) return;
+      void this.connect();
+    }, delay);
+  }
+
+  private dropStream() {
+    this.clearTimer('silence');
+    const c = this.conn;
+    this.conn = null;
+    if (!c) return;
+    c.closed = true;
+    try {
+      c.handle?.close();
+    } catch {
+      // כבר נסגר
+    }
+  }
+
+  private armSilence() {
+    this.clearTimer('silence');
+    this.timers.silence = setTimeout(() => {
+      this.timers.silence = null;
+      if (!this.conn) return;
+      this.dropStream();
+      this.scheduleReconnect();
+    }, this.t.silenceMs);
+  }
+
+  /** long-poll: כשאין זרם בסביבה, אחרי live_busy, או כשהזרם נכשל שוב ושוב. בלי הקלדה */
+  private async poll() {
+    if (this.polling) return;
+    this.polling = true;
+    const gen = this.gen;
+    this.setConnection('polling');
+    try {
+      while (gen === this.gen && this.canRun()) {
+        if (this.opener && this.now() >= this.pollUntil) break;
+        const started = this.now();
+        const r = await liveApi.sync(this.o.api, this.credential, this.lastSeq, this.t.pollWaitSeconds);
+        if (gen !== this.gen || this.disposed) return;
+        if (!r.ok) {
+          if (r.status === 401) return this.expire();
+          await this.wait(backoffDelay(this.attempt++, this.t, this.random));
+          continue;
+        }
+        this.attempt = 0;
+        this.applySync(r.data);
+        if (r.data.hasMore) continue;
+        const elapsed = this.now() - started;
+        if (elapsed < this.t.pollGapMs) await this.wait(this.t.pollGapMs - elapsed);
+      }
+    } finally {
+      this.polling = false;
+    }
+    if (gen === this.gen && this.canRun()) void this.connect();
+  }
+
+  private pollResolve: (() => void) | null = null;
+
+  private wait(ms: number) {
+    return new Promise<void>((resolve) => {
+      this.clearTimer('poll');
+      this.pollResolve = resolve;
+      this.timers.poll = setTimeout(() => {
+        this.timers.poll = null;
+        this.pollResolve = null;
+        resolve();
+      }, ms);
+    });
+  }
+
+  private armDeadline(iso: string | undefined) {
+    if (!iso || iso === this.armedDeadline) return;
+    const at = Date.parse(iso);
+    if (!Number.isFinite(at)) return;
+    this.armedDeadline = iso;
+    this.checkDeadline(Math.max(0, at - this.now()) + this.t.deadlineGraceMs, 0);
+  }
+
+  /** השרת הופך את השיחה לפנייה בתום ההמתנה. אם העדכון לא הגיע בזרם (או ברקע), הסנכרון מביא אותו */
+  private checkDeadline(delay: number, round: number) {
+    this.clearTimer('deadline');
+    this.timers.deadline = setTimeout(async () => {
+      this.timers.deadline = null;
+      if (this.disposed || this.paused || this.phase !== 'queued') return;
+      await this.syncAll();
+      if (!this.disposed && this.phase === 'queued' && round < 5) this.checkDeadline(this.t.deadlineRetryMs, round + 1);
+    }, delay);
+  }
+
+  private armExpiry() {
+    this.clearTimer('expiry');
+    const at = Date.parse(this.expiresAt);
+    if (!Number.isFinite(at)) return;
+    const ms = at - this.now();
+    if (ms <= 0) return this.expire();
+    this.timers.expiry = setTimeout(() => this.expire(), Math.min(ms, 2 ** 31 - 1));
+  }
+
+  // ---------- סיום ----------
+
+  private expire() {
+    this.end('expired');
+  }
+
+  private end(phase: 'replaced' | 'expired') {
+    if (this.isFinal()) return;
+    this.override = phase;
+    this.finish();
+    this.emit();
+  }
+
+  /** מצב סופי: עוצרים הכל ומוחקים את הקרדנשל מהמכשיר */
+  private finish() {
+    this.finished = true;
+    this.gen++;
+    this.dropStream();
+    for (const k of Object.keys(this.timers) as Array<keyof LiveSession['timers']>) this.clearTimer(k);
+    this.agentTyping = null;
+    this.connection = 'stopped';
+    void removeKey(this.o.store, this.o.storageKey);
+  }
+
+  private clearTimer(k: keyof LiveSession['timers']) {
+    const t = this.timers[k];
+    if (t) clearTimeout(t);
+    this.timers[k] = null;
+    if (k === 'poll' && this.pollResolve) {
+      // מסיימים את ההמתנה מיד, כדי שהלולאה תראה שה-gen השתנה ותשחרר את polling
+      const resolve = this.pollResolve;
+      this.pollResolve = null;
+      resolve();
+    }
+  }
+
+  // ---------- מחזור חיים ----------
+
+  /** מעבר לרקע: סוגרים את הזרם. ההודעות שבדרך ממשיכות לנסות */
+  pause() {
+    if (this.paused || this.disposed || this.isFinal()) return;
+    this.paused = true;
+    this.gen++;
+    this.dropStream();
+    this.clearTimer('reconnect');
+    this.clearTimer('poll');
+    this.clearTimer('typing');
+    this.agentTyping = null;
+    this.connection = 'paused';
+    this.emit();
+  }
+
+  /** חזרה לקדמה: השלמה של מה שהוחמץ ואז זרם חדש */
+  async resume() {
+    if (!this.paused || this.disposed) return;
+    this.paused = false;
+    if (this.isFinal()) return;
+    if (Date.parse(this.expiresAt) <= this.now()) return this.expire();
+    this.attempt = 0;
+    this.pollUntil = 0;
+    const gen = this.gen;
+    this.setConnection('reconnecting');
+    await this.syncAll();
+    if (gen === this.gen && this.canRun()) await this.connect();
+  }
+
+  /** עוצר בלי למחוק את הקרדנשל (למשל כשהאפליקציה נסגרת), כדי שאפשר יהיה לשחזר */
+  dispose() {
+    if (this.disposed) return;
+    this.gen++;
+    this.dropStream();
+    for (const k of Object.keys(this.timers) as Array<keyof LiveSession['timers']>) this.clearTimer(k);
+    this.disposed = true;
+  }
+
+  /** עוצר ומוחק את הקרדנשל (החלפת משתמש) */
+  forget() {
+    this.dispose();
+    void removeKey(this.o.store, this.o.storageKey);
+  }
+
+  // ---------- פקודות ----------
+
+  /** מחזיר קוד שגיאה, או null כשההודעה נוספה לתור השליחה */
+  send(text: string): string | null {
+    const value = String(text ?? '').trim();
+    if (!value) return null;
+    if (value.length > 2000) return 'live_message_too_long';
+    if (this.disposed || !isOpenState(this.phase)) return 'live_conversation_closed';
+    // נוצר פעם אחת, כשהמשתמש שולח, ומשמש לכל ניסיון חוזר של אותה הודעה
+    const clientId = randomId(22);
+    this.error = null;
+    this.chat = liveAddPending(this.chat, clientId, value, new Date(this.now()).toISOString());
+    this.stopTyping();
+    this.emit();
+    void this.deliver(clientId);
+    return null;
+  }
+
+  /** שליחה חוזרת של הודעה שנכשלה, עם אותו clientId */
+  retry(clientId: string) {
+    const p = this.chat.pending.find((x) => x.clientId === clientId);
+    if (!p || p.status !== 'failed' || this.disposed || !isOpenState(this.phase)) return;
+    this.setPending(clientId, 'sending');
+    void this.deliver(clientId);
+  }
+
+  /** null: מסיר את הבועה */
+  private setPending(clientId: string, status: LivePending['status'] | null) {
+    const next = liveSetPending(this.chat, clientId, status);
+    if (next === this.chat) return;
+    this.chat = next;
+    this.emit();
+  }
+
+  private async deliver(clientId: string) {
+    for (let attempt = 0; ; attempt++) {
+      const p = this.chat.pending.find((x) => x.clientId === clientId);
+      if (!p || this.disposed) return;
+      const r = await liveApi.message(this.o.api, this.credential, clientId, p.text);
+      if (this.disposed) return;
+      if (r.ok) {
+        // duplicate: true הוא הצלחה. האירוע המקורי מחליף את הבועה הממתינה
+        this.applyEvent(r.data.event);
+        this.setPending(clientId, null);
+        return;
+      }
+      if (retryable(r) && attempt + 1 < this.t.sendAttempts) {
+        await sleep(backoffDelay(attempt, this.t, this.random));
+        continue;
+      }
+      if (r.code === 'live_message_too_long') {
+        this.error = { code: r.code, message: r.message };
+        this.setPending(clientId, null);
+        this.emit();
+        return;
+      }
+      this.setPending(clientId, 'failed');
+      if (r.status === 401) return this.expire();
+      if (r.code === 'live_conversation_closed') void this.syncAll();
+      return;
+    }
+  }
+
+  /** נקרא בכל שינוי בשדה. on: true לכל היותר כל 3 שניות, on: false כשהשדה מתרוקן. בלי ניסיונות חוזרים */
+  typing(text: string) {
+    if (this.disposed || this.phase !== 'active') return;
+    if (!String(text ?? '').trim()) return this.stopTyping();
+    const now = this.now();
+    if (this.typingOn && now - this.lastTypingAt < this.t.typingThrottleMs) return;
+    this.typingOn = true;
+    this.lastTypingAt = now;
+    void liveApi.typing(this.o.api, this.credential, true);
+  }
+
+  private stopTyping() {
+    if (!this.typingOn) return;
+    this.typingOn = false;
+    this.lastTypingAt = 0;
+    if (this.phase === 'active') void liveApi.typing(this.o.api, this.credential, false);
+  }
+
+  /** "להשאיר הודעה במקום": השיחה הופכת לפנייה */
+  leaveMessage(text?: string): Promise<boolean> {
+    const value = String(text ?? '').trim().slice(0, 2000);
+    const clientId = value ? randomId(22) : undefined;
+    return this.command(() => liveApi.leaveMessage(this.o.api, this.credential, value || undefined, clientId));
+  }
+
+  /** סיום השיחה. בטוח לחזור עליו */
+  endChat(): Promise<boolean> {
+    return this.command(() => liveApi.end(this.o.api, this.credential));
+  }
+
+  private async command(fn: () => Promise<LiveResult<{ conversation: LiveConversation }>>): Promise<boolean> {
+    if (this.disposed || !isOpenState(this.phase)) return false;
+    this.stopTyping();
+    for (let attempt = 0; ; attempt++) {
+      const r = await fn();
+      if (this.disposed) return false;
+      if (r.ok) {
+        this.applyConversation(r.data.conversation);
+        return true;
+      }
+      if (retryable(r) && attempt + 1 < 4) {
+        await sleep(backoffDelay(attempt, this.t, this.random));
+        continue;
+      }
+      if (r.status === 401) {
+        this.expire();
+        return true;
+      }
+      if (r.code === 'live_conversation_closed') await this.syncAll();
+      else {
+        this.error = { code: r.code, message: r.message };
+        this.emit();
+      }
+      return false;
+    }
+  }
+
+  clearError() {
+    if (!this.error) return;
+    this.error = null;
+    this.emit();
+  }
+}
+
+async function removeKey(store: StorageAdapter, key: string) {
+  try {
+    if (store.removeItem) await store.removeItem(key);
+    else await store.setItem(key, '');
+  } catch {
+    // אין גישה לאחסון. הקרדנשל יפוג בכל מקרה אחרי 12 שעות
+  }
+}