@reverbia/sdk 1.0.0-next.20251219092050 → 1.0.0-next.20251219162520

package/dist/react/index.d.ts

@@ -978,6 +978,8 @@ interface StoredMessage {
     sources?: SearchSource[];
     responseDuration?: number;
     wasStopped?: boolean;
+    /** If set, indicates the message failed with this error */
+    error?: string;
 }
 interface StoredConversation {
     uniqueId: string;
@@ -1002,6 +1004,8 @@ interface CreateMessageOptions {
     vector?: number[];
     embeddingModel?: string;
     wasStopped?: boolean;
+    /** If set, indicates the message failed with this error */
+    error?: string;
 }
 interface CreateConversationOptions {
     conversationId?: string;
@@ -1063,6 +1067,7 @@ declare class Message extends Model {
     sources?: SearchSource[];
     responseDuration?: number;
     wasStopped?: boolean;
+    error?: string;
 }
 declare class Conversation extends Model {
     static table: string;
@@ -1248,6 +1253,7 @@ declare const sdkSchema: Readonly<{
  * Migration history:
  * - v2 → v3: Added `was_stopped` column to history table
  * - v3 → v4: Added `modelPreferences` table for settings storage
+ * - v4 → v5: Added `error` column to history table for error persistence
  */
 declare const sdkMigrations: Readonly<{
     validated: true;
@@ -1744,7 +1750,7 @@ declare function executeTool(tool: ClientTool, params: Record<string, unknown>):
  * Dropbox uses OAuth 2.0 with PKCE for browser apps.
  */
 /** Default folder path for Dropbox backups */
-declare const DEFAULT_BACKUP_FOLDER = "/ai-chat-app/conversations";
+declare const DEFAULT_BACKUP_FOLDER$1 = "/ai-chat-app/conversations";
 
 /**
  * Dropbox Backup Implementation
@@ -2191,12 +2197,339 @@ interface UseGoogleDriveBackupResult {
  */
 declare function useGoogleDriveBackup(options: UseGoogleDriveBackupOptions): UseGoogleDriveBackupResult;
 
+/**
+ * Props for ICloudAuthProvider
+ */
+interface ICloudAuthProviderProps {
+    /** CloudKit API token (from Apple Developer Console) */
+    apiToken: string;
+    /** CloudKit container identifier (default: "iCloud.Memoryless") */
+    containerIdentifier?: string;
+    /** CloudKit environment (default: "production") */
+    environment?: "development" | "production";
+    /** Children to render */
+    children: ReactNode;
+}
+/**
+ * Context value for iCloud authentication
+ */
+interface ICloudAuthContextValue {
+    /** Whether user is authenticated with iCloud */
+    isAuthenticated: boolean;
+    /** Whether iCloud is configured and available */
+    isConfigured: boolean;
+    /** Whether CloudKit JS is loaded */
+    isAvailable: boolean;
+    /** User record name (unique identifier) */
+    userRecordName: string | null;
+    /** Request access - triggers iCloud sign-in if needed */
+    requestAccess: () => Promise<void>;
+    /** Sign out from iCloud */
+    logout: () => void;
+}
+/**
+ * Provider component for iCloud authentication.
+ *
+ * Wrap your app with this provider to enable iCloud authentication.
+ * CloudKit JS is loaded automatically when needed.
+ *
+ * @example
+ * ```tsx
+ * import { ICloudAuthProvider } from "@reverbia/sdk/react";
+ *
+ * function App() {
+ *   return (
+ *     <ICloudAuthProvider
+ *       apiToken={process.env.NEXT_PUBLIC_CLOUDKIT_API_TOKEN!}
+ *       containerIdentifier="iCloud.Memoryless"
+ *       environment="production"
+ *     >
+ *       <MyApp />
+ *     </ICloudAuthProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @category Components
+ */
+declare function ICloudAuthProvider({ apiToken, containerIdentifier, environment, children, }: ICloudAuthProviderProps): JSX.Element;
+/**
+ * Hook to access iCloud authentication state and methods.
+ *
+ * Must be used within an ICloudAuthProvider.
+ *
+ * @example
+ * ```tsx
+ * import { useICloudAuth } from "@reverbia/sdk/react";
+ *
+ * function ICloudStatus() {
+ *   const { isAuthenticated, isAvailable, requestAccess, logout } = useICloudAuth();
+ *
+ *   if (!isAvailable) {
+ *     return <p>iCloud is not available. Please load CloudKit JS.</p>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       {isAuthenticated ? (
+ *         <>
+ *           <span>Connected to iCloud</span>
+ *           <button onClick={logout}>Disconnect</button>
+ *         </>
+ *       ) : (
+ *         <button onClick={requestAccess}>Connect to iCloud</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @category Hooks
+ */
+declare function useICloudAuth(): ICloudAuthContextValue;
+/**
+ * Check if iCloud is configured (has API token)
+ */
+declare function hasICloudCredentials(): boolean;
+/**
+ * Clear iCloud authentication state
+ * Note: This only clears local state; user remains signed in to iCloud
+ */
+declare function clearICloudAuth(): void;
+
+/**
+ * iCloud CloudKit API utilities
+ *
+ * Uses Apple CloudKit JS for file operations in iCloud Drive.
+ * Requires CloudKit container configuration and user authentication.
+ *
+ * CloudKit JS is loaded dynamically when needed.
+ */
+/** Default folder path for iCloud backups */
+declare const DEFAULT_BACKUP_FOLDER = "conversations";
+/** CloudKit record structure */
+interface CloudKitRecord {
+    recordName: string;
+    recordType: string;
+    fields: {
+        filename?: {
+            value: string;
+        };
+        data?: {
+            value: {
+                downloadURL: string;
+                size: number;
+            };
+        };
+    };
+    modified?: {
+        timestamp: number;
+    };
+    created?: {
+        timestamp: number;
+    };
+}
+/** CloudKit response structure */
+interface CloudKitResponse {
+    records?: CloudKitRecord[];
+    continuationMarker?: string;
+}
+declare global {
+    interface Window {
+        CloudKit?: {
+            configure: (config: {
+                containers: Array<{
+                    containerIdentifier: string;
+                    apiTokenAuth: {
+                        apiToken: string;
+                        persist: boolean;
+                        signInButton?: {
+                            id: string;
+                            theme?: string;
+                        };
+                        signOutButton?: {
+                            id: string;
+                            theme?: string;
+                        };
+                    };
+                    environment: string;
+                }>;
+            }) => void;
+            getDefaultContainer: () => CloudKitContainer;
+        };
+    }
+}
+interface CloudKitContainer {
+    containerIdentifier: string;
+    setUpAuth: (options?: {
+        buttonContainer?: HTMLElement;
+        signInButtonId?: string;
+        signOutButtonId?: string;
+    }) => Promise<CloudKitUserIdentity | null>;
+    whenUserSignsIn: () => Promise<CloudKitUserIdentity>;
+    whenUserSignsOut: () => Promise<void>;
+    privateCloudDatabase: CloudKitDatabase;
+}
+interface CloudKitUserIdentity {
+    userRecordName: string;
+    isDiscoverable?: boolean;
+}
+interface CloudKitDatabase {
+    saveRecords: (records: CloudKitRecordToSave | CloudKitRecordToSave[], options?: {
+        zoneName?: string;
+    }) => Promise<CloudKitResponse>;
+    deleteRecords: (recordNames: {
+        recordName: string;
+    }[], options?: {
+        zoneName?: string;
+    }) => Promise<CloudKitResponse>;
+    performQuery: (query: CloudKitQuery) => Promise<CloudKitResponse>;
+    fetchRecords: (recordNames: Array<{
+        recordName: string;
+    }>, options?: {
+        desiredKeys?: string[];
+    }) => Promise<CloudKitResponse>;
+}
+interface CloudKitRecordToSave {
+    recordType: string;
+    recordName?: string;
+    fields: Record<string, {
+        value: unknown;
+    }>;
+}
+interface CloudKitQuery {
+    recordType: string;
+    filterBy?: Array<{
+        fieldName: string;
+        comparator: string;
+        fieldValue: {
+            value: unknown;
+        };
+    }>;
+    sortBy?: Array<{
+        fieldName: string;
+        ascending: boolean;
+    }>;
+}
+
+/**
+ * iCloud Backup Implementation
+ *
+ * Generic backup/restore functionality for iCloud storage.
+ * Works directly with WatermelonDB database.
+ */
+
+interface ICloudExportResult {
+    success: boolean;
+    uploaded: number;
+    skipped: number;
+    total: number;
+}
+interface ICloudImportResult {
+    success: boolean;
+    restored: number;
+    failed: number;
+    total: number;
+    /** True if no backups were found in iCloud */
+    noBackupsFound?: boolean;
+}
+
+/**
+ * Options for useICloudBackup hook
+ */
+interface UseICloudBackupOptions {
+    /** WatermelonDB database instance */
+    database: Database;
+    /** Current user address (null if not signed in) */
+    userAddress: string | null;
+    /** Request encryption key for the user address */
+    requestEncryptionKey: (address: string) => Promise<void>;
+    /** Export a conversation to an encrypted blob */
+    exportConversation: (conversationId: string, userAddress: string) => Promise<{
+        success: boolean;
+        blob?: Blob;
+    }>;
+    /** Import a conversation from an encrypted blob */
+    importConversation: (blob: Blob, userAddress: string) => Promise<{
+        success: boolean;
+    }>;
+}
+/**
+ * Result returned by useICloudBackup hook
+ */
+interface UseICloudBackupResult {
+    /** Backup all conversations to iCloud */
+    backup: (options?: {
+        onProgress?: (current: number, total: number) => void;
+    }) => Promise<ICloudExportResult | {
+        error: string;
+    }>;
+    /** Restore conversations from iCloud */
+    restore: (options?: {
+        onProgress?: (current: number, total: number) => void;
+    }) => Promise<ICloudImportResult | {
+        error: string;
+    }>;
+    /** Whether iCloud is configured */
+    isConfigured: boolean;
+    /** Whether user has signed in to iCloud */
+    isAuthenticated: boolean;
+    /** Whether CloudKit JS is available */
+    isAvailable: boolean;
+}
+/**
+ * React hook for iCloud backup and restore functionality.
+ *
+ * This hook provides methods to backup conversations to iCloud and restore them.
+ * It handles all the logic for checking timestamps, skipping unchanged files,
+ * authentication, and managing the backup/restore process.
+ *
+ * Must be used within an ICloudAuthProvider.
+ *
+ * @example
+ * ```tsx
+ * import { useICloudBackup } from "@reverbia/sdk/react";
+ *
+ * function BackupButton() {
+ *   const { backup, restore, isConfigured, isAuthenticated, isAvailable } = useICloudBackup({
+ *     database,
+ *     userAddress,
+ *     requestEncryptionKey,
+ *     exportConversation,
+ *     importConversation,
+ *   });
+ *
+ *   if (!isAvailable) {
+ *     return <p>CloudKit JS not loaded</p>;
+ *   }
+ *
+ *   const handleBackup = async () => {
+ *     const result = await backup({
+ *       onProgress: (current, total) => {
+ *         console.log(`Progress: ${current}/${total}`);
+ *       },
+ *     });
+ *
+ *     if ("error" in result) {
+ *       console.error(result.error);
+ *     } else {
+ *       console.log(`Uploaded: ${result.uploaded}, Skipped: ${result.skipped}`);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleBackup} disabled={!isConfigured}>Backup to iCloud</button>;
+ * }
+ * ```
+ *
+ * @category Hooks
+ */
+declare function useICloudBackup(options: UseICloudBackupOptions): UseICloudBackupResult;
+
 /**
  * Props for BackupAuthProvider
  *
- * At least one of `dropboxAppKey` or `googleClientId` should be provided
- * for the provider to be useful. Both are optional to allow using just
- * one backup provider.
+ * At least one of `dropboxAppKey`, `googleClientId`, or `icloudApiToken` should be provided
+ * for the provider to be useful. All are optional to allow using just one backup provider.
  */
 interface BackupAuthProviderProps {
     /** Dropbox App Key (from Dropbox Developer Console). Optional - omit to disable Dropbox. */
@@ -2207,6 +2540,12 @@ interface BackupAuthProviderProps {
     googleClientId?: string;
     /** Google OAuth callback path (default: "/auth/google/callback") */
     googleCallbackPath?: string;
+    /** CloudKit API token (from Apple Developer Console). Optional - omit to disable iCloud. */
+    icloudApiToken?: string;
+    /** CloudKit container identifier (default: "iCloud.Memoryless") */
+    icloudContainerIdentifier?: string;
+    /** CloudKit environment (default: "production") */
+    icloudEnvironment?: "development" | "production";
     /**
      * API client for backend OAuth requests. Optional - uses the default SDK client if not provided.
      * Only needed if you have a custom client configuration (e.g., different baseUrl).
@@ -2240,6 +2579,8 @@ interface BackupAuthContextValue {
     dropbox: ProviderAuthState;
     /** Google Drive authentication state and methods */
     googleDrive: ProviderAuthState;
+    /** iCloud authentication state and methods */
+    icloud: ProviderAuthState;
     /** Check if any provider is configured */
     hasAnyProvider: boolean;
     /** Check if any provider is authenticated */
@@ -2265,6 +2606,8 @@ interface BackupAuthContextValue {
  *       dropboxCallbackPath="/auth/dropbox/callback"
  *       googleClientId={process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID}
  *       googleCallbackPath="/auth/google/callback"
+ *       icloudApiToken={process.env.NEXT_PUBLIC_CLOUDKIT_API_TOKEN}
+ *       icloudContainerIdentifier="iCloud.Memoryless"
  *       apiClient={apiClient}
  *     >
  *       <MyApp />
@@ -2275,7 +2618,7 @@ interface BackupAuthContextValue {
  *
  * @category Components
  */
-declare function BackupAuthProvider({ dropboxAppKey, dropboxCallbackPath, googleClientId, googleCallbackPath, apiClient, children, }: BackupAuthProviderProps): JSX.Element;
+declare function BackupAuthProvider({ dropboxAppKey, dropboxCallbackPath, googleClientId, googleCallbackPath, icloudApiToken, icloudContainerIdentifier, icloudEnvironment, apiClient, children, }: BackupAuthProviderProps): JSX.Element;
 /**
  * Hook to access unified backup authentication state and methods.
  *
@@ -2369,11 +2712,11 @@ interface ProviderBackupState {
     /** Whether user has authenticated with this provider */
     isAuthenticated: boolean;
     /** Backup all conversations to this provider */
-    backup: (options?: BackupOperationOptions) => Promise<DropboxExportResult | GoogleDriveExportResult | {
+    backup: (options?: BackupOperationOptions) => Promise<DropboxExportResult | GoogleDriveExportResult | ICloudExportResult | {
         error: string;
     }>;
     /** Restore conversations from this provider */
-    restore: (options?: BackupOperationOptions) => Promise<DropboxImportResult | GoogleDriveImportResult | {
+    restore: (options?: BackupOperationOptions) => Promise<DropboxImportResult | GoogleDriveImportResult | ICloudImportResult | {
         error: string;
     }>;
     /** Request access to this provider (triggers OAuth if needed) */
@@ -2389,6 +2732,8 @@ interface UseBackupResult {
     dropbox: ProviderBackupState;
     /** Google Drive backup state and methods */
     googleDrive: ProviderBackupState;
+    /** iCloud backup state and methods */
+    icloud: ProviderBackupState;
     /** Whether any backup provider is configured */
     hasAnyProvider: boolean;
     /** Whether any backup provider is authenticated */
@@ -2462,4 +2807,4 @@ interface UseBackupResult {
  */
 declare function useBackup(options: UseBackupOptions): UseBackupResult;
 
-export { DEFAULT_CONVERSATIONS_FOLDER as BACKUP_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as BACKUP_DRIVE_ROOT_FOLDER, type BackupAuthContextValue, BackupAuthProvider, type BackupAuthProviderProps, type BackupOperationOptions, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ClientTool, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, DEFAULT_BACKUP_FOLDER, DEFAULT_CONVERSATIONS_FOLDER as DEFAULT_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as DEFAULT_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER as DEFAULT_DROPBOX_FOLDER, DEFAULT_TOOL_SELECTOR_MODEL, type DropboxAuthContextValue, DropboxAuthProvider, type DropboxAuthProviderProps, type DropboxExportResult, type DropboxImportResult, type FileMetadata, type GoogleDriveAuthContextValue, GoogleDriveAuthProvider, type GoogleDriveAuthProviderProps, type GoogleDriveExportResult, type GoogleDriveImportResult, type MemoryItem, type MemoryType, type OCRFile, type PdfFile, type ProgressCallback, type ProviderAuthState, type ProviderBackupState, type SearchMessagesOptions, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type SignMessageFn, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, ModelPreference as StoredModelPreferenceModel, type ToolExecutionResult, type ToolParameter, type ToolSelectionResult, type UpdateMemoryOptions, type UpdateModelPreferenceOptions, type UseBackupOptions, type UseBackupResult, type UseChatStorageOptions, type UseChatStorageResult, type UseDropboxBackupOptions, type UseDropboxBackupResult, type UseGoogleDriveBackupOptions, type UseGoogleDriveBackupResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseSettingsOptions, type UseSettingsResult, chatStorageMigrations, chatStorageSchema, clearToken as clearDropboxToken, clearGoogleDriveToken, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, executeTool, extractConversationContext, formatMemoriesForChat, generateCompositeKey, generateConversationId, generateUniqueKey, getGoogleDriveStoredToken, hasDropboxCredentials, hasEncryptionKey, hasGoogleDriveCredentials, memoryStorageSchema, requestEncryptionKey, sdkMigrations, sdkModelClasses, sdkSchema, selectTool, settingsStorageSchema, useBackup, useBackupAuth, useChat, useChatStorage, useDropboxAuth, useDropboxBackup, useEncryption, useGoogleDriveAuth, useGoogleDriveBackup, useImageGeneration, useMemoryStorage, useModels, useOCR, usePdf, useSearch, useSettings };
+export { DEFAULT_CONVERSATIONS_FOLDER as BACKUP_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as BACKUP_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER as BACKUP_ICLOUD_FOLDER, type BackupAuthContextValue, BackupAuthProvider, type BackupAuthProviderProps, type BackupOperationOptions, Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ClientTool, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type CreateModelPreferenceOptions, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_BACKUP_FOLDER, DEFAULT_CONVERSATIONS_FOLDER as DEFAULT_DRIVE_CONVERSATIONS_FOLDER, DEFAULT_ROOT_FOLDER as DEFAULT_DRIVE_ROOT_FOLDER, DEFAULT_BACKUP_FOLDER$1 as DEFAULT_DROPBOX_FOLDER, DEFAULT_BACKUP_FOLDER as DEFAULT_ICLOUD_BACKUP_FOLDER, DEFAULT_TOOL_SELECTOR_MODEL, type DropboxAuthContextValue, DropboxAuthProvider, type DropboxAuthProviderProps, type DropboxExportResult, type DropboxImportResult, type FileMetadata, type GoogleDriveAuthContextValue, GoogleDriveAuthProvider, type GoogleDriveAuthProviderProps, type GoogleDriveExportResult, type GoogleDriveImportResult, type ICloudAuthContextValue, ICloudAuthProvider, type ICloudAuthProviderProps, type ICloudExportResult, type ICloudImportResult, type MemoryItem, type MemoryType, type OCRFile, type PdfFile, type ProgressCallback, type ProviderAuthState, type ProviderBackupState, type SearchMessagesOptions, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type SignMessageFn, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type StoredModelPreference, ModelPreference as StoredModelPreferenceModel, type ToolExecutionResult, type ToolParameter, type ToolSelectionResult, type UpdateMemoryOptions, type UpdateModelPreferenceOptions, type UseBackupOptions, type UseBackupResult, type UseChatStorageOptions, type UseChatStorageResult, type UseDropboxBackupOptions, type UseDropboxBackupResult, type UseGoogleDriveBackupOptions, type UseGoogleDriveBackupResult, type UseICloudBackupOptions, type UseICloudBackupResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseSettingsOptions, type UseSettingsResult, chatStorageMigrations, chatStorageSchema, clearToken as clearDropboxToken, clearGoogleDriveToken, clearICloudAuth, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, executeTool, extractConversationContext, formatMemoriesForChat, generateCompositeKey, generateConversationId, generateUniqueKey, getGoogleDriveStoredToken, hasDropboxCredentials, hasEncryptionKey, hasGoogleDriveCredentials, hasICloudCredentials, memoryStorageSchema, requestEncryptionKey, sdkMigrations, sdkModelClasses, sdkSchema, selectTool, settingsStorageSchema, useBackup, useBackupAuth, useChat, useChatStorage, useDropboxAuth, useDropboxBackup, useEncryption, useGoogleDriveAuth, useGoogleDriveBackup, useICloudAuth, useICloudBackup, useImageGeneration, useMemoryStorage, useModels, useOCR, usePdf, useSearch, useSettings };