@reverbia/sdk 1.0.0-next.20251217123222 → 1.0.0-next.20251217144159

package/dist/react/index.d.mts

@@ -1,6 +1,8 @@
 import { Database, Model } from '@nozbe/watermelondb';
+import * as _nozbe_watermelondb_Schema_migrations from '@nozbe/watermelondb/Schema/migrations';
 import * as _nozbe_watermelondb_Schema from '@nozbe/watermelondb/Schema';
 import { Associations } from '@nozbe/watermelondb/Model';
+import { ReactNode, JSX } from 'react';
 
 /**
  * ExtraFields contains additional metadata
@@ -475,7 +477,7 @@ type SendMessageResult = {
     error: null;
     toolExecution?: ToolExecutionResult;
 } | {
-    data: null;
+    data: LlmapiChatCompletionResponse | null;
     error: string;
     toolExecution?: ToolExecutionResult;
 };
@@ -706,6 +708,8 @@ interface StoredMessage {
     sources?: SearchSource[];
     /** Response time in seconds */
     responseDuration?: number;
+    /** Whether the message generation was stopped by the user */
+    wasStopped?: boolean;
 }
 /**
  * Stored conversation record
@@ -755,6 +759,8 @@ interface CreateMessageOptions {
     vector?: number[];
     /** Model used to generate the embedding */
     embeddingModel?: string;
+    /** Whether the message generation was stopped by the user */
+    wasStopped?: boolean;
 }
 /**
  * Options for creating a new conversation
@@ -982,6 +988,15 @@ declare const chatStorageSchema: Readonly<{
     tables: _nozbe_watermelondb_Schema.TableMap;
     unsafeSql?: (_: string, __: _nozbe_watermelondb_Schema.AppSchemaUnsafeSqlKind) => string;
 }>;
+/**
+ * Schema migrations
+ */
+declare const chatStorageMigrations: Readonly<{
+    validated: true;
+    minVersion: _nozbe_watermelondb_Schema.SchemaVersion;
+    maxVersion: _nozbe_watermelondb_Schema.SchemaVersion;
+    sortedMigrations: _nozbe_watermelondb_Schema_migrations.Migration[];
+}>;
 
 /**
  * Message model representing a single chat message
@@ -1018,6 +1033,8 @@ declare class Message extends Model {
     get sources(): SearchSource[] | undefined;
     /** Response time in seconds */
     get responseDuration(): number | undefined;
+    /** Whether the message generation was stopped by the user */
+    get wasStopped(): boolean;
 }
 /**
  * Conversation model representing conversation metadata
@@ -1396,6 +1413,139 @@ declare class Memory extends Model {
     get isDeleted(): boolean;
 }
 
+/**
+ * Stored model preference record (what gets persisted to the database)
+ */
+interface StoredModelPreference {
+    /** Primary key (WatermelonDB auto-generated) */
+    uniqueId: string;
+    /** User's wallet address */
+    walletAddress: string;
+    /** Preferred model identifiers */
+    models?: string;
+}
+/**
+ * Options for creating a new model preference
+ */
+interface CreateModelPreferenceOptions {
+    /** User's wallet address */
+    walletAddress: string;
+    /** Preferred model identifiers */
+    models?: string;
+}
+/**
+ * Options for updating a model preference
+ */
+interface UpdateModelPreferenceOptions {
+    /** New preferred model identifiers */
+    models?: string;
+}
+/**
+ * Base options for useSettings hook
+ */
+interface BaseUseSettingsOptions {
+    /** WatermelonDB database instance */
+    database: Database;
+    /** User's wallet address */
+    walletAddress?: string;
+}
+/**
+ * Base result returned by useSettings hook
+ */
+interface BaseUseSettingsResult {
+    /** Current model preference */
+    modelPreference: StoredModelPreference | null;
+    /** Whether the settings are loading */
+    isLoading: boolean;
+    /** Get model preference by wallet address. Throws on error. */
+    getModelPreference: (walletAddress: string) => Promise<StoredModelPreference | null>;
+    /** Create or update model preference. Throws on error. */
+    setModelPreference: (walletAddress: string, models?: string) => Promise<StoredModelPreference | null>;
+    /** Delete model preference. Throws on error. */
+    deleteModelPreference: (walletAddress: string) => Promise<boolean>;
+}
+
+/**
+ * Options for useSettings hook (React version)
+ */
+interface UseSettingsOptions extends BaseUseSettingsOptions {
+}
+/**
+ * Result returned by useSettings hook (React version)
+ */
+interface UseSettingsResult extends BaseUseSettingsResult {
+}
+/**
+ * A React hook for managing user settings with automatic persistence using WatermelonDB.
+ *
+ * This hook provides methods to get, set, and delete user model preferences,
+ * with automatic loading of preferences when a wallet address is provided.
+ *
+ * @param options - Configuration options
+ * @returns An object containing settings state and methods
+ *
+ * @example
+ * ```tsx
+ * import { Database } from '@nozbe/watermelondb';
+ * import { useSettings } from '@reverbia/sdk/react';
+ *
+ * function SettingsComponent({ database }: { database: Database }) {
+ *   const {
+ *     modelPreference,
+ *     isLoading,
+ *     setModelPreference,
+ *     getModelPreference,
+ *     deleteModelPreference,
+ *   } = useSettings({
+ *     database,
+ *     walletAddress: '0x123...', // Optional: auto-loads preference for this wallet
+ *   });
+ *
+ *   const handleModelChange = async (model: string) => {
+ *     await setModelPreference('0x123...', model);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>Current model: {modelPreference?.model ?? 'Not set'}</p>
+ *       <button onClick={() => handleModelChange('gpt-4o')}>
+ *         Use GPT-4o
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @category Hooks
+ */
+declare function useSettings(options: UseSettingsOptions): UseSettingsResult;
+
+/**
+ * WatermelonDB schema for settings storage
+ *
+ * * Defines one table::
+ * - modelPreferences: Model preferences metadata
+ */
+declare const settingsStorageSchema: Readonly<{
+    version: _nozbe_watermelondb_Schema.SchemaVersion;
+    tables: _nozbe_watermelondb_Schema.TableMap;
+    unsafeSql?: (_: string, __: _nozbe_watermelondb_Schema.AppSchemaUnsafeSqlKind) => string;
+}>;
+
+/**
+ * ModelPreference model representing user model preferences
+ *
+ * Note: This model uses raw column accessors instead of decorators
+ * for better TypeScript compatibility without requiring legacy decorators.
+ */
+declare class ModelPreference extends Model {
+    static table: string;
+    /** User's wallet address */
+    get walletAddress(): string;
+    /** Preferred model identifier */
+    get models(): string | undefined;
+}
+
 interface PdfFile {
     url: string;
     mediaType?: string;
@@ -1608,4 +1758,352 @@ declare function executeTool(tool: ClientTool, params: Record<string, unknown>):
     error?: string;
 }>;
 
-export { Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type ClientTool, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, DEFAULT_TOOL_SELECTOR_MODEL, type FileMetadata, type MemoryItem, type MemoryType, type OCRFile, type PdfFile, 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 ToolExecutionResult, type ToolParameter, type ToolSelectionResult, type UpdateMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, chatStorageSchema, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, executeTool, extractConversationContext, formatMemoriesForChat, generateCompositeKey, generateConversationId, generateUniqueKey, hasEncryptionKey, memoryStorageSchema, requestEncryptionKey, selectTool, useChat, useChatStorage, useEncryption, useImageGeneration, useMemoryStorage, useModels, useOCR, usePdf, useSearch };
+/**
+ * Dropbox API utilities
+ *
+ * Uses Dropbox HTTP API for file operations.
+ * 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";
+
+/**
+ * Dropbox Backup Implementation
+ *
+ * Generic backup/restore functionality for Dropbox storage.
+ * Works directly with WatermelonDB database.
+ */
+
+interface DropboxExportResult {
+    success: boolean;
+    uploaded: number;
+    skipped: number;
+    total: number;
+}
+interface DropboxImportResult {
+    success: boolean;
+    restored: number;
+    failed: number;
+    total: number;
+    /** True if no backups were found in Dropbox */
+    noBackupsFound?: boolean;
+}
+
+/**
+ * Options for useDropboxBackup hook
+ */
+interface UseDropboxBackupOptions {
+    /** 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;
+    }>;
+    /** Dropbox folder path for backups (default: '/ai-chat-app/conversations') */
+    backupFolder?: string;
+}
+/**
+ * Result returned by useDropboxBackup hook
+ */
+interface UseDropboxBackupResult {
+    /** Backup all conversations to Dropbox */
+    backup: (options?: {
+        onProgress?: (current: number, total: number) => void;
+    }) => Promise<DropboxExportResult | {
+        error: string;
+    }>;
+    /** Restore conversations from Dropbox */
+    restore: (options?: {
+        onProgress?: (current: number, total: number) => void;
+    }) => Promise<DropboxImportResult | {
+        error: string;
+    }>;
+    /** Whether Dropbox is configured */
+    isConfigured: boolean;
+    /** Whether user has a Dropbox token */
+    isAuthenticated: boolean;
+}
+/**
+ * React hook for Dropbox backup and restore functionality.
+ *
+ * This hook provides methods to backup conversations to Dropbox 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 a DropboxAuthProvider.
+ *
+ * @example
+ * ```tsx
+ * import { useDropboxBackup } from "@reverbia/sdk/react";
+ *
+ * function BackupButton() {
+ *   const { backup, restore, isConfigured } = useDropboxBackup({
+ *     database,
+ *     userAddress,
+ *     requestEncryptionKey,
+ *     exportConversation,
+ *     importConversation,
+ *   });
+ *
+ *   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</button>;
+ * }
+ * ```
+ *
+ * @category Hooks
+ */
+declare function useDropboxBackup(options: UseDropboxBackupOptions): UseDropboxBackupResult;
+
+/**
+ * Dropbox OAuth 2.0 with PKCE
+ *
+ * Flow:
+ * 1. Generate code_verifier and code_challenge
+ * 2. Redirect user to Dropbox authorization URL
+ * 3. User authorizes and is redirected back with authorization code
+ * 4. Exchange code for access token using code_verifier
+ */
+/**
+ * Get the stored access token from session storage
+ */
+declare function getStoredToken(): string | null;
+/**
+ * Store access token in session storage
+ */
+declare function storeToken(token: string): void;
+/**
+ * Clear stored access token
+ */
+declare function clearToken(): void;
+
+/**
+ * Props for DropboxAuthProvider
+ */
+interface DropboxAuthProviderProps {
+    /** Dropbox App Key (from Dropbox Developer Console) */
+    appKey: string | undefined;
+    /** OAuth callback path (e.g., "/auth/dropbox/callback") */
+    callbackPath?: string;
+    /** Children to render */
+    children: ReactNode;
+}
+/**
+ * Context value for Dropbox authentication
+ */
+interface DropboxAuthContextValue {
+    /** Current access token (null if not authenticated) */
+    accessToken: string | null;
+    /** Whether user has authenticated with Dropbox */
+    isAuthenticated: boolean;
+    /** Whether Dropbox is configured (app key exists) */
+    isConfigured: boolean;
+    /** Request Dropbox access - returns token or redirects to OAuth */
+    requestAccess: () => Promise<string>;
+    /** Clear stored token and log out */
+    logout: () => void;
+}
+/**
+ * Provider component for Dropbox OAuth authentication.
+ *
+ * Wrap your app with this provider to enable Dropbox authentication.
+ * It handles the OAuth 2.0 PKCE flow automatically.
+ *
+ * @example
+ * ```tsx
+ * import { DropboxAuthProvider } from "@reverbia/sdk/react";
+ *
+ * function App() {
+ *   return (
+ *     <DropboxAuthProvider
+ *       appKey={process.env.NEXT_PUBLIC_DROPBOX_APP_KEY}
+ *       callbackPath="/auth/dropbox/callback"
+ *     >
+ *       <MyApp />
+ *     </DropboxAuthProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @category Components
+ */
+declare function DropboxAuthProvider({ appKey, callbackPath, children, }: DropboxAuthProviderProps): JSX.Element;
+/**
+ * Hook to access Dropbox authentication state and methods.
+ *
+ * Must be used within a DropboxAuthProvider.
+ *
+ * @example
+ * ```tsx
+ * import { useDropboxAuth } from "@reverbia/sdk/react";
+ *
+ * function DropboxButton() {
+ *   const { isAuthenticated, isConfigured, requestAccess, logout } = useDropboxAuth();
+ *
+ *   if (!isConfigured) {
+ *     return <p>Dropbox not configured</p>;
+ *   }
+ *
+ *   if (isAuthenticated) {
+ *     return <button onClick={logout}>Disconnect Dropbox</button>;
+ *   }
+ *
+ *   return <button onClick={requestAccess}>Connect Dropbox</button>;
+ * }
+ * ```
+ *
+ * @category Hooks
+ */
+declare function useDropboxAuth(): DropboxAuthContextValue;
+
+/**
+ * Google Drive API utilities
+ *
+ * Uses Google Drive API v3 for file operations.
+ * Requires an OAuth 2.0 access token with drive.file scope.
+ */
+/** Default root folder name for backups */
+declare const DEFAULT_ROOT_FOLDER = "ai-chat-app";
+/** Default subfolder for conversation backups */
+declare const DEFAULT_CONVERSATIONS_FOLDER = "conversations";
+
+/**
+ * Google Drive Backup Implementation
+ *
+ * Generic backup/restore functionality for Google Drive storage.
+ * Works directly with WatermelonDB database.
+ */
+
+interface GoogleDriveExportResult {
+    success: boolean;
+    uploaded: number;
+    skipped: number;
+    total: number;
+}
+interface GoogleDriveImportResult {
+    success: boolean;
+    restored: number;
+    failed: number;
+    total: number;
+    /** True if no backups were found in Google Drive */
+    noBackupsFound?: boolean;
+}
+
+/**
+ * Options for useGoogleDriveBackup hook
+ */
+interface UseGoogleDriveBackupOptions {
+    /** WatermelonDB database instance */
+    database: Database;
+    /** Current user address (null if not signed in) */
+    userAddress: string | null;
+    /** Current Google Drive access token (null if not authenticated) */
+    accessToken: string | null;
+    /** Request Google Drive access - returns access token */
+    requestDriveAccess: () => Promise<string>;
+    /** 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;
+    }>;
+    /** Root folder name in Google Drive (default: 'ai-chat-app') */
+    rootFolder?: string;
+    /** Subfolder for conversations (default: 'conversations') */
+    conversationsFolder?: string;
+}
+/**
+ * Result returned by useGoogleDriveBackup hook
+ */
+interface UseGoogleDriveBackupResult {
+    /** Backup all conversations to Google Drive */
+    backup: (options?: {
+        onProgress?: (current: number, total: number) => void;
+    }) => Promise<GoogleDriveExportResult | {
+        error: string;
+    }>;
+    /** Restore conversations from Google Drive */
+    restore: (options?: {
+        onProgress?: (current: number, total: number) => void;
+    }) => Promise<GoogleDriveImportResult | {
+        error: string;
+    }>;
+    /** Whether user has a Google Drive token */
+    isAuthenticated: boolean;
+}
+/**
+ * React hook for Google Drive backup and restore functionality.
+ *
+ * This hook provides methods to backup conversations to Google Drive and restore them.
+ * It handles all the logic for checking timestamps, skipping unchanged files,
+ * and managing the backup/restore process.
+ *
+ * Unlike Dropbox, Google Drive auth requires browser-specific setup (Google Identity Services),
+ * so the auth provider must be implemented in the app. This hook accepts the auth
+ * callbacks as options.
+ *
+ * @example
+ * ```tsx
+ * import { useGoogleDriveBackup } from "@reverbia/sdk/react";
+ *
+ * function BackupButton() {
+ *   const { accessToken, requestDriveAccess } = useGoogleAccessToken();
+ *   const { backup, restore, isAuthenticated } = useGoogleDriveBackup({
+ *     database,
+ *     userAddress,
+ *     accessToken,
+ *     requestDriveAccess,
+ *     requestEncryptionKey,
+ *     exportConversation,
+ *     importConversation,
+ *   });
+ *
+ *   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}>Backup</button>;
+ * }
+ * ```
+ *
+ * @category Hooks
+ */
+declare function useGoogleDriveBackup(options: UseGoogleDriveBackupOptions): UseGoogleDriveBackupResult;
+
+export { 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_TOOL_SELECTOR_MODEL, type DropboxAuthContextValue, DropboxAuthProvider, type DropboxAuthProviderProps, type DropboxExportResult, type DropboxImportResult, type FileMetadata, type GoogleDriveExportResult, type GoogleDriveImportResult, type MemoryItem, type MemoryType, type OCRFile, type PdfFile, 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 UseChatStorageOptions, type UseChatStorageResult, type UseDropboxBackupOptions, type UseDropboxBackupResult, type UseGoogleDriveBackupOptions, type UseGoogleDriveBackupResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseSettingsOptions, type UseSettingsResult, chatStorageMigrations, chatStorageSchema, clearToken as clearDropboxToken, createMemoryContextSystemMessage, decryptData, decryptDataBytes, encryptData, executeTool, extractConversationContext, formatMemoriesForChat, generateCompositeKey, generateConversationId, generateUniqueKey, getStoredToken as getDropboxToken, hasEncryptionKey, memoryStorageSchema, requestEncryptionKey, selectTool, settingsStorageSchema, storeToken as storeDropboxToken, useChat, useChatStorage, useDropboxAuth, useDropboxBackup, useEncryption, useGoogleDriveBackup, useImageGeneration, useMemoryStorage, useModels, useOCR, usePdf, useSearch, useSettings };