@meetsmore-oss/use-ai-client 1.14.1 → 1.16.0

package/dist/index.d.ts

@@ -324,6 +324,18 @@ interface UseAIConfig {
     /** The WebSocket URL of the UseAI server */
     serverUrl: string;
 }
+/**
+ * Toggles for optional chat UI features. Each feature defaults to enabled
+ * when its flag is omitted, so set a flag to false to opt out of that feature.
+ */
+interface EnabledFeatures {
+    /**
+     * The "save as slash command" UI (hover save button + inline save editor)
+     * on user messages. Saved-command autocomplete via "/" is unaffected.
+     * @default true
+     */
+    slashCommands?: boolean;
+}
 
 /**
  * Handler for AG-UI events from the server.
@@ -656,24 +668,40 @@ interface FileAttachment {
     transformedContent?: string;
 }
 /**
- * Abstract file upload backend interface.
- * Converts File objects to URLs at send time.
+ * Result of preparing a file for send.
+ *
+ * Only one of the two is returned:
+ * - `{ url }`: a directly usable url (an inline base64 data URL, or a remote url).
+ *   The bytes travel along with the message.
+ * - `{ ref }`: a pointer into persistent storage (e.g. an S3 key). The bytes stay in
+ *   storage; only the ref travels with the message and is kept in history. It is
+ *   resolved on the server before being passed to the model.
+ *
+ * A backend may also return a bare `string`, which is treated as `{ url: string }`
+ * (for backward compatibility with backends written against the older signature).
+ */
+type FileUploadResult = {
+    url: string;
+} | {
+    ref: string;
+};
+/**
+ * Interface for an abstract file upload backend.
+ * Converts a File object into a sendable reference at send time.
  *
  * Implementations:
- * - EmbedFileUploadBackend: Converts to base64 data URL (built-in)
- * - S3FileUploadBackend: Uploads to S3 and returns public URL (future)
+ * - EmbedFileUploadBackend: converts to a base64 data URL (built-in)
+ * - S3FileUploadBackend: uploads to storage and returns a `ref` (future)
  */
 interface FileUploadBackend {
     /**
-     * Prepare file for sending to AI.
-     * Called at send time - converts File to URL.
+     * Prepare a file to send to the AI. Called at send time.
      *
      * @param file - The File object to prepare
-     * @returns Promise resolving to a URL string
-     *          - For embed: base64 data URL
-     *          - For S3: public URL after upload
+     * @returns A {@link FileUploadResult} (`{ url }` or `{ ref }`), or a bare url string
+     *          for backward compatibility (treated as `{ url }`).
      */
-    prepareForSend(file: File): Promise<string>;
+    prepareForSend(file: File): Promise<string | FileUploadResult>;
 }
 /**
  * Context provided to file transformers.
@@ -761,6 +789,14 @@ interface FileUploadConfig {
      * before being sent to the AI.
      */
     transformers?: FileTransformerMap;
+    /**
+     * Maximum number of attachments allowed per message.
+     * Enforced at attach time; files beyond the limit are rejected with an error.
+     * The value is the host's policy (e.g. set it below the AI provider's per-message
+     * limit). use-ai only exposes the knob and assumes no default. When undefined, the
+     * number of attachments is not limited.
+     */
+    maxAttachments?: number;
 }
 
 /**
@@ -799,11 +835,35 @@ interface PersistedTransformedFileContent {
     text: string;
     originalFile: PersistedFileMetadata;
 }
+/**
+ * Ref-backed attachment content part for persisted messages.
+ *
+ * Unlike {@link PersistedFileContent} (metadata only, discarded on reload), this part
+ * holds a `ref` into persistent storage (e.g. an S3 key). This lets attachments be
+ * re-sent to the AI even after a page reload. The actual bytes live in storage rather
+ * than localStorage, and the ref is resolved on the host before the next run.
+ *
+ * Covers both image and non-image attachments in a single type (the persistence layer
+ * does not split them: display is identical, and the re-send tag is derived from
+ * `mimeType`). On reload it is read two ways: as a name/size chip for display, and as a
+ * re-sendable `{ type: 'image_ref' | 'file_ref', ref }` wire part (see `messageConversion.ts`).
+ */
+interface PersistedAttachmentRefContent {
+    type: 'attachment_ref';
+    /** Ref into persistent storage (e.g. an S3 key). Never expires. */
+    ref: string;
+    /** Original file name (for display). */
+    name: string;
+    /** MIME type, e.g. 'image/jpeg' | 'application/pdf'. Decides whether to re-send as image or file. */
+    mimeType: string;
+    /** Byte size after client-side resize (for display). */
+    size: number;
+}
 /**
  * Content part for persisted messages.
- * Can be text, file metadata, or transformed file content.
+ * One of: text, file metadata, transformed file content, or a ref-backed attachment.
  */
-type PersistedContentPart = PersistedTextContent | PersistedFileContent | PersistedTransformedFileContent;
+type PersistedContentPart = PersistedTextContent | PersistedFileContent | PersistedTransformedFileContent | PersistedAttachmentRefContent;
 /**
  * Content that can be persisted.
  * Simple string for text-only messages, or array for multimodal content.
@@ -1188,6 +1248,8 @@ declare const defaultStrings: {
         fileSizeError: string;
         /** File type error (use {type} placeholder) */
         fileTypeError: string;
+        /** Error when too many files are attached (use {max} placeholder) */
+        maxAttachmentsError: string;
     };
     floatingButton: {
         /** Floating button title when connected */
@@ -1584,6 +1646,13 @@ interface UseAIProviderProps extends UseAIConfig {
      * Defaults to LocalStorageCommandRepository if not provided.
      */
     commandRepository?: CommandRepository;
+    /**
+     * Opt-out toggles for optional chat UI features. Each feature defaults to
+     * enabled, so only set a flag to false to hide it. For example, set
+     * `{ slashCommands: false }` to hide the "save as slash command" UI while
+     * keeping "/" autocomplete for existing saved commands.
+     */
+    enabledFeatures?: EnabledFeatures;
     /**
      * Whether to render the built-in chat UI (floating button + panel).
      * Set to false when using the `<UseAIChat>` component to control chat placement.
@@ -1695,7 +1764,7 @@ interface UseAIProviderProps extends UseAIConfig {
  * }
  * ```
  */
-declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton, CustomChat, chatRepository, forwardedPropsProvider, fileUploadConfig: fileUploadConfigProp, commandRepository, renderChat, theme: customTheme, strings: customStrings, visibleAgentIds, onOpenChange, submitMode, }: UseAIProviderProps): react_jsx_runtime.JSX.Element;
+declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton, CustomChat, chatRepository, forwardedPropsProvider, fileUploadConfig: fileUploadConfigProp, commandRepository, enabledFeatures, renderChat, theme: customTheme, strings: customStrings, visibleAgentIds, onOpenChange, submitMode, }: 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.
@@ -1744,6 +1813,13 @@ interface UseAIChatPanelProps {
     fileProcessing?: FileProcessingState | null;
     commands?: SavedCommand[];
     onSaveCommand?: (name: string, text: string) => Promise<string>;
+    /**
+     * Opt-out toggles for optional chat UI features. Each feature defaults to
+     * enabled when omitted. `slashCommands` controls the "save as slash command"
+     * UI (hover save button + inline editor); saved-command autocomplete is
+     * unaffected.
+     */
+    enabledFeatures?: EnabledFeatures;
     onRenameCommand?: (id: string, newName: string) => Promise<void>;
     onDeleteCommand?: (id: string) => Promise<void>;
     /** Optional close button to render in header (for floating mode) */
@@ -1786,7 +1862,7 @@ interface UseAIChatPanelProps {
  * Chat panel content - fills its container.
  * Use directly for embedded mode, or wrap with UseAIFloatingChatWrapper for floating mode.
  */
-declare function UseAIChatPanel({ onSendMessage, onAbort, messages, loading, connected, streamingText, streamingReasoning, currentChatId, onNewChat, onLoadChat, onDeleteChat, onListChats, onGetChat, suggestions, availableAgents, defaultAgent, selectedAgent, onAgentChange, fileUploadConfig, fileProcessing, commands, onSaveCommand, onRenameCommand, onDeleteCommand, closeButton, executingTool, feedbackEnabled, onFeedback, pendingApprovals, onApproveToolCall, onRejectToolCall, submitMode, }: UseAIChatPanelProps): react_jsx_runtime.JSX.Element;
+declare function UseAIChatPanel({ onSendMessage, onAbort, messages, loading, connected, streamingText, streamingReasoning, currentChatId, onNewChat, onLoadChat, onDeleteChat, onListChats, onGetChat, suggestions, availableAgents, defaultAgent, selectedAgent, onAgentChange, fileUploadConfig, fileProcessing, commands, onSaveCommand, enabledFeatures, onRenameCommand, onDeleteCommand, closeButton, executingTool, feedbackEnabled, onFeedback, pendingApprovals, onApproveToolCall, onRejectToolCall, submitMode, }: UseAIChatPanelProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Props for the floating chat wrapper.
@@ -2612,4 +2688,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 ExecutingToolDisplay, 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 PendingToolApproval, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type SubmitMode, type ToolExecutionContext, 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 UseMessageQueueOptions, type UseMessageQueueReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseServerEventsOptions, type UseServerEventsReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolSystemOptions, type UseToolSystemReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformerPattern, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFeedback, useFileUpload, useMessageQueue, usePromptState, useServerEvents, useSlashCommands, useStableTools, useStrings, useTheme, useToolSystem, 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 EnabledFeatures, type ExecutingToolDisplay, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FileUploadResult, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PendingToolApproval, type PersistedAttachmentRefContent, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type PersistedTransformedFileContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type SubmitMode, type ToolExecutionContext, 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 UseMessageQueueOptions, type UseMessageQueueReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseServerEventsOptions, type UseServerEventsReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolSystemOptions, type UseToolSystemReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformerPattern, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFeedback, useFileUpload, useMessageQueue, usePromptState, useServerEvents, useSlashCommands, useStableTools, useStrings, useTheme, useToolSystem, validateCommandName };