@ensembleapp/client-sdk 0.0.29 → 0.0.31

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1, { ReactElement } from 'react';
 import * as ai from 'ai';
 import { UIMessage } from 'ai';
-import z, { AnyZodObject } from 'zod';
-import React$1 from 'react';
+import { FlexibleSchema, InferSchema } from '@ai-sdk/provider-utils';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ClassValue } from 'clsx';
 
 /** Derived part type from UIMessage */
@@ -143,7 +143,45 @@ type EnrichmentResult<TData = unknown> = {
 
 /** Enriched results keyed by enrichment name */
 type EnrichedResults<T = unknown> = Record<string, EnrichmentResult<T>>;
-interface UIWidgetDefinition<TSchema extends AnyZodObject = AnyZodObject, TEnriched extends EnrichedResults = EnrichedResults> {
+/** Union type for SDK to handle both customer and SDK UI widgets */
+type AnyUIWidgetDefinition<TSchema extends FlexibleSchema = FlexibleSchema, TEnriched extends EnrichedResults = EnrichedResults> = UIWidgetDefinition<TSchema, TEnriched> | SDKUIWidgetDefinition<TSchema, TEnriched>;
+/** Internal marker to identify SDK-provided widgets */
+declare const SDK_WIDGET_MARKER: unique symbol;
+/**
+ * INTERNAL - Widget definition for SDK and marketplace widgets.
+ * These render directly in the SDK's React tree (no DOM bridge needed).
+ */
+interface SDKUIWidgetDefinition<TSchema extends FlexibleSchema = FlexibleSchema, TEnriched extends EnrichedResults = EnrichedResults> {
+    [SDK_WIDGET_MARKER]: true;
+    widgetType: string;
+    schema: TSchema;
+    enrich?: WidgetEnrichConfig;
+    render(payload: InferSchema<TSchema>, enriched: TEnriched): ReactElement;
+}
+/** Type guard to check if a widget is an SDK-provided widget */
+declare function isSDKWidget(widget: AnyUIWidgetDefinition): widget is SDKUIWidgetDefinition;
+/** Helper to create SDK widgets (used internally) */
+declare function createSDKWidget<TSchema extends FlexibleSchema, TEnriched extends EnrichedResults = EnrichedResults>(widget: Omit<SDKUIWidgetDefinition<TSchema, TEnriched>, typeof SDK_WIDGET_MARKER>): SDKUIWidgetDefinition<TSchema, TEnriched>;
+/**
+ * Type for customer's ReactDOM instance (supports React 16-18).
+ * Customers must provide their ReactDOM to enable cross-version widget rendering.
+ */
+interface CustomerReactDOM {
+    render?: (element: unknown, container: HTMLElement) => void;
+    unmountComponentAtNode?: (container: HTMLElement) => boolean;
+    createRoot?: (container: HTMLElement, options?: {
+        identifierPrefix?: string;
+        onRecoverableError?: (error: Error) => void;
+    }) => {
+        render: (children: unknown) => void;
+        unmount: () => void;
+    };
+}
+/**
+ * Widget definition for customer-defined widgets.
+ * Customer widgets require `reactDOM` to enable cross-React version rendering.
+ */
+interface UIWidgetDefinition<TSchema extends FlexibleSchema = FlexibleSchema, TEnriched extends EnrichedResults = EnrichedResults> {
     widgetType: string;
     schema: TSchema;
     /**
@@ -159,14 +197,59 @@ interface UIWidgetDefinition<TSchema extends AnyZodObject = AnyZodObject, TEnric
      * ```
      */
     enrich?: WidgetEnrichConfig;
+    /**
+     * Customer's ReactDOM instance for rendering widgets. REQUIRED.
+     *
+     * This ensures widgets render in the customer's React tree, enabling:
+     * - Full event handling (onClick, onChange, etc.)
+     * - React state and hooks inside widgets
+     * - Access to customer's React context
+     * - Cross-React version compatibility
+     *
+     * @example
+     * import ReactDOM from 'react-dom';  // React 16/17
+     * // or
+     * import ReactDOM from 'react-dom/client';  // React 18+
+     *
+     * const widget = {
+     *   widgetType: 'person',
+     *   schema: personSchema,
+     *   reactDOM: ReactDOM,
+     *   render: (payload) => <PersonCard {...payload} />
+     * };
+     */
+    reactDOM: CustomerReactDOM;
     /**
      * 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)
      */
-    render(payload: z.infer<TSchema>, enriched: TEnriched): unknown;
+    render(payload: InferSchema<TSchema>, enriched: TEnriched): unknown;
 }
-declare const createWidget: <TSchema extends AnyZodObject, TEnriched extends EnrichedResults = EnrichedResults>({ widgetType, schema, enrich, render, }: UIWidgetDefinition<TSchema, TEnriched>) => UIWidgetDefinition<TSchema, TEnriched>;
+/**
+ * Helper to create customer widgets with type inference.
+ *
+ * Provides autocomplete and type checking for widget definitions.
+ * The render function receives typed payload based on your schema.
+ *
+ * @example
+ * ```typescript
+ * import ReactDOM from 'react-dom/client';
+ * import { createWidget } from '@ensembleapp/client-sdk';
+ * import { z } from 'zod';
+ *
+ * const productWidget = createWidget({
+ *   widgetType: 'product-card',
+ *   schema: z.object({
+ *     name: z.string(),
+ *     price: z.number(),
+ *   }),
+ *   reactDOM: ReactDOM,
+ *   render: (payload) => <ProductCard {...payload} />
+ * });
+ * ```
+ */
+declare const createWidget: <TSchema extends FlexibleSchema, TEnriched extends EnrichedResults = EnrichedResults>({ widgetType, schema, enrich, reactDOM, render, }: UIWidgetDefinition<TSchema, TEnriched>) => UIWidgetDefinition<TSchema, TEnriched>;
 
 type DisplayMode = 'full' | 'brief';
 
@@ -207,6 +290,11 @@ interface ChatWidgetFeedbackOptions {
     /** Require comment when giving negative feedback. Default: false */
     requireCommentForNegative?: boolean;
 }
+/** Handle exposed by ChatWidget ref for programmatic control */
+interface ChatWidgetHandle {
+    /** Send a message programmatically */
+    sendMessage: (message: string) => void;
+}
 interface ChatWidgetConfig extends UseChatConfig {
     /** Title for the Chat window */
     title?: string;
@@ -224,11 +312,11 @@ interface ChatWidgetConfig extends UseChatConfig {
     styles?: ChatWidgetStyles;
     voice?: ChatWidgetVoiceOptions;
     speechToText?: ChatWidgetSpeechToTextOptions;
-    widgets?: UIWidgetDefinition[];
+    widgets?: AnyUIWidgetDefinition[];
     /** Feedback options for assistant messages. Enabled by default. */
     feedback?: ChatWidgetFeedbackOptions;
 }
-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;
+declare const ChatWidget: React$1.ForwardRefExoticComponent<ChatWidgetConfig & React$1.RefAttributes<ChatWidgetHandle>>;
 
 interface PopupAnchorConfig {
     enabled?: boolean;
@@ -344,7 +432,7 @@ declare function BriefRenderer({ sections, messageId, renderPart, renderGroup, }
 type RegisterChatWidgetsParams = {
     api: ApiConfig;
     threadId: string;
-    widgets: UIWidgetDefinition[];
+    widgets: AnyUIWidgetDefinition[];
     /** Called when API returns 401/unauthorized. Return a new token to retry the request. */
     onAuthError?: () => Promise<string | null>;
 };
@@ -371,14 +459,16 @@ declare global {
             show: () => void;
             updateConfig: (config: Partial<EmbeddableChatWidgetConfig>) => void;
             updateToken: (token: string) => void;
-            getVendorCardsWidget: (isProd?: boolean) => UIWidgetDefinition[];
+            getVendorCardsWidget: (isProd?: boolean) => AnyUIWidgetDefinition[];
+            /** Helper to create customer widgets with type inference */
+            createWidget: typeof createWidget;
         };
     }
 }
 
-declare const defaultChatWidgets: UIWidgetDefinition[];
-declare const getVendorCardsWidget: (isProd?: boolean) => UIWidgetDefinition[];
+declare const defaultChatWidgets: SDKUIWidgetDefinition[];
+declare const getVendorCardsWidget: (isProd?: boolean) => SDKUIWidgetDefinition[];
 
 declare function cn(...inputs: ClassValue[]): string;
 
-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 };
+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 };