@erdoai/ui 0.1.20 → 0.1.24

package/dist/index.d.cts

@@ -1,12 +1,19 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
 import React__default from 'react';
-import { ErdoClient, ContentItem, InvokeResult, LogEntry, ToolGroup, InvocationStatus as InvocationStatus$1, SSEEvent, InvokeParams } from '@erdoai/types';
+import { ErdoClient, ContentItem, InvokeResult, LogEntry, ToolGroup, InvocationStatus as InvocationStatus$1, SSEEvent, Thread } from '@erdoai/types';
 export { ContentItem } from '@erdoai/types';
 import * as RechartsPrimitive from 'recharts';
 import { UseQueryResult } from '@tanstack/react-query';
 import { ClassValue } from 'clsx';
 
+/**
+ * Dataset details returned by getDatasetDetails
+ */
+interface DatasetDetails {
+    id: string;
+    name: string;
+}
 /**
  * Interface for custom data fetching implementations.
  * Use this when you need to override the default REST API behavior,
@@ -17,6 +24,16 @@ import { ClassValue } from 'clsx';
  */
 interface DataFetcher {
     fetchDatasetContents: (slug: string, invocationId: string) => Promise<any[]>;
+    /**
+     * Get dataset details (id and name) by slug.
+     * Used by DatasetDownload component to resolve slug to downloadable dataset.
+     */
+    getDatasetDetails?: (slug: string, threadId: string) => Promise<DatasetDetails | null>;
+    /**
+     * Download a dataset file by ID.
+     * Returns a Blob that can be saved as a file.
+     */
+    downloadDataset?: (datasetId: string) => Promise<Blob>;
 }
 /**
  * Configuration for the ErdoProvider.
@@ -27,6 +44,11 @@ interface ErdoProviderConfig {
      * Used by default REST implementation in hooks.
      */
     baseUrl: string;
+    /**
+     * Optional thread ID for dataset operations.
+     * Used by DatasetDownload to resolve dataset slugs.
+     */
+    threadId?: string;
     /**
      * Optional auth token for API calls.
      * Will be sent as Bearer token in Authorization header.
@@ -46,8 +68,8 @@ interface ErdoProviderConfig {
      */
     token?: string;
     /**
-     * Optional ErdoClient for invoking bots.
-     * Required if using useInvocation hook.
+     * Optional ErdoClient for thread operations.
+     * Required if using useThread hook.
      */
     client?: ErdoClient;
     /**
@@ -82,6 +104,21 @@ interface ErdoProviderConfig {
         content: any;
         className?: string;
     }>;
+    /**
+     * Optional callback when a suggestion is clicked.
+     * Use this to submit the suggestion as a new message.
+     *
+     * Example:
+     * ```tsx
+     * <ErdoProvider config={{
+     *   baseUrl: '...',
+     *   onSuggestionClick: (suggestion) => sendMessage(suggestion)
+     * }}>
+     *   <App />
+     * </ErdoProvider>
+     * ```
+     */
+    onSuggestionClick?: (suggestion: string) => void;
 }
 interface ErdoProviderProps {
     children: React__default.ReactNode;
@@ -713,6 +750,14 @@ declare class ErrorBoundary extends React__default.Component<{
     render(): React__default.ReactNode;
 }
 
+/**
+ * Spinning loader shown while content is being written/generated.
+ */
+declare function WritingLoader(): react_jsx_runtime.JSX.Element;
+/**
+ * Bouncing dots loader shown while streaming content is being parsed.
+ */
+declare function StreamingLoader(): react_jsx_runtime.JSX.Element;
 /** Props passed to all content components */
 interface ContentComponentProps {
     content: ContentItem;
@@ -779,19 +824,29 @@ interface ErdoUIProps {
 /**
  * Main component for rendering Erdo agent results
  *
- * @example
+ * @example Server-side invocation result
+ * ```tsx
+ * import { ErdoUI } from '@erdoai/ui';
+ *
+ * // On your server
+ * const result = await client.invoke('my-bot', { messages: [...] });
+ *
+ * // On your client
+ * <ErdoUI result={result} />
+ * ```
+ *
+ * @example Client-side streaming with useThread
  * ```tsx
- * import { ErdoUI, useInvocation } from '@erdoai/ui';
+ * import { useThread, Content } from '@erdoai/ui';
  *
  * function MyComponent() {
- *   const { result, isStreaming, invoke } = useInvocation();
+ *   const { activeMessages, isStreaming, sendMessage } = useThread({ botKey: 'my-bot' });
  *
  *   return (
  *     <div>
- *       <button onClick={() => invoke('my-bot', { messages: [...] })}>
- *         Invoke
- *       </button>
- *       <ErdoUI result={result} isStreaming={isStreaming} />
+ *       {activeMessages.flatMap(msg => msg.contents).map(content => (
+ *         <Content key={content.id} content={content} />
+ *       ))}
  *     </div>
  *   );
  * }
@@ -1118,6 +1173,29 @@ interface StatusSpinnerProps {
  */
 declare function StatusSpinner({ status, color, size, className }: StatusSpinnerProps): react_jsx_runtime.JSX.Element;
 
+interface DatasetDownloadProps {
+    /** Dataset slug to download */
+    slug: string;
+    /** Invocation ID (used for context, may be needed by some backends) */
+    invocationId?: string;
+    /** Optional thread ID override (falls back to provider's threadId) */
+    threadId?: string;
+    /** Optional class name for styling */
+    className?: string;
+}
+/**
+ * A download button component for datasets.
+ *
+ * Uses the DataFetcher from ErdoProvider if available, otherwise falls back
+ * to REST API calls using baseUrl and auth tokens.
+ *
+ * @example
+ * ```tsx
+ * <DatasetDownload slug="my-dataset" invocationId="abc123" />
+ * ```
+ */
+declare function DatasetDownload({ slug, invocationId: _invocationId, threadId: threadIdProp, className, }: DatasetDownloadProps): react_jsx_runtime.JSX.Element | null;
+
 interface ZoomState {
     refAreaLeft: number | null;
     refAreaRight: number | null;
@@ -1181,58 +1259,118 @@ declare function useDatasetContents(datasetSlug: string, invocationId: string):
  */
 declare function useMultipleDatasetContents(datasetSlugs: string[], invocationId: string): UseQueryResult<any[], Error>[];
 
-interface UseInvocationOptions {
+interface UseThreadOptions {
+    /** Initial thread ID to use (if resuming an existing thread) */
+    threadId?: string;
+    /** Bot key to use for messages (optional - uses thread's default bot if not specified) */
+    botKey?: string;
     /** Called for each SSE event received during streaming */
     onEvent?: (event: SSEEvent) => void;
-    /** Called when invocation completes successfully */
-    onFinish?: (result: InvokeResult) => void;
+    /** Called when a message completes successfully */
+    onFinish?: () => void;
     /** Called if an error occurs */
     onError?: (error: Error) => void;
 }
-interface UseInvocationReturn {
-    /** Current invocation result (updates during streaming) */
-    result: InvokeResult | null;
-    /** Whether an invocation is currently in progress */
+interface UseThreadReturn {
+    /** Current thread (null if not yet created) */
+    thread: Thread | null;
+    /** Whether a message is currently being sent/streamed */
     isStreaming: boolean;
-    /** Error if the last invocation failed */
+    /** Error if the last operation failed */
     error: Error | null;
-    /** Function to start a new invocation */
-    invoke: (botKey: string, params: InvokeParams) => Promise<InvokeResult>;
-    /** Function to cancel the current invocation */
+    /** Active messages being streamed (with parsedJson populated) */
+    activeMessages: MessageWithContents[];
+    /**
+     * Flattened, filtered contents ready for rendering with the Content component.
+     * Only includes visible content (user_visibility === 'visible').
+     */
+    streamingContents: ContentItem[];
+    /** Function to send a message to the thread */
+    sendMessage: (content: string) => Promise<void>;
+    /** Function to cancel the current message */
     cancel: () => void;
+    /** Function to create or set the thread */
+    setThread: (thread: Thread) => void;
 }
 /**
- * Hook for invoking Erdo bots and streaming results.
+ * Hook for managing a thread and sending messages.
+ *
+ * Uses the thread/message API (`/threads/{id}/message`) which provides proper
+ * message persistence and SSE event structure for UI rendering.
+ *
+ * ## Why threads instead of direct bot invoke?
+ *
+ * The direct bot invoke endpoint (`/bots/{key}/invoke`) returns raw SSE events
+ * without message wrapping. The thread endpoint wraps all events with:
+ * - `message created` events that establish message IDs
+ * - Proper paths like `messages/{msgId}/contents/{idx}` for content
+ * - `message updated` events for completion status
+ *
+ * This structure is required by `handleSSEEvent` to build the entity tree
+ * that React components (like `Content`) use for rendering. Without it,
+ * the UI components cannot properly track and display streaming content.
+ *
+ * For server-side processing where you don't need React rendering,
+ * use `ErdoClient.invoke()` or `ErdoClient.invokeStream()` directly.
+ *
+ * ## Persisting message history
+ *
+ * This hook focuses on streaming new messages. For chat history, we recommend
+ * storing messages in your own database as they complete:
+ *
+ * ```tsx
+ * const { streamingContents, sendMessage } = useThread({
+ *   botKey: 'org.my-bot',
+ *   onFinish: () => {
+ *     // Save to your database when message completes
+ *     await saveMessageToDb(threadId, streamingContents);
+ *   },
+ * });
+ *
+ * // Load history from your database
+ * const { data: history } = useQuery({
+ *   queryKey: ['messages', threadId],
+ *   queryFn: () => fetchMessagesFromDb(threadId),
+ * });
+ * ```
+ *
+ * This gives you full control over your data and avoids extra API calls.
+ *
+ * Alternatively, you can fetch history from Erdo using `client.getThreadMessages()`:
+ *
+ * ```tsx
+ * const { data: history } = useQuery({
+ *   queryKey: ['thread', 'messages', threadId],
+ *   queryFn: () => client.getThreadMessages(threadId),
+ * });
+ * ```
  *
  * Requires ErdoProvider with a client configured.
  *
  * @example
  * ```tsx
- * function MyComponent() {
- *   const { result, isStreaming, invoke } = useInvocation({
- *     onEvent: (event) => console.log('Event:', event),
- *     onFinish: (result) => console.log('Done:', result),
- *   });
+ * import { useThread, Content } from '@erdoai/ui';
  *
- *   const handleAnalyze = async () => {
- *     await invoke('org.my-bot', {
- *       messages: [{ role: 'user', content: 'Analyze sales data' }],
- *       datasets: ['sales-2024'],
- *     });
- *   };
+ * function MyChat() {
+ *   const { isStreaming, streamingContents, sendMessage } = useThread({
+ *     botKey: 'org.my-bot',
+ *     onFinish: () => console.log('Message complete'),
+ *   });
  *
  *   return (
  *     <div>
- *       <button onClick={handleAnalyze} disabled={isStreaming}>
- *         {isStreaming ? 'Analyzing...' : 'Analyze'}
+ *       {streamingContents.map((content, idx) => (
+ *         <Content key={content.id || idx} content={content} />
+ *       ))}
+ *       <button onClick={() => sendMessage('Hello')} disabled={isStreaming}>
+ *         Send
  *       </button>
- *       {result && <div>Result: {JSON.stringify(result)}</div>}
  *     </div>
  *   );
  * }
  * ```
  */
-declare function useInvocation(options?: UseInvocationOptions): UseInvocationReturn;
+declare function useThread(options?: UseThreadOptions): UseThreadReturn;
 
 /**
  * Format a value based on its type and specified format pattern
@@ -1297,6 +1435,23 @@ declare function handleIncrementalMixedJsonParsing(outputContent: MessageContent
  * Returns the updated entity at the root level (typically a message or message_content),
  * or null if no update was performed (e.g., for message finished events).
  *
+ * ## Important: Requires message-wrapped SSE events
+ *
+ * This function expects SSE events from the thread/message endpoint (`/threads/{id}/message`),
+ * NOT from the direct bot invoke endpoint (`/bots/{key}/invoke`).
+ *
+ * The thread endpoint wraps events with message metadata:
+ * - `message created` events establish message IDs in activeMessagesByID
+ * - Event paths like `messages/{msgId}/contents/{idx}` locate content in the tree
+ * - `message updated` events signal completion
+ *
+ * The direct invoke endpoint returns raw events without this wrapping, so content
+ * cannot be properly associated with messages and the entity tree cannot be built.
+ *
+ * For React UI rendering, always use thread-based messaging via:
+ * - `useThread` hook (client-side)
+ * - `ErdoClient.sendMessage()` (server-side proxy)
+ *
  * Note: Only message or message_content types can be returned as root objects.
  * Other entity types like invocation, step, output, etc. will be nested inside
  * a message_content entity.
@@ -1313,4 +1468,4 @@ declare function handleIncrementalMixedJsonParsing(outputContent: MessageContent
  */
 declare function handleSSEEvent(eventType: string, event: SSEEventData, path: string[], threadID: string, activeMessagesByID: Record<string, MessageWithContents>, currentEntity?: Entity | null, parents?: Entity[], entityIds?: Record<string, string>): Entity | null;
 
-export { BarChart, type BaseChartProps, type BotInvocation, BotInvocationContent, type BotInvocationContentData, type BotInvocationContentProps, type BotInvocationData, type BotInvocationEventInfo, type BotInvocationStatusInfo, Chart, type ChartConfig, ChartContainer, ChartContent, type ChartContentProps, ChartLegend, ChartLegendContent, ChartStyle, ChartTooltip, ChartTooltipContent, CodeexecContent, type CodeexecContentProps, CodegenContent, type CodegenContentProps, CollapsibleCodeBlock, type CollapsibleCodeBlockProps, Content, type ContentChartConfig, type ContentChunk, type ContentComponentProps, type ContentProps, type ContentType, type DataFetcher, DatasetChart, type DatasetChartProps, DatasetTable, type DatasetTableProps, type Entity, type EntityType, ErdoProvider, type ErdoProviderConfig, type ErdoProviderProps, ErdoUI, type ErdoUIProps, ErrorBoundary, ExecutionStatus, ExpandableOutputContent, type ExpandableOutputContentProps, HeatmapChart, InvocationEvent, type InvocationEventProps, InvocationEvents, type InvocationEventsProps, InvocationStatus, JSONStreamParser, type JSONValue, JsonContent, type JsonContentProps, LineChart, Log, LogContent, type LogContentProps, type LogProps, MarkdownContent, type MarkdownContentProps, type Message, type MessageContent, type MessageStreamingState, type MessageWithContents, Output, type OutputContent, type OutputProps, type OutputWithContents, PieChart, type ResolvedBotInvocation, type ResultHandler, type SSEEventData, ScatterChart, type SpinnerStatus, SqlContent, type SqlContentProps, type Status, type StatusEvent, StatusSpinner, type StatusSpinnerProps, StderrText, StdoutText, StdwarnText, type Step, StepInvocation, type StepInvocationProps, StepInvocationStatus, type StepInvocationStatusProps, TableContent, type TableContentProps, TextContent, type TextContentProps, ThinkingContent, type ThinkingContentProps, ToolGroupContent, type ToolGroupContentProps, type UseInvocationOptions, type UseInvocationReturn, WebParseContent, type WebParseContentProps, WebSearchContent, type WebSearchContentProps, type WrapperType, cn, extractContentItems, formatValue, handleIncrementalMixedJsonParsing, handleSSEEvent, isJsonLike, isParsingComplete, isParsingInProgress, isWhitespaceChar, parseCompleteJson, parseMixedJson, parseToDate, resolveKeyFromData, toSnakeCase, useChartZoom, useDatasetContents, useErdoConfig, useErdoConfigOptional, useInvocation, useMultipleDatasetContents };
+export { BarChart, type BaseChartProps, type BotInvocation, BotInvocationContent, type BotInvocationContentData, type BotInvocationContentProps, type BotInvocationData, type BotInvocationEventInfo, type BotInvocationStatusInfo, Chart, type ChartConfig, ChartContainer, ChartContent, type ChartContentProps, ChartLegend, ChartLegendContent, ChartStyle, ChartTooltip, ChartTooltipContent, CodeexecContent, type CodeexecContentProps, CodegenContent, type CodegenContentProps, CollapsibleCodeBlock, type CollapsibleCodeBlockProps, Content, type ContentChartConfig, type ContentChunk, type ContentComponentProps, type ContentProps, type ContentType, type DataFetcher, DatasetChart, type DatasetChartProps, type DatasetDetails, DatasetDownload, type DatasetDownloadProps, DatasetTable, type DatasetTableProps, type Entity, type EntityType, ErdoProvider, type ErdoProviderConfig, type ErdoProviderProps, ErdoUI, type ErdoUIProps, ErrorBoundary, ExecutionStatus, ExpandableOutputContent, type ExpandableOutputContentProps, HeatmapChart, InvocationEvent, type InvocationEventProps, InvocationEvents, type InvocationEventsProps, InvocationStatus, JSONStreamParser, type JSONValue, JsonContent, type JsonContentProps, LineChart, Log, LogContent, type LogContentProps, type LogProps, MarkdownContent, type MarkdownContentProps, type Message, type MessageContent, type MessageStreamingState, type MessageWithContents, Output, type OutputContent, type OutputProps, type OutputWithContents, PieChart, type ResolvedBotInvocation, type ResultHandler, type SSEEventData, ScatterChart, type SpinnerStatus, SqlContent, type SqlContentProps, type Status, type StatusEvent, StatusSpinner, type StatusSpinnerProps, StderrText, StdoutText, StdwarnText, type Step, StepInvocation, type StepInvocationProps, StepInvocationStatus, type StepInvocationStatusProps, StreamingLoader, TableContent, type TableContentProps, TextContent, type TextContentProps, ThinkingContent, type ThinkingContentProps, ToolGroupContent, type ToolGroupContentProps, type UseThreadOptions, type UseThreadReturn, WebParseContent, type WebParseContentProps, WebSearchContent, type WebSearchContentProps, type WrapperType, WritingLoader, cn, extractContentItems, formatValue, handleIncrementalMixedJsonParsing, handleSSEEvent, isJsonLike, isParsingComplete, isParsingInProgress, isWhitespaceChar, parseCompleteJson, parseMixedJson, parseToDate, resolveKeyFromData, toSnakeCase, useChartZoom, useDatasetContents, useErdoConfig, useErdoConfigOptional, useMultipleDatasetContents, useThread };