@experiaapp/webchat-react-native 2.0.1

package/lib/plugin/withWebchat.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Expo config plugin — injects the media/mic/camera permissions the RN WebChat SDK needs.
+ *
+ * Consumers add this to their `app.json` / `app.config.js`:
+ *
+ *   {
+ *     "expo": {
+ *       "plugins": [
+ *         "@experiaapp/webchat-react-native",
+ *         // ...or with options:
+ *         ["@experiaapp/webchat-react-native", {
+ *           "photoLibraryPermission": "Allow $(PRODUCT_NAME) to attach photos in chat.",
+ *           "microphonePermission": "Allow $(PRODUCT_NAME) to record voice notes.",
+ *           "cameraPermission": "Allow $(PRODUCT_NAME) to take photos / join video calls.",
+ *           "backgroundCall": true   // add FOREGROUND_SERVICE[_MICROPHONE] for bg video calls
+ *         }]
+ *       ]
+ *     }
+ *   }
+ *
+ * Permissions injected:
+ *   iOS  — NSPhotoLibraryUsageDescription, NSMicrophoneUsageDescription,
+ *          NSCameraUsageDescription
+ *   Android — CAMERA, RECORD_AUDIO, READ_MEDIA_IMAGES, READ_MEDIA_VIDEO,
+ *             MODIFY_AUDIO_SETTINGS, READ_EXTERNAL_STORAGE (maxSdkVersion 32),
+ *             and — only when `backgroundCall` is set — FOREGROUND_SERVICE +
+ *             FOREGROUND_SERVICE_MICROPHONE.
+ *
+ * `@expo/config-plugins` is NOT a hard dependency of this SDK; it is provided by the Expo
+ * toolchain in the consumer's project. We resolve it at runtime via `require` so this file
+ * type-checks (and the package installs) even where Expo is absent. All Expo types are
+ * intentionally `any` to keep the SDK dependency-light.
+ */
+export interface WithWebchatOptions {
+    /** iOS NSPhotoLibraryUsageDescription copy. */
+    photoLibraryPermission?: string;
+    /** iOS NSMicrophoneUsageDescription copy. */
+    microphonePermission?: string;
+    /** iOS NSCameraUsageDescription copy. */
+    cameraPermission?: string;
+    /**
+     * Add Android FOREGROUND_SERVICE + FOREGROUND_SERVICE_MICROPHONE so a video call can keep
+     * running while the app is backgrounded. Off by default — only opt in if you implement the
+     * background-call foreground service (Android 14+ requires the typed `_MICROPHONE` flavor).
+     */
+    backgroundCall?: boolean;
+}
+/**
+ * The config plugin. Typed loosely (`any`) because `@expo/config-plugins`' `ExpoConfig`
+ * type is not a dependency here. Returns the config unchanged when Expo is unavailable.
+ */
+declare const withWebchat: (config: any, options?: WithWebchatOptions) => any;
+export default withWebchat;

package/lib/plugin/withWebchat.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Expo config plugin — injects the media/mic/camera permissions the RN WebChat SDK needs.
+ *
+ * Consumers add this to their `app.json` / `app.config.js`:
+ *
+ *   {
+ *     "expo": {
+ *       "plugins": [
+ *         "@experiaapp/webchat-react-native",
+ *         // ...or with options:
+ *         ["@experiaapp/webchat-react-native", {
+ *           "photoLibraryPermission": "Allow $(PRODUCT_NAME) to attach photos in chat.",
+ *           "microphonePermission": "Allow $(PRODUCT_NAME) to record voice notes.",
+ *           "cameraPermission": "Allow $(PRODUCT_NAME) to take photos / join video calls.",
+ *           "backgroundCall": true   // add FOREGROUND_SERVICE[_MICROPHONE] for bg video calls
+ *         }]
+ *       ]
+ *     }
+ *   }
+ *
+ * Permissions injected:
+ *   iOS  — NSPhotoLibraryUsageDescription, NSMicrophoneUsageDescription,
+ *          NSCameraUsageDescription
+ *   Android — CAMERA, RECORD_AUDIO, READ_MEDIA_IMAGES, READ_MEDIA_VIDEO,
+ *             MODIFY_AUDIO_SETTINGS, READ_EXTERNAL_STORAGE (maxSdkVersion 32),
+ *             and — only when `backgroundCall` is set — FOREGROUND_SERVICE +
+ *             FOREGROUND_SERVICE_MICROPHONE.
+ *
+ * `@expo/config-plugins` is NOT a hard dependency of this SDK; it is provided by the Expo
+ * toolchain in the consumer's project. We resolve it at runtime via `require` so this file
+ * type-checks (and the package installs) even where Expo is absent. All Expo types are
+ * intentionally `any` to keep the SDK dependency-light.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const DEFAULTS = {
+    photoLibraryPermission: "Allow $(PRODUCT_NAME) to access your photos so you can attach them in chat.",
+    microphonePermission: "Allow $(PRODUCT_NAME) to access your microphone so you can record voice notes and join video calls in chat.",
+    cameraPermission: "Allow $(PRODUCT_NAME) to access your camera so you can take photos and join video calls in chat.",
+    backgroundCall: false,
+};
+/** Plain Android permissions (no extra manifest attributes). */
+const ANDROID_PERMISSIONS = [
+    "android.permission.CAMERA",
+    "android.permission.RECORD_AUDIO",
+    "android.permission.READ_MEDIA_IMAGES",
+    "android.permission.READ_MEDIA_VIDEO",
+    "android.permission.MODIFY_AUDIO_SETTINGS",
+];
+/** Foreground-service permissions, only added when `backgroundCall` is enabled. */
+const ANDROID_BACKGROUND_CALL_PERMISSIONS = [
+    "android.permission.FOREGROUND_SERVICE",
+    "android.permission.FOREGROUND_SERVICE_MICROPHONE",
+];
+/**
+ * Permissions that carry extra manifest attributes (so the Expo `addPermission` helper —
+ * which only writes a bare `android:name` — can't express them). Merged by hand.
+ */
+const ANDROID_PERMISSIONS_WITH_ATTRS = [
+    // Scoped storage: legacy read only matters up to Android 12L (API 32). API 33+ uses
+    // READ_MEDIA_IMAGES/VIDEO above, so cap this one to avoid a Play Console review flag.
+    {
+        name: "android.permission.READ_EXTERNAL_STORAGE",
+        attrs: { "android:maxSdkVersion": "32" },
+    },
+];
+/**
+ * Lazily load `@expo/config-plugins`. Returns `null` when it cannot be resolved, so the
+ * plugin degrades to a no-op instead of crashing a project that doesn't use Expo prebuild.
+ */
+function loadConfigPlugins() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+        return require("@expo/config-plugins");
+    }
+    catch {
+        return null;
+    }
+}
+/** iOS: merge the three usage-description strings into Info.plist. */
+function applyIos(config, opts, plugins) {
+    const { withInfoPlist } = plugins;
+    return withInfoPlist(config, (cfg) => {
+        const plist = cfg.modResults;
+        if (!plist.NSPhotoLibraryUsageDescription) {
+            plist.NSPhotoLibraryUsageDescription = opts.photoLibraryPermission;
+        }
+        if (!plist.NSMicrophoneUsageDescription) {
+            plist.NSMicrophoneUsageDescription = opts.microphonePermission;
+        }
+        if (!plist.NSCameraUsageDescription) {
+            plist.NSCameraUsageDescription = opts.cameraPermission;
+        }
+        return cfg;
+    });
+}
+/** Ensure the manifest has a `uses-permission` array and return it. */
+function usesPermissionList(manifest) {
+    const root = manifest.manifest;
+    if (!Array.isArray(root["uses-permission"])) {
+        root["uses-permission"] = [];
+    }
+    return root["uses-permission"];
+}
+function hasPermission(list, name) {
+    return list.some((entry) => (entry === null || entry === void 0 ? void 0 : entry.$) && entry.$["android:name"] === name);
+}
+/** Android: add the media/mic/camera permissions to AndroidManifest.xml. */
+function applyAndroid(config, opts, plugins) {
+    const { withAndroidManifest, AndroidConfig } = plugins;
+    return withAndroidManifest(config, (cfg) => {
+        const plain = [
+            ...ANDROID_PERMISSIONS,
+            ...(opts.backgroundCall ? ANDROID_BACKGROUND_CALL_PERMISSIONS : []),
+        ];
+        // Bare-name permissions: prefer Expo's helper when present.
+        const addPermission = AndroidConfig &&
+            AndroidConfig.Permissions &&
+            AndroidConfig.Permissions.addPermission;
+        if (typeof addPermission === "function") {
+            for (const perm of plain) {
+                addPermission(cfg.modResults, perm);
+            }
+        }
+        else {
+            const list = usesPermissionList(cfg.modResults);
+            for (const perm of plain) {
+                if (!hasPermission(list, perm)) {
+                    list.push({ $: { "android:name": perm } });
+                }
+            }
+        }
+        // Attribute-carrying permissions (e.g. maxSdkVersion) always need a manual merge —
+        // the helper can only write a bare android:name.
+        const list = usesPermissionList(cfg.modResults);
+        for (const { name, attrs } of ANDROID_PERMISSIONS_WITH_ATTRS) {
+            const existing = list.find((entry) => (entry === null || entry === void 0 ? void 0 : entry.$) && entry.$["android:name"] === name);
+            if (existing) {
+                existing.$ = { ...existing.$, ...attrs };
+            }
+            else {
+                list.push({ $: { "android:name": name, ...attrs } });
+            }
+        }
+        return cfg;
+    });
+}
+/**
+ * The config plugin. Typed loosely (`any`) because `@expo/config-plugins`' `ExpoConfig`
+ * type is not a dependency here. Returns the config unchanged when Expo is unavailable.
+ */
+const withWebchat = (config, options) => {
+    const opts = { ...DEFAULTS, ...(options || {}) };
+    const plugins = loadConfigPlugins();
+    if (!plugins) {
+        // No Expo prebuild context — nothing to inject. Bare projects edit native files directly.
+        return config;
+    }
+    let next = config;
+    next = applyIos(next, opts, plugins);
+    next = applyAndroid(next, opts, plugins);
+    return next;
+};
+exports.default = withWebchat;

package/lib/state/WebchatProvider.d.ts

@@ -0,0 +1,132 @@
+import React from "react";
+import type { MinimalSocket } from "../core/WebchatClient";
+import type { Message, Config, MessageReaction } from "../core/types";
+import type { WebChatTheme } from "../theme/themeFactory";
+import type { Dir } from "../theme/dir";
+import type { Asset } from "../adapters/picker";
+import type { AudioAdapter } from "../adapters/audio";
+import { type VideoCallClient } from "../core/VideoCallClient";
+/**
+ * Phase 3 video seam (Group E). The audio-route surface the provider brackets a
+ * call with — `AudioRoute` (`adapters/audioRoute`) satisfies it. Kept structural
+ * so a spy `{ start, stop }` works in tests and the provider never imports a
+ * native module unless a real call is actually placed.
+ */
+export interface AudioRouteLike {
+    start(opts?: {
+        media?: "video" | "audio";
+    }): void;
+    stop(): void;
+    setSpeaker?(on: boolean): void;
+}
+/**
+ * #5 — object form for {@link Ctx.send}. A bare string is shorthand for
+ * `{ text }`. `payload` is what reaches the backend as the message body (display
+ * `text` shown in the bubble); `metadata` is forwarded untouched on the
+ * OutgoingPayload (S9).
+ */
+export type SendInput = string | {
+    text?: string;
+    payload?: string;
+    metadata?: Record<string, unknown>;
+};
+export interface Ctx {
+    messages: Message[];
+    status: string;
+    isStorageReady: boolean;
+    unread: number;
+    /**
+     * Item 23 — "awaiting a bot reply" state that gates the typing indicator. True
+     * when the most recent message in the thread was sent by the user and no bot
+     * (`response`) message has arrived since (the SDK-faithful analog of the web
+     * trigger, which flips `displayTypingIndication` while the agent is composing).
+     * The MessageList renders <TypingIndicator> when this is true AND
+     * `resolvedConfig.displayTypingIndication` is on.
+     */
+    awaitingReply: boolean;
+    /**
+     * Item 34 — has a connection EVER been established this mount? Latches true the
+     * first time the status reaches "connected"/"session-confirmed" and never resets.
+     * Consumers (the Surface/Launcher, when `config.hideWhenNotConnected` is set) use
+     * it to distinguish the INITIAL pre-connect (never connected -> keep visible so the
+     * user can open to connect) from a connect-then-disconnect drop (hide while down).
+     */
+    wasConnected: boolean;
+    /**
+     * Web parity (ChatContainer `!sessionId` gate): true when the CURRENT session was
+     * RESUMED from a stored id (a returning user), false for a brand-new session. The
+     * prechat form is shown only for a NEW session — a resume continues the existing
+     * conversation without re-asking. Latched at hydrate (restored.sessionId present),
+     * cleared by resetSession (which forces a brand-new session).
+     */
+    resumedSession: boolean;
+    /**
+     * Injected playback adapter for received voice notes (audit #23). When present,
+     * the live MessageList/Bubble render an inline <VoiceMessage> player for audio
+     * attachments instead of a download FileTile. Undefined for chat-only consumers
+     * that never wire an audio surface.
+     */
+    audioAdapter?: AudioAdapter;
+    /**
+     * Route the active call's audio output (speakerphone <-> earpiece, B14/audit #25).
+     * Delegates to the provider's REAL AudioRoute (audioRouteRef, started in startCall);
+     * a no-op when no call is active. The live VideoCall surface wires its speaker
+     * toggle to this so the toggle reaches the provider's audio session, not a stub.
+     */
+    setSpeaker: (on: boolean) => void;
+    /** Merged config (prop > server > default) — the single source of truth. */
+    resolvedConfig: Config;
+    /** Active theme = buildTheme(variant, publicStyle). */
+    theme: WebChatTheme;
+    /** Reading direction derived from language ('ar' -> 'rtl', else 'ltr'). */
+    dir: Dir;
+    /** Resolved language (prop > server > localize default). */
+    language: string;
+    send: (input: SendInput) => void;
+    /**
+     * Phase 2 — send picked/recorded media. Creates an optimistic user message that
+     * transitions queued → encoding → sending, emits `user_uttered` with the
+     * base64 `media[]` + a stable `messageKey`, and reconciles to `sent` (URL
+     * patched, base64 stripped) on the server echo. Rejected/failed assets surface
+     * a typed {@link WebChatError} via the `onError` prop.
+     */
+    attach: (assets: Asset[]) => Promise<void>;
+    clearHistory: () => void;
+    resetSession: () => void;
+    /**
+     * Section 4 — apply a like/dislike feedback reaction to a RECEIVED message (web
+     * parity). `messageKey` is the SERVER id (not the SDK's client `key`). Mutually
+     * exclusive + toggle-clear: clicking the ACTIVE reaction clears it. Reads the
+     * message's current `userReaction`, computes the next state + the backend verb
+     * (`like`/`unlike`/`dislike`/`undislike`), dispatches `REACT` optimistically, and
+     * emits `socket.emit("activity", { messageKey, type })`. The server reflection on
+     * `"activityAck"` reconciles the stored reaction.
+     */
+    react: (messageKey: string, reaction: MessageReaction) => void;
+    /** True while a 1:1 video call is active (Surface renders <VideoCall> instead of the thread). */
+    videoCallStarted: boolean;
+    /**
+     * Place a 1:1 video call over the EXISTING chat socket (no second connection).
+     * Builds a {@link VideoCallClient} bound to the live socket + the current
+     * `session_id` (web parity, C8), starts the audio route (speakerphone default,
+     * B14) and the answerer-only signaling. No-op if a call is already up or the
+     * socket isn't ready yet.
+     */
+    startCall: () => void;
+    /** Tear the active call down: leave_room, release camera/mic, restore audio. Idempotent. */
+    endCall: () => void;
+    /**
+     * Internal seam for the WebChat Surface: the live socket + session accessor +
+     * the already-built {@link VideoCallClient}, so `<VideoCall>` renders as a view
+     * over the provider's single client (it does NOT build a second one). Null
+     * until {@link startCall} runs. Consumers should use `videoCallStarted`/
+     * `startCall`/`endCall`; this is wiring, not public surface.
+     */
+    _video?: {
+        socket: MinimalSocket | null;
+        getSessionId: () => string;
+        client: VideoCallClient | null;
+    };
+}
+export declare const WebchatContext: React.Context<Ctx | null>;
+export declare function WebchatProvider(props: any): import("react/jsx-runtime").JSX.Element;