@kavchat/react-native 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxsave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# @kavchat/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Kavchat for React Native: the scripted support chat (no language model) as a provider, a chat screen and an optional floating launcher.
+Answers come from the scripts you publish in the Kavchat dashboard, run on the device by the shared engine `@kavchat/core`.
+
+## Install
+
+The package is pure JS (no native code of its own, no icon library), so it works the same in bare React Native and in Expo.
+Peer dependencies: `react` 18+, `react-native` 0.72+.
+
+### React Native CLI (bare)
+
+```sh
+yarn add @kavchat/react-native @react-native-async-storage/async-storage
+cd ios && pod install
+```
+
+AsyncStorage is a native module: `pod install` links it on iOS, and autolinking handles Android. Minimum `react-native` 0.72.
+
+### Expo
+
+```sh
+yarn add @kavchat/react-native
+npx expo install @react-native-async-storage/async-storage
+```
+
+Works in Expo Go and in development builds.
+
+### Without AsyncStorage
+
+AsyncStorage keeps the published release and the conversation between app launches. It is optional: without it the SDK keeps
+everything in memory (the bot still works, it just downloads the release again on every launch).
+To use another store (for example MMKV), pass the `storage` prop with any `{ getItem, setItem, removeItem? }`, sync or async:
+
+```tsx
+import { MMKV } from 'react-native-mmkv';
+const mmkv = new MMKV();
+const storage = {
+  getItem: (k: string) => mmkv.getString(k) ?? null,
+  setItem: (k: string, v: string) => mmkv.set(k, v),
+  removeItem: (k: string) => mmkv.delete(k),
+};
+
+<KavchatProvider publicKey="pk_live_..." storage={storage}>
+```
+
+## Usage
+
+```tsx
+import { KavchatProvider, KavchatChat, KavchatLauncher, useKavchat } from '@kavchat/react-native';
+
+export default function App() {
+  return (
+    <KavchatProvider publicKey="pk_live_..." onScreen={(screen, id) => navigation.navigate(screen, { id })}>
+      <Navigation />
+      {/* floating button, bottom end corner; opens the chat in a modal */}
+      <KavchatLauncher />
+    </KavchatProvider>
+  );
+}
+
+// or as a screen in your own navigator
+function SupportScreen() {
+  return <KavchatChat />;
+}
+
+// or your own button
+function HelpButton() {
+  const { available, open } = useKavchat();
+  if (!available) return null; // bot is off, limited to testers, or over quota
+  return <Button title="Help" onPress={open} />;
+}
+```
+
+`KavchatProvider` props:
+
+| Prop | |
+|---|---|
+| `publicKey` | `pk_live_...` from the dashboard. Safe to ship in the app. |
+| `apiBase` | Default `https://api.kavchat.com`. |
+| `locale` | UI language (`he`, `en`, `ar`, `ru`, `es`, `fr`, `de`, `pt`, `it`, `tr`). Default: the device language, else the bot language. The scripts are matched in the bot language either way. |
+| `userToken`, `userName` | Identity, see below. |
+| `onScreen(screen, targetId?)` | Called for buttons of type "screen" in a script. Without it those buttons do nothing. |
+| `screens` | The app screens those buttons can open, `[{ id, label, needsTarget? }]`. See Screens. |
+| `onEvent(event)` | `ready`, `unavailable`, `effect`, `ticket`. |
+| `storage` | Any `{ getItem, setItem, removeItem? }` (sync or async). Default AsyncStorage, else memory. |
+| `theme` | Override of the colors (see Theming). |
+
+`useKavchat()` returns `{ status, available, offline, locale, isOpen, open, close, toggle, setUser, startNewConversation, openContactForm, controller }`.
+
+`KavchatChat` props: `onClose?` (shows a close button), `hideHeader?`, `style?`. `KavchatLauncher` props: `style?` (position), `onPress?` (use your own screen instead of the built-in modal).
+
+## Identity token
+
+Without a token the user is a guest: the contact form asks for an email or a phone.
+To identify a signed-in user, sign a short-lived JWT on **your server** with the workspace secret key (`sk_live_...`, never in the app)
+and pass it in:
+
+```tsx
+<KavchatProvider publicKey="pk_live_..." userToken={session?.kavchatToken} userName={session?.firstName}>
+```
+
+Changing `userToken` (sign-in, sign-out) reloads the release, because the "testers" audience depends on who the user is.
+You can also call `useKavchat().setUser({ token, name })`. The token is sent only as `Authorization: Bearer`; it is never written to storage
+(a saved conversation is tied to a fingerprint of it, so another account on the same device starts fresh).
+
+## Links, screens and the contact form
+
+- Script buttons of type `link` open only `https:` and `tel:` URLs, through `Linking.openURL`. Other schemes are ignored.
+- Buttons of type `screen` call `onScreen`. The chat stays where it was.
+- "Talk to our team" opens the contact form with the conversation attached; the ticket number is shown after sending.
+
+## Screens
+
+Declare the screens of your app once. The SDK registers them with Kavchat, and the script editor in the dashboard then offers
+them in a dropdown (and warns about a button that points to an unknown screen) instead of a free text field:
+
+```tsx
+const screens = [
+  { id: 'orders', label: 'My orders' },
+  { id: 'product', label: 'Product page', needsTarget: true }, // the button also carries a product id
+  { id: 'settings', label: 'Settings' },
+];
+
+<KavchatProvider
+  publicKey="pk_live_..."
+  screens={screens}
+  onScreen={(screen, targetId) => navigation.navigate(screen, targetId ? { id: targetId } : undefined)}
+>
+```
+
+- `onScreen` receives the screen `id` and, for screens with `needsTarget`, the `targetId` the admin set on the button.
+- `id`: letters, digits, `_`, `.`, `-`, up to 40 characters. `label`: 1 to 60 characters. Up to 100 screens. Invalid entries and
+  duplicate ids are dropped (with a warning in development builds only).
+- The list is sent after the release loads, only when it changed or once a week, in the background. A failure is retried on the
+  next launch; it never affects the chat or the user.
+- Changing the `screens` prop later (or `useKavchat().controller.registerScreens(list)`) registers the new list.
+
+## Theming and RTL
+
+Colors come from the bot settings in the dashboard (`primaryColor`); the text color on it is picked by WCAG contrast.
+Override any of them: `theme={{ primary: '#0f766e', background: '#ffffff', botBubble, userBubble, text, muted, accent, onPrimary, error }}`.
+
+The SDK does **not** change the layout direction of your app. It follows `I18nManager.isRTL` (start/end styles), and text
+is aligned by its own language, so Hebrew and Arabic read correctly in an LTR app too.
+If your app is Hebrew or Arabic, set RTL once in your app as usual (`I18nManager.forceRTL(true)` + restart).
+
+The free plan shows "Powered by Kavchat" under the chat (linking to kavchat.com); paid plans hide it automatically.
+
+## AI answers (Premium)
+
+Nothing to configure in the app. When the workspace owner turns on AI answers in the dashboard (Premium, with the
+workspace's own AI provider key), the release carries `settings.aiAnswers: true`. Then a typed question that no script
+matches is sent to `POST /v1/client/{publicKey}/ai/answer` (at most 300 characters, 20 second timeout) while a typing
+indicator shows. The answer appears as plain text with a small "AI answer" label in the UI language, followed by a
+button to the script the AI suggests (if any), "Talk to our team" and the main menu.
+
+If there is no answer, the request fails, times out or is rate limited (429), the chat shows the regular "no match"
+message. The unmatched question is reported to the dashboard exactly as before, and AI answers are saved with the
+conversation like any other bot message.
+
+## Behavior
+
+- The published release is cached with its ETag (`If-None-Match`, 304). Offline, the cached release is shown with a banner.
+- The conversation is saved on the device and restored for 24 hours on the same release and user.
+- The conversation path is reported 2 seconds after the last action and when the app goes to the background.
+- Requests send no custom headers (only `Authorization`, `Content-Type`, `If-None-Match`).
+
+## Development
+
+Logic (`src/api.ts`, `src/storage.ts`, `src/screens.ts`, `src/controller.ts`, `src/text.ts`, `src/theme.ts`) is plain TypeScript without React Native and is
+tested with vitest. `@kavchat/core` is not on npm yet, so `vitest.config.mts` aliases it to `../core/src`, and the tests run with the vitest
+already installed at the repo root:
+
+```sh
+cd react-native && ../node_modules/.bin/vitest run
+```
+
+Type checking needs `react-native` and `@types/react`, which are not installed in the monorepo. Install them in a temporary folder and
+point a tsconfig at it (`paths` for `react`, `react-native` to `types_generated/index.d.ts`, and `@kavchat/core` to `../core/src/index.ts`).
+`legacy/` holds the original ACB screen and engine, kept for reference only; it is not part of the package.

package/lib/api.d.ts

@@ -0,0 +1,87 @@
+import type { ClientRelease, TranscriptEntry } from '@kavchat/core';
+/**
+ * קריאות ל-Client API, כמו בווידג'ט לאתר
+ * כלל CORS: בלי כותרות מותאמות (Cache-Control, Pragma וכו'). רק Authorization, Content-Type
+ * ו-If-None-Match, שהשרת מתיר. מניעת מטמון נעשית עם cache: 'no-store'
+ */
+export type FetchLike = (url: string, init?: Record<string, unknown>) => Promise<{
+    status: number;
+    ok: boolean;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+}>;
+export interface ApiConfig {
+    apiBase: string;
+    publicKey: string;
+    getToken: () => string | undefined;
+    /** להחלפה בבדיקות. ברירת מחדל: fetch הגלובלי של React Native */
+    fetch?: FetchLike;
+}
+export type DisabledRelease = {
+    enabled: false;
+    reason?: string;
+};
+export type AnyRelease = ClientRelease | DisabledRelease;
+export type EnabledRelease = Extract<ClientRelease, {
+    enabled: true;
+}>;
+export type ReleaseResult = {
+    kind: 'ok';
+    release: AnyRelease;
+    etag: string;
+} | {
+    kind: 'not-modified';
+}
+/** מפתח שגוי או חסום: לא מציגים את הבוט */
+ | {
+    kind: 'denied';
+    status: number;
+}
+/** אין רשת או שהשרת נפל: משתמשים בעותק השמור */
+ | {
+    kind: 'offline';
+};
+export interface TicketInput {
+    message: string;
+    name?: string;
+    email?: string;
+    phone?: string;
+    topicId?: string;
+    scriptId?: string;
+    sessionId?: string;
+    transcript?: TranscriptEntry[];
+}
+export type TicketResult = {
+    ok: true;
+    id: string;
+    number: number;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export declare function fetchRelease(c: ApiConfig, etag?: string): Promise<ReleaseResult>;
+export interface AiAnswer {
+    answer: string;
+    scriptId: string | null;
+}
+export declare const AI_TIMEOUT_MS = 20000;
+/**
+ * תשובת AI לשאלה שאין לה תסריט (פרימיום). כל כישלון, 429, זמן קצוב או answer: null מחזירים null,
+ * והצ'אט מציג את הודעת "לא נמצא" הרגילה
+ */
+export declare function postAiAnswer(c: ApiConfig, sessionId: string, question: string, timeoutMs?: number): Promise<AiAnswer | null>;
+export declare function postEvents(c: ApiConfig, payload: unknown): Promise<boolean>;
+export declare function postTicket(c: ApiConfig, input: TicketInput): Promise<TicketResult>;
+export interface ScreensPayload {
+    platform: 'react-native';
+    screens: {
+        id: string;
+        label: string;
+        needsTarget: boolean;
+    }[];
+}
+/** רישום המסכים. הצלחה רק ב-200 עם success, כדי לא לשמור טביעה על תשובה חלקית */
+export declare function postScreens(c: ApiConfig, payload: ScreensPayload): Promise<boolean>;

package/lib/api.js

@@ -0,0 +1,112 @@
+const endpoint = (c, path) => `${c.apiBase.replace(/\/+$/, '')}/v1/client/${encodeURIComponent(c.publicKey)}/${path}`;
+function headers(c, extra = {}) {
+    const token = c.getToken();
+    return token ? { ...extra, Authorization: `Bearer ${token}` } : extra;
+}
+const doFetch = (c) => c.fetch ?? globalThis.fetch;
+export async function fetchRelease(c, etag) {
+    let res;
+    try {
+        res = await doFetch(c)(endpoint(c, 'release'), {
+            method: 'GET',
+            cache: 'no-store',
+            credentials: 'omit',
+            headers: headers(c, etag ? { 'If-None-Match': etag } : {}),
+        });
+    }
+    catch {
+        return { kind: 'offline' };
+    }
+    if (res.status === 304)
+        return { kind: 'not-modified' };
+    if (res.status >= 500 || res.status === 429)
+        return { kind: 'offline' };
+    if (!res.ok)
+        return { kind: 'denied', status: res.status };
+    const body = (await res.json().catch(() => null));
+    if (!body || body.success !== true || !body.data || typeof body.data.enabled !== 'boolean')
+        return { kind: 'offline' };
+    return { kind: 'ok', release: body.data, etag: res.headers.get('ETag') || '' };
+}
+function postJson(c, path, body, signal) {
+    return doFetch(c)(endpoint(c, path), {
+        method: 'POST',
+        cache: 'no-store',
+        credentials: 'omit',
+        headers: headers(c, { 'Content-Type': 'application/json' }),
+        body: JSON.stringify(body),
+        ...(signal ? { signal } : {}),
+    });
+}
+export const AI_TIMEOUT_MS = 20000;
+/**
+ * תשובת AI לשאלה שאין לה תסריט (פרימיום). כל כישלון, 429, זמן קצוב או answer: null מחזירים null,
+ * והצ'אט מציג את הודעת "לא נמצא" הרגילה
+ */
+export async function postAiAnswer(c, sessionId, question, timeoutMs = AI_TIMEOUT_MS) {
+    const ctrl = typeof AbortController === 'function' ? new AbortController() : null;
+    let timer = null;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            ctrl?.abort();
+            resolve(null);
+        }, timeoutMs);
+    });
+    const request = (async () => {
+        try {
+            const res = await postJson(c, 'ai/answer', { sessionId, question }, ctrl?.signal);
+            if (!res.ok)
+                return null;
+            const body = (await res.json().catch(() => null));
+            const answer = body && body.success === true && body.data && typeof body.data.answer === 'string' ? body.data.answer.trim() : '';
+            if (!answer)
+                return null;
+            const scriptId = typeof body.data.scriptId === 'string' && body.data.scriptId ? body.data.scriptId : null;
+            return { answer, scriptId };
+        }
+        catch {
+            return null;
+        }
+    })();
+    try {
+        return await Promise.race([request, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+export async function postEvents(c, payload) {
+    try {
+        const res = await postJson(c, 'events', payload);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function postTicket(c, input) {
+    try {
+        const res = await postJson(c, 'tickets', input);
+        const body = (await res.json().catch(() => null));
+        if (res.ok && body && body.success && body.data)
+            return { ok: true, id: String(body.data.id), number: Number(body.data.number) };
+        return { ok: false, code: String(body?.code || `http_${res.status}`), message: String(body?.message || '') };
+    }
+    catch {
+        return { ok: false, code: 'network', message: '' };
+    }
+}
+/** רישום המסכים. הצלחה רק ב-200 עם success, כדי לא לשמור טביעה על תשובה חלקית */
+export async function postScreens(c, payload) {
+    try {
+        const res = await postJson(c, 'screens', payload);
+        if (res.status !== 200)
+            return false;
+        const body = (await res.json().catch(() => null));
+        return !!body && body.success === true;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/controller.d.ts

@@ -0,0 +1,147 @@
+import type { BotChip, BotEffect, BotState, UiTexts } from '@kavchat/core';
+import { EnabledRelease, FetchLike } from './api';
+import { KavchatScreen } from './screens';
+import { StorageAdapter } from './storage';
+/**
+ * הבקר: טעינת הגרסה עם ETag ומטמון, שמירת השיחה, דיווח לשרת ופניות
+ * קוד TypeScript רגיל בלי React Native, כדי שאפשר יהיה לבדוק אותו ב-Node.
+ * לוגיקת ההתאמה ומכונת המצבים נמצאות ב-@kavchat/core ולא כאן
+ */
+export declare const DEFAULT_API = "https://api.kavchat.com";
+export declare const BRANDING_URL = "https://kavchat.com";
+export type ContactEffect = Extract<BotEffect, {
+    type: 'contact';
+}>;
+export type KavchatStatus = 'loading' | 'ready' | 'unavailable';
+export type KavchatView = 'chat' | 'form' | 'sent';
+export type KavchatEvent = {
+    type: 'ready';
+    version: number;
+    offline: boolean;
+} | {
+    type: 'unavailable';
+    reason?: string;
+} | {
+    type: 'effect';
+    effect: BotEffect;
+} | {
+    type: 'ticket';
+    id: string;
+    number: number;
+};
+export interface KavchatSnapshot {
+    status: KavchatStatus;
+    release: EnabledRelease | null;
+    /** הוצגה גרסה שמורה כי אין רשת */
+    offline: boolean;
+    /** שפת הממשק (הטקסטים הקבועים), לא שפת התסריט */
+    locale: string;
+    rtl: boolean;
+    texts: UiTexts;
+    conversation: BotState | null;
+    /** מחכים לתשובת AI: מציגים סימן הקלדה ולא מקבלים קלט */
+    typing: boolean;
+    view: KavchatView;
+    contact: ContactEffect | null;
+    ticketNumber: number | null;
+    /** למה הבוט לא זמין, למשל quota */
+    reason?: string;
+    identified: boolean;
+    userName?: string;
+}
+export interface ControllerOptions {
+    publicKey: string;
+    apiBase?: string;
+    locale?: string;
+    userToken?: string;
+    userName?: string;
+    storage?: StorageAdapter;
+    fetch?: FetchLike;
+    /** שפת המכשיר, כשלא נקבעה locale */
+    deviceLocale?: string;
+    /** כפתור מסוג screen בתסריט. בלי callback הכפתור לא עושה דבר */
+    onScreen?: (screen: string, targetId?: string) => void;
+    /** פתיחת קישור https או tel. ב-React Native זה Linking.openURL */
+    onLink?: (url: string) => void;
+    onEvent?: (event: KavchatEvent) => void;
+    /** מסכי האפליקציה שכפתור screen יכול לפתוח. נרשמים בשרת כדי שהעורך יציע אותם ברשימה */
+    screens?: readonly KavchatScreen[];
+    reportDelayMs?: number;
+    sessionMaxAgeMs?: number;
+    now?: () => number;
+}
+export interface ContactFields {
+    name?: string;
+    email?: string;
+    phone?: string;
+    topicId?: string;
+    message: string;
+}
+export declare class KavchatController {
+    private opts;
+    private api;
+    private store;
+    private snap;
+    private listeners;
+    private session;
+    private loadSeq;
+    private reportTimer;
+    private dirty;
+    private disposed;
+    private screens;
+    /** הגרסה כבר נטענה פעם אחת מהשרת, ולכן אפשר לרשום מסכים */
+    private releaseFetched;
+    /** הטביעה שכבר נוסתה בהפעלה הזו, בהצלחה או בכישלון. אחרי כישלון מנסים רק בהפעלה הבאה */
+    private screensTried;
+    /** מתממש כשהטעינה האחרונה הסתיימה */
+    ready: Promise<void>;
+    /** מתממש כשניסיון רישום המסכים האחרון הסתיים. בשביל בדיקות */
+    screensSync: Promise<void>;
+    constructor(options: ControllerOptions);
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => KavchatSnapshot;
+    private update;
+    /** callbacks שמשתנים בכל רינדור (onScreen וכו') מתעדכנים בלי לבנות בקר חדש */
+    setCallbacks(cb: Pick<ControllerOptions, 'onScreen' | 'onLink' | 'onEvent'>): void;
+    load(): Promise<void>;
+    private doLoad;
+    private apply;
+    private restoreSession;
+    /** החלפת משתמש (התחברות או התנתקות). הגרסה נטענת מחדש, כי הקהל testers תלוי בזהות */
+    setUser(user: {
+        token?: string | null;
+        name?: string | null;
+    } | null): Promise<void>;
+    /** הצהרה או עדכון של המסכים אחרי היצירה. נשלח רק אם הרשימה השתנתה */
+    registerScreens(screens: readonly KavchatScreen[] | null | undefined): void;
+    /** לא מחכים לזה בטעינה: רישום המסכים לא אמור לעכב או להפיל את הבוט */
+    private syncScreens;
+    setLocale(locale: string | undefined): void;
+    /** מתחיל שיחה אם עוד אין. קוראים לזה כשהצ'אט נפתח */
+    ensureConversation(): void;
+    startFresh(): void;
+    pressChip(chip: BotChip): void;
+    /** מתממש כשהתשובה הוצגה. עם תשובות AI זה אחרי הקריאה לשרת */
+    sendText(text: string): Promise<void>;
+    private askAi;
+    /**
+     * התסריט נבדק בשפת הבוט, והטקסטים הקבועים של הצ'אט מוצגים בשפת הממשק.
+     * ההגדרה של המנוע גלובלית, ולכן קובעים אותה לפני כל קריאה
+     */
+    private run;
+    private setConversation;
+    private afterAction;
+    private handleEffect;
+    /** פתיחת הטופס מכפתור מחוץ לתסריט */
+    openContactForm(prefill?: string): void;
+    backToChat(): void;
+    /** שולח פנייה. מחזיר הודעת שגיאה בשפת הממשק, או null אם נשלחה */
+    submitTicket(fields: ContactFields): Promise<string | null>;
+    private scheduleReport;
+    /** שולח את המסלול עכשיו. קוראים לזה גם כשהאפליקציה עוברת לרקע */
+    flush(): Promise<boolean>;
+    dispose(): void;
+    private now;
+    private emit;
+    private safeCall;
+}