@reverbia/sdk 1.0.0-next.20260109140427 → 1.0.0-next.20260109180912

package/dist/expo/index.cjs

@@ -1303,6 +1303,36 @@ function finalizeThoughtProcess(thoughtProcess) {
     (phase, idx) => idx === thoughtProcess.length - 1 ? { ...phase, status: "completed" } : phase
   );
 }
+function extractUserMessageFromMessages(messages) {
+  if (!messages || messages.length === 0) {
+    return null;
+  }
+  const userMessages = messages.filter((m) => m.role === "user");
+  const lastUserMessage = userMessages[userMessages.length - 1];
+  if (!lastUserMessage || !lastUserMessage.content) {
+    return null;
+  }
+  const textParts = [];
+  const files = [];
+  for (const part of lastUserMessage.content) {
+    if (part.type === "text" && part.text) {
+      textParts.push(part.text);
+    } else if (part.type === "image_url" && part.image_url?.url) {
+      files.push({
+        id: `img_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+        name: "image",
+        type: "image/unknown",
+        size: 0,
+        url: part.image_url.url
+      });
+    }
+  }
+  const content = textParts.join("\n");
+  return {
+    content,
+    files: files.length > 0 ? files : void 0
+  };
+}
 
 // src/lib/db/chat/operations.ts
 var import_watermelondb3 = require("@nozbe/watermelondb");
@@ -1679,9 +1709,8 @@ function useChatStorage(options) {
   const sendMessage = (0, import_react2.useCallback)(
     async (args) => {
       const {
-        content,
+        messages,
         model,
-        messages: providedMessages,
         includeHistory = true,
         maxHistoryMessages = 50,
         files,
@@ -1702,6 +1731,15 @@ function useChatStorage(options) {
         reasoning,
         thinking
       } = args;
+      const extracted = extractUserMessageFromMessages(messages);
+      if (!extracted || !extracted.content) {
+        return {
+          data: null,
+          error: "No user message found in messages array"
+        };
+      }
+      const contentForStorage = extracted.content;
+      const filesForStorage = files ?? extracted.files;
       let convId;
       try {
         convId = await ensureConversation();
@@ -1712,33 +1750,18 @@ function useChatStorage(options) {
         };
       }
       let messagesToSend = [];
-      if (includeHistory && !providedMessages) {
+      if (includeHistory) {
         const storedMessages = await getMessages(convId);
         const validMessages = storedMessages.filter((msg) => !msg.error);
         const limitedMessages = validMessages.slice(-maxHistoryMessages);
-        messagesToSend = limitedMessages.map(storedToLlmapiMessage);
-      } else if (providedMessages) {
-        messagesToSend = providedMessages;
-      }
-      const userMessageContent = [
-        { type: "text", text: content }
-      ];
-      if (files?.length) {
-        for (const file of files) {
-          if (file.url) {
-            userMessageContent.push({
-              type: "image_url",
-              image_url: { url: file.url }
-            });
-          }
-        }
+        messagesToSend = [
+          ...limitedMessages.map(storedToLlmapiMessage),
+          ...messages
+        ];
+      } else {
+        messagesToSend = [...messages];
       }
-      const userMessage = {
-        role: "user",
-        content: userMessageContent
-      };
-      messagesToSend.push(userMessage);
-      const sanitizedFiles = files?.map((file) => ({
+      const sanitizedFiles = filesForStorage?.map((file) => ({
         id: file.id,
         name: file.name,
         type: file.type,
@@ -1751,7 +1774,7 @@ function useChatStorage(options) {
         storedUserMessage = await createMessageOp(storageCtx, {
           conversationId: convId,
           role: "user",
-          content,
+          content: contentForStorage,
           files: sanitizedFiles,
           model
         });

package/dist/expo/index.d.mts

@@ -554,6 +554,7 @@ type BaseSendMessageResult = {
 };
 /**
  * Base options for useChat hook
+ * @inline
  */
 type BaseUseChatOptions = {
     getToken?: () => Promise<string | null>;
@@ -623,6 +624,9 @@ type SendMessageArgs = BaseSendMessageArgs & {
     searchContext?: string;
 };
 type SendMessageResult = BaseSendMessageResult;
+/**
+ * @inline
+ */
 type UseChatOptions = BaseUseChatOptions;
 type UseChatResult = BaseUseChatResult & {
     sendMessage: (args: SendMessageArgs) => Promise<SendMessageResult>;
@@ -731,6 +735,9 @@ interface StoredMemory extends MemoryItem {
 interface StoredMemoryWithSimilarity extends StoredMemory {
     similarity: number;
 }
+/**
+ * @inline
+ */
 interface BaseUseMemoryStorageOptions {
     database: Database;
     completionsModel?: string;
@@ -871,27 +878,122 @@ interface UpdateMessageOptions {
  * @inline
  */
 interface BaseUseChatStorageOptions {
+    /** WatermelonDB database instance for storing conversations and messages */
     database: Database;
+    /** ID of an existing conversation to load and continue */
     conversationId?: string;
+    /** Automatically create a new conversation if none is set (default: true) */
     autoCreateConversation?: boolean;
+    /** Title for auto-created conversations (default: "New conversation") */
     defaultConversationTitle?: string;
+    /** Function to retrieve the auth token for API requests */
     getToken?: () => Promise<string | null>;
+    /** Base URL for the chat API endpoint */
     baseUrl?: string;
+    /** Callback invoked with each streamed response chunk */
     onData?: (chunk: string) => void;
+    /** Callback invoked when the response completes successfully */
     onFinish?: (response: LlmapiResponseResponse) => void;
+    /** Callback invoked when an error occurs during the request */
     onError?: (error: Error) => void;
 }
+/**
+ * Base arguments for sending a message with automatic storage.
+ *
+ * These arguments control both the AI request and how the message
+ * is persisted to the local database.
+ * @inline
+ */
 interface BaseSendMessageWithStorageArgs {
-    content: string;
+    /**
+     * The message array to send to the AI.
+     *
+     * Uses the modern array format that supports multimodal content (text, images, files).
+     * The last user message in this array will be extracted and stored in the database.
+     *
+     * When `includeHistory` is true (default), conversation history is prepended.
+     * When `includeHistory` is false, only these messages are sent.
+     *
+     * @example
+     * ```ts
+     * // Simple usage
+     * sendMessage({
+     *   messages: [
+     *     { role: "user", content: [{ type: "text", text: "Hello!" }] }
+     *   ]
+     * })
+     *
+     * // With system prompt and history disabled
+     * sendMessage({
+     *   messages: [
+     *     { role: "system", content: [{ type: "text", text: "You are helpful" }] },
+     *     { role: "user", content: [{ type: "text", text: "Question" }] },
+     *   ],
+     *   includeHistory: false
+     * })
+     *
+     * // With images
+     * sendMessage({
+     *   messages: [
+     *     { role: "user", content: [
+     *       { type: "text", text: "What's in this image?" },
+     *       { type: "image_url", image_url: { url: "data:image/png;base64,..." } }
+     *     ]}
+     *   ]
+     * })
+     * ```
+     */
+    messages: LlmapiMessage[];
+    /**
+     * The model identifier to use for this request (e.g., "gpt-4o", "claude-sonnet-4-20250514").
+     * If not specified, uses the default model configured on the server.
+     */
     model?: string;
-    messages?: LlmapiMessage[];
+    /**
+     * Whether to automatically include previous messages from the conversation as context.
+     * When true, fetches stored messages and prepends them to the request.
+     * Ignored if `messages` is provided.
+     * @default true
+     */
     includeHistory?: boolean;
+    /**
+     * Maximum number of historical messages to include when `includeHistory` is true.
+     * Only the most recent N messages are included to manage context window size.
+     * @default 50
+     */
     maxHistoryMessages?: number;
+    /**
+     * File attachments to include with the message (images, documents, etc.).
+     * Files with image MIME types and URLs are sent as image content parts.
+     * File metadata is stored with the message (URLs are stripped if they're data URIs).
+     */
     files?: FileMetadata[];
+    /**
+     * Per-request callback invoked with each streamed response chunk.
+     * Overrides the hook-level `onData` callback for this request only.
+     * Use this to update UI as the response streams in.
+     */
     onData?: (chunk: string) => void;
+    /**
+     * Additional context from memory/RAG system to include in the request.
+     * Typically contains retrieved relevant information from past conversations.
+     */
     memoryContext?: string;
+    /**
+     * Additional context from search results to include in the request.
+     * Typically contains relevant information from web or document searches.
+     */
     searchContext?: string;
+    /**
+     * Search sources to attach to the stored message for citation/reference.
+     * These are combined with any sources extracted from the assistant's response.
+     */
     sources?: SearchSource[];
+    /**
+     * Activity phases for tracking the request lifecycle in the UI.
+     * Each phase represents a step like "Searching", "Thinking", "Generating".
+     * The final phase is automatically marked as completed when stored.
+     */
     thoughtProcess?: ActivityPhase[];
     /**
      * Whether to store the response server-side.
@@ -909,33 +1011,43 @@ interface BaseSendMessageWithStorageArgs {
     serverConversation?: string;
     /**
      * Controls randomness in the response (0.0 to 2.0).
+     * Lower values make output more deterministic, higher values more creative.
      */
     temperature?: number;
     /**
      * Maximum number of tokens to generate in the response.
+     * Use this to limit response length and control costs.
      */
     maxOutputTokens?: number;
     /**
      * Array of tool definitions available to the model.
+     * Tools enable the model to call functions, search, execute code, etc.
      */
     tools?: LlmapiTool[];
     /**
-     * Controls which tool to use: "auto", "any", "none", "required", or a specific tool name.
+     * Controls which tool the model should use:
+     * - "auto": Model decides whether to use a tool (default)
+     * - "any": Model must use one of the provided tools
+     * - "none": Model cannot use any tools
+     * - "required": Model must use a tool
+     * - Specific tool name: Model must use that specific tool
      */
     toolChoice?: string;
     /**
      * Reasoning configuration for o-series and other reasoning models.
-     * Controls reasoning effort and summary output.
+     * Controls reasoning effort level and whether to include reasoning summary.
      */
     reasoning?: LlmapiResponseReasoning;
     /**
      * Extended thinking configuration for Anthropic models (Claude).
-     * Enables the model to think through complex problems step by step.
+     * Enables the model to think through complex problems step by step
+     * before generating the final response.
      */
     thinking?: LlmapiThinkingOptions;
     /**
      * Per-request callback for thinking/reasoning chunks.
      * Called with delta chunks as the model "thinks" through a problem.
+     * Use this to display thinking progress in the UI.
      */
     onThinking?: (chunk: string) => void;
 }
@@ -1003,8 +1115,10 @@ declare class Conversation extends Model {
  * Options for useChatStorage hook (Expo version)
  *
  * Uses the base options without React-specific features (no local chat, no tools).
+ * @inline
  */
-type UseChatStorageOptions = BaseUseChatStorageOptions;
+interface UseChatStorageOptions extends BaseUseChatStorageOptions {
+}
 /**
  * Arguments for sendMessage with storage (Expo version)
  *
@@ -1080,6 +1194,9 @@ interface UseChatStorageResult extends BaseUseChatStorageResult {
  */
 declare function useChatStorage(options: UseChatStorageOptions): UseChatStorageResult;
 
+/**
+ * @inline
+ */
 type UseImageGenerationOptions = {
     /**
      * Custom function to get auth token for API calls
@@ -1117,6 +1234,9 @@ type UseImageGenerationResult = {
  */
 declare function useImageGeneration(options?: UseImageGenerationOptions): UseImageGenerationResult;
 
+/**
+ * @inline
+ */
 type UseModelsOptions = {
     /**
      * Custom function to get auth token for API calls
@@ -1176,8 +1296,10 @@ declare class Memory extends Model {
  * Options for useMemoryStorage hook (Expo version)
  *
  * Uses the base options.
+ * @inline
  */
-type UseMemoryStorageOptions = BaseUseMemoryStorageOptions;
+interface UseMemoryStorageOptions extends BaseUseMemoryStorageOptions {
+}
 /**
  * Result returned by useMemoryStorage hook (Expo version)
  *
@@ -1305,4 +1427,4 @@ declare const sdkMigrations: Readonly<{
  */
 declare const sdkModelClasses: Class<Model$1>[];
 
-export { Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type FileMetadata, type MemoryItem, type MemoryType, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type UpdateMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseModelsOptions, type UseModelsResult, chatStorageMigrations, chatStorageSchema, generateCompositeKey, generateConversationId, generateUniqueKey, memoryStorageSchema, sdkMigrations, sdkModelClasses, sdkSchema, useChat, useChatStorage, useImageGeneration, useMemoryStorage, useModels };
+export { Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type FileMetadata, type MemoryItem, type MemoryType, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type UpdateMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseImageGenerationResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseModelsOptions, type UseModelsResult, chatStorageMigrations, chatStorageSchema, generateCompositeKey, generateConversationId, generateUniqueKey, memoryStorageSchema, sdkMigrations, sdkModelClasses, sdkSchema, useChat, useChatStorage, useImageGeneration, useMemoryStorage, useModels };

package/dist/expo/index.d.ts

@@ -554,6 +554,7 @@ type BaseSendMessageResult = {
 };
 /**
  * Base options for useChat hook
+ * @inline
  */
 type BaseUseChatOptions = {
     getToken?: () => Promise<string | null>;
@@ -623,6 +624,9 @@ type SendMessageArgs = BaseSendMessageArgs & {
     searchContext?: string;
 };
 type SendMessageResult = BaseSendMessageResult;
+/**
+ * @inline
+ */
 type UseChatOptions = BaseUseChatOptions;
 type UseChatResult = BaseUseChatResult & {
     sendMessage: (args: SendMessageArgs) => Promise<SendMessageResult>;
@@ -731,6 +735,9 @@ interface StoredMemory extends MemoryItem {
 interface StoredMemoryWithSimilarity extends StoredMemory {
     similarity: number;
 }
+/**
+ * @inline
+ */
 interface BaseUseMemoryStorageOptions {
     database: Database;
     completionsModel?: string;
@@ -871,27 +878,122 @@ interface UpdateMessageOptions {
  * @inline
  */
 interface BaseUseChatStorageOptions {
+    /** WatermelonDB database instance for storing conversations and messages */
     database: Database;
+    /** ID of an existing conversation to load and continue */
     conversationId?: string;
+    /** Automatically create a new conversation if none is set (default: true) */
     autoCreateConversation?: boolean;
+    /** Title for auto-created conversations (default: "New conversation") */
     defaultConversationTitle?: string;
+    /** Function to retrieve the auth token for API requests */
     getToken?: () => Promise<string | null>;
+    /** Base URL for the chat API endpoint */
     baseUrl?: string;
+    /** Callback invoked with each streamed response chunk */
     onData?: (chunk: string) => void;
+    /** Callback invoked when the response completes successfully */
     onFinish?: (response: LlmapiResponseResponse) => void;
+    /** Callback invoked when an error occurs during the request */
     onError?: (error: Error) => void;
 }
+/**
+ * Base arguments for sending a message with automatic storage.
+ *
+ * These arguments control both the AI request and how the message
+ * is persisted to the local database.
+ * @inline
+ */
 interface BaseSendMessageWithStorageArgs {
-    content: string;
+    /**
+     * The message array to send to the AI.
+     *
+     * Uses the modern array format that supports multimodal content (text, images, files).
+     * The last user message in this array will be extracted and stored in the database.
+     *
+     * When `includeHistory` is true (default), conversation history is prepended.
+     * When `includeHistory` is false, only these messages are sent.
+     *
+     * @example
+     * ```ts
+     * // Simple usage
+     * sendMessage({
+     *   messages: [
+     *     { role: "user", content: [{ type: "text", text: "Hello!" }] }
+     *   ]
+     * })
+     *
+     * // With system prompt and history disabled
+     * sendMessage({
+     *   messages: [
+     *     { role: "system", content: [{ type: "text", text: "You are helpful" }] },
+     *     { role: "user", content: [{ type: "text", text: "Question" }] },
+     *   ],
+     *   includeHistory: false
+     * })
+     *
+     * // With images
+     * sendMessage({
+     *   messages: [
+     *     { role: "user", content: [
+     *       { type: "text", text: "What's in this image?" },
+     *       { type: "image_url", image_url: { url: "data:image/png;base64,..." } }
+     *     ]}
+     *   ]
+     * })
+     * ```
+     */
+    messages: LlmapiMessage[];
+    /**
+     * The model identifier to use for this request (e.g., "gpt-4o", "claude-sonnet-4-20250514").
+     * If not specified, uses the default model configured on the server.
+     */
     model?: string;
-    messages?: LlmapiMessage[];
+    /**
+     * Whether to automatically include previous messages from the conversation as context.
+     * When true, fetches stored messages and prepends them to the request.
+     * Ignored if `messages` is provided.
+     * @default true
+     */
     includeHistory?: boolean;
+    /**
+     * Maximum number of historical messages to include when `includeHistory` is true.
+     * Only the most recent N messages are included to manage context window size.
+     * @default 50
+     */
     maxHistoryMessages?: number;
+    /**
+     * File attachments to include with the message (images, documents, etc.).
+     * Files with image MIME types and URLs are sent as image content parts.
+     * File metadata is stored with the message (URLs are stripped if they're data URIs).
+     */
     files?: FileMetadata[];
+    /**
+     * Per-request callback invoked with each streamed response chunk.
+     * Overrides the hook-level `onData` callback for this request only.
+     * Use this to update UI as the response streams in.
+     */
     onData?: (chunk: string) => void;
+    /**
+     * Additional context from memory/RAG system to include in the request.
+     * Typically contains retrieved relevant information from past conversations.
+     */
     memoryContext?: string;
+    /**
+     * Additional context from search results to include in the request.
+     * Typically contains relevant information from web or document searches.
+     */
     searchContext?: string;
+    /**
+     * Search sources to attach to the stored message for citation/reference.
+     * These are combined with any sources extracted from the assistant's response.
+     */
     sources?: SearchSource[];
+    /**
+     * Activity phases for tracking the request lifecycle in the UI.
+     * Each phase represents a step like "Searching", "Thinking", "Generating".
+     * The final phase is automatically marked as completed when stored.
+     */
     thoughtProcess?: ActivityPhase[];
     /**
      * Whether to store the response server-side.
@@ -909,33 +1011,43 @@ interface BaseSendMessageWithStorageArgs {
     serverConversation?: string;
     /**
      * Controls randomness in the response (0.0 to 2.0).
+     * Lower values make output more deterministic, higher values more creative.
      */
     temperature?: number;
     /**
      * Maximum number of tokens to generate in the response.
+     * Use this to limit response length and control costs.
      */
     maxOutputTokens?: number;
     /**
      * Array of tool definitions available to the model.
+     * Tools enable the model to call functions, search, execute code, etc.
      */
     tools?: LlmapiTool[];
     /**
-     * Controls which tool to use: "auto", "any", "none", "required", or a specific tool name.
+     * Controls which tool the model should use:
+     * - "auto": Model decides whether to use a tool (default)
+     * - "any": Model must use one of the provided tools
+     * - "none": Model cannot use any tools
+     * - "required": Model must use a tool
+     * - Specific tool name: Model must use that specific tool
      */
     toolChoice?: string;
     /**
      * Reasoning configuration for o-series and other reasoning models.
-     * Controls reasoning effort and summary output.
+     * Controls reasoning effort level and whether to include reasoning summary.
      */
     reasoning?: LlmapiResponseReasoning;
     /**
      * Extended thinking configuration for Anthropic models (Claude).
-     * Enables the model to think through complex problems step by step.
+     * Enables the model to think through complex problems step by step
+     * before generating the final response.
      */
     thinking?: LlmapiThinkingOptions;
     /**
      * Per-request callback for thinking/reasoning chunks.
      * Called with delta chunks as the model "thinks" through a problem.
+     * Use this to display thinking progress in the UI.
      */
     onThinking?: (chunk: string) => void;
 }
@@ -1003,8 +1115,10 @@ declare class Conversation extends Model {
  * Options for useChatStorage hook (Expo version)
  *
  * Uses the base options without React-specific features (no local chat, no tools).
+ * @inline
  */
-type UseChatStorageOptions = BaseUseChatStorageOptions;
+interface UseChatStorageOptions extends BaseUseChatStorageOptions {
+}
 /**
  * Arguments for sendMessage with storage (Expo version)
  *
@@ -1080,6 +1194,9 @@ interface UseChatStorageResult extends BaseUseChatStorageResult {
  */
 declare function useChatStorage(options: UseChatStorageOptions): UseChatStorageResult;
 
+/**
+ * @inline
+ */
 type UseImageGenerationOptions = {
     /**
      * Custom function to get auth token for API calls
@@ -1117,6 +1234,9 @@ type UseImageGenerationResult = {
  */
 declare function useImageGeneration(options?: UseImageGenerationOptions): UseImageGenerationResult;
 
+/**
+ * @inline
+ */
 type UseModelsOptions = {
     /**
      * Custom function to get auth token for API calls
@@ -1176,8 +1296,10 @@ declare class Memory extends Model {
  * Options for useMemoryStorage hook (Expo version)
  *
  * Uses the base options.
+ * @inline
  */
-type UseMemoryStorageOptions = BaseUseMemoryStorageOptions;
+interface UseMemoryStorageOptions extends BaseUseMemoryStorageOptions {
+}
 /**
  * Result returned by useMemoryStorage hook (Expo version)
  *
@@ -1305,4 +1427,4 @@ declare const sdkMigrations: Readonly<{
  */
 declare const sdkModelClasses: Class<Model$1>[];
 
-export { Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type FileMetadata, type MemoryItem, type MemoryType, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type UpdateMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseModelsOptions, type UseModelsResult, chatStorageMigrations, chatStorageSchema, generateCompositeKey, generateConversationId, generateUniqueKey, memoryStorageSchema, sdkMigrations, sdkModelClasses, sdkSchema, useChat, useChatStorage, useImageGeneration, useMemoryStorage, useModels };
+export { Conversation as ChatConversation, Message as ChatMessage, type ChatRole, type CreateConversationOptions, type CreateMemoryOptions, type CreateMessageOptions, type FileMetadata, type MemoryItem, type MemoryType, type SearchSource, type SendMessageWithStorageArgs, type SendMessageWithStorageResult, type ChatCompletionUsage as StoredChatCompletionUsage, type StoredConversation, type StoredMemory, Memory as StoredMemoryModel, type StoredMemoryWithSimilarity, type StoredMessage, type StoredMessageWithSimilarity, type UpdateMemoryOptions, type UseChatStorageOptions, type UseChatStorageResult, type UseImageGenerationResult, type UseMemoryStorageOptions, type UseMemoryStorageResult, type UseModelsOptions, type UseModelsResult, chatStorageMigrations, chatStorageSchema, generateCompositeKey, generateConversationId, generateUniqueKey, memoryStorageSchema, sdkMigrations, sdkModelClasses, sdkSchema, useChat, useChatStorage, useImageGeneration, useMemoryStorage, useModels };