@cadraos/sdk 0.1.6 → 0.1.8

package/dist/chat/index.d.ts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Components } from 'react-markdown';
 import * as React$1 from 'react';
+import React__default from 'react';
 
 interface MarkdownContentProps {
     /** Markdown content to render */
@@ -188,11 +189,19 @@ interface AttachmentFile {
     /** Original file object */
     file: File;
     /** Upload status */
-    status: "pending" | "uploading" | "ready" | "failed";
+    status: "pending" | "uploading" | "processing" | "ready" | "error" | "failed";
     /** Preview URL for local display */
     previewUrl?: string;
     /** Progress percentage (0-100) */
-    progress?: number;
+    progress: number;
+    /** File category */
+    category: "document" | "image" | "audio";
+    /** Error message when status is "error" */
+    error?: string;
+    /** Whether a thumbnail has been generated */
+    hasThumbnail?: boolean;
+    /** Override file.size for external attachments where actual File is empty */
+    actualSize?: number;
 }
 
 interface ChatMessageProps {
@@ -370,7 +379,11 @@ interface ExecuteInput {
     context?: Record<string, unknown>;
     /** Attachment UUIDs to include with the message (for images, documents, etc.) */
     attachmentIds?: string[];
-    /** Team UUID for team-based execution (routes to team's lead orchestrator) */
+    /**
+     * Team UUID for team-based execution (routes to team's lead orchestrator).
+     * @deprecated Pass the team UUID directly as the agent/entity ID instead.
+     * The platform now auto-detects whether a UUID is an agent, team, or tool.
+     */
     teamUuid?: string;
     /** Execution options */
     options?: ExecuteOptions;
@@ -1101,14 +1114,62 @@ interface ChatAdapter {
     /**
      * Get the SSE stream URL for an execution.
      *
-     * @deprecated Prefer implementing `createStream` which provides
-     * fetch-based SSE with auth headers. This is kept for backward
-     * compatibility with EventSource-based streaming.
+     * @deprecated Use `subscribeToStream` instead which provides secure
+     * header-based auth. This method exposes API keys in URLs which are
+     * logged by browsers, proxies, and servers.
      *
      * @param executionId - Execution UUID
      * @returns Full URL for SSE connection
      */
     getStreamUrl?(executionId: string): string;
+    /**
+     * Subscribe to SSE stream for an execution using header-based auth.
+     *
+     * Uses @microsoft/fetch-event-source for SSE with Authorization header.
+     * This is the secure alternative to getStreamUrl() which exposed API keys
+     * in URLs.
+     *
+     * @param executionId - Execution UUID to stream
+     * @param callbacks - Event callbacks
+     * @returns Cleanup function to unsubscribe
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = adapter.subscribeToStream(executionId, {
+     *   onEvent: (event) => console.log(event),
+     *   onError: (error) => console.error(error),
+     *   onComplete: () => console.log('Done'),
+     * });
+     *
+     * // Later, to stop streaming:
+     * unsubscribe();
+     * ```
+     */
+    subscribeToStream?(executionId: string, callbacks: StreamSubscriptionCallbacks): () => void;
+}
+/**
+ * SSE event received from the stream
+ */
+interface StreamEvent {
+    /** Event type (progress, tool_call, complete, failed, etc.) */
+    type: string;
+    /** Event ID for reconnection */
+    id?: string;
+    /** Event data payload */
+    data: unknown;
+}
+/**
+ * Callbacks for subscribeToStream
+ */
+interface StreamSubscriptionCallbacks {
+    /** Called for each SSE event received */
+    onEvent: (event: StreamEvent) => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** Called when the stream completes (terminal event received) */
+    onComplete?: () => void;
+    /** Called when connection state changes */
+    onConnectionChange?: (connected: boolean) => void;
 }
 
 interface AgentChatProps {
@@ -1167,7 +1228,7 @@ interface AgentChatProps {
     className?: string;
     /** Theme mode */
     theme?: ThemeMode;
-    /** Enable file attachments (future feature) */
+    /** Enable file attachments */
     enableAttachments?: boolean;
     /** Enable markdown rendering */
     enableMarkdown?: boolean;
@@ -1195,6 +1256,7 @@ interface AgentChatProps {
  * <ChatConfigProvider config={{ baseUrl: '...', apiKey: '...' }}>
  *   <AgentChat
  *     agentId="agent-uuid"
+ *     enableAttachments
  *     onMessage={(msg) => console.log('New message:', msg)}
  *   />
  * </ChatConfigProvider>
@@ -2711,9 +2773,9 @@ declare class AISaaSClient {
 }
 
 /**
- * Default adapter for ChatAdapter — thin wrapper around AISaaSClient
+ * Default adapter for ChatAdapter — thin wrapper around CadraClient
  *
- * Uses the AISaaSClient for all operations, providing proper auth,
+ * Uses the CadraClient for all operations, providing proper auth,
  * retries, and streaming support out of the box.
  *
  * @module @cadraos/sdk/chat
@@ -2724,7 +2786,7 @@ declare class AISaaSClient {
  */
 interface DefaultAdapterConfig {
     /**
-     * Pre-constructed AISaaSClient (takes priority over individual options)
+     * Pre-constructed CadraClient (takes priority over individual options)
      */
     client?: AISaaSClient;
     /**
@@ -2750,10 +2812,10 @@ interface DefaultAdapterConfig {
     orgId?: number;
 }
 /**
- * Create a default adapter that wraps AISaaSClient
+ * Create a default adapter that wraps CadraClient
  *
  * @param config - Adapter configuration
- * @returns ChatAdapter implementation backed by AISaaSClient
+ * @returns ChatAdapter implementation backed by CadraClient
  *
  * @example
  * ```typescript
@@ -2855,6 +2917,13 @@ interface UseAgentChatOptions {
     /** Callback fired when clarification is needed */
     onClarification?: (data: ClarificationData) => void;
 }
+/**
+ * Options for sendMessage
+ */
+interface SendMessageOptions {
+    /** UUIDs of attached files to include with the message */
+    attachmentUuids?: string[];
+}
 interface UseAgentChatResult {
     /** Current messages in the chat */
     messages: ChatMessage$1[];
@@ -2871,7 +2940,7 @@ interface UseAgentChatResult {
     /** Current clarification request if any */
     clarification: ClarificationData | null;
     /** Send a message to the agent */
-    sendMessage: (content: string) => Promise<void>;
+    sendMessage: (content: string, options?: SendMessageOptions) => Promise<void>;
     /** Respond to a clarification request */
     respondToClarification: (response: string) => Promise<void>;
     /** Cancel the current execution */
@@ -2978,6 +3047,122 @@ interface UseExecutionStreamResult {
  */
 declare function useExecutionStream(options: UseExecutionStreamOptions): UseExecutionStreamResult;
 
+/**
+ * FileDropZone - Reusable file upload component with drag-and-drop
+ *
+ * Supports drag-and-drop file upload with visual feedback, file validation,
+ * image compression, upload progress tracking, and thumbnail previews.
+ *
+ * Two modes:
+ * - Standalone: renders a drop zone UI (default)
+ * - Wrapper: wraps children with a drag-drop overlay (when children provided)
+ *
+ * @packageDocumentation
+ */
+
+interface FileDropZoneProps {
+    files: AttachmentFile[];
+    onFilesChange: (files: AttachmentFile[]) => void;
+    /** Upload a file. Return the UUID and presigned URL. If uploadUrl is empty, the S3 PUT step is skipped. */
+    onUpload: (file: File, metadata: {
+        filename: string;
+        mimeType: string;
+        size: number;
+    }) => Promise<{
+        uuid: string;
+        uploadUrl: string;
+    }>;
+    /** Confirm the upload after S3 PUT succeeds */
+    onConfirmUpload?: (uuid: string) => Promise<void>;
+    /** Error callback instead of toast */
+    onError?: (message: string) => void;
+    maxFiles?: number;
+    maxTotalSizeMB?: number;
+    disabled?: boolean;
+    className?: string;
+    /** Restrict accepted file types, e.g. "image/*" */
+    accept?: string;
+    /** Compact mode for embedding in small panels */
+    compact?: boolean;
+    children?: React__default.ReactNode;
+}
+/** Ref interface for programmatic access to FileDropZone */
+interface FileDropZoneRef {
+    /** Trigger the file selection dialog */
+    openFileDialog: () => void;
+}
+declare const FileDropZone: React__default.ForwardRefExoticComponent<FileDropZoneProps & React__default.RefAttributes<FileDropZoneRef>>;
+
+interface UseFileAttachmentsOptions {
+    /**
+     * Upload handler called immediately when files are dropped/selected.
+     * Return the UUID and a presigned upload URL.
+     * If uploadUrl is empty, the S3 PUT step in FileDropZone is skipped
+     * (useful for direct-upload patterns where the upload happens here).
+     */
+    onUpload: (file: File, metadata: {
+        filename: string;
+        mimeType: string;
+        size: number;
+    }) => Promise<{
+        uuid: string;
+        uploadUrl: string;
+    }>;
+    /** Optional confirm callback after S3 PUT succeeds */
+    onConfirmUpload?: (uuid: string) => Promise<void>;
+    /**
+     * Deferred upload handler called during prepareForSubmit().
+     * Use this for two-phase upload patterns where files are uploaded to local
+     * storage on drop, but a second upload to an AI service happens on submit.
+     *
+     * Receives the file and localUuid (from onUpload) and should return
+     * the AI service's attachment UUID.
+     *
+     * If not provided, prepareForSubmit() returns the UUIDs from onUpload as-is.
+     */
+    onSubmitUpload?: (file: File, localUuid: string, metadata: {
+        filename: string;
+        mimeType: string;
+        size: number;
+    }) => Promise<string>;
+    /** Error handler */
+    onError?: (message: string) => void;
+    /** Maximum number of files (default: 10) */
+    maxFiles?: number;
+    /** Maximum total upload size in MB (default: 100) */
+    maxTotalSizeMB?: number;
+}
+interface UseFileAttachmentsResult {
+    /** Current attachment files */
+    files: AttachmentFile[];
+    /**
+     * Props to spread onto FileDropZone.
+     * Includes: files, onFilesChange, onUpload, onConfirmUpload, onError, maxFiles, maxTotalSizeMB
+     */
+    dropZoneProps: Pick<FileDropZoneProps, "files" | "onFilesChange" | "onUpload" | "onConfirmUpload" | "onError" | "maxFiles" | "maxTotalSizeMB">;
+    /** Remove a file by UUID */
+    removeFile: (uuid: string) => void;
+    /** Get UUIDs of ready (uploaded) attachments — for Cadra adapter pattern */
+    getReadyUuids: () => string[];
+    /** Get UUIDs of ready attachments as URLs — for direct-upload pattern where uuid IS the url */
+    getReadyUrls: () => string[];
+    /**
+     * Two-phase submit: uploads ready files to the AI service via onSubmitUpload,
+     * returns the AI service attachment UUIDs. Call this on Generate/Remix.
+     * If onSubmitUpload is not configured, returns getReadyUuids().
+     */
+    prepareForSubmit: () => Promise<string[]>;
+    /** Clear all attachments (revokes preview URLs) */
+    clear: () => void;
+    /** Whether any files are currently uploading */
+    isUploading: boolean;
+    /** Whether there are files ready to send */
+    hasReadyFiles: boolean;
+    /** Total number of files */
+    fileCount: number;
+}
+declare function useFileAttachments(options: UseFileAttachmentsOptions): UseFileAttachmentsResult;
+
 interface ChatContainerProps {
     /** Child components (MessageList, ChatInput, etc.) */
     children: React$1.ReactNode;
@@ -3014,6 +3199,14 @@ interface ChatInputProps {
     isLoading?: boolean;
     /** Whether to enable attachments */
     enableAttachments?: boolean;
+    /** Current attachment files (when enableAttachments is true) */
+    attachments?: AttachmentFile[];
+    /** Callback to remove an attachment */
+    onRemoveAttachment?: (uuid: string) => void;
+    /** Ref to FileDropZone for triggering file dialog */
+    dropZoneRef?: React$1.RefObject<FileDropZoneRef | null>;
+    /** Whether attachments are currently uploading */
+    isUploadingAttachments?: boolean;
     /** Additional CSS classes */
     className?: string;
 }
@@ -3031,7 +3224,7 @@ interface ChatInputProps {
  * />
  * ```
  */
-declare function ChatInput({ onSend, onStop, placeholder, disabled, isLoading, enableAttachments, className, }: ChatInputProps): react_jsx_runtime.JSX.Element;
+declare function ChatInput({ onSend, onStop, placeholder, disabled, isLoading, enableAttachments, attachments, onRemoveAttachment, dropZoneRef, isUploadingAttachments, className, }: ChatInputProps): react_jsx_runtime.JSX.Element;
 
 interface ToolCallEntryProps {
     /** Tool call data */
@@ -3163,4 +3356,25 @@ declare function HelpCircleIcon({ className, ...props }: IconProps): react_jsx_r
 declare function DatabaseIcon({ className, ...props }: IconProps): react_jsx_runtime.JSX.Element;
 declare function ClockIcon({ className, ...props }: IconProps): react_jsx_runtime.JSX.Element;
 
-export { AgentChat, type AgentChatProps, AlertCircleIcon, type Artifact$1 as Artifact, AskUserPrompt, type AskUserPromptProps, type AttachmentData, type AttachmentFile, BotIcon, type ChatAdapter, ChatConfigProvider, type ChatConfigProviderProps, ChatContainer, type ChatContainerProps, type ChatError, ChatInput, type ChatInputProps, ChatMessage, type ChatMessageProps, type ChatMessage$1 as ChatMessageType, CheckCircleIcon, CheckIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, CircleIcon, type ClarificationData, ClockIcon, CodeIcon, CopyIcon, DatabaseIcon, type DefaultAdapterConfig, DownloadIcon, type Execution, type ExecutionResult, type ExecutionStreamEvent, ExternalLinkIcon, FileIcon, FileTextIcon, HelpCircleIcon, type HistoryMessage, type IconProps, ImageIcon, ImagesIcon, type ListSessionsInput, ListTodoIcon, LoadingSpinner, MarkdownContent, type MarkdownContentProps, Maximize2Icon, MessageCircleIcon, MessageList, type MessageListProps, Minimize2Icon, PaperclipIcon, SendIcon, type SendMessageInput$1 as SendMessageInput, type SessionHistory$1 as SessionHistory, type SessionList, type SessionListItem, SparklesIcon, type StartExecutionInput, StopCircleIcon, type ThemeMode, type ThinkingBlock, type TodoItem, TodoList, type TodoListProps, type ToolCall, ToolCallEntry, type ToolCallEntryProps, type UploadUrlInput, type UploadUrlResult, type UseAgentChatOptions, type UseAgentChatResult, type UseExecutionStreamOptions, type UseExecutionStreamResult, UserIcon, XIcon, ZoomInIcon, ZoomOutIcon, createDefaultAdapter, useAgentChat, useChatConfig, useChatConfigOptional, useExecutionStream };
+/**
+ * Client-side image compression using Canvas API.
+ *
+ * Resizes images to max 1920px on longest side and iteratively
+ * reduces JPEG/WebP quality to hit a ~150KB target size.
+ * Skips SVGs, non-image files, and files already under the target.
+ */
+/**
+ * Compress an image file to approximately targetSizeKB using Canvas API.
+ *
+ * - Returns the original file if it's already under targetSizeKB
+ * - Skips SVGs and non-image files (returns as-is)
+ * - Resizes to max 1920px on longest side
+ * - Iteratively reduces quality to approach target size
+ *
+ * @param file - The File to compress
+ * @param targetSizeKB - Target output size in KB (default: 150)
+ * @returns Compressed File, or the original if no compression needed
+ */
+declare function compressImage(file: File, targetSizeKB?: number): Promise<File>;
+
+export { AgentChat, type AgentChatProps, AlertCircleIcon, type Artifact$1 as Artifact, AskUserPrompt, type AskUserPromptProps, type AttachmentData, type AttachmentFile, BotIcon, type ChatAdapter, ChatConfigProvider, type ChatConfigProviderProps, ChatContainer, type ChatContainerProps, type ChatError, ChatInput, type ChatInputProps, ChatMessage, type ChatMessageProps, type ChatMessage$1 as ChatMessageType, CheckCircleIcon, CheckIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, CircleIcon, type ClarificationData, ClockIcon, CodeIcon, CopyIcon, DatabaseIcon, type DefaultAdapterConfig, DownloadIcon, type Execution, type ExecutionResult, type ExecutionStreamEvent, ExternalLinkIcon, FileDropZone, type FileDropZoneProps, type FileDropZoneRef, FileIcon, FileTextIcon, HelpCircleIcon, type HistoryMessage, type IconProps, ImageIcon, ImagesIcon, type ListSessionsInput, ListTodoIcon, LoadingSpinner, MarkdownContent, type MarkdownContentProps, Maximize2Icon, MessageCircleIcon, MessageList, type MessageListProps, Minimize2Icon, PaperclipIcon, SendIcon, type SendMessageInput$1 as SendMessageInput, type SendMessageOptions, type SessionHistory$1 as SessionHistory, type SessionList, type SessionListItem, SparklesIcon, type StartExecutionInput, StopCircleIcon, type ThemeMode, type ThinkingBlock, type TodoItem, TodoList, type TodoListProps, type ToolCall, ToolCallEntry, type ToolCallEntryProps, type UploadUrlInput, type UploadUrlResult, type UseAgentChatOptions, type UseAgentChatResult, type UseExecutionStreamOptions, type UseExecutionStreamResult, type UseFileAttachmentsOptions, type UseFileAttachmentsResult, UserIcon, XIcon, ZoomInIcon, ZoomOutIcon, compressImage, createDefaultAdapter, useAgentChat, useChatConfig, useChatConfigOptional, useExecutionStream, useFileAttachments };