@erdoai/ui 0.1.19 → 0.1.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,7 +1,7 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
2
  import * as React$1 from 'react';
3
3
  import React__default from 'react';
4
- import { ErdoClient, ContentItem, InvokeResult, LogEntry, ToolGroup, InvocationStatus as InvocationStatus$1, SSEEvent, InvokeParams } from '@erdoai/types';
4
+ import { ErdoClient, ContentItem, InvokeResult, LogEntry, ToolGroup, InvocationStatus as InvocationStatus$1, SSEEvent, Thread } from '@erdoai/types';
5
5
  export { ContentItem } from '@erdoai/types';
6
6
  import * as RechartsPrimitive from 'recharts';
7
7
  import { UseQueryResult } from '@tanstack/react-query';
@@ -46,8 +46,8 @@ interface ErdoProviderConfig {
46
46
  */
47
47
  token?: string;
48
48
  /**
49
- * Optional ErdoClient for invoking bots.
50
- * Required if using useInvocation hook.
49
+ * Optional ErdoClient for thread operations.
50
+ * Required if using useThread hook.
51
51
  */
52
52
  client?: ErdoClient;
53
53
  /**
@@ -82,6 +82,21 @@ interface ErdoProviderConfig {
82
82
  content: any;
83
83
  className?: string;
84
84
  }>;
85
+ /**
86
+ * Optional callback when a suggestion is clicked.
87
+ * Use this to submit the suggestion as a new message.
88
+ *
89
+ * Example:
90
+ * ```tsx
91
+ * <ErdoProvider config={{
92
+ * baseUrl: '...',
93
+ * onSuggestionClick: (suggestion) => sendMessage(suggestion)
94
+ * }}>
95
+ * <App />
96
+ * </ErdoProvider>
97
+ * ```
98
+ */
99
+ onSuggestionClick?: (suggestion: string) => void;
85
100
  }
86
101
  interface ErdoProviderProps {
87
102
  children: React__default.ReactNode;
@@ -713,6 +728,14 @@ declare class ErrorBoundary extends React__default.Component<{
713
728
  render(): React__default.ReactNode;
714
729
  }
715
730
 
731
+ /**
732
+ * Spinning loader shown while content is being written/generated.
733
+ */
734
+ declare function WritingLoader(): react_jsx_runtime.JSX.Element;
735
+ /**
736
+ * Bouncing dots loader shown while streaming content is being parsed.
737
+ */
738
+ declare function StreamingLoader(): react_jsx_runtime.JSX.Element;
716
739
  /** Props passed to all content components */
717
740
  interface ContentComponentProps {
718
741
  content: ContentItem;
@@ -779,19 +802,29 @@ interface ErdoUIProps {
779
802
  /**
780
803
  * Main component for rendering Erdo agent results
781
804
  *
782
- * @example
805
+ * @example Server-side invocation result
806
+ * ```tsx
807
+ * import { ErdoUI } from '@erdoai/ui';
808
+ *
809
+ * // On your server
810
+ * const result = await client.invoke('my-bot', { messages: [...] });
811
+ *
812
+ * // On your client
813
+ * <ErdoUI result={result} />
814
+ * ```
815
+ *
816
+ * @example Client-side streaming with useThread
783
817
  * ```tsx
784
- * import { ErdoUI, useInvocation } from '@erdoai/ui';
818
+ * import { useThread, Content } from '@erdoai/ui';
785
819
  *
786
820
  * function MyComponent() {
787
- * const { result, isStreaming, invoke } = useInvocation();
821
+ * const { activeMessages, isStreaming, sendMessage } = useThread({ botKey: 'my-bot' });
788
822
  *
789
823
  * return (
790
824
  * <div>
791
- * <button onClick={() => invoke('my-bot', { messages: [...] })}>
792
- * Invoke
793
- * </button>
794
- * <ErdoUI result={result} isStreaming={isStreaming} />
825
+ * {activeMessages.flatMap(msg => msg.contents).map(content => (
826
+ * <Content key={content.id} content={content} />
827
+ * ))}
795
828
  * </div>
796
829
  * );
797
830
  * }
@@ -1181,58 +1214,99 @@ declare function useDatasetContents(datasetSlug: string, invocationId: string):
1181
1214
  */
1182
1215
  declare function useMultipleDatasetContents(datasetSlugs: string[], invocationId: string): UseQueryResult<any[], Error>[];
1183
1216
 
1184
- interface UseInvocationOptions {
1217
+ interface UseThreadOptions {
1218
+ /** Initial thread ID to use (if resuming an existing thread) */
1219
+ threadId?: string;
1220
+ /** Bot key to use for messages (optional - uses thread's default bot if not specified) */
1221
+ botKey?: string;
1185
1222
  /** Called for each SSE event received during streaming */
1186
1223
  onEvent?: (event: SSEEvent) => void;
1187
- /** Called when invocation completes successfully */
1188
- onFinish?: (result: InvokeResult) => void;
1224
+ /** Called when a message completes successfully */
1225
+ onFinish?: () => void;
1189
1226
  /** Called if an error occurs */
1190
1227
  onError?: (error: Error) => void;
1191
1228
  }
1192
- interface UseInvocationReturn {
1193
- /** Current invocation result (updates during streaming) */
1194
- result: InvokeResult | null;
1195
- /** Whether an invocation is currently in progress */
1229
+ interface UseThreadReturn {
1230
+ /** Current thread (null if not yet created) */
1231
+ thread: Thread | null;
1232
+ /** Whether a message is currently being sent/streamed */
1196
1233
  isStreaming: boolean;
1197
- /** Error if the last invocation failed */
1234
+ /** Error if the last operation failed */
1198
1235
  error: Error | null;
1199
- /** Function to start a new invocation */
1200
- invoke: (botKey: string, params: InvokeParams) => Promise<InvokeResult>;
1201
- /** Function to cancel the current invocation */
1236
+ /** Active messages being streamed (with parsedJson populated) */
1237
+ activeMessages: MessageWithContents[];
1238
+ /**
1239
+ * Flattened, filtered contents ready for rendering with the Content component.
1240
+ * Only includes visible content (user_visibility === 'visible').
1241
+ */
1242
+ streamingContents: ContentItem[];
1243
+ /** Function to send a message to the thread */
1244
+ sendMessage: (content: string) => Promise<void>;
1245
+ /** Function to cancel the current message */
1202
1246
  cancel: () => void;
1247
+ /** Function to create or set the thread */
1248
+ setThread: (thread: Thread) => void;
1203
1249
  }
1204
1250
  /**
1205
- * Hook for invoking Erdo bots and streaming results.
1251
+ * Hook for managing a thread and sending messages.
1252
+ *
1253
+ * Uses the thread/message API (`/threads/{id}/message`) which provides proper
1254
+ * message persistence and SSE event structure for UI rendering.
1255
+ *
1256
+ * ## Why threads instead of direct bot invoke?
1257
+ *
1258
+ * The direct bot invoke endpoint (`/bots/{key}/invoke`) returns raw SSE events
1259
+ * without message wrapping. The thread endpoint wraps all events with:
1260
+ * - `message created` events that establish message IDs
1261
+ * - Proper paths like `messages/{msgId}/contents/{idx}` for content
1262
+ * - `message updated` events for completion status
1263
+ *
1264
+ * This structure is required by `handleSSEEvent` to build the entity tree
1265
+ * that React components (like `Content`) use for rendering. Without it,
1266
+ * the UI components cannot properly track and display streaming content.
1267
+ *
1268
+ * For server-side processing where you don't need React rendering,
1269
+ * use `ErdoClient.invoke()` or `ErdoClient.invokeStream()` directly.
1270
+ *
1271
+ * ## Loading message history
1272
+ *
1273
+ * This hook focuses on streaming new messages. To load existing thread messages
1274
+ * (chat history), use `client.getThreadMessages(threadId)` with React Query or
1275
+ * your preferred data fetching solution:
1276
+ *
1277
+ * ```tsx
1278
+ * const { data: history } = useQuery({
1279
+ * queryKey: ['thread', 'messages', threadId],
1280
+ * queryFn: () => client.getThreadMessages(threadId),
1281
+ * });
1282
+ * ```
1206
1283
  *
1207
1284
  * Requires ErdoProvider with a client configured.
1208
1285
  *
1209
1286
  * @example
1210
1287
  * ```tsx
1211
- * function MyComponent() {
1212
- * const { result, isStreaming, invoke } = useInvocation({
1213
- * onEvent: (event) => console.log('Event:', event),
1214
- * onFinish: (result) => console.log('Done:', result),
1215
- * });
1288
+ * import { useThread, Content } from '@erdoai/ui';
1216
1289
  *
1217
- * const handleAnalyze = async () => {
1218
- * await invoke('org.my-bot', {
1219
- * messages: [{ role: 'user', content: 'Analyze sales data' }],
1220
- * datasets: ['sales-2024'],
1221
- * });
1222
- * };
1290
+ * function MyChat() {
1291
+ * const { isStreaming, streamingContents, sendMessage } = useThread({
1292
+ * botKey: 'org.my-bot',
1293
+ * onFinish: () => console.log('Message complete'),
1294
+ * });
1223
1295
  *
1224
1296
  * return (
1225
1297
  * <div>
1226
- * <button onClick={handleAnalyze} disabled={isStreaming}>
1227
- * {isStreaming ? 'Analyzing...' : 'Analyze'}
1298
+ * {streamingContents.map((content, idx) => (
1299
+ * <Content key={content.id || idx} content={content} />
1300
+ * ))}
1301
+ * <button onClick={() => sendMessage('Hello')} disabled={isStreaming}>
1302
+ * Send
1228
1303
  * </button>
1229
- * {result && <div>Result: {JSON.stringify(result)}</div>}
1230
1304
  * </div>
1231
1305
  * );
1232
1306
  * }
1233
1307
  * ```
1234
1308
  */
1235
- declare function useInvocation(options?: UseInvocationOptions): UseInvocationReturn;
1309
+ declare function useThread(options?: UseThreadOptions): UseThreadReturn;
1236
1310
 
1237
1311
  /**
1238
1312
  * Format a value based on its type and specified format pattern
@@ -1297,6 +1371,23 @@ declare function handleIncrementalMixedJsonParsing(outputContent: MessageContent
1297
1371
  * Returns the updated entity at the root level (typically a message or message_content),
1298
1372
  * or null if no update was performed (e.g., for message finished events).
1299
1373
  *
1374
+ * ## Important: Requires message-wrapped SSE events
1375
+ *
1376
+ * This function expects SSE events from the thread/message endpoint (`/threads/{id}/message`),
1377
+ * NOT from the direct bot invoke endpoint (`/bots/{key}/invoke`).
1378
+ *
1379
+ * The thread endpoint wraps events with message metadata:
1380
+ * - `message created` events establish message IDs in activeMessagesByID
1381
+ * - Event paths like `messages/{msgId}/contents/{idx}` locate content in the tree
1382
+ * - `message updated` events signal completion
1383
+ *
1384
+ * The direct invoke endpoint returns raw events without this wrapping, so content
1385
+ * cannot be properly associated with messages and the entity tree cannot be built.
1386
+ *
1387
+ * For React UI rendering, always use thread-based messaging via:
1388
+ * - `useThread` hook (client-side)
1389
+ * - `ErdoClient.sendMessage()` (server-side proxy)
1390
+ *
1300
1391
  * Note: Only message or message_content types can be returned as root objects.
1301
1392
  * Other entity types like invocation, step, output, etc. will be nested inside
1302
1393
  * a message_content entity.
@@ -1313,4 +1404,4 @@ declare function handleIncrementalMixedJsonParsing(outputContent: MessageContent
1313
1404
  */
1314
1405
  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;
1315
1406
 
1316
- 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 };
1407
+ 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, 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 };
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
2
  import * as React$1 from 'react';
3
3
  import React__default from 'react';
4
- import { ErdoClient, ContentItem, InvokeResult, LogEntry, ToolGroup, InvocationStatus as InvocationStatus$1, SSEEvent, InvokeParams } from '@erdoai/types';
4
+ import { ErdoClient, ContentItem, InvokeResult, LogEntry, ToolGroup, InvocationStatus as InvocationStatus$1, SSEEvent, Thread } from '@erdoai/types';
5
5
  export { ContentItem } from '@erdoai/types';
6
6
  import * as RechartsPrimitive from 'recharts';
7
7
  import { UseQueryResult } from '@tanstack/react-query';
@@ -46,8 +46,8 @@ interface ErdoProviderConfig {
46
46
  */
47
47
  token?: string;
48
48
  /**
49
- * Optional ErdoClient for invoking bots.
50
- * Required if using useInvocation hook.
49
+ * Optional ErdoClient for thread operations.
50
+ * Required if using useThread hook.
51
51
  */
52
52
  client?: ErdoClient;
53
53
  /**
@@ -82,6 +82,21 @@ interface ErdoProviderConfig {
82
82
  content: any;
83
83
  className?: string;
84
84
  }>;
85
+ /**
86
+ * Optional callback when a suggestion is clicked.
87
+ * Use this to submit the suggestion as a new message.
88
+ *
89
+ * Example:
90
+ * ```tsx
91
+ * <ErdoProvider config={{
92
+ * baseUrl: '...',
93
+ * onSuggestionClick: (suggestion) => sendMessage(suggestion)
94
+ * }}>
95
+ * <App />
96
+ * </ErdoProvider>
97
+ * ```
98
+ */
99
+ onSuggestionClick?: (suggestion: string) => void;
85
100
  }
86
101
  interface ErdoProviderProps {
87
102
  children: React__default.ReactNode;
@@ -713,6 +728,14 @@ declare class ErrorBoundary extends React__default.Component<{
713
728
  render(): React__default.ReactNode;
714
729
  }
715
730
 
731
+ /**
732
+ * Spinning loader shown while content is being written/generated.
733
+ */
734
+ declare function WritingLoader(): react_jsx_runtime.JSX.Element;
735
+ /**
736
+ * Bouncing dots loader shown while streaming content is being parsed.
737
+ */
738
+ declare function StreamingLoader(): react_jsx_runtime.JSX.Element;
716
739
  /** Props passed to all content components */
717
740
  interface ContentComponentProps {
718
741
  content: ContentItem;
@@ -779,19 +802,29 @@ interface ErdoUIProps {
779
802
  /**
780
803
  * Main component for rendering Erdo agent results
781
804
  *
782
- * @example
805
+ * @example Server-side invocation result
806
+ * ```tsx
807
+ * import { ErdoUI } from '@erdoai/ui';
808
+ *
809
+ * // On your server
810
+ * const result = await client.invoke('my-bot', { messages: [...] });
811
+ *
812
+ * // On your client
813
+ * <ErdoUI result={result} />
814
+ * ```
815
+ *
816
+ * @example Client-side streaming with useThread
783
817
  * ```tsx
784
- * import { ErdoUI, useInvocation } from '@erdoai/ui';
818
+ * import { useThread, Content } from '@erdoai/ui';
785
819
  *
786
820
  * function MyComponent() {
787
- * const { result, isStreaming, invoke } = useInvocation();
821
+ * const { activeMessages, isStreaming, sendMessage } = useThread({ botKey: 'my-bot' });
788
822
  *
789
823
  * return (
790
824
  * <div>
791
- * <button onClick={() => invoke('my-bot', { messages: [...] })}>
792
- * Invoke
793
- * </button>
794
- * <ErdoUI result={result} isStreaming={isStreaming} />
825
+ * {activeMessages.flatMap(msg => msg.contents).map(content => (
826
+ * <Content key={content.id} content={content} />
827
+ * ))}
795
828
  * </div>
796
829
  * );
797
830
  * }
@@ -1181,58 +1214,99 @@ declare function useDatasetContents(datasetSlug: string, invocationId: string):
1181
1214
  */
1182
1215
  declare function useMultipleDatasetContents(datasetSlugs: string[], invocationId: string): UseQueryResult<any[], Error>[];
1183
1216
 
1184
- interface UseInvocationOptions {
1217
+ interface UseThreadOptions {
1218
+ /** Initial thread ID to use (if resuming an existing thread) */
1219
+ threadId?: string;
1220
+ /** Bot key to use for messages (optional - uses thread's default bot if not specified) */
1221
+ botKey?: string;
1185
1222
  /** Called for each SSE event received during streaming */
1186
1223
  onEvent?: (event: SSEEvent) => void;
1187
- /** Called when invocation completes successfully */
1188
- onFinish?: (result: InvokeResult) => void;
1224
+ /** Called when a message completes successfully */
1225
+ onFinish?: () => void;
1189
1226
  /** Called if an error occurs */
1190
1227
  onError?: (error: Error) => void;
1191
1228
  }
1192
- interface UseInvocationReturn {
1193
- /** Current invocation result (updates during streaming) */
1194
- result: InvokeResult | null;
1195
- /** Whether an invocation is currently in progress */
1229
+ interface UseThreadReturn {
1230
+ /** Current thread (null if not yet created) */
1231
+ thread: Thread | null;
1232
+ /** Whether a message is currently being sent/streamed */
1196
1233
  isStreaming: boolean;
1197
- /** Error if the last invocation failed */
1234
+ /** Error if the last operation failed */
1198
1235
  error: Error | null;
1199
- /** Function to start a new invocation */
1200
- invoke: (botKey: string, params: InvokeParams) => Promise<InvokeResult>;
1201
- /** Function to cancel the current invocation */
1236
+ /** Active messages being streamed (with parsedJson populated) */
1237
+ activeMessages: MessageWithContents[];
1238
+ /**
1239
+ * Flattened, filtered contents ready for rendering with the Content component.
1240
+ * Only includes visible content (user_visibility === 'visible').
1241
+ */
1242
+ streamingContents: ContentItem[];
1243
+ /** Function to send a message to the thread */
1244
+ sendMessage: (content: string) => Promise<void>;
1245
+ /** Function to cancel the current message */
1202
1246
  cancel: () => void;
1247
+ /** Function to create or set the thread */
1248
+ setThread: (thread: Thread) => void;
1203
1249
  }
1204
1250
  /**
1205
- * Hook for invoking Erdo bots and streaming results.
1251
+ * Hook for managing a thread and sending messages.
1252
+ *
1253
+ * Uses the thread/message API (`/threads/{id}/message`) which provides proper
1254
+ * message persistence and SSE event structure for UI rendering.
1255
+ *
1256
+ * ## Why threads instead of direct bot invoke?
1257
+ *
1258
+ * The direct bot invoke endpoint (`/bots/{key}/invoke`) returns raw SSE events
1259
+ * without message wrapping. The thread endpoint wraps all events with:
1260
+ * - `message created` events that establish message IDs
1261
+ * - Proper paths like `messages/{msgId}/contents/{idx}` for content
1262
+ * - `message updated` events for completion status
1263
+ *
1264
+ * This structure is required by `handleSSEEvent` to build the entity tree
1265
+ * that React components (like `Content`) use for rendering. Without it,
1266
+ * the UI components cannot properly track and display streaming content.
1267
+ *
1268
+ * For server-side processing where you don't need React rendering,
1269
+ * use `ErdoClient.invoke()` or `ErdoClient.invokeStream()` directly.
1270
+ *
1271
+ * ## Loading message history
1272
+ *
1273
+ * This hook focuses on streaming new messages. To load existing thread messages
1274
+ * (chat history), use `client.getThreadMessages(threadId)` with React Query or
1275
+ * your preferred data fetching solution:
1276
+ *
1277
+ * ```tsx
1278
+ * const { data: history } = useQuery({
1279
+ * queryKey: ['thread', 'messages', threadId],
1280
+ * queryFn: () => client.getThreadMessages(threadId),
1281
+ * });
1282
+ * ```
1206
1283
  *
1207
1284
  * Requires ErdoProvider with a client configured.
1208
1285
  *
1209
1286
  * @example
1210
1287
  * ```tsx
1211
- * function MyComponent() {
1212
- * const { result, isStreaming, invoke } = useInvocation({
1213
- * onEvent: (event) => console.log('Event:', event),
1214
- * onFinish: (result) => console.log('Done:', result),
1215
- * });
1288
+ * import { useThread, Content } from '@erdoai/ui';
1216
1289
  *
1217
- * const handleAnalyze = async () => {
1218
- * await invoke('org.my-bot', {
1219
- * messages: [{ role: 'user', content: 'Analyze sales data' }],
1220
- * datasets: ['sales-2024'],
1221
- * });
1222
- * };
1290
+ * function MyChat() {
1291
+ * const { isStreaming, streamingContents, sendMessage } = useThread({
1292
+ * botKey: 'org.my-bot',
1293
+ * onFinish: () => console.log('Message complete'),
1294
+ * });
1223
1295
  *
1224
1296
  * return (
1225
1297
  * <div>
1226
- * <button onClick={handleAnalyze} disabled={isStreaming}>
1227
- * {isStreaming ? 'Analyzing...' : 'Analyze'}
1298
+ * {streamingContents.map((content, idx) => (
1299
+ * <Content key={content.id || idx} content={content} />
1300
+ * ))}
1301
+ * <button onClick={() => sendMessage('Hello')} disabled={isStreaming}>
1302
+ * Send
1228
1303
  * </button>
1229
- * {result && <div>Result: {JSON.stringify(result)}</div>}
1230
1304
  * </div>
1231
1305
  * );
1232
1306
  * }
1233
1307
  * ```
1234
1308
  */
1235
- declare function useInvocation(options?: UseInvocationOptions): UseInvocationReturn;
1309
+ declare function useThread(options?: UseThreadOptions): UseThreadReturn;
1236
1310
 
1237
1311
  /**
1238
1312
  * Format a value based on its type and specified format pattern
@@ -1297,6 +1371,23 @@ declare function handleIncrementalMixedJsonParsing(outputContent: MessageContent
1297
1371
  * Returns the updated entity at the root level (typically a message or message_content),
1298
1372
  * or null if no update was performed (e.g., for message finished events).
1299
1373
  *
1374
+ * ## Important: Requires message-wrapped SSE events
1375
+ *
1376
+ * This function expects SSE events from the thread/message endpoint (`/threads/{id}/message`),
1377
+ * NOT from the direct bot invoke endpoint (`/bots/{key}/invoke`).
1378
+ *
1379
+ * The thread endpoint wraps events with message metadata:
1380
+ * - `message created` events establish message IDs in activeMessagesByID
1381
+ * - Event paths like `messages/{msgId}/contents/{idx}` locate content in the tree
1382
+ * - `message updated` events signal completion
1383
+ *
1384
+ * The direct invoke endpoint returns raw events without this wrapping, so content
1385
+ * cannot be properly associated with messages and the entity tree cannot be built.
1386
+ *
1387
+ * For React UI rendering, always use thread-based messaging via:
1388
+ * - `useThread` hook (client-side)
1389
+ * - `ErdoClient.sendMessage()` (server-side proxy)
1390
+ *
1300
1391
  * Note: Only message or message_content types can be returned as root objects.
1301
1392
  * Other entity types like invocation, step, output, etc. will be nested inside
1302
1393
  * a message_content entity.
@@ -1313,4 +1404,4 @@ declare function handleIncrementalMixedJsonParsing(outputContent: MessageContent
1313
1404
  */
1314
1405
  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;
1315
1406
 
1316
- 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 };
1407
+ 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, 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 };