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

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;
@@ -217,6 +418,16 @@ type SagepilotMobileState = SagepilotLifecycleState & {
 };
 type SagepilotMobileSubscription = () => void;
 type SagepilotMessageComposerMode = "auto" | "new";
+type SagepilotConversationCreatedEvent = {
+    chat_id: string;
+    workspace_id?: string;
+    channel_id?: string;
+    session_id?: string;
+    customer_id?: string;
+    message_id?: string;
+    created_at?: string;
+    metadata?: Record<string, unknown>;
+};
 type SagepilotMessageComposerOptions = {
     /**
      * auto: prefill the composer and let the hosted widget reuse an existing
@@ -224,6 +435,20 @@ type SagepilotMessageComposerOptions = {
      * new: force the hosted widget to start a fresh conversation.
      */
     mode?: SagepilotMessageComposerMode;
+    /**
+     * Opens a specific hosted conversation. This value is treated as an opaque
+     * conversation handle and is verified by the hosted customer session.
+     */
+    chatId?: string;
+    /**
+     * App-owned metadata returned to the conversation-created callback so callers
+     * can persist mappings such as order_id -> chat_id.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Fires when this composer invocation creates a new conversation.
+     */
+    onConversationCreated?: (event: SagepilotConversationCreatedEvent) => void;
 };
 type SagepilotChatHookState = {
     configured: boolean;
@@ -240,6 +465,7 @@ type SagepilotChatHookState = {
     identify: (identity: SagepilotIdentity) => Promise<SagepilotIdentifyResult>;
     logout: () => Promise<SagepilotLogoutResponse>;
     getUnreadCount: () => Promise<number>;
+    onConversationCreated: (callback: (event: SagepilotConversationCreatedEvent) => void) => SagepilotMobileSubscription;
 };
 type SagepilotChatProviderProps = {
     children?: ReactNode;
@@ -259,6 +485,7 @@ declare const SagepilotChat: {
         pending: boolean;
     };
     onIdentify: (callback: Callback<SagepilotIdentifyResult>) => SagepilotMobileSubscription;
+    onConversationCreated: (callback: Callback<SagepilotConversationCreatedEvent>) => SagepilotMobileSubscription;
     getUnreadCount: () => Promise<number>;
     onUnreadChange: (callback: Callback<SagepilotUnreadState>) => SagepilotMobileSubscription;
     startUnreadPolling: (intervalMs?: number) => () => void;
@@ -316,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 SagepilotDeviceInfo, type SagepilotDeviceInfoAdapter, type SagepilotIdentifyResult, type SagepilotIdentity, type SagepilotIdentityState, type SagepilotLifecycleState, type SagepilotLogoutResponse, 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 };