@ensembleapp/client-sdk 0.0.35 → 0.0.37

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import React$1, { ReactElement } from 'react';
+import React, { ReactElement, ReactNode } from 'react';
 import * as ai from 'ai';
 import { UIMessage } from 'ai';
 import { FlexibleSchema, InferSchema } from '@ai-sdk/provider-utils';
+import z from 'zod';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ClassValue } from 'clsx';
 
@@ -39,7 +40,7 @@ type DeprecatedChatConfig = {
     agentExecutionId?: string;
 };
 interface ApiConfig {
-    /** The base URL where /chat and /chat/messages are hosted */
+    /** The base URL where /api/chat and /api/chat/messages are hosted */
     baseUrl: string;
     /** JWT token generated from Secret */
     token: string;
@@ -53,7 +54,7 @@ type UseChatConfig = DeprecatedChatConfig & {
     /** Thread ID for keeping conversation history */
     threadId: string;
     /** Ensemble agent ID to connect to */
-    agentId?: string;
+    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 */
@@ -92,8 +93,24 @@ declare function useChat({ api, threadId, agentId, agentVersion, agentExecutionI
     setMessages: (messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[]) => UIMessage<unknown, ai.UIDataTypes, ai.UITools>[])) => void;
 };
 
-/** @minimum 1 */
-type VersionSelector = 'latest' | 'published' | number;
+declare const VersionSelectorSchema: z.ZodUnion<readonly [z.ZodLiteral<"latest">, z.ZodLiteral<"published">, z.ZodNumber]>;
+type VersionSelector = z.infer<typeof VersionSelectorSchema>;
+
+declare const FeedbackRatingSchema: z.ZodEnum<{
+    positive: "positive";
+    negative: "negative";
+}>;
+type FeedbackRating = z.infer<typeof FeedbackRatingSchema>;
+interface FeedbackNote {
+    noteId?: string;
+    [key: string]: unknown;
+}
+interface MessageFeedback {
+    rating?: FeedbackRating;
+    improvementText?: string;
+    notes?: FeedbackNote[];
+}
+
 /**
  * fetch data via tool call.
  */
@@ -141,6 +158,43 @@ type EnrichmentResult<TData = unknown> = {
     data?: TData;
 };
 
+/**
+ * Client-specific types for the SDK.
+ * Core feedback types (FeedbackRating, FeedbackNote, MessageFeedback, CreateFeedbackRequest)
+ * are in @repo/agent-sdk/schemas.
+ */
+
+interface SubmitFeedbackParams {
+    rating?: FeedbackRating | null;
+    improvementText?: string | null;
+    notes?: FeedbackNote[];
+}
+/**
+ * Feedback handlers for a specific message.
+ * messageId is not necessary here and is handled at a higher level.
+ */
+interface FeedbackHandlers {
+    getFeedback: () => MessageFeedback | undefined;
+    submitFeedback: (params: SubmitFeedbackParams) => Promise<MessageFeedback | null>;
+}
+/**
+ * Feedback configuration for MessageRenderer.
+ * Contains handlers and UI options for feedback display.
+ */
+interface FeedbackConfig extends FeedbackHandlers {
+    /** Whether a submission is in progress (disables interaction) */
+    loading?: boolean;
+    /** Whether comment is required for negative feedback */
+    requireCommentForNegative?: boolean;
+}
+/**
+ * Message-level context provided to child.
+ * Contains message-scoped data and feedback utilities.
+ */
+interface MessageContext extends FeedbackHandlers {
+    messageId: string;
+}
+
 /** Enriched results keyed by enrichment name */
 type EnrichedResults<T = unknown> = Record<string, EnrichmentResult<T>>;
 /** Union type for SDK to handle both customer and SDK UI widgets */
@@ -156,7 +210,9 @@ interface SDKUIWidgetDefinition<TSchema extends FlexibleSchema = FlexibleSchema,
     widgetType: string;
     schema: TSchema;
     enrich?: WidgetEnrichConfig;
-    render(payload: InferSchema<TSchema>, enriched: TEnriched): ReactElement;
+    render(payload: InferSchema<TSchema>, enriched: TEnriched, options: {
+        messageContext?: MessageContext;
+    }): ReactElement;
 }
 /** Type guard to check if a widget is an SDK-provided widget */
 declare function isSDKWidget(widget: AnyUIWidgetDefinition): widget is SDKUIWidgetDefinition;
@@ -228,8 +284,11 @@ interface UIWidgetDefinition<TSchema extends FlexibleSchema = FlexibleSchema, TE
      * Render function that receives the payload and enriched results.
      * @param payload - The LLM-generated data matching the schema
      * @param enriched - Enrichment results keyed by name (empty object if no enrich config)
+     * @param options - Render options (messageContext, etc.)
      */
-    render(payload: InferSchema<TSchema>, enriched: TEnriched): unknown;
+    render(payload: InferSchema<TSchema>, enriched: TEnriched, options: {
+        messageContext?: MessageContext;
+    }): unknown;
 }
 /**
  * Helper to create customer widgets.
@@ -259,7 +318,9 @@ declare const createWidget: <TEnriched extends EnrichedResults = EnrichedResults
     schema: any;
     enrich?: WidgetEnrichConfig;
     reactDOM: CustomerReactDOM;
-    render(payload: any, enriched: TEnriched): unknown;
+    render(payload: any, enriched: TEnriched, options: {
+        messageContext?: MessageContext;
+    }): unknown;
 }) => UIWidgetDefinition<FlexibleSchema, TEnriched>;
 
 type DisplayMode = 'full' | 'brief';
@@ -327,7 +388,7 @@ interface ChatWidgetConfig extends UseChatConfig {
     /** Feedback options for assistant messages. Enabled by default. */
     feedback?: ChatWidgetFeedbackOptions;
 }
-declare const ChatWidget: React$1.ForwardRefExoticComponent<ChatWidgetConfig & React$1.RefAttributes<ChatWidgetHandle>>;
+declare const ChatWidget: React.ForwardRefExoticComponent<ChatWidgetConfig & React.RefAttributes<ChatWidgetHandle>>;
 
 interface PopupAnchorConfig {
     enabled?: boolean;
@@ -337,13 +398,13 @@ interface PopupAnchorConfig {
     render?: (options: {
         isOpen: boolean;
         toggle: () => void;
-    }) => React$1.ReactNode;
+    }) => React.ReactNode;
     closeButton?: PopupCloseConfig;
 }
 interface PopupCloseConfig {
     render?: (options: {
         toggle: () => void;
-    }) => React$1.ReactNode;
+    }) => React.ReactNode;
     position?: 'top-end' | 'top-start';
     show?: boolean;
 }
@@ -363,38 +424,44 @@ 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;
+    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;
+declare function useFeedback({ api, threadId, agentId, agentVersion, }: UseFeedbackConfig): {
+    submitFeedback: (messageId: string, { rating, improvementText, notes }: SubmitFeedbackParams) => Promise<MessageFeedback | null>;
+    getFeedbackForMessage: (messageId: string) => MessageFeedback | undefined;
     hasFeedback: (messageId: string) => boolean;
     isSubmitting: string | null;
     error: Error | null;
 };
 
+/**
+ * Transforms a UIMessage into a ChatMessage with sections.
+ *
+ * Groups UIMessage.parts into step and group sections:
+ * - step: content between step-start markers (one LLM turn)
+ * - group: content within data-tag-start/end markers (sub-agent output)
+ *
+ * Parts pass through as-is - no content transformation.
+ * Structural markers (step-start, data-tag-*, data-transfer, data-thoughts)
+ * are consumed during grouping and not included in output.
+ *
+ * @param msg - The UIMessage from AI SDK
+ * @returns ChatMessage with sections
+ */
+declare function transformMessage(msg: UIMessage): ChatMessage;
+
+interface TagGroupDisplayProps {
+    tagId: string;
+    isExpanded: boolean;
+    onToggle: () => void;
+    children: ReactNode;
+}
+declare function TagGroupDisplay({ tagId, isExpanded, onToggle, children, }: TagGroupDisplayProps): react_jsx_runtime.JSX.Element;
+
 /** Tool part from UIMessage - either typed tool-* or dynamic-tool */
 type ToolPart = Extract<UIMessagePart, {
     type: `tool-${string}`;
@@ -407,38 +474,57 @@ interface ToolCallDisplayProps {
 }
 declare function ToolCallDisplay({ toolPart, className }: ToolCallDisplayProps): react_jsx_runtime.JSX.Element;
 
-interface TagGroupDisplayProps {
-    tagId: string;
-    isExpanded: boolean;
-    onToggle: () => void;
-    children: React.ReactNode;
+interface MessageRendererProps {
+    /** The message to render */
+    message: ChatMessage;
+    /** Widget definitions for rendering data-ui parts */
+    widgets?: AnyUIWidgetDefinition[];
+    /** Readonly mode - disables all widget interactions */
+    readonly?: boolean;
+    /** Display mode: 'brief' collapses previous steps, 'full' shows everything */
+    displayMode?: 'brief' | 'full';
+    /** Tag expansion state and handler */
+    tagExpansion?: {
+        state: Map<string, boolean>;
+        onToggle: (tagId: string) => void;
+    };
+    /** Optional className for the container */
+    className?: string;
+    /** Feedback config - if provided, feedback UI will be shown */
+    feedback?: FeedbackConfig;
 }
-declare function TagGroupDisplay({ tagId, isExpanded, onToggle, children, }: TagGroupDisplayProps): react_jsx_runtime.JSX.Element;
+/**
+ * MessageRenderer - renders message content with optional feedback UI.
+ *
+ * Renders the content of a ChatMessage (text, tools, widgets, groups) and optionally
+ * displays feedback buttons for assistant messages.
+ */
+declare function MessageRenderer({ message, widgets, readonly, displayMode, tagExpansion, className, feedback, }: MessageRendererProps): react_jsx_runtime.JSX.Element;
 
-interface RendererProps {
+interface DisplayModeProps {
     /** 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;
+    renderPart: (part: UIMessagePart, key: string) => ReactNode;
     /** Render function for group sections */
-    renderGroup: (groupName: string, key: string, children: React$1.ReactNode) => React$1.ReactNode;
+    renderGroup: (groupName: string, key: string, children: ReactNode) => 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.
+ * Brief display mode - 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;
+declare function BriefDisplayMode({ sections, messageId, renderPart, renderGroup, }: DisplayModeProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Full display mode - shows all content without collapsing.
+ * Each section is rendered as-is in chronological order.
+ */
+declare function FullDisplayMode({ sections, messageId, renderPart, renderGroup, }: DisplayModeProps): react_jsx_runtime.JSX.Element;
 
 type RegisterChatWidgetsParams = {
     api: ApiConfig;
@@ -482,4 +568,4 @@ declare const getVendorCardsWidget: (isProd?: boolean) => SDKUIWidgetDefinition[
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { type AgentVersion, type AnyUIWidgetDefinition, type ApiConfig, BriefRenderer, type ChatMessage, type ChatMessageSection, ChatWidget, type ChatWidgetFeedbackOptions, type ChatWidgetHandle, type ChatWidgetConfig as ChatWidgetProps, type ChatWidgetSpeechToTextOptions, type ChatWidgetStyles, type ChatWidgetVoiceOptions, type CustomerReactDOM, type DisplayMode, type EmbeddableChatWidgetConfig, type EnrichedResults, type FeedbackRating, type FeedbackState, FullRenderer, type MessageFeedback, type PopupAnchorConfig, PopupChatWidget, type PopupChatWidgetProps, type RendererProps, type SDKUIWidgetDefinition, SDK_WIDGET_MARKER, type SubmitFeedbackParams, TagGroupDisplay, type TagGroupDisplayProps, ToolCallDisplay, type ToolCallDisplayProps, type ToolPart, type UIMessagePart, type UIWidgetDefinition, type UseChatConfig, type UseFeedbackConfig, type WidgetEnrichConfig, cn, createSDKWidget, createWidget, defaultChatWidgets, getVendorCardsWidget, isSDKWidget, registerChatWidgets, useChat, useFeedback };
+export { type AgentVersion, type AnyUIWidgetDefinition, type ApiConfig, BriefDisplayMode, BriefDisplayMode as BriefRenderer, type ChatMessage, type ChatMessageSection, ChatWidget, type ChatWidgetFeedbackOptions, type ChatWidgetHandle, type ChatWidgetConfig as ChatWidgetProps, type ChatWidgetSpeechToTextOptions, type ChatWidgetStyles, type ChatWidgetVoiceOptions, type CustomerReactDOM, type DisplayMode, type DisplayModeProps, type EmbeddableChatWidgetConfig, type EnrichedResults, type FeedbackConfig, type FeedbackHandlers, type FeedbackNote, type FeedbackRating, FullDisplayMode, FullDisplayMode as FullRenderer, type MessageContext, type MessageFeedback, MessageRenderer, type MessageRendererProps, type PopupAnchorConfig, PopupChatWidget, type PopupChatWidgetProps, type DisplayModeProps as RendererProps, type SDKUIWidgetDefinition, SDK_WIDGET_MARKER, type SubmitFeedbackParams, TagGroupDisplay, type TagGroupDisplayProps, ToolCallDisplay, type ToolCallDisplayProps, type ToolPart, type UIMessagePart, type UIWidgetDefinition, type UseChatConfig, type UseFeedbackConfig, type WidgetEnrichConfig, cn, createSDKWidget, createWidget, defaultChatWidgets, getVendorCardsWidget, isSDKWidget, registerChatWidgets, transformMessage, useChat, useFeedback };