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

package/README.md

@@ -12,13 +12,21 @@ The SDK opens the Sagepilot-hosted chat experience inside a React Native WebView
 - A Sagepilot workspace id and chat channel id
 - Secure token storage for production apps
 
-## Install
+## Install And Configure
+
+### 1. Install The Base Chat SDK
+
+Use this install when your app wants Sagepilot chat without Sagepilot's Android CameraX implementation:
 
 ```bash
-npm install @sagepilot-ai/react-native-sdk react-native-webview
+npm install @sagepilot-ai/react-native-sdk@latest react-native-webview
 ```
 
-For secure persisted sessions, also install one storage library:
+This installs the base SDK only. It includes `SagepilotChat.configure`, hosted chat WebView, auth/session handling, the native bridge, attachment bridge protocol, `SagepilotFilePickerAdapter`, and custom picker support. It does not include CameraX or Android CameraX Gradle dependencies.
+
+### 2. Add Secure Session Storage
+
+For production apps, install one secure storage library so Sagepilot customer sessions survive app restarts.
 
 ```bash
 npm install react-native-keychain
@@ -30,6 +38,94 @@ Expo apps can use `expo-secure-store` instead:
 npx expo install expo-secure-store
 ```
 
+### 3. Configure The SDK
+
+Configure Sagepilot once when your app starts. The minimum working setup is:
+
+```ts
+import { SagepilotChat } from "@sagepilot-ai/react-native-sdk";
+
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id"
+});
+```
+
+For production, pass secure token storage:
+
+```ts
+import * as Keychain from "react-native-keychain";
+import {
+  SagepilotChat,
+  createKeychainTokenStorage
+} from "@sagepilot-ai/react-native-sdk";
+
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id",
+  tokenStorage: createKeychainTokenStorage(Keychain)
+});
+```
+
+Then mount `SagepilotChatProvider` once near the top of your app so the SDK can render the hosted chat WebView when you open it:
+
+```tsx
+import { useEffect, type ReactNode } from "react";
+import * as Keychain from "react-native-keychain";
+import {
+  SagepilotChat,
+  SagepilotChatProvider,
+  createKeychainTokenStorage
+} from "@sagepilot-ai/react-native-sdk";
+
+function SagepilotProvider({ children }: { children: ReactNode }) {
+  useEffect(() => {
+    void SagepilotChat.configure({
+      key: "workspace_id:channel_id",
+      tokenStorage: createKeychainTokenStorage(Keychain)
+    });
+
+    return () => {
+      SagepilotChat.destroy();
+    };
+  }, []);
+
+  return <SagepilotChatProvider>{children}</SagepilotChatProvider>;
+}
+
+export function App() {
+  return (
+    <SagepilotProvider>
+      <RootNavigator />
+    </SagepilotProvider>
+  );
+}
+```
+
+### 4. Optional: Add Sagepilot Android CameraX
+
+Install this addon only when you want Sagepilot's Android in-app CameraX picker. Apps that skip this step keep the smaller base SDK install.
+
+```bash
+npm install @sagepilot-ai/react-native-camera-addon@latest
+```
+
+The addon declares `@sagepilot-ai/react-native-sdk` as a peer dependency. Keep the base SDK installed directly in your app; the addon should not be treated as a replacement SDK.
+
+After installing the addon, run a fresh native Android build. A Metro reload is not enough for React Native autolinking to register `NativeModules.SagepilotInAppCamera`.
+
+Then pass the addon picker into `SagepilotChat.configure`:
+
+```ts
+import { SagepilotChat } from "@sagepilot-ai/react-native-sdk";
+import { createSagepilotCameraXFilePicker } from "@sagepilot-ai/react-native-camera-addon";
+
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id",
+  filePicker: createSagepilotCameraXFilePicker()
+});
+```
+
+With this setup, the base SDK still owns chat configuration, hosted WebView rendering, auth/session, and the bridge. The camera addon owns CameraX dependencies, native module registration, camera activity, overlay, and image processing.
+
 ## Configuration Values
 
 You configure the SDK with:
@@ -69,9 +165,6 @@ 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. |
@@ -181,50 +274,68 @@ export function ChatLauncher() {
 }
 ```
 
-## Push Notifications With Webhooks
+## Native File Picker
 
-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.
+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. Pending batches are pinned to the hosted chat route that requested them, so a recovered photo is re-delivered to the originating thread. On Android the SDK also runs a liveness watchdog on app-resume that repaints and, if the widget is confirmed dead, remounts the WebView.
 
-Recommended flow:
+The base package does not include CameraX. Apps that want the smallest install can use only:
 
-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.
+```bash
+npm install @sagepilot-ai/react-native-sdk@latest react-native-webview
+```
 
-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.
+### Optional Android CameraX Addon
 
-## Native File Picker (Strongly Recommended)
+Install the CameraX addon only when you want Sagepilot's Android in-app camera implementation:
 
-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.
+```bash
+npm install @sagepilot-ai/react-native-camera-addon@latest
+```
+
+The addon declares `@sagepilot-ai/react-native-sdk` as a peer dependency. Keep the base SDK installed directly in your app; the addon should not be treated as a replacement SDK.
+
+Run a clean native Android rebuild after installing the addon. If you only Metro-reload, the native module is not linked yet and `createSagepilotCameraXFilePicker()` returns `undefined`, so the hosted widget falls back to the WebView file input.
+
+Then configure the addon adapter:
+
+```ts
+import { SagepilotChat } from "@sagepilot-ai/react-native-sdk";
+import { createSagepilotCameraXFilePicker } from "@sagepilot-ai/react-native-camera-addon";
+
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id",
+  filePicker: createSagepilotCameraXFilePicker()
+});
+```
 
-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.
+The addon owns the Android CameraX Gradle dependencies, `CAMERA` permission merge, native module, camera activity, overlay, and image processing. The base SDK continues to own the hosted chat WebView, auth/session, bridge, attachment protocol, and `SagepilotFilePickerAdapter` type.
 
-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.
+For the strongest resilience (a photo captured right before the OS kills the app survives the restart, at any size), 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` lifts that limit by writing bytes to an app-private file and persisting only file keys in the manifest:
 
 ```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";
+import { createAsyncStorageCacheStorage, createSagepilotFileStore } from "@sagepilot-ai/react-native-sdk";
+import { createSagepilotCameraXFilePicker } from "@sagepilot-ai/react-native-camera-addon";
 
 await SagepilotChat.configure({
   key: "workspace_id:channel_id",
   cacheStorage: createAsyncStorageCacheStorage(AsyncStorage),
   fileStore: createSagepilotFileStore(ReactNativeBlobUtil),
-  filePicker: createSagepilotFilePicker({ imagePicker, documentsPicker, fileReader: ReactNativeBlobUtil })
+  filePicker: createSagepilotCameraXFilePicker()
 });
 ```
 
+### Host-Provided Pickers
+
+You can also provide your own picker modules to the base SDK. Modules are passed in rather than imported by the SDK, so Metro never resolves packages your app did not install.
+
 Install the optional dependencies your app needs:
 
 ```sh
-# Camera and photo gallery (required for the native picker)
+# Camera/gallery through react-native-image-picker
 npm install react-native-image-picker
 
 # Document/file picking (optional)
@@ -257,11 +368,11 @@ await SagepilotChat.configure({
 
 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.
+- Android CameraX images are captured by `@sagepilot-ai/react-native-camera-addon` and 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 CameraX addon can also expose Android Photo Picker and document sources from its native module. The base `createSagepilotFilePicker(...)` helper uses only the host-provided modules you pass into it.
+- Gallery multi-select is capped at 5 by default (`imageSelectionLimit`); documents are rejected above 20MB (`documentMaxFileSizeBytes`) and images above 15MB (`imageMaxFileSizeBytes`) **before** they are read into memory, preventing out-of-memory crashes on large files.
 - 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`.
+- Android apps that install the CameraX addon must grant `CAMERA` at runtime; the addon requests it automatically before opening the camera and surfaces a clear message (with a Settings hint) when it is denied. iOS apps using `react-native-image-picker` 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
@@ -311,7 +422,7 @@ Configure the SDK after your app knows the current workspace/channel and, if ava
 
 ```tsx
 import * as Keychain from "react-native-keychain";
-import { useEffect } from "react";
+import { useEffect, type ReactNode } from "react";
 import {
   SagepilotChat,
   SagepilotChatProvider,
@@ -320,7 +431,7 @@ import {
 
 const tokenStorage = createKeychainTokenStorage(Keychain);
 
-export function SagepilotProvider({ children }: { children: React.ReactNode }) {
+export function SagepilotProvider({ children }: { children: ReactNode }) {
   useEffect(() => {
     let cancelled = false;
 

package/android/build.gradle

@@ -3,18 +3,23 @@ buildscript {
     google()
     mavenCentral()
   }
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.5.0"
+  }
 }
 
-plugins {
-  id "com.android.library"
-}
+apply plugin: "com.android.library"
 
 def isNewArchitectureEnabled() {
   return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true"
 }
 
 if (isNewArchitectureEnabled()) {
-  apply plugin: "com.facebook.react"
+  try {
+    apply plugin: "com.facebook.react"
+  } catch (e) {
+    logger.warn("Could not apply 'com.facebook.react' plugin. This is expected if syncing the library standalone.")
+  }
 }
 
 def safeExtGet(prop, fallback) {
@@ -31,6 +36,10 @@ android {
     buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
   }
 
+  buildFeatures {
+    buildConfig true
+  }
+
   compileOptions {
     sourceCompatibility JavaVersion.VERSION_17
     targetCompatibility JavaVersion.VERSION_17

package/android/src/main/java/ai/sagepilot/reactnativesdk/SagepilotReactNativeSdkPackage.java

@@ -8,11 +8,13 @@ import java.util.Collections;
 import java.util.List;
 
 public class SagepilotReactNativeSdkPackage implements ReactPackage {
+  /** Registers SDK-owned native modules exposed to JavaScript. */
   @Override
   public List<NativeModule> createNativeModules(ReactApplicationContext reactContext) {
     return Collections.emptyList();
   }
 
+  /** Registers the existing SDK view managers without changing their surface. */
   @Override
   public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) {
     return Collections.singletonList(new SagepilotInsetsViewManager());

package/dist/index.d.mts

@@ -11,6 +11,21 @@ type SagepilotPickedFile = {
     size: number;
     data_base64: string;
 };
+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.
+ */
+declare class SagepilotFilePickerError extends Error {
+    readonly code: SagepilotFilePickerErrorCode;
+    /** Creates a typed picker error that can be surfaced over the widget bridge. */
+    constructor(code: SagepilotFilePickerErrorCode, message: string);
+}
+declare const SAGEPILOT_DEFAULT_IMAGE_MAX_DIMENSION = 1920;
+declare const SAGEPILOT_DEFAULT_IMAGE_QUALITY = 0.8;
+declare const SAGEPILOT_DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES: number;
+
 type SagepilotFilePickerSource = "camera" | "library" | "documents";
 type SagepilotFilePickerRequest = {
     source: SagepilotFilePickerSource;
@@ -97,18 +112,15 @@ type SagepilotCreateFilePickerOptions = {
     /** Reject camera/library images larger than this (bytes). */
     imageMaxFileSizeBytes?: number;
 };
-type SagepilotFilePickerErrorCode = "permission_denied" | "camera_unavailable" | "encode_failed" | "file_too_large" | "read_failed" | "unknown";
+/** Shows an actionable Android settings prompt after permanent camera denial. */
+declare function promptOpenSagepilotCameraSettings(): Promise<void>;
 /**
- * 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).
+ * Android apps that declare the CAMERA permission must also hold it at runtime
+ * before the SDK-owned camera screen can open. Request it defensively; apps
+ * that never declared it are unaffected and native launch can surface the real
+ * failure.
  */
-declare class SagepilotFilePickerError extends Error {
-    readonly code: SagepilotFilePickerErrorCode;
-    constructor(code: SagepilotFilePickerErrorCode, message: string);
-}
+declare function ensureSagepilotAndroidCameraPermission(): Promise<void>;
 /**
  * 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
@@ -300,7 +312,8 @@ type SagepilotMobileConfig = {
      * 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().
+     * while the camera is open). Build with createSagepilotFilePicker() or
+     * the optional @sagepilot-ai/react-native-camera-addon package.
      */
     filePicker?: SagepilotFilePickerAdapter;
     /**
@@ -543,4 +556,4 @@ declare function SagepilotChatProvider({ children, closeLabel, loadingLabel }: S
 
 declare function useSagepilotChat(): SagepilotChatHookState;
 
-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 };
+export { SAGEPILOT_DEFAULT_IMAGE_MAX_DIMENSION, SAGEPILOT_DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES, SAGEPILOT_DEFAULT_IMAGE_QUALITY, 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, ensureSagepilotAndroidCameraPermission, promptOpenSagepilotCameraSettings, useSagepilotChat };

package/dist/index.d.ts

@@ -11,6 +11,21 @@ type SagepilotPickedFile = {
     size: number;
     data_base64: string;
 };
+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.
+ */
+declare class SagepilotFilePickerError extends Error {
+    readonly code: SagepilotFilePickerErrorCode;
+    /** Creates a typed picker error that can be surfaced over the widget bridge. */
+    constructor(code: SagepilotFilePickerErrorCode, message: string);
+}
+declare const SAGEPILOT_DEFAULT_IMAGE_MAX_DIMENSION = 1920;
+declare const SAGEPILOT_DEFAULT_IMAGE_QUALITY = 0.8;
+declare const SAGEPILOT_DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES: number;
+
 type SagepilotFilePickerSource = "camera" | "library" | "documents";
 type SagepilotFilePickerRequest = {
     source: SagepilotFilePickerSource;
@@ -97,18 +112,15 @@ type SagepilotCreateFilePickerOptions = {
     /** Reject camera/library images larger than this (bytes). */
     imageMaxFileSizeBytes?: number;
 };
-type SagepilotFilePickerErrorCode = "permission_denied" | "camera_unavailable" | "encode_failed" | "file_too_large" | "read_failed" | "unknown";
+/** Shows an actionable Android settings prompt after permanent camera denial. */
+declare function promptOpenSagepilotCameraSettings(): Promise<void>;
 /**
- * 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).
+ * Android apps that declare the CAMERA permission must also hold it at runtime
+ * before the SDK-owned camera screen can open. Request it defensively; apps
+ * that never declared it are unaffected and native launch can surface the real
+ * failure.
  */
-declare class SagepilotFilePickerError extends Error {
-    readonly code: SagepilotFilePickerErrorCode;
-    constructor(code: SagepilotFilePickerErrorCode, message: string);
-}
+declare function ensureSagepilotAndroidCameraPermission(): Promise<void>;
 /**
  * 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
@@ -300,7 +312,8 @@ type SagepilotMobileConfig = {
      * 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().
+     * while the camera is open). Build with createSagepilotFilePicker() or
+     * the optional @sagepilot-ai/react-native-camera-addon package.
      */
     filePicker?: SagepilotFilePickerAdapter;
     /**
@@ -543,4 +556,4 @@ declare function SagepilotChatProvider({ children, closeLabel, loadingLabel }: S
 
 declare function useSagepilotChat(): SagepilotChatHookState;
 
-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 };
+export { SAGEPILOT_DEFAULT_IMAGE_MAX_DIMENSION, SAGEPILOT_DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES, SAGEPILOT_DEFAULT_IMAGE_QUALITY, 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, ensureSagepilotAndroidCameraPermission, promptOpenSagepilotCameraSettings, useSagepilotChat };