@kavchat/react-native 0.0.1 → 0.0.3

package/lib/live/api.d.ts

@@ -0,0 +1,93 @@
+import type { FetchLike } from '../api';
+/**
+ * Client API של צ'אט עם נציג (/v1/client/{publicKey}/live), לפי docs/live-chat-protocol.md.
+ * אפליקציה לא צריכה להתחשב ב-CORS, ולכן הגוף נשלח כ-application/json והשפה ב-Accept-Language.
+ * הקרדנשל (lvc_...) עובר רק בגוף, אף פעם לא בכתובת, ולא נכתב ללוג
+ */
+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 declare const liveUrl: (c: LiveApiConfig, path: string) => string;
+/** האם כדאי לנסות שוב: אין רשת, 5xx או 429. שאר ה-4xx סופיים */
+export declare const retryable: (r: {
+    ok: boolean;
+    status: number;
+}) => boolean;
+export declare const liveApi: {
+    availability: (c: LiveApiConfig, departmentId?: string) => Promise<LiveResult<LiveAvailability>>;
+    request: (c: LiveApiConfig, body: LiveRequestBody) => Promise<LiveResult<LiveAccepted | LiveUnavailable>>;
+    message: (c: LiveApiConfig, credential: string, clientId: string, text: string) => Promise<LiveResult<{
+        event: LiveEvent;
+        duplicate?: boolean;
+    }>>;
+    typing: (c: LiveApiConfig, credential: string, on: boolean) => Promise<LiveResult<{
+        ok: true;
+    }>>;
+    sync: (c: LiveApiConfig, credential: string, after: number, wait?: number) => Promise<LiveResult<LiveSync>>;
+    streamTicket: (c: LiveApiConfig, credential: string) => Promise<LiveResult<{
+        ticket: string;
+        expiresIn: number;
+    }>>;
+    leaveMessage: (c: LiveApiConfig, credential: string, text?: string, clientId?: string) => Promise<LiveResult<{
+        conversation: LiveConversation;
+    }>>;
+    end: (c: LiveApiConfig, credential: string) => Promise<LiveResult<{
+        conversation: LiveConversation;
+    }>>;
+};
+/** כתובת הזרם. מכילה כרטיס חד-פעמי: לא לכתוב אותה ללוג */
+export declare const streamUrl: (c: LiveApiConfig, ticket: string, after: number) => string;

package/lib/live/api.js

@@ -0,0 +1,41 @@
+export const liveUrl = (c, path) => `${c.apiBase.replace(/\/+$/, '')}/v1/client/${encodeURIComponent(c.publicKey)}/live/${path}`;
+const doFetch = (c) => c.fetch ?? globalThis.fetch;
+/** האם כדאי לנסות שוב: אין רשת, 5xx או 429. שאר ה-4xx סופיים */
+export const retryable = (r) => !r.ok && (r.status === 0 || r.status === 429 || r.status >= 500);
+async function call(c, method, path, body, auth = false) {
+    const headers = { '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;
+    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));
+    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, departmentId) => call(c, 'GET', departmentId ? `availability?departmentId=${encodeURIComponent(departmentId)}` : 'availability', undefined, true),
+    request: (c, body) => call(c, 'POST', 'requests', body, true),
+    message: (c, credential, clientId, text) => call(c, 'POST', 'messages', { credential, clientId, text }),
+    typing: (c, credential, on) => call(c, 'POST', 'typing', { credential, on }),
+    sync: (c, credential, after, wait = 0) => call(c, 'POST', 'sync', wait > 0 ? { credential, after, wait } : { credential, after }),
+    streamTicket: (c, credential) => call(c, 'POST', 'stream-ticket', { credential }),
+    leaveMessage: (c, credential, text, clientId) => call(c, 'POST', 'leave-message', text ? { credential, text, clientId } : { credential }),
+    end: (c, credential) => call(c, 'POST', 'end', { credential }),
+};
+/** כתובת הזרם. מכילה כרטיס חד-פעמי: לא לכתוב אותה ללוג */
+export const streamUrl = (c, ticket, after) => `${liveUrl(c, 'stream')}?ticket=${encodeURIComponent(ticket)}&after=${Math.max(0, Math.floor(after))}`;

package/lib/live/session.d.ts

@@ -0,0 +1,183 @@
+import { StorageAdapter } from '../storage';
+import { LiveAccepted, LiveApiConfig, LiveConversation, LiveEvent, LiveRequestBody, LiveResult, LiveUnavailable } from './api';
+import { StreamOpener } from './sse';
+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 declare const DEFAULT_TIMING: LiveTiming;
+/** מה נשמר במכשיר כדי לחזור לשיחה אחרי הפעלה מחדש. הקרדנשל רק כאן ובזיכרון */
+export interface StoredLive {
+    credential: string;
+    expiresAt: string;
+    conversationId: string;
+    user: string;
+    waitSeconds?: number;
+}
+export declare const liveKey: (publicKey: string) => string;
+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;
+}
+export declare const isFinalPhase: (p: LivePhase) => boolean;
+export declare function backoffDelay(attempt: number, t: Pick<LiveTiming, 'backoffMs' | 'jitter'>, random?: () => number): number;
+/** בקשת נציג עם ניסיונות חוזרים על רשת, 5xx ו-429. ה-requestId זהה בכל הניסיונות */
+export declare function requestHandoff(api: LiveApiConfig, body: LiveRequestBody, timing?: Partial<LiveTiming>, random?: () => number, attempts?: number): Promise<LiveResult<LiveAccepted | LiveUnavailable>>;
+export declare class LiveSession {
+    private o;
+    private t;
+    private random;
+    private opener;
+    private credential;
+    private expiresAt;
+    /** המצב עצמו (שיחה, אירועים, הודעות שבדרך) מנוהל על ידי המכונה הטהורה ב-@kavchat/core */
+    private chat;
+    /** מצבים סופיים שלא באים מהשרת: הקרדנשל הוחלף (bye replaced) או פג */
+    private override;
+    private finished;
+    private agentTyping;
+    private connection;
+    private waitSeconds;
+    private error;
+    private snap;
+    /** עולה בכל עצירה (רקע, סיום, dispose), כדי שלולאות ישנות ייעצרו אחרי await */
+    private gen;
+    private conn;
+    private attempt;
+    private failuresWithoutReady;
+    private pollUntil;
+    private polling;
+    private paused;
+    private disposed;
+    private typingOn;
+    private lastTypingAt;
+    private armedDeadline;
+    private timers;
+    private get phase();
+    private get lastSeq();
+    private constructor();
+    /** אחרי accepted: שומר את הקרדנשל, מציג המתנה ופותח את הזרם */
+    static start(o: LiveSessionOptions, accepted: LiveAccepted): Promise<LiveSession>;
+    /**
+     * אחרי הפעלה מחדש: אם יש קרדנשל בתוקף של אותו משתמש, בונה את השיחה מ-sync after 0 וממשיך.
+     * שיחה שהסתיימה בינתיים או קרדנשל שפג: מוחק ומחזיר null
+     */
+    static restore(o: LiveSessionOptions): Promise<LiveSession | null>;
+    getSnapshot: () => LiveSnapshot;
+    isFinal(): boolean;
+    private build;
+    private emit;
+    private now;
+    private canRun;
+    private setConnection;
+    /** מחליף את המצב בתוצאה של המכונה הטהורה, ומטפל בתוצאות הצדדיות: מועדים, הקלדה, סיום */
+    private setChat;
+    private afterChange;
+    /** אובייקט השיחה הוא מקור האמת. closed ו-ticket סופיים: המכונה לא חוזרת מהם */
+    private applyConversation;
+    /** כפילות לפי seq מתעלמים, מכניסים לפי הסדר, ולא מחכים ל-seq חסר (liveApplyEvent) */
+    private applyEvent;
+    private applySync;
+    /** POST /sync עד hasMore=false. false כשנכשל */
+    private syncAll;
+    private run;
+    private connect;
+    private onMessage;
+    private setTyping;
+    private onStreamFailure;
+    private scheduleReconnect;
+    private dropStream;
+    private armSilence;
+    /** long-poll: כשאין זרם בסביבה, אחרי live_busy, או כשהזרם נכשל שוב ושוב. בלי הקלדה */
+    private poll;
+    private pollResolve;
+    private wait;
+    private armDeadline;
+    /** השרת הופך את השיחה לפנייה בתום ההמתנה. אם העדכון לא הגיע בזרם (או ברקע), הסנכרון מביא אותו */
+    private checkDeadline;
+    private armExpiry;
+    private expire;
+    private end;
+    /** מצב סופי: עוצרים הכל ומוחקים את הקרדנשל מהמכשיר */
+    private finish;
+    private clearTimer;
+    /** מעבר לרקע: סוגרים את הזרם. ההודעות שבדרך ממשיכות לנסות */
+    pause(): void;
+    /** חזרה לקדמה: השלמה של מה שהוחמץ ואז זרם חדש */
+    resume(): Promise<void>;
+    /** עוצר בלי למחוק את הקרדנשל (למשל כשהאפליקציה נסגרת), כדי שאפשר יהיה לשחזר */
+    dispose(): void;
+    /** עוצר ומוחק את הקרדנשל (החלפת משתמש) */
+    forget(): void;
+    /** מחזיר קוד שגיאה, או null כשההודעה נוספה לתור השליחה */
+    send(text: string): string | null;
+    /** שליחה חוזרת של הודעה שנכשלה, עם אותו clientId */
+    retry(clientId: string): void;
+    /** null: מסיר את הבועה */
+    private setPending;
+    private deliver;
+    /** נקרא בכל שינוי בשדה. on: true לכל היותר כל 3 שניות, on: false כשהשדה מתרוקן. בלי ניסיונות חוזרים */
+    typing(text: string): void;
+    private stopTyping;
+    /** "להשאיר הודעה במקום": השיחה הופכת לפנייה */
+    leaveMessage(text?: string): Promise<boolean>;
+    /** סיום השיחה. בטוח לחזור עליו */
+    endChat(): Promise<boolean>;
+    private command;
+    clearError(): void;
+}