useChatStorage

useChatStorage(options: object): UseChatStorageResult

Defined in: src/expo/useChatStorage.ts:250

A React hook that wraps useChat with automatic message persistence using WatermelonDB.

Expo/React Native version - This is a lightweight version that only supports API-based chat completions. Local chat and client-side tools are not available.

Parameters

Parameter	Type	Description
`options`	`object`	Configuration options
`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`	Auto-flush queued operations when key becomes available. 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.
`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. 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 to poll for wallet address during Privy initialization.
`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.
`options.walletAddress?`	`string`	Wallet address for field-level encryption. When provided with signMessage, all sensitive content is encrypted at rest.

Returns

UseChatStorageResult

An object containing chat state, methods, and storage operations

Example


import { Database } from '@nozbe/watermelondb';
import { useChatStorage } from '@reverbia/sdk/expo';
 
function ChatScreen({ database }: { database: Database }) {
  const {
    isLoading,
    sendMessage,
    conversationId,
    getMessages,
  } = useChatStorage({
    database,
    getToken: async () => getAuthToken(),
    onData: (chunk) => setResponse((prev) => prev + chunk),
  });
 
  const handleSend = async () => {
    const result = await sendMessage({
      content: 'Hello!',
      model: 'gpt-4o-mini',
      includeHistory: true,
    });
  };
 
  return (
    <View>
      <Button onPress={handleSend} disabled={isLoading} title="Send" />
    </View>
  );
}