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

package/dist/index.d.ts

@@ -1,5 +1,203 @@
 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 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;
+    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;
+};
+/** Shows an actionable Android settings prompt after permanent camera denial. */
+declare function promptOpenSagepilotCameraSettings(): Promise<void>;
+/**
+ * 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 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
+ * 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 +308,22 @@ 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() or
+     * the optional @sagepilot-ai/react-native-camera-addon package.
+     */
+    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 +556,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 { 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 };