@magemetrics/ai 0.11.3 → 0.11.5

package/dist/react/index.d.ts

@@ -6,6 +6,7 @@ import { DirectAuthProvider } from '@magemetrics/core';
 import { ExternalAuthProvider } from '@magemetrics/core';
 import { ExternalAuthProviderConfig } from '@magemetrics/core';
 import { FetchNextPageOptions } from '@tanstack/react-query';
+import { FileUIPart } from 'ai';
 import { ForwardRefExoticComponent } from 'react';
 import { InfiniteData } from '@tanstack/react-query';
 import { InfiniteQueryObserverResult } from '@tanstack/react-query';
@@ -92,6 +93,7 @@ declare interface ChatComponent extends default_2.MemoExoticComponent<(props: Ch
 export declare interface ChatContextValue {
     flowId: string | undefined | null;
     enableSpeechToText?: boolean;
+    enableFileUpload?: boolean;
 }
 
 /**
@@ -142,9 +144,10 @@ export declare interface ChatInputContextValue {
     isAwaitingUserAnswer: boolean;
     onRetry?: () => void;
     onStop?: () => void;
-    sendMessage: (text: string, isEditing: boolean) => void;
+    sendMessage: (text: string, isEditing: boolean, files?: FileUIPart[]) => void;
     lastUserMessage?: string;
     enableSpeechToText?: boolean;
+    enableFileUpload?: boolean;
 }
 
 declare const ChatInputDefault: default_2.FC;
@@ -152,6 +155,7 @@ declare const ChatInputDefault: default_2.FC;
 declare interface ChatProps {
     flowId: string | undefined | null;
     enableSpeechToText?: boolean;
+    enableFileUpload?: boolean;
     children?: default_2.ReactNode;
 }
 
@@ -205,6 +209,7 @@ declare interface ConfigurableChatComponent extends default_2.FC<ConfigurableCha
 declare type ConfigurableChatComponentProps = {
     flowId: string | undefined | null;
     enableSpeechToText?: boolean;
+    enableFileUpload?: boolean;
     disableCanvas?: boolean;
     children?: default_2.ReactNode;
     /**
@@ -214,6 +219,15 @@ declare type ConfigurableChatComponentProps = {
     appearance?: AppearanceConfig;
 };
 
+/** Context usage — the modal reuses an ancestor `MageMetricsContextProvider`. */
+declare type ContextManagedModalProps = ManagedModalInnerProps & {
+    apiKey?: never;
+    externalJwt?: never;
+    apiUrl?: never;
+    components?: never;
+    applicationName?: never;
+};
+
 /** @deprecated This type is no longer used and will be removed in a future version. */
 declare type ControlledModalProps = {
     visible: boolean;
@@ -227,6 +241,7 @@ declare interface ConversationContentProps {
     topBar?: React.ReactNode;
     disableCanvas?: boolean;
     enableSpeechToText?: boolean;
+    enableFileUpload?: boolean;
     children?: React.ReactNode;
 }
 
@@ -271,6 +286,51 @@ export { ExternalAuthProvider }
 
 export { ExternalAuthProviderConfig }
 
+export declare interface FileAttachment {
+    /** Unique ID for this attachment (for React keys and removal) */
+    id: string;
+    /** Original file name */
+    filename: string;
+    /** File size in bytes */
+    size: number;
+    /** The FileUIPart ready to be sent via sendMessage */
+    filePart: FileUIPart;
+    /** Validation error, if any */
+    error?: string;
+}
+
+export declare interface FileUploadConfig {
+    /** Maximum file size per file in bytes. Default: 10 * 1024 * 1024 (10 MB) */
+    maxFileSize?: number;
+    /** Maximum combined file size in bytes. Default: 20 * 1024 * 1024 (20 MB) */
+    maxCombinedSize?: number;
+}
+
+export declare interface FileUploadController {
+    /** Currently attached files (valid and invalid) */
+    attachments: FileAttachment[];
+    /** Whether all attachments are valid and ready to send */
+    isReady: boolean;
+    /** Whether any file is currently being read (FileReader in progress) */
+    isProcessing: boolean;
+    /** Total size of all valid attachments in bytes */
+    totalSize: number;
+    /** Combined size limit error, if total exceeds maxCombinedSize */
+    combinedSizeError?: string;
+    /** Add files from a FileList (e.g., from an input[type=file]) */
+    addFiles: (files: FileList) => void;
+    /** Remove a specific attachment by ID */
+    removeFile: (id: string) => void;
+    /** Clear all attachments */
+    clearFiles: () => void;
+    /** Get all valid FileUIParts for sendMessage */
+    getFileParts: () => FileUIPart[];
+    /** Open the native file picker (programmatic trigger) */
+    openFilePicker: () => void;
+    /** Ref to attach to a hidden file input element */
+    fileInputRef: React.RefObject<HTMLInputElement | null>;
+}
+
 /**
  * This module handles the formatting and normalization of table cell values for display and sorting.
  *
@@ -450,23 +510,18 @@ declare type MageMetricsPublicContextProviderProps = PropsWithChildren<Pick<Mage
 
 export declare const ManagedModal: React.FC<ManagedModalProps>;
 
-declare type ManagedModalBaseProps = ModalProps & {
-    /** API key for authenticating with the MageMetrics service */
-    apiKey: string;
-    /** External JWT token for user authentication */
-    externalJwt: string;
-    /** Base URL for the MageMetrics API */
-    apiUrl: string;
+/**
+ * Props shared by both standalone and context-aware usage of `ManagedModal`.
+ * These are the props that `ManagedModalInner` actually consumes — they have
+ * nothing to do with provider initialisation.
+ */
+declare type ManagedModalInnerProps = ModalProps & {
     /** Whether to disable canvas functionality in conversations */
     disableCanvas?: boolean;
     /** Whether to render data freshness info in the conversation header */
     showDataFreshness?: boolean;
     /** Where to persist modal state (localStorage, queryParam, or none) */
     persist?: PersistenceOptions;
-    /** Custom component overrides for extending functionality */
-    components?: Components;
-    /** Application name to associate with flows created through this modal */
-    applicationName?: string;
     /**
      * Appearance configuration for customizing the visual style.
      * Includes brand colors and modal-specific styling options.
@@ -479,10 +534,7 @@ declare type ManagedModalBaseProps = ModalProps & {
     };
 };
 
-/**
- * Props for ManagedModal component.
- */
-declare type ManagedModalProps = ManagedModalBaseProps;
+declare type ManagedModalProps = StandaloneManagedModalProps | ContextManagedModalProps;
 
 declare const MessagesContainer: default_2.FC;
 
@@ -610,6 +662,32 @@ export declare const StandaloneDataTable: React.FC<{
     onStateChange?: (state: DataTableState) => void;
 }>;
 
+/**
+ * Props for ManagedModal component.
+ *
+ * When rendered inside a `MageMetricsContextProvider`, the modal reuses the
+ * parent context instead of creating a duplicate. In that case `apiKey`,
+ * `externalJwt`, `apiUrl`, `components`, and `applicationName` must **not**
+ * be passed (they are inherited from the parent provider).
+ *
+ * When rendered standalone (no parent context), `apiKey`, `externalJwt`, and
+ * `apiUrl` are **required**, and `components`/`applicationName` may optionally
+ * be provided.
+ */
+/** Standalone usage — the modal creates its own `MageMetricsContextProvider`. */
+declare type StandaloneManagedModalProps = ManagedModalInnerProps & {
+    /** API key for authenticating with the MageMetrics service */
+    apiKey: string;
+    /** External JWT token for user authentication */
+    externalJwt: string;
+    /** Base URL for the MageMetrics API */
+    apiUrl: string;
+    /** Custom component overrides for extending functionality */
+    components?: Components;
+    /** Application name to associate with flows created through this modal */
+    applicationName?: string;
+};
+
 declare type StartOptions = DisplayControlProps & {
     /** Label text displayed above the chat launcher input */
     label?: string;
@@ -619,6 +697,8 @@ declare type StartOptions = DisplayControlProps & {
     autoFocus?: boolean;
     /** Whether speech-to-text controls should be shown */
     enableSpeechToText?: boolean;
+    /** Whether file upload should be enabled in the chat input */
+    enableFileUpload?: boolean;
 };
 
 declare type TableFilters = Record<string, TableFilterValue>;
@@ -928,6 +1008,8 @@ export declare const useDownloadReportData: (options?: UseMutationOptions<Export
     mutateAsync: UseMutateAsyncFunction<ExportReportDataResult, Error, ExportReportDataParams, unknown>;
 };
 
+export declare function useFileUpload(config?: FileUploadConfig): FileUploadController;
+
 export declare const useMageMetricsApiUrl: () => string;
 
 export declare const useMageMetricsClient: () => MageMetricsClient;
@@ -1083,22 +1165,13 @@ withTitle: boolean;
 exportingEnabled?: boolean;
 } & RefAttributes<HTMLDivElement>>;
 
-export declare type WebComponentManagedModalProps = ManagedModalProps & {
+export declare type WebComponentManagedModalProps = StandaloneManagedModalProps & {
     enableCsvDownload: boolean;
 };
 
 export { }
 
 
-declare module "react" {
-    namespace JSX {
-        interface IntrinsicElements {
-            "magemetrics-ai": WebComponentManagedModalProps;
-        }
-    }
-}
-
-
 declare module "react" {
     namespace JSX {
         interface IntrinsicElements {