@experiaapp/webchat-react-native 2.0.1

package/README.md

@@ -0,0 +1,254 @@
+# @experiaapp/webchat-react-native
+
+A drop-in **React Native webchat SDK** — real-time chat, media attachments (images, documents, voice notes), and 1:1 video calls — that you embed in your app with a single component. Theming, language (English/Arabic), and behavior are driven by your channel configuration.
+
+- 💬 Real-time messaging (text, quick replies, message status, unread tracking)
+- 📎 Attachments — photos, PDF documents, and recorded voice notes
+- 🎥 In-app video calls (optional)
+- 🎨 Server-driven theming + a customizable launcher
+- 🌍 English / Arabic with full RTL
+- ⚙️ Works in **Expo** and **bare React Native**
+
+---
+
+## Requirements
+
+- React Native **>= 0.74**, React **>= 18**
+- An Expo-managed / dev-client app, **or** a bare RN app with Expo Modules (see [Bare React Native](#bare-react-native))
+- A **channel** and connection details from your Experia account
+
+---
+
+## Installation
+
+```bash
+# the SDK
+npm install @experiaapp/webchat-react-native
+
+# required peers
+npx expo install \
+  react-native-safe-area-context \
+  react-native-localize \
+  @react-native-async-storage/async-storage
+```
+
+### Optional peers (each enables a feature when installed)
+
+Install only what you need — the SDK auto-detects them and degrades gracefully when absent:
+
+| Feature | Install |
+| --- | --- |
+| Photo / document attachments | `npx expo install expo-image-picker expo-document-picker expo-file-system` |
+| Voice-note recording & playback | `npx expo install expo-audio` |
+| Crisp vector icons | `npx expo install react-native-svg` |
+| Connectivity-aware reconnect | `npx expo install @react-native-community/netinfo` |
+| Video calls | `npx expo install react-native-webrtc react-native-incall-manager` |
+
+### Expo config plugin
+
+Add the plugin to your `app.json` / `app.config.js` so the required iOS/Android permissions (camera, microphone, photo library) are injected at build time:
+
+```jsonc
+{
+  "expo": {
+    "plugins": [
+      "@experiaapp/webchat-react-native",
+      "@config-plugins/react-native-webrtc"   // only if you use video calls
+    ]
+  }
+}
+```
+
+Then create a development build (`eas build`, or `expo prebuild && expo run:ios|run:android`) — the chat, media, and video features rely on native modules and **won't work in Expo Go**.
+
+### Bare React Native
+
+The optional Expo peers above need the Expo Modules runtime. In a bare app, run once:
+
+```bash
+npx install-expo-modules@latest
+```
+
+Then `cd ios && pod install` and rebuild.
+
+---
+
+## Quick start
+
+```tsx
+import React from "react";
+import { SafeAreaProvider } from "react-native-safe-area-context";
+import { WebChat } from "@experiaapp/webchat-react-native";
+
+const CONFIG = {
+  channelId: "YOUR_CHANNEL_ID",
+  connectionUrl: "YOUR_SOCKET_HOST",
+  configUrl: "YOUR_CONFIG_HOST",
+  language: "en", // "en" | "ar"
+};
+
+export default function App() {
+  return (
+    <SafeAreaProvider>
+      <WebChat config={CONFIG} />
+    </SafeAreaProvider>
+  );
+}
+```
+
+That's the whole integration: a floating launcher button appears, and tapping it opens the chat. **Branding, title, avatar, and theme come from your channel configuration** (fetched via `configUrl`), so you usually only provide the connection details above.
+
+> `channelId`, `connectionUrl`, and `configUrl` identify and connect your channel — you receive these with your Experia account.
+
+---
+
+## Configuration
+
+The `config` prop carries your **connection details**. Everything else — video calls, attachments, the pre-chat form, branding, title, avatar, and colors — is configured in your **Experia channel** and fetched at runtime via `configUrl`. In most apps you only pass the connection details (plus, optionally, the language):
+
+```tsx
+<WebChat
+  config={{
+    channelId: "YOUR_CHANNEL_ID",
+    connectionUrl: "YOUR_SOCKET_HOST",
+    configUrl: "YOUR_CONFIG_HOST",
+    language: "en", // "en" | "ar" — drives RTL (optional)
+  }}
+/>
+```
+
+### Managed in your Experia channel (no app changes)
+
+Controlled from your channel configuration and applied automatically — you don't set these in code:
+
+- **Features:** video calls, image / document / voice attachments, emoji picker, typing indicator, "powered by" badge
+- **Launcher & chrome:** default launcher visibility, close button, online/offline status, connecting text
+- **Branding:** theme & colors, header title/subtitle, agent avatar, launcher image
+- **Pre-chat form:** enabled, fields (text / email / phone / dropdown), labels, headline, submit label
+- **Behavior:** history-persistence window, welcome message
+
+### Advanced — overriding the channel config
+
+Precedence is **prop → channel → default**, so you *can* override any setting per build by passing it on `config`. This is an escape hatch, not the usual path — e.g. force a pre-chat form or turn video off regardless of the channel:
+
+```tsx
+<WebChat
+  config={{
+    channelId: "YOUR_CHANNEL_ID",
+    connectionUrl: "YOUR_SOCKET_HOST",
+    configUrl: "YOUR_CONFIG_HOST",
+    makeVideoCall: false, // override the channel
+    prechatForm: {
+      enabled: true,
+      fields: [{ key: "name", type: "text", label: { en: "Name", ar: "الاسم" }, required: true }],
+    },
+  }}
+/>
+```
+
+### Host-side props
+
+These live on the component, not the channel config:
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `config` | object | Connection details (+ optional overrides). **Required.** |
+| `open` | `boolean` | Open the surface on mount. |
+| `title` | `string` | Override the channel's header title. |
+| `renderLauncher` | `({ open }) => ReactNode` | Render your own launcher (see below). |
+| `prechatValues` | `Record<string, string>` | Pre-fill the greeting with known user data. |
+| `disabledInput` | `boolean` | Lock the composer. |
+| `secureScreen` | `boolean` | Block screen capture while the chat is open (best-effort). |
+
+Callbacks: `onOpen`, `onClose`, `onMessageReceived(message)`, `onConnected`, `onDisconnected`, `onError(error)`, `onUnreadChange(count)`.
+
+---
+
+## Controlling the chat (imperative API)
+
+Attach a `ref` to open/close the chat or manage the session from anywhere in your app:
+
+```tsx
+import { useRef } from "react";
+import { WebChat, type WebChatHandle } from "@experiaapp/webchat-react-native";
+
+const chat = useRef<WebChatHandle>(null);
+
+<WebChat ref={chat} config={CONFIG} />;
+
+// elsewhere:
+chat.current?.open();
+chat.current?.close();
+chat.current?.sendMessage("Hello");
+chat.current?.getUnreadCount();   // number
+chat.current?.clearHistory();     // drop messages, keep the session
+chat.current?.resetSession();     // start a new session + clear history
+```
+
+> `clearHistory()` / `resetSession()` erase the locally stored conversation — call one on user logout.
+
+---
+
+## Customizing the launcher
+
+The default is a round floating button. You can change it four ways:
+
+**1. Your own launcher (any shape):**
+
+```tsx
+<WebChat
+  config={CONFIG}
+  renderLauncher={({ open }) => (
+    <Pressable onPress={open} style={{ /* a pill, bar, avatar, anything */ }}>
+      <Text>Chat with us</Text>
+    </Pressable>
+  )}
+/>
+```
+
+**2. Trigger from your own UI** — hide the built-in button and open via the ref:
+
+```tsx
+<WebChat ref={chat} config={{ ...CONFIG, showButtonChat: false }} />
+// <YourButton onPress={() => chat.current?.open()} />
+```
+
+**3. Reshape the default** via channel theme tokens (size, color, corner radius).
+
+**4. Use a branded image** via the `openLauncherImage` channel config.
+
+---
+
+## Media & video
+
+- **Attachments:** images (PNG/JPEG), PDF documents, and voice notes. Picking is gated by the `uploadMedia` / `upload*` flags; selected files are validated against the channel's allow-list before sending.
+- **Video calls:** set `makeVideoCall: true` to show the call button (a call can also start automatically when your channel triggers it). Video requires the `react-native-webrtc` + `react-native-incall-manager` peers, the `@config-plugins/react-native-webrtc` Expo plugin (managed apps), and a development build.
+
+Notifications: the SDK does **not** integrate push. Use the `onMessageReceived` callback to fire your own local notification.
+
+---
+
+## TypeScript
+
+The package ships full type declarations. Import types alongside values:
+
+```tsx
+import { WebChat, type WebChatHandle } from "@experiaapp/webchat-react-native";
+```
+
+Lower-level building blocks (the theme helpers, media utilities, individual UI pieces, and the video-call primitives) are also exported if you need to compose a custom surface.
+
+---
+
+## Troubleshooting
+
+- **Native feature does nothing / picker won't open in Expo Go** — Expo Go can't load the native modules; use a development build (`eas build` / `expo prebuild`).
+- **Icons render as plain glyphs** — install `react-native-svg`.
+- **Video-call button missing** — set `makeVideoCall: true`, install the WebRTC peers + plugin, and ensure your channel enables it.
+- **The same conversation keeps resuming** — that's `storage: "localStorage"` (the default). Use `"sessionStorage"` to start fresh each launch, or call `resetSession()`.
+
+---
+
+## License
+
+Proprietary. © Experia. All rights reserved. Use is governed by your agreement with Experia.

package/app.plugin.js

@@ -0,0 +1,6 @@
+// Expo loads this file (by convention) when the package name appears in `expo.plugins`.
+// It re-exports the compiled config plugin from `lib/` (built via `tsc -p tsconfig.build.json`).
+// CommonJS interop: the plugin is the default export, so unwrap `.default`.
+const mod = require('./lib/plugin/withWebchat');
+
+module.exports = mod.default || mod;

package/lib/adapters/audio.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Canonical voice-note codec, RESOLVED for web parity (plan B6 / Task 6).
+ *
+ * The backend expects exactly what the web widget sends: Ogg/Opus. A real
+ * Opus-capable recorder MUST be injected — note that iOS cannot natively
+ * record Opus, so the bare/Expo impls have to wrap an Opus-capable library
+ * (validated in the Task 6 pre-step). Tests inject {@link NoopAudioAdapter}
+ * and assert against this constant rather than calling a native module.
+ */
+export declare const CANONICAL_AUDIO_MIME: "audio/ogg;codecs=opus";
+/**
+ * Result of a completed recording. `mimeType` is expected to equal
+ * {@link CANONICAL_AUDIO_MIME}; `durationMs` is the recorded length.
+ */
+export interface RecordingResult {
+    uri: string;
+    mimeType: string;
+    durationMs: number;
+}
+/**
+ * Live playback progress (Task 6 UI). Reported by an engine that emits position
+ * updates so a player can show "current / total" and reset when the note ends.
+ * Times are in ms; `durationMs` is 0 until the engine knows the media length.
+ */
+export interface PlaybackStatus {
+    positionMs: number;
+    durationMs: number;
+    isPlaying: boolean;
+    didJustFinish: boolean;
+}
+/**
+ * The injectable audio surface. `startRecording`/`stopRecording` capture a
+ * note; `play`/`stop` drive inline playback. Real impls request mic permission
+ * and coordinate mic mutual-exclusion with video calls at the call site.
+ */
+export interface AudioAdapter {
+    startRecording(): Promise<void>;
+    stopRecording(): Promise<RecordingResult>;
+    /**
+     * Start inline playback of `uri`. When `opts.onStatus` is provided AND the
+     * engine reports progress, it is called with position/duration so the player UI
+     * can show "current / total" and reset on finish. Engines without progress
+     * events simply never call it (the UI keeps showing the recorded total).
+     */
+    play(uri: string, opts?: {
+        onStatus?: (status: PlaybackStatus) => void;
+    }): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Marks an adapter whose `startRecording`/`stopRecording` are INERT stubs (e.g.
+     * the default {@link createExpoAudioAdapter}, where recording is hook-only and
+     * cannot live on an object method). When `true`, the {@link AudioRecorder}
+     * component MUST NOT call this adapter to capture a note — it drives the
+     * expo-audio `useAudioRecorder` hook directly instead (and falls back to a
+     * hidden/disabled recorder when expo-audio is absent). When absent/false the
+     * adapter's imperative `startRecording`/`stopRecording` are the real capture
+     * surface (a host-injected recorder, or the test fakes) and are used as-is.
+     */
+    recordingDelegated?: boolean;
+}
+/**
+ * Inert adapter for unit tests and SSR/no-mic environments. It records no audio
+ * and returns a zero-length result tagged with the canonical codec, so the
+ * surrounding state machine and attach() path can be exercised without any
+ * native module.
+ */
+export declare class NoopAudioAdapter implements AudioAdapter {
+    startRecording(): Promise<void>;
+    stopRecording(): Promise<RecordingResult>;
+    play(_uri: string, _opts?: {
+        onStatus?: (status: PlaybackStatus) => void;
+    }): Promise<void>;
+    stop(): Promise<void>;
+}

package/lib/adapters/audio.js

@@ -0,0 +1,39 @@
+"use strict";
+// src/adapters/audio.ts
+//
+// Voice record/playback behind an injectable interface so the core never
+// touches a native audio module directly. The recorder MUST emit the canonical
+// codec below (web parity); the player accepts a local/remote URI.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopAudioAdapter = exports.CANONICAL_AUDIO_MIME = void 0;
+/**
+ * Canonical voice-note codec, RESOLVED for web parity (plan B6 / Task 6).
+ *
+ * The backend expects exactly what the web widget sends: Ogg/Opus. A real
+ * Opus-capable recorder MUST be injected — note that iOS cannot natively
+ * record Opus, so the bare/Expo impls have to wrap an Opus-capable library
+ * (validated in the Task 6 pre-step). Tests inject {@link NoopAudioAdapter}
+ * and assert against this constant rather than calling a native module.
+ */
+exports.CANONICAL_AUDIO_MIME = "audio/ogg;codecs=opus";
+/**
+ * Inert adapter for unit tests and SSR/no-mic environments. It records no audio
+ * and returns a zero-length result tagged with the canonical codec, so the
+ * surrounding state machine and attach() path can be exercised without any
+ * native module.
+ */
+class NoopAudioAdapter {
+    async startRecording() {
+        /* no-op */
+    }
+    async stopRecording() {
+        return { uri: "", mimeType: exports.CANONICAL_AUDIO_MIME, durationMs: 0 };
+    }
+    async play(_uri, _opts) {
+        /* no-op */
+    }
+    async stop() {
+        /* no-op */
+    }
+}
+exports.NoopAudioAdapter = NoopAudioAdapter;

package/lib/adapters/audioRoute.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The subset of `react-native-incall-manager` this wrapper drives. The library
+ * exports a singleton instance as its default export; only these four methods
+ * are used here. Structural so a `{ start: jest.fn(), ... }` spy satisfies it.
+ */
+export interface InCallManagerLike {
+    start(setup?: {
+        auto?: boolean;
+        media?: "video" | "audio";
+        ringback?: string;
+    }): void;
+    stop(setup?: {
+        busytone?: string;
+    }): void;
+    setForceSpeakerphoneOn(flag: boolean): void;
+    setSpeakerphoneOn?(enable: boolean): void;
+}
+export interface AudioRouteStartOptions {
+    /** `"video"` (default) configures the session for a video call. */
+    media?: "video" | "audio";
+}
+/**
+ * Owns the audio route for the lifetime of a call. Construct once per call with
+ * the injected manager, `start()` on connect, toggle the speaker mid-call, and
+ * `stop()` on teardown to hand the audio session back to the OS.
+ */
+export declare class AudioRoute {
+    private readonly manager;
+    private active;
+    constructor(manager: InCallManagerLike);
+    /**
+     * Begin the in-call audio session and route to the loudspeaker by default
+     * (B14 — a video call should be audible without holding the phone to the ear).
+     * Idempotent: calling `start` twice is a no-op until `stop` runs.
+     */
+    start(opts?: AudioRouteStartOptions): void;
+    /**
+     * Toggle the output route mid-call. `true` forces speakerphone; `false`
+     * releases the force so audio returns to the earpiece (or a connected
+     * Bluetooth/wired route the OS prefers).
+     */
+    setSpeaker(on: boolean): void;
+    /** Whether an in-call audio session is currently active. */
+    isActive(): boolean;
+    /**
+     * End the in-call audio session and restore the previous audio mode. Releases
+     * the speakerphone force first so the OS route is clean for the next call /
+     * for Phase-2 voice playback (shared-mic mutual exclusion, §4.4). Idempotent.
+     */
+    stop(): void;
+}
+/**
+ * Real {@link AudioRoute} backed by the `react-native-incall-manager` singleton.
+ * The module is lazy-required so importing this file for the type alone does not
+ * load native bindings (chat-only consumers / the unit-test core never touch it).
+ */
+export declare function reactNativeAudioRoute(): AudioRoute;

package/lib/adapters/audioRoute.js

@@ -0,0 +1,77 @@
+"use strict";
+// src/adapters/audioRoute.ts
+//
+// Audio-route control for video calls, a thin wrapper over
+// `react-native-incall-manager`. The signaling core / call lifecycle calls
+// {@link AudioRoute.start} when a call begins (default speakerphone, B14),
+// {@link AudioRoute.setSpeaker} for the in-call route toggle, and
+// {@link AudioRoute.stop} on teardown to restore the audio session (Plan Task 4).
+//
+// The native manager is injected so this is unit-testable with a spy and never
+// pulls native bindings into the test/core import graph. Real impls construct
+// {@link reactNativeAudioRoute}, which lazy-requires the singleton default
+// export of `react-native-incall-manager`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioRoute = void 0;
+exports.reactNativeAudioRoute = reactNativeAudioRoute;
+/**
+ * Owns the audio route for the lifetime of a call. Construct once per call with
+ * the injected manager, `start()` on connect, toggle the speaker mid-call, and
+ * `stop()` on teardown to hand the audio session back to the OS.
+ */
+class AudioRoute {
+    constructor(manager) {
+        this.active = false;
+        this.manager = manager;
+    }
+    /**
+     * Begin the in-call audio session and route to the loudspeaker by default
+     * (B14 — a video call should be audible without holding the phone to the ear).
+     * Idempotent: calling `start` twice is a no-op until `stop` runs.
+     */
+    start(opts = {}) {
+        var _a;
+        if (this.active)
+            return;
+        this.manager.start({ media: (_a = opts.media) !== null && _a !== void 0 ? _a : "video", auto: false });
+        // Force-route to speakerphone so the remote party is audible by default.
+        this.manager.setForceSpeakerphoneOn(true);
+        this.active = true;
+    }
+    /**
+     * Toggle the output route mid-call. `true` forces speakerphone; `false`
+     * releases the force so audio returns to the earpiece (or a connected
+     * Bluetooth/wired route the OS prefers).
+     */
+    setSpeaker(on) {
+        this.manager.setForceSpeakerphoneOn(on);
+    }
+    /** Whether an in-call audio session is currently active. */
+    isActive() {
+        return this.active;
+    }
+    /**
+     * End the in-call audio session and restore the previous audio mode. Releases
+     * the speakerphone force first so the OS route is clean for the next call /
+     * for Phase-2 voice playback (shared-mic mutual exclusion, §4.4). Idempotent.
+     */
+    stop() {
+        if (!this.active)
+            return;
+        this.manager.setForceSpeakerphoneOn(false);
+        this.manager.stop();
+        this.active = false;
+    }
+}
+exports.AudioRoute = AudioRoute;
+/**
+ * Real {@link AudioRoute} backed by the `react-native-incall-manager` singleton.
+ * The module is lazy-required so importing this file for the type alone does not
+ * load native bindings (chat-only consumers / the unit-test core never touch it).
+ */
+function reactNativeAudioRoute() {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const InCallManager = require("react-native-incall-manager")
+        .default;
+    return new AudioRoute(InCallManager);
+}

package/lib/adapters/expoDefaults.d.ts

@@ -0,0 +1,77 @@
+import type { PickerAdapter } from "./picker";
+import type { AudioAdapter } from "./audio";
+/**
+ * Default {@link PickerAdapter} backed by Expo. Returns `undefined` when NEITHER
+ * expo-image-picker nor expo-document-picker is installed — so the attach button
+ * stays hidden (feature-detect parity with the absent-prop case). When only one
+ * lib is present the adapter exposes only that method (a partial picker is valid;
+ * the Surface omits the missing row).
+ */
+export declare function createExpoPicker(): PickerAdapter | undefined;
+/**
+ * Default file->base64 reader backed by `expo-file-system`. Returns RAW base64
+ * (no `data:` prefix) — `toDataUrl` adds the prefix downstream. Only invoked for
+ * assets WITHOUT eager base64 (documents, recorded audio); image-picker assets
+ * carry `base64` and short-circuit it.
+ *
+ * SDK drift: SDK 54 promoted the OO `File`/`Directory` API to the package root and
+ * DEPRECATED the classic functions. On SDK 56 the root `readAsStringAsync` is a STUB
+ * that THROWS at runtime ("This method will throw in runtime"), so we MUST prefer the
+ * OO `new File(uri).base64()` and only fall back to `readAsStringAsync` on OLDER SDKs
+ * (<=53) where the `File` class doesn't exist. Returns `undefined` when the lib is
+ * absent (provider's throwing reader still only fires if an attach without eager
+ * base64 is actually attempted).
+ */
+export declare function createExpoReadBase64(): ((uri: string) => Promise<string>) | undefined;
+/**
+ * Shape of `publicStyle.defaultFontFamily` (web parity). One remote TTF per
+ * weight (ExtraLight..Black); `name` is the family-level label. All optional —
+ * an absent/empty `fonts` array means "no custom font" and the loader resolves
+ * to an empty map. Kept local (not imported from core) so this adapter file has
+ * no cross-layer dependency, mirroring the picker/audio adapters.
+ */
+export interface BrandFontFamily {
+    name?: string;
+    fonts?: Array<{
+        url: string;
+        fontWeight?: string;
+        fontName?: string;
+    }>;
+}
+/**
+ * Default brand-font loader backed by `expo-font`. Returns `undefined` (no-op)
+ * when expo-font is absent — so Metro never pulls the native module into the
+ * import graph and the jest suite (where it is not installed) keeps working,
+ * exactly like the other expo defaults.
+ *
+ * When present it returns `loadBrandFonts(fontFamily)`, an async loader that:
+ *   - maps each provided font entry to a stable RN family name (`webchat-{…}`),
+ *   - calls `Font.loadAsync({ [familyName]: url })` for each (in parallel via
+ *     Promise.all), TOLERATING individual failures (a bad url drops just that
+ *     weight, never rejects the whole batch),
+ *   - RESOLVES to a `weight -> familyName` map for the apply phase. The map is
+ *     keyed by each entry's `fontWeight` (so `resolveFontFamily(map, weight)`
+ *     can look a weight up); entries without a `fontWeight` are still loaded but
+ *     are only reachable via the family-level `name` key (added when present).
+ *
+ * An empty/undefined `fonts` array resolves to `{}` (no fonts loaded).
+ */
+export declare function createExpoFontLoader(): ((fontFamily?: BrandFontFamily) => Promise<Record<string, string>>) | undefined;
+/**
+ * Default PLAYBACK-CAPABLE {@link AudioAdapter} backed by `expo-audio`. Returns
+ * `undefined` when expo-audio is absent (received-voice falls back to a download
+ * tile — parity with the absent-prop case).
+ *
+ * PLAYBACK (imperative, fully implemented here):
+ *   play(uri)  -> createAudioPlayer(uri); player.play(); retain the player.
+ *   stop()     -> retained player.pause() + player.remove() (MUST remove() to free
+ *                 native resources); null-safe; a single active player is retained,
+ *                 so a new play() removes any prior one first.
+ *
+ * RECORDING (delegated to Phase 2 component): startRecording()/stopRecording() are
+ * inert stubs that keep the AudioAdapter type satisfied. expo-audio's recorder is
+ * HOOK-ONLY (useAudioRecorder), so the real capture lives in the <AudioRecorder>
+ * component (Phase 2) which drives the hook and yields a RecordingResult tagged with
+ * the m4a container mime above. The default object adapter cannot call a hook.
+ */
+export declare function createExpoAudioAdapter(): AudioAdapter | undefined;