useChatStorage

options

object

‐

options.apiType?

ApiType

Which API endpoint to use. Default: “responses”

• “responses”: OpenAI Responses API (supports thinking, reasoning, conversations)
• “completions”: OpenAI Chat Completions API (wider model compatibility)

options.autoCreateConversation?

boolean

Automatically create a new conversation if none is set (default: true)

options.autoEmbedMessages?

boolean

Automatically generate embeddings for messages after saving. Enables semantic search over past conversations via searchMessages().

Default

true

options.autoFlushOnKeyAvailable?

boolean

Automatically flush queued operations when the encryption key becomes available. Requires enableQueue to be true.

Default

true

options.baseUrl?

string

Base URL for the chat API endpoint

options.conversationId?

string

ID of an existing conversation to load and continue

options.database

Database

WatermelonDB database instance for storing conversations and messages

options.defaultConversationTitle?

string

Title for auto-created conversations (default: “New conversation”)

options.embeddedWalletSigner?

EmbeddedWalletSignerFn

Function for silent signing with Privy embedded wallets. When provided, enables automatic encryption key derivation without user confirmation modals.

options.embeddingModel?

string

Embedding model to use when autoEmbedMessages is enabled.

Default

DEFAULT_API_EMBEDDING_MODEL

options.enableQueue?

boolean

Enable the in-memory write queue for operations when encryption key isn’t yet available. When enabled, operations are held in memory and flushed to encrypted storage once the key becomes available.

Default

true

options.fileProcessingOptions?

{ keepOriginalFiles?: boolean; maxFileSizeBytes?: number; onError?: (fileName: string, error: Error) => void; onProgress?: (current: number, total: number, fileName: string) => void; }

Options for file preprocessing behavior

options.fileProcessingOptions.keepOriginalFiles?

boolean

Whether to keep original file attachments (default: true)

options.fileProcessingOptions.maxFileSizeBytes?

number

Max file size to process in bytes (default: 10MB)

options.fileProcessingOptions.onError?

(fileName: string, error: Error) => void

Callback for errors (non-fatal)

options.fileProcessingOptions.onProgress?

(current: number, total: number, fileName: string) => void

Callback for progress updates

options.fileProcessors?

any[] | null

File preprocessors to use for automatic text extraction.

• undefined (default): Use all built-in processors (PDF, Excel, Word)
• null or []: Disable preprocessing
• FileProcessor[]: Use specific processors

options.getToken?

() => Promise<string | null>

Function to retrieve the auth token for API requests

options.getWalletAddress?

() => Promise<string | null>

Async function that returns the wallet address when available. Used for polling during Privy embedded wallet initialization. When the wallet isn’t ready yet, should return null.

options.minContentLength?

number

Minimum content length required to generate embeddings. Messages shorter than this are skipped as they provide limited semantic value.

Default

10

options.onData?

(chunk: string) => void

Callback invoked with each streamed response chunk

options.onError?

(error: Error) => void

Callback invoked when an error occurs during the request

options.onFinish?

(response: LlmapiResponseResponse) => void

Callback invoked when the response completes successfully

options.onServerToolCall?

(toolCall: ServerToolCallEvent) => void

Callback invoked when a server-side tool (MCP) is called during streaming. Use this to show activity indicators like “Searching…” in the UI.

options.onThinking?

(chunk: string) => void

Callback invoked when thinking/reasoning content is received (from <think> tags or API reasoning)

options.serverTools?

{ cacheExpirationMs?: number; }

Configuration for server-side tools fetching and caching. Server tools are fetched from /api/v1/tools and cached in localStorage.

options.serverTools.cacheExpirationMs?

number

Cache expiration time in milliseconds (default: 86400000 = 1 day)

options.signMessage?

SignMessageFn

Function to sign a message for encryption key derivation. Typically from Privy’s useSignMessage hook. Required together with walletAddress for field-level encryption.

options.walletAddress?

string

Wallet address for encrypted file storage and field-level encryption. When provided with signMessage, all sensitive message content, conversation titles, and media metadata are encrypted at rest using AES-GCM with wallet-derived keys.

Requires:

• OPFS browser support (for file storage)
• signMessage function (for encryption key derivation)

When not provided, data is stored in plaintext (backwards compatible).