@sagepilot-ai/react-native-sdk 0.2.4 → 0.2.5

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sagepilot AI
+
+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

@@ -69,6 +69,9 @@ These options are part of the supported React Native SDK configuration contract.
 | `headers` | Additional headers for SDK service requests. Do not pass server API keys or long-lived secrets from a mobile app. |
 | `fetch` | Custom fetch implementation for runtimes that need one. |
 | `tokenStorage` | Secure storage adapter for SDK-created customer session tokens. |
+| `cacheStorage` | Optional durable cache adapter used by SDK features such as native file-picker batch recovery. |
+| `filePicker` | Optional native picker adapter created with `createSagepilotFilePicker(...)` for camera, gallery, and document attachments. |
+| `fileStore` | Optional native file-store adapter created with `createSagepilotFileStore(...)` for durable picked-file bytes. |
 | `anonymousId` | Optional stable anonymous identifier sent when the SDK creates a customer session. |
 | `metadata` | Optional app metadata merged into the session creation payload. |
 | `deviceInfo` | Optional adapter that returns device metadata to include during session creation. |
@@ -178,6 +181,89 @@ export function ChatLauncher() {
 }
 ```
 
+## Push Notifications With Webhooks
+
+The React Native SDK does not register APNs/FCM device tokens and does not send operating-system push notifications directly. Use Sagepilot webhooks to connect new support messages to your own push-notification system.
+
+Recommended flow:
+
+1. Register and store the app user's push token in your backend.
+2. Configure a Sagepilot webhook subscription for `support.message.created`.
+3. When your webhook receives a new customer-visible support message, map the webhook's customer/conversation data to your app user.
+4. Send the push notification from your backend through APNs, FCM, or your notification provider.
+
+The webhook event includes conversation, customer, message, and SDK context so your backend can decide whether to notify the user. Keep push-token storage, notification preferences, and "user is currently viewing chat" suppression logic in your app/backend.
+
+## Native File Picker (Strongly Recommended)
+
+By default, the hosted chat widget's attach button uses the WebView's `<input type="file">`. On low-RAM Android devices this is unreliable: while the system camera is in the foreground, Android can kill the WebView render process, leaving a dead white screen and losing the captured photo.
+
+Configure `filePicker` so the attach button uses native pickers instead. Captured files are delivered to the widget over a hardened bridge (protocol v2): they are held in app memory **and** mirrored to `cacheStorage`, then **re-delivered until the widget acknowledges them** — surviving the WebView hydration race, renderer crashes, and (for small batches) full app-process death. On Android the SDK also runs a liveness watchdog on app-resume that repaints and, if the widget is confirmed dead, remounts the WebView — healing the blank-white-screen-after-camera case that no reload-on-crash handler can catch.
+
+For the strongest resilience (a photo captured right before the OS kills the app survives the restart, within the widget's upload limits), pass BOTH `cacheStorage` (stores the tiny manifest) and `fileStore` (stores the bytes on disk). `cacheStorage` alone keeps only small (≤~2MB) batches durable, because Android's AsyncStorage caps a single row near 2MB; `fileStore` removes that durability bottleneck by writing bytes to an app-private file and persisting only file keys in the manifest. The hosted widget still enforces the final upload limits listed below.
+
+```ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import * as imagePicker from "react-native-image-picker";
+import * as documentsPicker from "@react-native-documents/picker";
+import ReactNativeBlobUtil from "react-native-blob-util";
+import {
+  createAsyncStorageCacheStorage,
+  createSagepilotFilePicker,
+  createSagepilotFileStore
+} from "@sagepilot-ai/react-native-sdk";
+
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id",
+  cacheStorage: createAsyncStorageCacheStorage(AsyncStorage),
+  fileStore: createSagepilotFileStore(ReactNativeBlobUtil),
+  filePicker: createSagepilotFilePicker({ imagePicker, documentsPicker, fileReader: ReactNativeBlobUtil })
+});
+```
+
+Install the optional dependencies your app needs:
+
+```sh
+# Camera and photo gallery (required for the native picker)
+npm install react-native-image-picker
+
+# Document/file picking (optional)
+npm install @react-native-documents/picker
+
+# Reliable document reads (optional, recommended with the documents picker)
+npm install react-native-blob-util
+```
+
+Then pass the modules to `createSagepilotFilePicker`:
+
+```ts
+import * as imagePicker from "react-native-image-picker";
+import * as documentsPicker from "@react-native-documents/picker";
+import ReactNativeBlobUtil from "react-native-blob-util";
+import {
+  SagepilotChat,
+  createSagepilotFilePicker
+} from "@sagepilot-ai/react-native-sdk";
+
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id",
+  filePicker: createSagepilotFilePicker({
+    imagePicker,
+    documentsPicker,
+    fileReader: ReactNativeBlobUtil
+  })
+});
+```
+
+Notes:
+
+- Camera and gallery images are downscaled natively (1920px longest edge, JPEG quality 0.8 by default; override with `imageMaxDimension` / `imageQuality`). This keeps memory and upload sizes low on constrained devices.
+- The hosted widget enforces the final attachment limits for both WebView and native picker flows: up to 5 files at a time, total previewable images up to 5MB, and total non-image files up to 10MB.
+- The native picker also has earlier safety guards before files are read into memory: gallery multi-select is capped at 5 by default (`imageSelectionLimit`), documents are rejected above 20MB (`documentMaxFileSizeBytes`), and images above 15MB (`imageMaxFileSizeBytes`). These higher guards prevent out-of-memory crashes; they do not raise the hosted widget's final upload limits.
+- Failures are never silent: the picker distinguishes user-cancel from real errors and surfaces a typed `code` (`permission_denied`, `camera_unavailable`, `encode_failed`, `file_too_large`, `read_failed`) to the widget.
+- Android apps that declare the `CAMERA` permission in their manifest must grant it at runtime; the SDK requests it automatically before opening the camera and surfaces a clear message (with a Settings hint) when it is denied. iOS apps need `NSCameraUsageDescription` and `NSPhotoLibraryUsageDescription` in `Info.plist`.
+- Apps that skip `filePicker` keep the WebView file input. The SDK still recovers from WebView renderer crashes by reloading the widget, but a photo captured at crash time cannot be restored in that mode.
+
 ## Secure Session Storage
 
 The SDK creates opaque customer session tokens at runtime. These tokens are not exposed through hooks or public session APIs.

package/dist/index.d.mts

@@ -1,5 +1,191 @@
 import { ReactNode } from 'react';
 
+/**
+ * Wire shape delivered to the hosted widget. Matches the Customer API
+ * attachment input (`data_base64`) so the widget can reuse its existing
+ * validation and send path without backend changes.
+ */
+type SagepilotPickedFile = {
+    file_name: string;
+    mime_type: string;
+    size: number;
+    data_base64: string;
+};
+type SagepilotFilePickerSource = "camera" | "library" | "documents";
+type SagepilotFilePickerRequest = {
+    source: SagepilotFilePickerSource;
+    multiple: boolean;
+};
+/**
+ * Host-app-provided native file picker. When configured, the hosted widget's
+ * attach button routes through native pickers instead of the WebView's
+ * `<input type="file">`. This is required for reliable camera capture on
+ * low-RAM Android devices: the OS can kill the WebView render process while
+ * the camera activity is foregrounded, which destroys any in-WebView file
+ * chooser state. Natively captured files survive that kill and are
+ * re-delivered after the WebView reloads.
+ */
+type SagepilotFilePickerAdapter = {
+    /** Sources offered to the customer in the attachment chooser. */
+    sources: SagepilotFilePickerSource[];
+    /** Resolves picked files, or an empty array when the customer cancels. */
+    pickFiles: (request: SagepilotFilePickerRequest) => Promise<SagepilotPickedFile[]>;
+};
+/** Structural subset of `react-native-image-picker` used by the SDK. */
+type SagepilotImagePickerModule = {
+    launchCamera: (options: Record<string, unknown>) => Promise<SagepilotImagePickerResult>;
+    launchImageLibrary: (options: Record<string, unknown>) => Promise<SagepilotImagePickerResult>;
+};
+type SagepilotImagePickerResult = {
+    didCancel?: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+    assets?: Array<{
+        fileName?: string | null;
+        type?: string | null;
+        fileSize?: number | null;
+        base64?: string | null;
+        uri?: string | null;
+    }>;
+};
+/** Structural subset of `@react-native-documents/picker` used by the SDK. */
+type SagepilotDocumentsPickerModule = {
+    pick: (options?: Record<string, unknown>) => Promise<Array<{
+        uri: string;
+        name: string | null;
+        size: number | null;
+        type: string | null;
+    }>>;
+    keepLocalCopy?: (options: {
+        files: Array<{
+            uri: string;
+            fileName: string;
+        }>;
+        destination: "cachesDirectory" | "documentDirectory";
+    }) => Promise<Array<{
+        status: string;
+        sourceUri: string;
+        localUri?: string;
+        copyError?: string;
+    }>>;
+};
+/** Structural subset of `react-native-blob-util` used for document reads. */
+type SagepilotFileReaderModule = {
+    fs: {
+        readFile: (path: string, encoding: string) => Promise<unknown>;
+    };
+};
+type SagepilotCreateFilePickerOptions = {
+    imagePicker?: SagepilotImagePickerModule;
+    documentsPicker?: SagepilotDocumentsPickerModule;
+    /** Optional `react-native-blob-util` for reliable document reads. */
+    fileReader?: SagepilotFileReaderModule;
+    /**
+     * Longest image edge in pixels for camera/library picks. Downscaling
+     * natively keeps memory and upload size low on low-RAM devices.
+     */
+    imageMaxDimension?: number;
+    /** JPEG quality (0-1) applied to camera/library picks. */
+    imageQuality?: number;
+    /**
+     * Max images per gallery selection. Defaults to 5. Set 0 for unlimited
+     * (not recommended: a large batch produces a multi-megabyte bridge payload).
+     */
+    imageSelectionLimit?: number;
+    /** Reject documents larger than this (bytes) before reading them. */
+    documentMaxFileSizeBytes?: number;
+    /** Reject camera/library images larger than this (bytes). */
+    imageMaxFileSizeBytes?: number;
+};
+type SagepilotFilePickerErrorCode = "permission_denied" | "camera_unavailable" | "encode_failed" | "file_too_large" | "read_failed" | "unknown";
+/**
+ * Structured picker failure. The provider maps `.code` to a user-facing message
+ * and surfaces it via sagepilot:file_picker_error so a failed capture is never
+ * silently swallowed (the historical bug: cancel, OEM cancel-misreport, and
+ * base64-encode failure all collapsed into an empty array indistinguishable
+ * from a real user cancel).
+ */
+declare class SagepilotFilePickerError extends Error {
+    readonly code: SagepilotFilePickerErrorCode;
+    constructor(code: SagepilotFilePickerErrorCode, message: string);
+}
+/**
+ * Builds the SDK file picker adapter from host-app-installed native modules.
+ * Modules are passed in (rather than required by the SDK) so Metro never
+ * tries to resolve packages the host app has not installed.
+ *
+ * @example
+ * import * as imagePicker from "react-native-image-picker";
+ * import * as documentsPicker from "@react-native-documents/picker";
+ *
+ * SagepilotChat.configure({
+ *   key: "...",
+ *   filePicker: createSagepilotFilePicker({ imagePicker, documentsPicker })
+ * });
+ */
+declare function createSagepilotFilePicker(options: SagepilotCreateFilePickerOptions): SagepilotFilePickerAdapter | undefined;
+
+/**
+ * Durable file outbox for natively-picked attachments.
+ *
+ * Persisting attachment BYTES in `cacheStorage` (AsyncStorage) does not scale:
+ * Android's SQLite-backed store caps a single row at ~2MB (CursorWindow), so a
+ * multi-megabyte capture cannot be stored there at all. Instead we write the
+ * bytes to a stable app-private file and persist only a tiny manifest of file
+ * keys + metadata in `cacheStorage`. This makes durability size-independent and
+ * lets a capture survive a full app-process death during the camera round-trip.
+ *
+ * The store is built from the host app's `react-native-blob-util` so the SDK
+ * itself depends on no filesystem package (same injection pattern as the
+ * native file picker).
+ */
+/** Structural subset of `react-native-blob-util` used by the file store. */
+type SagepilotBlobUtilLike = {
+    fs: {
+        dirs: {
+            DocumentDir: string;
+        };
+        writeFile: (path: string, data: string, encoding: string) => Promise<unknown>;
+        readFile: (path: string, encoding: string) => Promise<unknown>;
+        unlink: (path: string) => Promise<unknown>;
+        exists: (path: string) => Promise<boolean>;
+        ls: (path: string) => Promise<string[]>;
+        mkdir: (path: string) => Promise<unknown>;
+    };
+};
+/**
+ * Persists attachment bytes to disk under stable, app-private keys. Keys (not
+ * absolute paths) are stored in the manifest so persistence survives the
+ * platform relocating the app container between launches (notably iOS).
+ */
+type SagepilotPersistedFileStore = {
+    /** Writes base64 content under `key`; resolves once durably on disk. */
+    write: (key: string, base64: string) => Promise<void>;
+    /** Reads previously-written content back as base64. */
+    read: (key: string) => Promise<string>;
+    /** Best-effort delete of a single key. */
+    remove: (key: string) => Promise<void>;
+    /** Best-effort delete of every stored file whose key is not in `keepKeys`. */
+    prune: (keepKeys: string[]) => Promise<void>;
+};
+type SagepilotCreateFileStoreOptions = {
+    /** Sub-directory under DocumentDir. Defaults to "sagepilot-attachments". */
+    directoryName?: string;
+};
+/**
+ * Builds a {@link SagepilotPersistedFileStore} backed by react-native-blob-util.
+ *
+ * @example
+ * import ReactNativeBlobUtil from "react-native-blob-util";
+ * SagepilotChat.configure({
+ *   key: "...",
+ *   cacheStorage: createAsyncStorageCacheStorage(AsyncStorage),
+ *   fileStore: createSagepilotFileStore(ReactNativeBlobUtil),
+ *   filePicker: createSagepilotFilePicker({ imagePicker, documentsPicker, fileReader: ReactNativeBlobUtil })
+ * });
+ */
+declare function createSagepilotFileStore(blobUtil: SagepilotBlobUtilLike, options?: SagepilotCreateFileStoreOptions): SagepilotPersistedFileStore;
+
 type SagepilotMobilePresentationStyle = "sheet" | "fullScreen" | "push";
 type SagepilotMobileColorScheme = "system" | "light" | "dark";
 type SagepilotChatErrorCode = "invalid_config" | "not_initialized" | "already_initialized" | "network_error" | "invalid_response" | "invalid_request" | "unauthorized" | "forbidden" | "session_not_found" | "session_expired" | "channel_not_found" | "conversation_not_found" | "message_not_found" | "contact_required" | "otp_required" | "otp_invalid" | "otp_expired" | "identity_verification_failed" | "rate_limited" | "idempotency_conflict" | "not_implemented" | "internal_error";
@@ -110,6 +296,21 @@ type SagepilotMobileConfig = {
     cacheStorage?: SagepilotCacheStorage;
     deviceInfo?: SagepilotDeviceInfoAdapter;
     biometrics?: SagepilotBiometricsAdapter;
+    /**
+     * Native file picker used by the hosted chat widget's attach button.
+     * Strongly recommended: in-WebView camera capture is unreliable on
+     * low-RAM Android devices (the OS can kill the WebView render process
+     * while the camera is open). Build with createSagepilotFilePicker().
+     */
+    filePicker?: SagepilotFilePickerAdapter;
+    /**
+     * Durable on-disk store for picked attachments. When provided, a captured
+     * photo/document survives a full app-process death during the camera
+     * round-trip (the SDK rehydrates and re-delivers it on relaunch), with no
+     * size limit. Without it, durability falls back to small batches stored in
+     * cacheStorage. Build with createSagepilotFileStore(ReactNativeBlobUtil).
+     */
+    fileStore?: SagepilotPersistedFileStore;
     presentation?: SagepilotMobilePresentationConfig;
     theme?: SagepilotMobileThemeConfig;
     behavior?: SagepilotMobileBehaviorConfig;
@@ -342,4 +543,4 @@ declare function SagepilotChatProvider({ children, closeLabel, loadingLabel }: S
 
 declare function useSagepilotChat(): SagepilotChatHookState;
 
-export { type SagepilotBiometricsAdapter, type SagepilotBootstrapChannelResponse, type SagepilotCacheStorage, SagepilotChat, SagepilotChatError, type SagepilotChatErrorCode, type SagepilotChatHookState, SagepilotChatProvider, type SagepilotChatProviderProps, type SagepilotConversationCreatedEvent, type SagepilotDeviceInfo, type SagepilotDeviceInfoAdapter, type SagepilotIdentifyResult, type SagepilotIdentity, type SagepilotIdentityState, type SagepilotLifecycleState, type SagepilotLogoutResponse, type SagepilotMessageComposerOptions, type SagepilotMobileBehaviorConfig, type SagepilotMobileColorScheme, type SagepilotMobileConfig, type SagepilotMobileConfigureResult, type SagepilotMobileLauncherConfig, type SagepilotMobilePresentationConfig, type SagepilotMobilePresentationStyle, type SagepilotMobileResolvedLauncherConfig, type SagepilotMobileState, type SagepilotMobileSubscription, type SagepilotMobileThemeConfig, type SagepilotMobileThemeState, type SagepilotSessionState, type SagepilotTokenStorage, type SagepilotUnreadState, createAsyncStorageCacheStorage, createKeychainTokenStorage, useSagepilotChat };
+export { type SagepilotBiometricsAdapter, type SagepilotBlobUtilLike, type SagepilotBootstrapChannelResponse, type SagepilotCacheStorage, SagepilotChat, SagepilotChatError, type SagepilotChatErrorCode, type SagepilotChatHookState, SagepilotChatProvider, type SagepilotChatProviderProps, type SagepilotConversationCreatedEvent, type SagepilotCreateFilePickerOptions, type SagepilotCreateFileStoreOptions, type SagepilotDeviceInfo, type SagepilotDeviceInfoAdapter, type SagepilotDocumentsPickerModule, type SagepilotFilePickerAdapter, SagepilotFilePickerError, type SagepilotFilePickerErrorCode, type SagepilotFilePickerRequest, type SagepilotFilePickerSource, type SagepilotFileReaderModule, type SagepilotIdentifyResult, type SagepilotIdentity, type SagepilotIdentityState, type SagepilotImagePickerModule, type SagepilotImagePickerResult, type SagepilotLifecycleState, type SagepilotLogoutResponse, type SagepilotMessageComposerOptions, type SagepilotMobileBehaviorConfig, type SagepilotMobileColorScheme, type SagepilotMobileConfig, type SagepilotMobileConfigureResult, type SagepilotMobileLauncherConfig, type SagepilotMobilePresentationConfig, type SagepilotMobilePresentationStyle, type SagepilotMobileResolvedLauncherConfig, type SagepilotMobileState, type SagepilotMobileSubscription, type SagepilotMobileThemeConfig, type SagepilotMobileThemeState, type SagepilotPersistedFileStore, type SagepilotPickedFile, type SagepilotSessionState, type SagepilotTokenStorage, type SagepilotUnreadState, createAsyncStorageCacheStorage, createKeychainTokenStorage, createSagepilotFilePicker, createSagepilotFileStore, useSagepilotChat };

package/dist/index.d.ts

@@ -1,5 +1,191 @@
 import { ReactNode } from 'react';
 
+/**
+ * Wire shape delivered to the hosted widget. Matches the Customer API
+ * attachment input (`data_base64`) so the widget can reuse its existing
+ * validation and send path without backend changes.
+ */
+type SagepilotPickedFile = {
+    file_name: string;
+    mime_type: string;
+    size: number;
+    data_base64: string;
+};
+type SagepilotFilePickerSource = "camera" | "library" | "documents";
+type SagepilotFilePickerRequest = {
+    source: SagepilotFilePickerSource;
+    multiple: boolean;
+};
+/**
+ * Host-app-provided native file picker. When configured, the hosted widget's
+ * attach button routes through native pickers instead of the WebView's
+ * `<input type="file">`. This is required for reliable camera capture on
+ * low-RAM Android devices: the OS can kill the WebView render process while
+ * the camera activity is foregrounded, which destroys any in-WebView file
+ * chooser state. Natively captured files survive that kill and are
+ * re-delivered after the WebView reloads.
+ */
+type SagepilotFilePickerAdapter = {
+    /** Sources offered to the customer in the attachment chooser. */
+    sources: SagepilotFilePickerSource[];
+    /** Resolves picked files, or an empty array when the customer cancels. */
+    pickFiles: (request: SagepilotFilePickerRequest) => Promise<SagepilotPickedFile[]>;
+};
+/** Structural subset of `react-native-image-picker` used by the SDK. */
+type SagepilotImagePickerModule = {
+    launchCamera: (options: Record<string, unknown>) => Promise<SagepilotImagePickerResult>;
+    launchImageLibrary: (options: Record<string, unknown>) => Promise<SagepilotImagePickerResult>;
+};
+type SagepilotImagePickerResult = {
+    didCancel?: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+    assets?: Array<{
+        fileName?: string | null;
+        type?: string | null;
+        fileSize?: number | null;
+        base64?: string | null;
+        uri?: string | null;
+    }>;
+};
+/** Structural subset of `@react-native-documents/picker` used by the SDK. */
+type SagepilotDocumentsPickerModule = {
+    pick: (options?: Record<string, unknown>) => Promise<Array<{
+        uri: string;
+        name: string | null;
+        size: number | null;
+        type: string | null;
+    }>>;
+    keepLocalCopy?: (options: {
+        files: Array<{
+            uri: string;
+            fileName: string;
+        }>;
+        destination: "cachesDirectory" | "documentDirectory";
+    }) => Promise<Array<{
+        status: string;
+        sourceUri: string;
+        localUri?: string;
+        copyError?: string;
+    }>>;
+};
+/** Structural subset of `react-native-blob-util` used for document reads. */
+type SagepilotFileReaderModule = {
+    fs: {
+        readFile: (path: string, encoding: string) => Promise<unknown>;
+    };
+};
+type SagepilotCreateFilePickerOptions = {
+    imagePicker?: SagepilotImagePickerModule;
+    documentsPicker?: SagepilotDocumentsPickerModule;
+    /** Optional `react-native-blob-util` for reliable document reads. */
+    fileReader?: SagepilotFileReaderModule;
+    /**
+     * Longest image edge in pixels for camera/library picks. Downscaling
+     * natively keeps memory and upload size low on low-RAM devices.
+     */
+    imageMaxDimension?: number;
+    /** JPEG quality (0-1) applied to camera/library picks. */
+    imageQuality?: number;
+    /**
+     * Max images per gallery selection. Defaults to 5. Set 0 for unlimited
+     * (not recommended: a large batch produces a multi-megabyte bridge payload).
+     */
+    imageSelectionLimit?: number;
+    /** Reject documents larger than this (bytes) before reading them. */
+    documentMaxFileSizeBytes?: number;
+    /** Reject camera/library images larger than this (bytes). */
+    imageMaxFileSizeBytes?: number;
+};
+type SagepilotFilePickerErrorCode = "permission_denied" | "camera_unavailable" | "encode_failed" | "file_too_large" | "read_failed" | "unknown";
+/**
+ * Structured picker failure. The provider maps `.code` to a user-facing message
+ * and surfaces it via sagepilot:file_picker_error so a failed capture is never
+ * silently swallowed (the historical bug: cancel, OEM cancel-misreport, and
+ * base64-encode failure all collapsed into an empty array indistinguishable
+ * from a real user cancel).
+ */
+declare class SagepilotFilePickerError extends Error {
+    readonly code: SagepilotFilePickerErrorCode;
+    constructor(code: SagepilotFilePickerErrorCode, message: string);
+}
+/**
+ * Builds the SDK file picker adapter from host-app-installed native modules.
+ * Modules are passed in (rather than required by the SDK) so Metro never
+ * tries to resolve packages the host app has not installed.
+ *
+ * @example
+ * import * as imagePicker from "react-native-image-picker";
+ * import * as documentsPicker from "@react-native-documents/picker";
+ *
+ * SagepilotChat.configure({
+ *   key: "...",
+ *   filePicker: createSagepilotFilePicker({ imagePicker, documentsPicker })
+ * });
+ */
+declare function createSagepilotFilePicker(options: SagepilotCreateFilePickerOptions): SagepilotFilePickerAdapter | undefined;
+
+/**
+ * Durable file outbox for natively-picked attachments.
+ *
+ * Persisting attachment BYTES in `cacheStorage` (AsyncStorage) does not scale:
+ * Android's SQLite-backed store caps a single row at ~2MB (CursorWindow), so a
+ * multi-megabyte capture cannot be stored there at all. Instead we write the
+ * bytes to a stable app-private file and persist only a tiny manifest of file
+ * keys + metadata in `cacheStorage`. This makes durability size-independent and
+ * lets a capture survive a full app-process death during the camera round-trip.
+ *
+ * The store is built from the host app's `react-native-blob-util` so the SDK
+ * itself depends on no filesystem package (same injection pattern as the
+ * native file picker).
+ */
+/** Structural subset of `react-native-blob-util` used by the file store. */
+type SagepilotBlobUtilLike = {
+    fs: {
+        dirs: {
+            DocumentDir: string;
+        };
+        writeFile: (path: string, data: string, encoding: string) => Promise<unknown>;
+        readFile: (path: string, encoding: string) => Promise<unknown>;
+        unlink: (path: string) => Promise<unknown>;
+        exists: (path: string) => Promise<boolean>;
+        ls: (path: string) => Promise<string[]>;
+        mkdir: (path: string) => Promise<unknown>;
+    };
+};
+/**
+ * Persists attachment bytes to disk under stable, app-private keys. Keys (not
+ * absolute paths) are stored in the manifest so persistence survives the
+ * platform relocating the app container between launches (notably iOS).
+ */
+type SagepilotPersistedFileStore = {
+    /** Writes base64 content under `key`; resolves once durably on disk. */
+    write: (key: string, base64: string) => Promise<void>;
+    /** Reads previously-written content back as base64. */
+    read: (key: string) => Promise<string>;
+    /** Best-effort delete of a single key. */
+    remove: (key: string) => Promise<void>;
+    /** Best-effort delete of every stored file whose key is not in `keepKeys`. */
+    prune: (keepKeys: string[]) => Promise<void>;
+};
+type SagepilotCreateFileStoreOptions = {
+    /** Sub-directory under DocumentDir. Defaults to "sagepilot-attachments". */
+    directoryName?: string;
+};
+/**
+ * Builds a {@link SagepilotPersistedFileStore} backed by react-native-blob-util.
+ *
+ * @example
+ * import ReactNativeBlobUtil from "react-native-blob-util";
+ * SagepilotChat.configure({
+ *   key: "...",
+ *   cacheStorage: createAsyncStorageCacheStorage(AsyncStorage),
+ *   fileStore: createSagepilotFileStore(ReactNativeBlobUtil),
+ *   filePicker: createSagepilotFilePicker({ imagePicker, documentsPicker, fileReader: ReactNativeBlobUtil })
+ * });
+ */
+declare function createSagepilotFileStore(blobUtil: SagepilotBlobUtilLike, options?: SagepilotCreateFileStoreOptions): SagepilotPersistedFileStore;
+
 type SagepilotMobilePresentationStyle = "sheet" | "fullScreen" | "push";
 type SagepilotMobileColorScheme = "system" | "light" | "dark";
 type SagepilotChatErrorCode = "invalid_config" | "not_initialized" | "already_initialized" | "network_error" | "invalid_response" | "invalid_request" | "unauthorized" | "forbidden" | "session_not_found" | "session_expired" | "channel_not_found" | "conversation_not_found" | "message_not_found" | "contact_required" | "otp_required" | "otp_invalid" | "otp_expired" | "identity_verification_failed" | "rate_limited" | "idempotency_conflict" | "not_implemented" | "internal_error";
@@ -110,6 +296,21 @@ type SagepilotMobileConfig = {
     cacheStorage?: SagepilotCacheStorage;
     deviceInfo?: SagepilotDeviceInfoAdapter;
     biometrics?: SagepilotBiometricsAdapter;
+    /**
+     * Native file picker used by the hosted chat widget's attach button.
+     * Strongly recommended: in-WebView camera capture is unreliable on
+     * low-RAM Android devices (the OS can kill the WebView render process
+     * while the camera is open). Build with createSagepilotFilePicker().
+     */
+    filePicker?: SagepilotFilePickerAdapter;
+    /**
+     * Durable on-disk store for picked attachments. When provided, a captured
+     * photo/document survives a full app-process death during the camera
+     * round-trip (the SDK rehydrates and re-delivers it on relaunch), with no
+     * size limit. Without it, durability falls back to small batches stored in
+     * cacheStorage. Build with createSagepilotFileStore(ReactNativeBlobUtil).
+     */
+    fileStore?: SagepilotPersistedFileStore;
     presentation?: SagepilotMobilePresentationConfig;
     theme?: SagepilotMobileThemeConfig;
     behavior?: SagepilotMobileBehaviorConfig;
@@ -342,4 +543,4 @@ declare function SagepilotChatProvider({ children, closeLabel, loadingLabel }: S
 
 declare function useSagepilotChat(): SagepilotChatHookState;
 
-export { type SagepilotBiometricsAdapter, type SagepilotBootstrapChannelResponse, type SagepilotCacheStorage, SagepilotChat, SagepilotChatError, type SagepilotChatErrorCode, type SagepilotChatHookState, SagepilotChatProvider, type SagepilotChatProviderProps, type SagepilotConversationCreatedEvent, type SagepilotDeviceInfo, type SagepilotDeviceInfoAdapter, type SagepilotIdentifyResult, type SagepilotIdentity, type SagepilotIdentityState, type SagepilotLifecycleState, type SagepilotLogoutResponse, type SagepilotMessageComposerOptions, type SagepilotMobileBehaviorConfig, type SagepilotMobileColorScheme, type SagepilotMobileConfig, type SagepilotMobileConfigureResult, type SagepilotMobileLauncherConfig, type SagepilotMobilePresentationConfig, type SagepilotMobilePresentationStyle, type SagepilotMobileResolvedLauncherConfig, type SagepilotMobileState, type SagepilotMobileSubscription, type SagepilotMobileThemeConfig, type SagepilotMobileThemeState, type SagepilotSessionState, type SagepilotTokenStorage, type SagepilotUnreadState, createAsyncStorageCacheStorage, createKeychainTokenStorage, useSagepilotChat };
+export { type SagepilotBiometricsAdapter, type SagepilotBlobUtilLike, type SagepilotBootstrapChannelResponse, type SagepilotCacheStorage, SagepilotChat, SagepilotChatError, type SagepilotChatErrorCode, type SagepilotChatHookState, SagepilotChatProvider, type SagepilotChatProviderProps, type SagepilotConversationCreatedEvent, type SagepilotCreateFilePickerOptions, type SagepilotCreateFileStoreOptions, type SagepilotDeviceInfo, type SagepilotDeviceInfoAdapter, type SagepilotDocumentsPickerModule, type SagepilotFilePickerAdapter, SagepilotFilePickerError, type SagepilotFilePickerErrorCode, type SagepilotFilePickerRequest, type SagepilotFilePickerSource, type SagepilotFileReaderModule, type SagepilotIdentifyResult, type SagepilotIdentity, type SagepilotIdentityState, type SagepilotImagePickerModule, type SagepilotImagePickerResult, type SagepilotLifecycleState, type SagepilotLogoutResponse, type SagepilotMessageComposerOptions, type SagepilotMobileBehaviorConfig, type SagepilotMobileColorScheme, type SagepilotMobileConfig, type SagepilotMobileConfigureResult, type SagepilotMobileLauncherConfig, type SagepilotMobilePresentationConfig, type SagepilotMobilePresentationStyle, type SagepilotMobileResolvedLauncherConfig, type SagepilotMobileState, type SagepilotMobileSubscription, type SagepilotMobileThemeConfig, type SagepilotMobileThemeState, type SagepilotPersistedFileStore, type SagepilotPickedFile, type SagepilotSessionState, type SagepilotTokenStorage, type SagepilotUnreadState, createAsyncStorageCacheStorage, createKeychainTokenStorage, createSagepilotFilePicker, createSagepilotFileStore, useSagepilotChat };