@meetsmore-oss/use-ai-client 1.5.1 → 1.7.0

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import { z } from 'zod';
 export { z } from 'zod';
-import * as _meetsmore_oss_use_ai_core from '@meetsmore-oss/use-ai-core';
-import { ToolAnnotations, ToolDefinition, WorkflowStatus, FeedbackValue, AgentInfo, McpHeadersMap, MultimodalContent, AGUIEvent, Message as Message$1, UseAIClientMessage } from '@meetsmore-oss/use-ai-core';
+import { ToolAnnotations, ToolDefinition, WorkflowStatus, FeedbackValue, AgentInfo, MultimodalContent, UseAIForwardedProps, AGUIEvent, Message as Message$1, UseAIClientMessage } from '@meetsmore-oss/use-ai-core';
 export { AgentInfo, ToolAnnotations, ToolDefinition } from '@meetsmore-oss/use-ai-core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1, { ReactNode } from 'react';
@@ -351,19 +350,30 @@ interface FileTransformerContext {
 }
 /**
  * A transformer that converts files into string representations for the AI.
+ *
+ * Receives all files that were matched to this transformer instance
+ * and returns one string per file in the same order.
+ *
+ * @example
+ * ```typescript
+ * const pdfTransformer: FileTransformer = {
+ *   transform: async (files, context) =>
+ *     Promise.all(files.map(f => extractText(f))),
+ * };
+ * ```
  */
 interface FileTransformer {
     /**
-     * Transform the file into a string representation for the AI.
+     * Transform files into string representations for the AI.
      *
-     * @param file - The file to transform
+     * @param files - The files to transform (all matched to this transformer instance)
      * @param context - Context including the current chat and its metadata
      * @param onProgress - Optional callback for reporting progress (0-100).
      *                     If called, UI shows progress bar; otherwise shows spinner.
-     * @returns A string representation the AI will receive
+     * @returns One string per input file, in the same order
      * @throws If transformation fails
      */
-    transform(file: File, context: FileTransformerContext, onProgress?: (progress: number) => void): Promise<string>;
+    transform(files: File[], context: FileTransformerContext, onProgress?: (progress: number) => void): Promise<string[]>;
 }
 /**
  * Map of MIME type patterns to transformers.
@@ -702,6 +712,24 @@ declare const defaultStrings: {
         /** Fallback messages when no tool title is provided (one randomly selected) */
         fallbackMessages: string[];
     };
+    toolApproval: {
+        /** Title shown in the approval dialog */
+        title: string;
+        /** Message shown in the approval dialog. {toolName} is replaced with tool name. */
+        message: string;
+        /** Message shown when multiple tools are awaiting approval. {count} is replaced with number. */
+        batchMessage: string;
+        /** Label for approve button */
+        approve: string;
+        /** Label for approve all button (batch mode) */
+        approveAll: string;
+        /** Label for reject button */
+        reject: string;
+        /** Label for reject all button (batch mode) */
+        rejectAll: string;
+        /** Label for showing tool arguments */
+        showDetails: string;
+    };
 };
 /**
  * Customizable text labels for the chat UI.
@@ -859,12 +887,23 @@ interface UseAIChatPanelProps {
     feedbackEnabled?: boolean;
     /** Callback when user submits feedback on a message */
     onFeedback?: (messageId: string, traceId: string, feedback: FeedbackValue) => void;
+    /** Pending tool approvals awaiting user confirmation */
+    pendingApprovals?: Array<{
+        toolCallId: string;
+        toolCallName: string;
+        toolCallArgs: Record<string, unknown>;
+        annotations?: ToolAnnotations;
+    }>;
+    /** Callback to approve all pending tool calls */
+    onApproveToolCall?: () => void;
+    /** Callback to reject all pending tool calls */
+    onRejectToolCall?: (reason?: string) => void;
 }
 /**
  * Chat panel content - fills its container.
  * Use directly for embedded mode, or wrap with UseAIFloatingChatWrapper for floating mode.
  */
-declare function UseAIChatPanel({ onSendMessage, messages, loading, connected, streamingText, currentChatId, onNewChat, onLoadChat, onDeleteChat, onListChats, onGetChat, suggestions, availableAgents, defaultAgent, selectedAgent, onAgentChange, fileUploadConfig, fileProcessing, commands, onSaveCommand, onRenameCommand, onDeleteCommand, closeButton, executingTool, feedbackEnabled, onFeedback, }: UseAIChatPanelProps): react_jsx_runtime.JSX.Element;
+declare function UseAIChatPanel({ onSendMessage, messages, loading, connected, streamingText, currentChatId, onNewChat, onLoadChat, onDeleteChat, onListChats, onGetChat, suggestions, availableAgents, defaultAgent, selectedAgent, onAgentChange, fileUploadConfig, fileProcessing, commands, onSaveCommand, onRenameCommand, onDeleteCommand, closeButton, executingTool, feedbackEnabled, onFeedback, pendingApprovals, onApproveToolCall, onRejectToolCall, }: UseAIChatPanelProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Handler for AG-UI events from the server.
@@ -901,7 +940,6 @@ declare class UseAIClient {
     private _tools;
     private _messages;
     private _state;
-    private mcpHeadersProvider?;
     private _availableAgents;
     private _defaultAgent;
     private _selectedAgent;
@@ -942,20 +980,15 @@ declare class UseAIClient {
      * @param state - The current state object to provide to the AI
      */
     updateState(state: unknown): void;
-    /**
-     * Sets the MCP headers provider.
-     * The provider will be called each time a message is sent to get fresh headers.
-     *
-     * @param provider - Function that returns MCP headers configuration
-     */
-    setMcpHeadersProvider(provider: () => McpHeadersMap | Promise<McpHeadersMap>): void;
     /**
      * Sends a user prompt to the AI.
      *
      * @param prompt - The user's prompt/question (text part)
      * @param multimodalContent - Optional multimodal content (text, images, files)
+     * @param forwardedProps - Optional props to forward to the server (e.g., telemetryMetadata, mcpHeaders).
+     *                         Internally merged with other forwardedProps.
      */
-    sendPrompt(prompt: string, multimodalContent?: MultimodalContent[]): Promise<void>;
+    sendPrompt(prompt: string, multimodalContent?: MultimodalContent[], forwardedProps?: UseAIForwardedProps): Promise<void>;
     /**
      * Sends the result of a tool execution back to the server.
      *
@@ -964,6 +997,14 @@ declare class UseAIClient {
      * @param state - Optional updated state to send back to the AI
      */
     sendToolResponse(toolCallId: string, result: unknown, state?: unknown): void;
+    /**
+     * Sends a tool approval response back to the server.
+     *
+     * @param toolCallId - The ID of the tool call being approved/rejected
+     * @param approved - Whether the tool execution is approved
+     * @param reason - Optional reason for rejection (shown to AI)
+     */
+    sendToolApprovalResponse(toolCallId: string, approved: boolean, reason?: string): void;
     /**
      * Retrieves accumulated tool call data for a specific tool call ID.
      * Used to get the complete tool name and arguments after they've been streamed
@@ -1114,6 +1155,11 @@ interface SendMessageOptions {
     openChat?: boolean;
     /** Metadata to set on the new chat (only used when newChat: true) */
     metadata?: ChatMetadata;
+    /**
+     * Forwarded props for observability and configuration (e.g., telemetryMetadata, mcpHeaders).
+     * This is merged with provider-level forwardedProps (message-level takes precedence).
+     */
+    forwardedProps?: UseAIForwardedProps;
 }
 interface UseChatManagementOptions {
     /** Chat repository for persistence */
@@ -1125,13 +1171,15 @@ interface UseChatManagementOptions {
     /** Setter for messages state (owned by provider) */
     setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
     /** Callback to send a message (from UseAIProvider) */
-    onSendMessage?: (message: string, attachments?: FileAttachment[]) => Promise<void>;
+    onSendMessage?: (message: string, attachments?: FileAttachment[], forwardedProps?: UseAIForwardedProps) => Promise<void>;
     /** Callback to open/close the chat panel */
     setOpen?: (open: boolean) => void;
     /** Whether the client is connected */
     connected?: boolean;
     /** Whether the AI is currently loading/processing a response */
     loading?: boolean;
+    /** Whether there's a pending tool approval blocking the queue */
+    hasPendingApproval?: boolean;
 }
 interface UseChatManagementReturn {
     /** Current active chat ID where AI responses are saved */
@@ -1202,7 +1250,7 @@ interface UseChatManagementReturn {
  * });
  * ```
  */
-declare function useChatManagement({ repository, clientRef, messages, setMessages, onSendMessage, setOpen, connected, loading, }: UseChatManagementOptions): UseChatManagementReturn;
+declare function useChatManagement({ repository, clientRef, messages, setMessages, onSendMessage, setOpen, connected, loading, hasPendingApproval, }: UseChatManagementOptions): UseChatManagementReturn;
 
 /**
  * Chat management context (from useChatManagement hook).
@@ -1357,33 +1405,41 @@ interface UseAIProviderProps extends UseAIConfig {
      */
     chatRepository?: ChatRepository;
     /**
-     * Callback to provide HTTP headers for MCP endpoints.
-     * Called each time AI is invoked by use-ai.
-     * Returns a mapping of MCP endpoint patterns to header configurations.
-     *
-     * Patterns can be:
-     * - Constant strings: `https://api.example.com` - Exact match
-     * - Glob patterns: `https://*.meetsmore.com` - Wildcard matching using picomatch
+     * Provider function for forwarded props (telemetry metadata, MCP headers, etc.).
+     * Called before each message is sent. Can be sync or async.
+     * Props from this provider are merged with message-level forwardedProps,
+     * with message-level taking precedence.
      *
      * @example
-     * ```typescript
-     * mcpHeadersProvider={() => ({
-     *   // Exact match
-     *   'https://api.example.com': {
-     *     headers: { 'Authorization': `Bearer ${userToken}` }
-     *   },
-     *   // Wildcard subdomain
-     *   'https://*.meetsmore.com': {
-     *     headers: { 'X-API-Key': apiKey }
-     *   },
-     *   // Multiple wildcards
-     *   '*://*.example.com': {
-     *     headers: { 'X-Custom': 'value' }
-     *   }
-     * })}
+     * ```tsx
+     * <UseAIProvider
+     *   serverUrl="wss://your-server.com"
+     *   forwardedPropsProvider={() => ({
+     *     mcpHeaders: {
+     *       // Exact match
+     *       'https://api.example.com': {
+     *         headers: { 'Authorization': `Bearer ${userToken}` }
+     *       },
+     *       // Wildcard subdomain
+     *       'https://*.meetsmore.com': {
+     *         headers: { 'X-API-Key': apiKey }
+     *       },
+     *       // Multiple wildcards
+     *       '*://*.example.com': {
+     *         headers: { 'X-Custom': 'value' }
+     *       },
+     *     },
+     *     telemetryMetadata: {
+     *       userId: currentUser.id,
+     *       tenantId: tenant.id,
+     *     },
+     *   })}
+     * >
+     *   <App />
+     * </UseAIProvider>
      * ```
      */
-    mcpHeadersProvider?: () => _meetsmore_oss_use_ai_core.McpHeadersMap | Promise<_meetsmore_oss_use_ai_core.McpHeadersMap>;
+    forwardedPropsProvider?: () => UseAIForwardedProps | Promise<UseAIForwardedProps>;
     /**
      * Configuration for file uploads.
      * File upload is enabled by default with EmbedFileUploadBackend, 10MB max size,
@@ -1497,7 +1553,7 @@ interface UseAIProviderProps extends UseAIConfig {
  * }
  * ```
  */
-declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton, CustomChat, chatRepository, mcpHeadersProvider, fileUploadConfig: fileUploadConfigProp, commandRepository, renderChat, theme: customTheme, strings: customStrings, visibleAgentIds, onOpenChange, }: UseAIProviderProps): react_jsx_runtime.JSX.Element;
+declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton, CustomChat, chatRepository, forwardedPropsProvider, fileUploadConfig: fileUploadConfigProp, commandRepository, renderChat, theme: customTheme, strings: customStrings, visibleAgentIds, onOpenChange, }: UseAIProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access the UseAI context.
  * When used outside a UseAIProvider, returns a no-op context and logs a warning.
@@ -1770,7 +1826,8 @@ declare function useFileUpload({ config, disabled, resetDependency, getCurrentCh
  */
 declare function matchesMimeType(mimeType: string, pattern: string): boolean;
 /**
- * Find the most specific transformer for a MIME type.
+ * Find the most specific transformer pattern key for a MIME type.
+ * Returns the pattern string (e.g., 'application/pdf', 'image/*') or undefined.
  *
  * Specificity rules:
  * 1. Exact match (no wildcard) always wins
@@ -1781,7 +1838,7 @@ declare function matchesMimeType(mimeType: string, pattern: string): boolean;
  * - 'image/*' (length 7, second)
  * - '*' (length 1, last)
  */
-declare function findTransformer(mimeType: string, transformers: FileTransformerMap | undefined): FileTransformer | undefined;
+declare function findTransformerPattern(mimeType: string, transformers: FileTransformerMap | undefined): string | undefined;
 
 /**
  * Configuration for processing file attachments.
@@ -1800,6 +1857,9 @@ interface ProcessAttachmentsConfig {
  * Process file attachments into multimodal content for AI.
  * Handles transformation (with caching) or URL encoding.
  *
+ * Files matching the same transformer are grouped and passed together
+ * to `transformer.transform()`.
+ *
  * @param attachments - The file attachments to process
  * @param config - Processing configuration
  * @returns Array of multimodal content parts
@@ -2244,4 +2304,4 @@ interface UseDropdownStateOptions {
  */
 declare function useDropdownState(options?: UseDropdownStateOptions): UseDropdownStateReturn;
 
-export { type AgentContextValue, type Chat, type ChatContextValue, type ChatMetadata, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFeedbackOptions, type UseFeedbackReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolRegistryReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformer, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFeedback, useFileUpload, usePromptState, useSlashCommands, useStableTools, useStrings, useTheme, useToolRegistry, validateCommandName };
+export { type AgentContextValue, type Chat, type ChatContextValue, type ChatMetadata, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFeedbackOptions, type UseFeedbackReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolRegistryReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformerPattern, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFeedback, useFileUpload, usePromptState, useSlashCommands, useStableTools, useStrings, useTheme, useToolRegistry, validateCommandName };