@ensembleapp/client-sdk 0.0.26 → 0.0.28

package/dist/index.d.ts

@@ -1,99 +1,38 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as ai from 'ai';
 import { UIMessage } from 'ai';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import z, { AnyZodObject } from 'zod';
 import React$1 from 'react';
 import { ClassValue } from 'clsx';
 
-/** @minimum 1 */
-type VersionSelector = 'latest' | 'published' | number;
+/** Derived part type from UIMessage */
+type UIMessagePart = UIMessage['parts'][number];
 /**
- * fetch data via tool call.
- */
-type ToolCallConfig = {
-    toolId: string;
-    /**
-     * Select the tool version (default to 'latest' if not provided).
-     * - 'latest': pick draft if exists, fallback to latest published version
-     * - 'published': pick latest published version, fallback to draft version
-     * - number: specific tool version (1+)
-     */
-    version?: VersionSelector;
-    /**
-     * Tool input can be literal or templated string with expressions
-     */
-    inputs?: Record<string, unknown>;
-};
-/**
- * Widget enrichment configuration.
- * Keys are used to access the enrichment results in the render function.
+ * ChatMessageSection = a block of content
+ * - step: one LLM turn's output (content between step-start markers)
+ * - group: sub-agent output (content within data-tag-start/end markers)
  *
- * Example:
- * ```typescript
- * enrich: {
- *   vendorDetails: { toolId: 'vendor-tool', inputs: { ids: "${vendors}" } },
- *   pricing: { toolId: 'pricing-tool', inputs: { ids: "${vendors}" } },
- * },
- * render: (payload, enriched) => {
- *   const vendors = enriched?.vendorDetails?.data;
- *   const pricing = enriched?.pricing?.data;
- * }
- * ```
+ * Parts are raw UIMessagePart from AI SDK - no transformation.
+ * Structural markers (step-start, data-tag-start/end, data-transfer) are consumed during grouping.
  */
-type WidgetEnrichConfig = Record<string, ToolCallConfig>;
-/**
- * Enrichment result containing the full tool response.
- * This should mirror ToolResult on server-side without debug/metadata info.
- */
-type EnrichmentResult<TData = unknown> = {
-    success: boolean;
-    error?: {
-        message?: string;
-        code?: string;
-    };
-    data?: TData;
-};
-/** Widget output shape sent to the client */
-type UIWidget = {
-    widgetType: string;
-    /** LLM-generated data based on the widget schema specified by the client */
-    payload: unknown;
-    /** Server-injected enrichment results from tool calls, keyed by enrichment name */
-    enriched?: Record<string, EnrichmentResult>;
-};
-
-interface ToolCallContent {
-    type: 'tool-call';
-    toolName: string;
-    input?: Record<string, unknown>;
-    state: 'pending' | 'output-available' | 'error';
-    output?: unknown;
-}
-type ChatContentItem = string | UIWidget | ToolCallContent;
-/** A grouped section of sub-agent output, wrapped by data-tag-start/end markers */
-interface TagGroup {
-    tagId: string;
-    content: ChatContentItem[];
-    /** Index into content[] where the last step begins (for promoting only final output) */
-    lastStepStartIndex?: number;
-}
-/** A single section in the message, rendered in chronological order */
-type MessageSection = {
-    type: 'content';
-    item: ChatContentItem;
+type ChatMessageSection = {
+    type: 'step';
+    parts: UIMessagePart[];
 } | {
-    type: 'tag-group';
-    group: TagGroup;
+    type: 'group';
+    groupName: string;
+    parts: UIMessagePart[];
 };
+/**
+ * ChatMessage = our UIMessage abstraction to account for step and groupings
+ * Passes through id, role, metadata. Replaces parts with sections.
+ */
 interface ChatMessage {
     id: string;
     role: 'user' | 'assistant';
-    /** Ordered sections: content items and tag groups interleaved chronologically */
-    sections: MessageSection[];
-    thoughts?: (string | UIWidget)[];
-    createdAt?: Date;
+    metadata?: unknown;
+    sections: ChatMessageSection[];
 }
-type DisplayMode = 'full' | 'brief';
 
 type DeprecatedChatConfig = {
     /** @deprecated use agentId instead */
@@ -106,6 +45,8 @@ interface ApiConfig {
     token: string;
     headers?: Record<string, string>;
 }
+/** Agent version selector: 'latest' (default), 'published', or a specific version number */
+type AgentVersion = 'latest' | 'published' | number;
 type UseChatConfig = DeprecatedChatConfig & {
     /** The server API configuration */
     api: ApiConfig;
@@ -113,10 +54,10 @@ type UseChatConfig = DeprecatedChatConfig & {
     threadId: string;
     /** Ensemble agent ID to connect to */
     agentId?: string;
+    /** Agent version: 'latest' (default), 'published', or a specific version number */
+    agentVersion?: AgentVersion;
     /** additional context (anything) that needs to be passed to the LLM */
     dataContext?: unknown;
-    /** Display mode: 'brief' (default) shows only last block per step, 'full' shows everything */
-    displayMode?: DisplayMode;
     onError?: (error: Error) => void;
     /** Called when API returns 401/unauthorized (e.g., token expiry). Return a new token to retry the request. */
     onAuthError?: () => Promise<string | null>;
@@ -124,7 +65,7 @@ type UseChatConfig = DeprecatedChatConfig & {
     onData?: (data: any) => void;
     onMessage?: (message: UIMessage) => void;
 };
-declare function useChat({ api, threadId, agentId, agentExecutionId, dataContext, displayMode, onError, onAuthError, onFinish, onData, onMessage, }: UseChatConfig): {
+declare function useChat({ api, threadId, agentId, agentVersion, agentExecutionId, dataContext, onError, onAuthError, onFinish, onData, onMessage, }: UseChatConfig): {
     messages: ChatMessage[];
     status: ai.ChatStatus;
     isLoadingInitial: boolean;
@@ -151,35 +92,53 @@ declare function useChat({ api, threadId, agentId, agentExecutionId, dataContext
     setMessages: (messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[]) => UIMessage<unknown, ai.UIDataTypes, ai.UITools>[])) => void;
 };
 
-type FeedbackRating = 'positive' | 'negative';
-interface MessageFeedback {
-    id: string;
-    messageId: string;
-    rating: FeedbackRating;
-    improvementText?: string;
-    createdAt: Date;
-}
-interface FeedbackState {
-    rating: FeedbackRating;
-    comment?: string;
-}
-interface UseFeedbackConfig {
-    api: ApiConfig;
-    threadId: string;
-    agentId?: string;
-    agentExecutionId?: string;
-}
-interface SubmitFeedbackParams {
-    messageId: string;
-    rating: FeedbackRating;
-    improvementText?: string;
-}
-declare function useFeedback({ api, threadId, agentId, agentExecutionId, }: UseFeedbackConfig): {
-    submitFeedback: ({ messageId, rating, improvementText }: SubmitFeedbackParams) => Promise<MessageFeedback | null>;
-    getFeedbackForMessage: (messageId: string) => FeedbackState | undefined;
-    hasFeedback: (messageId: string) => boolean;
-    isSubmitting: string | null;
-    error: Error | null;
+/** @minimum 1 */
+type VersionSelector = 'latest' | 'published' | number;
+/**
+ * fetch data via tool call.
+ */
+type ToolCallConfig = {
+    toolId: string;
+    /**
+     * Select the tool version (default to 'latest' if not provided).
+     * - 'latest': pick draft if exists, fallback to latest published version
+     * - 'published': pick latest published version, fallback to draft version
+     * - number: specific tool version (1+)
+     */
+    version?: VersionSelector;
+    /**
+     * Tool input can be literal or templated string with expressions
+     */
+    inputs?: Record<string, unknown>;
+};
+/**
+ * Widget enrichment configuration.
+ * Keys are used to access the enrichment results in the render function.
+ *
+ * Example:
+ * ```typescript
+ * enrich: {
+ *   vendorDetails: { toolId: 'vendor-tool', inputs: { ids: "${vendors}" } },
+ *   pricing: { toolId: 'pricing-tool', inputs: { ids: "${vendors}" } },
+ * },
+ * render: (payload, enriched) => {
+ *   const vendors = enriched?.vendorDetails?.data;
+ *   const pricing = enriched?.pricing?.data;
+ * }
+ * ```
+ */
+type WidgetEnrichConfig = Record<string, ToolCallConfig>;
+/**
+ * Enrichment result containing the full tool response.
+ * This should mirror ToolResult on server-side without debug/metadata info.
+ */
+type EnrichmentResult<TData = unknown> = {
+    success: boolean;
+    error?: {
+        message?: string;
+        code?: string;
+    };
+    data?: TData;
 };
 
 /** Enriched results keyed by enrichment name */
@@ -209,6 +168,8 @@ interface UIWidgetDefinition<TSchema extends AnyZodObject = AnyZodObject, TEnric
 }
 declare const createWidget: <TSchema extends AnyZodObject, TEnriched extends EnrichedResults = EnrichedResults>({ widgetType, schema, enrich, render, }: UIWidgetDefinition<TSchema, TEnriched>) => UIWidgetDefinition<TSchema, TEnriched>;
 
+type DisplayMode = 'full' | 'brief';
+
 interface ChatWidgetStyles {
     primaryColor?: string;
     primaryTextColor?: string;
@@ -246,11 +207,9 @@ interface ChatWidgetFeedbackOptions {
     /** Require comment when giving negative feedback. Default: false */
     requireCommentForNegative?: boolean;
 }
-interface ChatWidgetConfig extends Omit<UseChatConfig, 'displayMode'> {
+interface ChatWidgetConfig extends UseChatConfig {
     /** Title for the Chat window */
     title?: string;
-    /** Display mode: 'brief' (default) shows only last block per step, 'full' shows everything */
-    displayMode?: DisplayMode;
     /** Initial assistant message displayed at the start of the chat (if history is empty).
      * Skipped if initialUserMessage is provided. */
     initialAssistantMessage?: string;
@@ -259,6 +218,8 @@ interface ChatWidgetConfig extends Omit<UseChatConfig, 'displayMode'> {
     initialUserMessage?: string;
     /** Placeholder text for the input box */
     inputPlaceholder?: string;
+    /** Display mode: 'brief' (default) collapses previous steps, 'full' shows everything */
+    displayMode?: DisplayMode;
     className?: string;
     styles?: ChatWidgetStyles;
     voice?: ChatWidgetVoiceOptions;
@@ -267,7 +228,7 @@ interface ChatWidgetConfig extends Omit<UseChatConfig, 'displayMode'> {
     /** Feedback options for assistant messages. Enabled by default. */
     feedback?: ChatWidgetFeedbackOptions;
 }
-declare function ChatWidget({ api, threadId, agentId, agentExecutionId, dataContext, displayMode, onError, onAuthError, onFinish, onMessage, title, initialAssistantMessage, initialUserMessage, inputPlaceholder, className, styles: styleProps, voice, speechToText, widgets, feedback, }: ChatWidgetConfig): react_jsx_runtime.JSX.Element;
+declare function ChatWidget({ api, threadId, agentId, agentVersion, agentExecutionId, dataContext, displayMode, onError, onAuthError, onFinish, onMessage, title, initialAssistantMessage, initialUserMessage, inputPlaceholder, className, styles: styleProps, voice, speechToText, widgets, feedback, }: ChatWidgetConfig): react_jsx_runtime.JSX.Element;
 
 interface PopupAnchorConfig {
     enabled?: boolean;
@@ -303,11 +264,49 @@ interface PopupChatWidgetProps extends ChatWidgetConfig {
 }
 declare function PopupChatWidget({ anchor, ...props }: PopupChatWidgetProps): react_jsx_runtime.JSX.Element;
 
+type FeedbackRating = 'positive' | 'negative';
+interface MessageFeedback {
+    id: string;
+    messageId: string;
+    rating: FeedbackRating;
+    improvementText?: string;
+    createdAt: Date;
+}
+interface FeedbackState {
+    rating: FeedbackRating;
+    comment?: string;
+}
+interface UseFeedbackConfig {
+    api: ApiConfig;
+    threadId: string;
+    agentId?: string;
+    agentVersion?: AgentVersion;
+    agentExecutionId?: string;
+}
+interface SubmitFeedbackParams {
+    messageId: string;
+    rating: FeedbackRating;
+    improvementText?: string;
+}
+declare function useFeedback({ api, threadId, agentId, agentVersion, agentExecutionId, }: UseFeedbackConfig): {
+    submitFeedback: ({ messageId, rating, improvementText }: SubmitFeedbackParams) => Promise<MessageFeedback | null>;
+    getFeedbackForMessage: (messageId: string) => FeedbackState | undefined;
+    hasFeedback: (messageId: string) => boolean;
+    isSubmitting: string | null;
+    error: Error | null;
+};
+
+/** Tool part from UIMessage - either typed tool-* or dynamic-tool */
+type ToolPart = Extract<UIMessagePart, {
+    type: `tool-${string}`;
+} | {
+    type: 'dynamic-tool';
+}>;
 interface ToolCallDisplayProps {
-    toolCall: ToolCallContent;
+    toolPart: ToolPart;
     className?: string;
 }
-declare function ToolCallDisplay({ toolCall, className }: ToolCallDisplayProps): react_jsx_runtime.JSX.Element;
+declare function ToolCallDisplay({ toolPart, className }: ToolCallDisplayProps): react_jsx_runtime.JSX.Element;
 
 interface TagGroupDisplayProps {
     tagId: string;
@@ -317,6 +316,31 @@ interface TagGroupDisplayProps {
 }
 declare function TagGroupDisplay({ tagId, isExpanded, onToggle, children, }: TagGroupDisplayProps): react_jsx_runtime.JSX.Element;
 
+interface RendererProps {
+    /** Message sections to render */
+    sections: ChatMessageSection[];
+    /** Unique message ID for keying */
+    messageId: string;
+    /** Render function for individual parts (text, widgets, tool calls) */
+    renderPart: (part: UIMessagePart, key: string) => React$1.ReactNode;
+    /** Render function for group sections */
+    renderGroup: (groupName: string, key: string, children: React$1.ReactNode) => React$1.ReactNode;
+}
+
+/**
+ * Full display mode renderer - shows all content without collapsing.
+ * Each section is rendered as-is in chronological order.
+ */
+declare function FullRenderer({ sections, messageId, renderPart, renderGroup, }: RendererProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Brief display mode renderer - collapses previous steps.
+ *
+ * All steps before the last one are collapsed into a single "Show more" section.
+ * Groups collapse their internal content similarly.
+ */
+declare function BriefRenderer({ sections, messageId, renderPart, renderGroup, }: RendererProps): react_jsx_runtime.JSX.Element;
+
 type RegisterChatWidgetsParams = {
     api: ApiConfig;
     threadId: string;
@@ -357,4 +381,4 @@ declare const getVendorCardsWidget: (isProd?: boolean) => UIWidgetDefinition[];
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { type ApiConfig, type ChatContentItem, type ChatMessage, ChatWidget, type ChatWidgetFeedbackOptions, type ChatWidgetConfig as ChatWidgetProps, type ChatWidgetSpeechToTextOptions, type ChatWidgetStyles, type ChatWidgetVoiceOptions, type DisplayMode, type EmbeddableChatWidgetConfig, type EnrichedResults, type FeedbackRating, type FeedbackState, type MessageFeedback, type MessageSection, type PopupAnchorConfig, PopupChatWidget, type PopupChatWidgetProps, type SubmitFeedbackParams, type TagGroup, TagGroupDisplay, type TagGroupDisplayProps, type ToolCallContent, ToolCallDisplay, type ToolCallDisplayProps, type UIWidgetDefinition, type UseChatConfig, type UseFeedbackConfig, type WidgetEnrichConfig, cn, createWidget, defaultChatWidgets, getVendorCardsWidget, registerChatWidgets, useChat, useFeedback };
+export { type AgentVersion, type ApiConfig, BriefRenderer, type ChatMessage, type ChatMessageSection, ChatWidget, type ChatWidgetFeedbackOptions, type ChatWidgetConfig as ChatWidgetProps, type ChatWidgetSpeechToTextOptions, type ChatWidgetStyles, type ChatWidgetVoiceOptions, type DisplayMode, type EmbeddableChatWidgetConfig, type EnrichedResults, type FeedbackRating, type FeedbackState, FullRenderer, type MessageFeedback, type PopupAnchorConfig, PopupChatWidget, type PopupChatWidgetProps, type RendererProps, type SubmitFeedbackParams, TagGroupDisplay, type TagGroupDisplayProps, ToolCallDisplay, type ToolCallDisplayProps, type ToolPart, type UIMessagePart, type UIWidgetDefinition, type UseChatConfig, type UseFeedbackConfig, type WidgetEnrichConfig, cn, createWidget, defaultChatWidgets, getVendorCardsWidget, registerChatWidgets, useChat, useFeedback };