UseChatStorageOptions

Defined in: src/react/useChatStorage.ts:670

Options for useChatStorage hook (React version)

Extends base options with apiType support.

Extends

BaseUseChatStorageOptions

Properties

activeToolSets?

optional activeToolSets: string[]

Defined in: src/react/useChatStorage.ts:752

Tool set names that should expand unconditionally for this request, bypassing the anchor-similarity check. Use when conversation state implies a set should be present regardless of how the prompt is phrased — e.g., pass ["slides"] when the conversation already contains a slide deck artifact, so short follow-up prompts (“add a thank you slide”, “make it bigger”) still get the full slide toolkit.

Read via a ref so updates are visible to in-flight sendMessage calls without rebuilding the callback.

Names must match a set’s name from BUILT_IN_TOOL_SETS or extraToolSets. Unknown names are ignored.

apiType?

optional apiType: ApiType

Defined in: src/react/useChatStorage.ts:676

Which API endpoint to use. Default: “responses”

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

autoCreateConversation?

optional autoCreateConversation: boolean

Defined in: src/lib/db/chat/types.ts:346

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

Inherited from

BaseUseChatStorageOptions.autoCreateConversation

autoEmbedMessages?

optional autoEmbedMessages: boolean

Defined in: src/lib/db/chat/types.ts:404

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

Default


true

Inherited from

BaseUseChatStorageOptions.autoEmbedMessages

autoFlushOnKeyAvailable?

optional autoFlushOnKeyAvailable: boolean

Defined in: src/react/useChatStorage.ts:725

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

Default


true

baseUrl?

optional baseUrl: string

Defined in: src/lib/db/chat/types.ts:352

Base URL for the chat API endpoint

Inherited from

BaseUseChatStorageOptions.baseUrl

conversationId?

optional conversationId: string

Defined in: src/lib/db/chat/types.ts:344

ID of an existing conversation to load and continue

Inherited from

BaseUseChatStorageOptions.conversationId

database

database: Database

Defined in: src/lib/db/chat/types.ts:342

WatermelonDB database instance for storing conversations and messages

Inherited from

BaseUseChatStorageOptions.database

defaultConversationTitle?

optional defaultConversationTitle: string

Defined in: src/lib/db/chat/types.ts:348

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

Inherited from

BaseUseChatStorageOptions.defaultConversationTitle

embeddedWalletSigner?

optional embeddedWalletSigner: EmbeddedWalletSignerFn

Defined in: src/react/useChatStorage.ts:703

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

embeddingModel?

optional embeddingModel: string

Defined in: src/lib/db/chat/types.ts:409

Embedding model to use when autoEmbedMessages is enabled.

Default


DEFAULT_API_EMBEDDING_MODEL

Inherited from

BaseUseChatStorageOptions.embeddingModel

enableQueue?

optional enableQueue: boolean

Defined in: src/react/useChatStorage.ts:718

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

extraToolSets?

optional extraToolSets: ToolSet[]

Defined in: src/react/useChatStorage.ts:736

Additional tool sets to apply on top of the built-in ones (app-generation, slides, github). When any anchor tool in a custom set is selected by semantic matching, all members of that set are included automatically.

Treated as static config — set once at hook setup. Changing it across renders does not affect in-flight sendMessage calls; use activeToolSets for dynamic, conversation-state-driven overrides.

fileProcessingOptions?

optional fileProcessingOptions: object

Defined in: src/lib/db/chat/types.ts:381

Options for file preprocessing behavior

keepOriginalFiles?

optional keepOriginalFiles: boolean

Whether to keep original file attachments (default: true)

maxFileSizeBytes?

optional maxFileSizeBytes: number

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

onError()?

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

Callback for errors (non-fatal)

Parameters

Parameter	Type
`fileName`	`string`
`error`	`Error`

Returns

void

onProgress()?

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

Callback for progress updates

Parameters

Parameter	Type
`current`	`number`
`total`	`number`
`fileName`	`string`

Returns

void

Inherited from

BaseUseChatStorageOptions.fileProcessingOptions

fileProcessors?

optional fileProcessors: FileProcessor[] | null

Defined in: src/lib/db/chat/types.ts:377

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

Inherited from

BaseUseChatStorageOptions.fileProcessors

getToken()?

optional getToken: () => Promise<string | null>

Defined in: src/lib/db/chat/types.ts:350

Function to retrieve the auth token for API requests

Returns

Promise<string | null>

Inherited from

BaseUseChatStorageOptions.getToken

getWalletAddress()?

optional getWalletAddress: () => Promise<string | null>

Defined in: src/react/useChatStorage.ts:710

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.

Returns

Promise<string | null>

mcpR2Domain?

optional mcpR2Domain: string

Defined in: src/lib/db/chat/types.ts:421

R2 domain for identifying MCP-generated image URLs. When set, enables OPFS caching of generated images. Defaults to the hardcoded MCP_R2_DOMAIN from clientConfig.

Inherited from

BaseUseChatStorageOptions.mcpR2Domain

minContentLength?

optional minContentLength: number

Defined in: src/lib/db/chat/types.ts:415

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

Default

Inherited from

BaseUseChatStorageOptions.minContentLength

onData()?

optional onData: (chunk: string) => void

Defined in: src/lib/db/chat/types.ts:354

Callback invoked with each streamed response chunk

Parameters

Parameter	Type
`chunk`	`string`

Returns

void

Inherited from

BaseUseChatStorageOptions.onData

onError()?

optional onError: (error: Error) => void

Defined in: src/lib/db/chat/types.ts:360

Callback invoked when an error occurs during the request

Parameters

Parameter	Type
`error`	`Error`

Returns

void

Inherited from

BaseUseChatStorageOptions.onError

onFinish()?

optional onFinish: (response: LlmapiResponseResponse) => void

Defined in: src/lib/db/chat/types.ts:358

Callback invoked when the response completes successfully

Parameters

Parameter	Type
`response`	`LlmapiResponseResponse`

Returns

void

Inherited from

BaseUseChatStorageOptions.onFinish

onServerToolCall()?

optional onServerToolCall: (toolCall: ServerToolCallEvent) => void

Defined in: src/lib/db/chat/types.ts:365

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

Parameters

Parameter	Type
`toolCall`	`ServerToolCallEvent`

Returns

void

Inherited from

BaseUseChatStorageOptions.onServerToolCall

onThinking()?

optional onThinking: (chunk: string) => void

Defined in: src/lib/db/chat/types.ts:356

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

Parameters

Parameter	Type
`chunk`	`string`

Returns

void

Inherited from

BaseUseChatStorageOptions.onThinking

onToolCallArgumentsDelta()?

optional onToolCallArgumentsDelta: (event: ToolCallArgumentsDeltaEvent) => void

Defined in: src/lib/db/chat/types.ts:370

Called with partial tool call arguments as they stream in. Use for live preview of artifacts (HTML, slides) being generated.

Parameters

Parameter	Type
`event`	`ToolCallArgumentsDeltaEvent`

Returns

void

Inherited from

BaseUseChatStorageOptions.onToolCallArgumentsDelta

preProcessors?

optional preProcessors: PromptPreProcessor[]

Defined in: src/lib/db/chat/types.ts:431

Pre-processors run after the last user message is received but before the first LLM request. Each receives the prompt text and a shared embedding (computed once per request) and may return messages to enrich the conversation. Forwarded to the underlying useChat hook. See createWebSearchPreProcessor, createCryptoPricePreProcessor, createStockPricePreProcessor, createWeatherPreProcessor, or write a custom one matching PromptPreProcessor.

Inherited from

BaseUseChatStorageOptions.preProcessors

serverTools?

optional serverTools: object

Defined in: src/lib/db/chat/types.ts:395

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

cacheExpirationMs?

optional cacheExpirationMs: number

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

Inherited from

BaseUseChatStorageOptions.serverTools

signMessage?

optional signMessage: SignMessageFn

Defined in: src/react/useChatStorage.ts:696

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

walletAddress?

optional walletAddress: string

Defined in: src/react/useChatStorage.ts:689

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).