@ensembleapp/client-sdk 0.0.38 → 0.0.40

package/dist/index.d.ts

@@ -1,11 +1,128 @@
 import React, { ReactElement, ReactNode } from 'react';
 import * as ai from 'ai';
 import { UIMessage } from 'ai';
+import z, { z as z$1 } from 'zod';
 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';
 
+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[];
+}
+
+/**
+ * Arguments for the collect_user_input tool.
+ */
+declare const CollectUserInputArgsSchema: z$1.ZodObject<{
+    title: z$1.ZodOptional<z$1.ZodString>;
+    description: z$1.ZodOptional<z$1.ZodString>;
+    fields: z$1.ZodArray<z$1.ZodDiscriminatedUnion<[z$1.ZodObject<{
+        type: z$1.ZodLiteral<"choices">;
+        name: z$1.ZodString;
+        label: z$1.ZodString;
+        options: z$1.ZodArray<z$1.ZodObject<{
+            label: z$1.ZodString;
+            value: z$1.ZodString;
+            description: z$1.ZodOptional<z$1.ZodString>;
+        }, z$1.core.$strip>>;
+        multiSelect: z$1.ZodOptional<z$1.ZodBoolean>;
+        required: z$1.ZodOptional<z$1.ZodBoolean>;
+        defaultValue: z$1.ZodOptional<z$1.ZodUnion<readonly [z$1.ZodString, z$1.ZodArray<z$1.ZodString>]>>;
+    }, z$1.core.$strip>, z$1.ZodObject<{
+        type: z$1.ZodLiteral<"text">;
+        name: z$1.ZodString;
+        label: z$1.ZodString;
+        placeholder: z$1.ZodOptional<z$1.ZodString>;
+        multiline: z$1.ZodOptional<z$1.ZodBoolean>;
+        required: z$1.ZodOptional<z$1.ZodBoolean>;
+        defaultValue: z$1.ZodOptional<z$1.ZodString>;
+    }, z$1.core.$strip>, z$1.ZodObject<{
+        type: z$1.ZodLiteral<"number">;
+        name: z$1.ZodString;
+        label: z$1.ZodString;
+        min: z$1.ZodOptional<z$1.ZodNumber>;
+        max: z$1.ZodOptional<z$1.ZodNumber>;
+        required: z$1.ZodOptional<z$1.ZodBoolean>;
+        defaultValue: z$1.ZodOptional<z$1.ZodNumber>;
+    }, z$1.core.$strip>, z$1.ZodObject<{
+        type: z$1.ZodLiteral<"checkbox">;
+        name: z$1.ZodString;
+        label: z$1.ZodString;
+        defaultValue: z$1.ZodOptional<z$1.ZodBoolean>;
+    }, z$1.core.$strip>, z$1.ZodObject<{
+        type: z$1.ZodLiteral<"date">;
+        name: z$1.ZodString;
+        label: z$1.ZodString;
+        required: z$1.ZodOptional<z$1.ZodBoolean>;
+        defaultValue: z$1.ZodOptional<z$1.ZodString>;
+    }, z$1.core.$strip>], "type">>;
+    submitLabel: z$1.ZodOptional<z$1.ZodString>;
+    cancelLabel: z$1.ZodOptional<z$1.ZodString>;
+    allowFreeformResponse: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodBoolean>>;
+}, z$1.core.$strip>;
+type CollectUserInputArgs = z$1.infer<typeof CollectUserInputArgsSchema>;
+
+/**
+ * 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;
+};
+
 /** Derived part type from UIMessage */
 type UIMessagePart = UIMessage['parts'][number];
 /**
@@ -35,6 +152,19 @@ interface ChatMessage {
     sections: ChatMessageSection[];
 }
 
+/** Pending tool input detected from tool call (e.g., collect_user_input) */
+interface PendingToolOutput {
+    toolCallId: string;
+    args: CollectUserInputArgs;
+}
+/** Pending tool approval detected from tool call */
+interface PendingToolApproval {
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    /** The approval ID required for addToolApprovalResponse */
+    approvalId: string;
+}
 type DeprecatedChatConfig = {
     /** @deprecated use agentId instead */
     agentExecutionId?: string;
@@ -91,72 +221,49 @@ declare function useChat({ api, threadId, agentId, agentVersion, agentExecutionI
     } | undefined, options?: ai.ChatRequestOptions) => Promise<void>;
     stop: () => Promise<void>;
     setMessages: (messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[] | ((messages: UIMessage<unknown, ai.UIDataTypes, ai.UITools>[]) => UIMessage<unknown, ai.UIDataTypes, ai.UITools>[])) => void;
+    addToolOutput: <TOOL extends string>({ state, tool, toolCallId, output, errorText, }: {
+        state?: "output-available";
+        tool: TOOL;
+        toolCallId: string;
+        output: unknown;
+        errorText?: never;
+    } | {
+        state: "output-error";
+        tool: TOOL;
+        toolCallId: string;
+        output?: never;
+        errorText: string;
+    }) => Promise<void>;
+    addToolApprovalResponse: ai.ChatAddToolApproveResponseFunction;
+    pendingToolOutput: PendingToolOutput | null;
+    pendingToolApproval: PendingToolApproval | null;
 };
 
-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;
+/** Matches POST /api/tools/:toolId/invoke request body */
+interface ToolInvokeRequest {
+    /** Tool arguments (defaults to empty object) */
+    args?: Record<string, unknown>;
+    /** Key/value context data passed to the tool */
+    dataContext?: Record<string, unknown>;
+    /** Tool version: 'latest' (default), 'published', or specific version number */
+    version?: 'latest' | 'published' | number;
 }
-interface MessageFeedback {
-    rating?: FeedbackRating;
-    improvementText?: string;
-    notes?: FeedbackNote[];
-}
-
-/**
- * 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> = {
+/** Matches POST /api/tools/:toolId/invoke response body */
+interface ToolInvokeResult {
     success: boolean;
+    /** Tool execution result (when success: true) */
+    data?: unknown;
+    /** Error details (when success: false) */
     error?: {
-        message?: string;
+        message: string;
+        details?: string[];
         code?: string;
     };
-    data?: TData;
-};
+    debug?: {
+        executionTime: number;
+    };
+}
+type InvokeTool = (toolId: string, request?: ToolInvokeRequest) => Promise<ToolInvokeResult>;
 
 /**
  * Client-specific types for the SDK.
@@ -194,6 +301,16 @@ interface FeedbackConfig extends FeedbackHandlers {
 interface MessageContext extends FeedbackHandlers {
     messageId: string;
 }
+/**
+ * Options passed to widget render functions.
+ * Provides utilities for message context and tool invocation.
+ */
+interface WidgetRenderOptions {
+    /** Message-level context with feedback handlers */
+    messageContext?: MessageContext;
+    /** Function to invoke tools from within widgets (client-side enrichment) */
+    invokeTool?: InvokeTool;
+}
 
 /** Enriched results keyed by enrichment name */
 type EnrichedResults<T = unknown> = Record<string, EnrichmentResult<T>>;
@@ -210,9 +327,7 @@ interface SDKUIWidgetDefinition<TSchema extends FlexibleSchema = FlexibleSchema,
     widgetType: string;
     schema: TSchema;
     enrich?: WidgetEnrichConfig;
-    render(payload: InferSchema<TSchema>, enriched: TEnriched, options: {
-        messageContext?: MessageContext;
-    }): ReactElement;
+    render(payload: InferSchema<TSchema>, enriched: TEnriched, options: WidgetRenderOptions): ReactElement;
 }
 /** Type guard to check if a widget is an SDK-provided widget */
 declare function isSDKWidget(widget: AnyUIWidgetDefinition): widget is SDKUIWidgetDefinition;
@@ -284,11 +399,9 @@ 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.)
+     * @param options - Render options (messageContext, invokeTool)
      */
-    render(payload: InferSchema<TSchema>, enriched: TEnriched, options: {
-        messageContext?: MessageContext;
-    }): unknown;
+    render(payload: InferSchema<TSchema>, enriched: TEnriched, options: WidgetRenderOptions): unknown;
 }
 /**
  * Helper to create customer widgets.
@@ -318,22 +431,38 @@ declare const createWidget: <TEnriched extends EnrichedResults = EnrichedResults
     schema: any;
     enrich?: WidgetEnrichConfig;
     reactDOM: CustomerReactDOM;
-    render(payload: any, enriched: TEnriched, options: {
-        messageContext?: MessageContext;
-    }): unknown;
+    render(payload: any, enriched: TEnriched, options: WidgetRenderOptions): unknown;
 }) => UIWidgetDefinition<FlexibleSchema, TEnriched>;
 
 type DisplayMode = 'full' | 'brief';
 
 interface ChatWidgetStyles {
+    /**
+     * Theme mode: 'light', 'dark', or 'auto' (detects from user's system/app preference).
+     * When 'auto', the widget checks: CSS color-scheme, prefers-color-scheme media query,
+     * and common dark mode indicators (data-theme, class="dark", etc.)
+     * Default: 'auto'
+     */
+    theme?: 'light' | 'dark' | 'auto';
     primaryColor?: string;
     primaryTextColor?: string;
     backgroundColor?: string;
+    backgroundSecondary?: string;
+    backgroundTertiary?: string;
     borderColor?: string;
+    borderColorLight?: string;
     headerTextColor?: string;
     userBubbleTextColor?: string;
     assistantBubbleBackground?: string;
     assistantBubbleTextColor?: string;
+    /** Main text color */
+    textColor?: string;
+    /** Secondary/muted text color */
+    textSecondary?: string;
+    /** Muted text color (lighter than secondary) */
+    textMuted?: string;
+    /** Disabled text color */
+    textDisabled?: string;
     fontFamily?: string;
     borderRadius?: string;
     inputBackground?: string;
@@ -438,6 +567,35 @@ declare function useFeedback({ api, threadId, agentId, agentVersion, }: UseFeedb
     error: Error | null;
 };
 
+/** Approval UI configuration returned from the server */
+interface ApprovalUIConfig {
+    /** The message to display (evaluated from template) */
+    message: string;
+    /** Label for the approve button */
+    approveLabel: string;
+    /** Label for the deny button */
+    denyLabel: string;
+}
+interface FetchApprovalConfigOptions {
+    /** API configuration */
+    api: ApiConfig;
+    /** Agent ID that contains the tool */
+    agentId: string;
+    /** Agent version */
+    agentVersion?: AgentVersion;
+    /** Tool name (will be normalized on server) */
+    toolName: string;
+    /** Tool arguments for template evaluation */
+    args?: Record<string, unknown>;
+    /** Called on 401 to refresh token */
+    onAuthError?: () => Promise<string | null>;
+}
+/**
+ * Fetches the approval UI configuration for a tool.
+ * The server evaluates template expressions in message/labels with the provided args.
+ */
+declare function fetchApprovalConfig(options: FetchApprovalConfigOptions): Promise<ApprovalUIConfig | null>;
+
 /**
  * Transforms a UIMessage into a ChatMessage with sections.
  *
@@ -492,6 +650,8 @@ interface MessageRendererProps {
     className?: string;
     /** Feedback config - if provided, feedback UI will be shown */
     feedback?: FeedbackConfig;
+    /** Function to invoke tools from widgets (client-side enrichment) */
+    invokeTool?: InvokeTool;
 }
 /**
  * MessageRenderer - renders message content with optional feedback UI.
@@ -499,7 +659,7 @@ interface MessageRendererProps {
  * 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;
+declare function MessageRenderer({ message, widgets, readonly, displayMode, tagExpansion, className, feedback, invokeTool, }: MessageRendererProps): react_jsx_runtime.JSX.Element;
 
 interface DisplayModeProps {
     /** Message sections to render */
@@ -564,8 +724,13 @@ declare global {
 }
 
 declare const defaultChatWidgets: SDKUIWidgetDefinition[];
+/**
+ * Hybrid vendor cards widget:
+ * - Server enriches vendor details (parallel to LLM, immediate render)
+ * - Client fetches distance matrix (progressive, fills in after render)
+ */
 declare const getVendorCardsWidget: (isProd?: boolean) => SDKUIWidgetDefinition[];
 
 declare function cn(...inputs: ClassValue[]): string;
 
-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 };
+export { type AgentVersion, type AnyUIWidgetDefinition, type ApiConfig, type ApprovalUIConfig, 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, type FetchApprovalConfigOptions, FullDisplayMode, FullDisplayMode as FullRenderer, type InvokeTool, type MessageContext, type MessageFeedback, MessageRenderer, type MessageRendererProps, type PendingToolApproval, type PendingToolOutput, type PopupAnchorConfig, PopupChatWidget, type PopupChatWidgetProps, type DisplayModeProps as RendererProps, type SDKUIWidgetDefinition, SDK_WIDGET_MARKER, type SubmitFeedbackParams, TagGroupDisplay, type TagGroupDisplayProps, ToolCallDisplay, type ToolCallDisplayProps, type ToolInvokeRequest, type ToolInvokeResult, type ToolPart, type UIMessagePart, type UIWidgetDefinition, type UseChatConfig, type UseFeedbackConfig, type WidgetEnrichConfig, type WidgetRenderOptions, cn, createSDKWidget, createWidget, defaultChatWidgets, fetchApprovalConfig, getVendorCardsWidget, isSDKWidget, registerChatWidgets, transformMessage, useChat, useFeedback };