vanilla-agent 1.9.0 → 1.10.0

package/dist/index.d.cts

@@ -363,10 +363,58 @@ interface AgentWidgetStreamParser {
      */
     close?(): Promise<void> | void;
 }
+/**
+ * Component renderer function signature for custom components
+ */
+type AgentWidgetComponentRenderer = (props: Record<string, unknown>, context: {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    updateProps: (newProps: Record<string, unknown>) => void;
+}) => HTMLElement;
+/**
+ * Result from custom SSE event parser
+ */
+type AgentWidgetSSEEventResult = {
+    /** Text content to display */
+    text?: string;
+    /** Whether the stream is complete */
+    done?: boolean;
+    /** Error message if an error occurred */
+    error?: string;
+} | null;
+/**
+ * Custom SSE event parser function
+ * Allows transforming non-standard SSE event formats to vanilla-agent's expected format
+ */
+type AgentWidgetSSEEventParser = (eventData: unknown) => AgentWidgetSSEEventResult | Promise<AgentWidgetSSEEventResult>;
+/**
+ * Custom fetch function for full control over API requests
+ * Use this for custom authentication, request transformation, etc.
+ */
+type AgentWidgetCustomFetch = (url: string, init: RequestInit, payload: AgentWidgetRequestPayload) => Promise<Response>;
+/**
+ * Dynamic headers function - called before each request
+ */
+type AgentWidgetHeadersFunction = () => Record<string, string> | Promise<Record<string, string>>;
 type AgentWidgetConfig = {
     apiUrl?: string;
     flowId?: string;
+    /**
+     * Static headers to include with each request.
+     * For dynamic headers (e.g., auth tokens), use `getHeaders` instead.
+     */
     headers?: Record<string, string>;
+    /**
+     * Dynamic headers function - called before each request.
+     * Useful for adding auth tokens that may change.
+     * @example
+     * ```typescript
+     * getHeaders: async () => ({
+     *   'Authorization': `Bearer ${await getAuthToken()}`
+     * })
+     * ```
+     */
+    getHeaders?: AgentWidgetHeadersFunction;
     copy?: {
         welcomeTitle?: string;
         welcomeSubtitle?: string;
@@ -398,6 +446,32 @@ type AgentWidgetConfig = {
     actionParsers?: AgentWidgetActionParser[];
     actionHandlers?: AgentWidgetActionHandler[];
     storageAdapter?: AgentWidgetStorageAdapter;
+    /**
+     * Registry of custom components that can be rendered from JSON directives.
+     * Components are registered by name and can be invoked via JSON responses
+     * with the format: `{"component": "ComponentName", "props": {...}}`
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   components: {
+     *     ProductCard: (props, context) => {
+     *       const card = document.createElement("div");
+     *       card.innerHTML = `<h3>${props.title}</h3><p>$${props.price}</p>`;
+     *       return card;
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    components?: Record<string, AgentWidgetComponentRenderer>;
+    /**
+     * Enable component streaming. When true, component props will be updated
+     * incrementally as they stream in from the JSON response.
+     *
+     * @default true
+     */
+    enableComponentStreaming?: boolean;
     /**
      * Custom stream parser for extracting text from streaming structured responses.
      * Handles incremental parsing of JSON, XML, or other formats.
@@ -454,6 +528,68 @@ type AgentWidgetConfig = {
      * ```
      */
     parserType?: "plain" | "json" | "regex-json" | "xml";
+    /**
+     * Custom fetch function for full control over API requests.
+     * Use this for custom authentication, request/response transformation, etc.
+     *
+     * When provided, this function is called instead of the default fetch.
+     * You receive the URL, RequestInit, and the payload that would be sent.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   customFetch: async (url, init, payload) => {
+     *     // Transform request for your API format
+     *     const myPayload = {
+     *       flow: { id: 'my-flow-id' },
+     *       messages: payload.messages,
+     *       options: { stream_response: true }
+     *     };
+     *
+     *     // Add auth header
+     *     const token = await getAuthToken();
+     *
+     *     return fetch('/my-api/dispatch', {
+     *       method: 'POST',
+     *       headers: {
+     *         'Content-Type': 'application/json',
+     *         'Authorization': `Bearer ${token}`
+     *       },
+     *       body: JSON.stringify(myPayload),
+     *       signal: init.signal
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    customFetch?: AgentWidgetCustomFetch;
+    /**
+     * Custom SSE event parser for non-standard streaming response formats.
+     *
+     * Use this when your API returns SSE events in a different format than expected.
+     * Return `{ text }` for text chunks, `{ done: true }` for completion,
+     * `{ error }` for errors, or `null` to ignore the event.
+     *
+     * @example
+     * ```typescript
+     * // For Travrse API format
+     * config: {
+     *   parseSSEEvent: (data) => {
+     *     if (data.type === 'step_chunk' && data.chunk) {
+     *       return { text: data.chunk };
+     *     }
+     *     if (data.type === 'flow_complete') {
+     *       return { done: true };
+     *     }
+     *     if (data.type === 'step_error') {
+     *       return { error: data.error };
+     *     }
+     *     return null; // Ignore other events
+     *   }
+     * }
+     * ```
+     */
+    parseSSEEvent?: AgentWidgetSSEEventParser;
 };
 type AgentWidgetMessageRole = "user" | "assistant" | "system";
 type AgentWidgetReasoning = {
@@ -613,9 +749,17 @@ declare class AgentWidgetClient {
     private readonly createStreamParser;
     private readonly contextProviders;
     private readonly requestMiddleware?;
+    private readonly customFetch?;
+    private readonly parseSSEEvent?;
+    private readonly getHeaders?;
     constructor(config?: AgentWidgetConfig);
     dispatch(options: DispatchOptions, onEvent: SSEHandler): Promise<void>;
     private buildPayload;
+    /**
+     * Handle custom SSE event parsing via parseSSEEvent callback
+     * Returns true if event was handled, false otherwise
+     */
+    private handleCustomSSEEvent;
     private streamResponse;
 }
 
@@ -724,6 +868,138 @@ declare class PluginRegistry {
 }
 declare const pluginRegistry: PluginRegistry;
 
+/**
+ * Context provided to component renderers
+ */
+interface ComponentContext {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    /**
+     * Update component props during streaming
+     */
+    updateProps: (newProps: Record<string, unknown>) => void;
+}
+/**
+ * Component renderer function signature
+ */
+type ComponentRenderer = (props: Record<string, unknown>, context: ComponentContext) => HTMLElement;
+/**
+ * Component registry for managing custom components
+ */
+declare class ComponentRegistry {
+    private components;
+    /**
+     * Register a custom component
+     */
+    register(name: string, renderer: ComponentRenderer): void;
+    /**
+     * Unregister a component
+     */
+    unregister(name: string): void;
+    /**
+     * Get a component renderer by name
+     */
+    get(name: string): ComponentRenderer | undefined;
+    /**
+     * Check if a component is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered component names
+     */
+    getAllNames(): string[];
+    /**
+     * Clear all registered components
+     */
+    clear(): void;
+    /**
+     * Register multiple components at once
+     */
+    registerAll(components: Record<string, ComponentRenderer>): void;
+}
+/**
+ * Global component registry instance
+ */
+declare const componentRegistry: ComponentRegistry;
+
+/**
+ * Represents a component directive extracted from JSON
+ */
+interface ComponentDirective {
+    component: string;
+    props: Record<string, unknown>;
+    raw: string;
+}
+/**
+ * Creates a parser that extracts component directives from JSON streams
+ * This parser looks for objects with a "component" field and extracts
+ * the component name and props incrementally as they stream in.
+ */
+declare function createComponentStreamParser(): {
+    /**
+     * Get the currently extracted component directive
+     */
+    getExtractedDirective: () => ComponentDirective | null;
+    /**
+     * Process a chunk of JSON and extract component directive if present
+     */
+    processChunk: (accumulatedContent: string) => ComponentDirective | null;
+    /**
+     * Reset the parser state
+     */
+    reset: () => void;
+};
+/**
+ * Type guard to check if an object is a component directive
+ */
+declare function isComponentDirectiveType(obj: unknown): obj is ComponentDirective;
+
+type MessageTransform = (context: {
+    text: string;
+    message: AgentWidgetMessage;
+    streaming: boolean;
+    raw?: string;
+}) => string;
+
+/**
+ * Options for component middleware
+ */
+interface ComponentMiddlewareOptions {
+    config: AgentWidgetConfig;
+    message: AgentWidgetMessage;
+    transform: MessageTransform;
+    onPropsUpdate?: (props: Record<string, unknown>) => void;
+}
+/**
+ * Renders a component directive into an HTMLElement
+ */
+declare function renderComponentDirective(directive: ComponentDirective, options: ComponentMiddlewareOptions): HTMLElement | null;
+/**
+ * Creates middleware that processes component directives from streamed JSON
+ */
+declare function createComponentMiddleware(): {
+    /**
+     * Process accumulated content and extract component directive
+     */
+    processChunk: (accumulatedContent: string) => ComponentDirective | null;
+    /**
+     * Get the currently extracted directive
+     */
+    getDirective: () => ComponentDirective | null;
+    /**
+     * Reset the parser state
+     */
+    reset: () => void;
+};
+/**
+ * Checks if a message contains a component directive in its raw content
+ */
+declare function hasComponentDirective(message: AgentWidgetMessage): boolean;
+/**
+ * Extracts component directive from a complete message
+ */
+declare function extractComponentDirectiveFromMessage(message: AgentWidgetMessage): ComponentDirective | null;
+
 /**
  * Default widget configuration
  * Single source of truth for all default values
@@ -735,4 +1011,4 @@ declare const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig>;
  */
 declare function mergeWithDefaults(config?: Partial<AgentWidgetConfig>): Partial<AgentWidgetConfig>;
 
-export { AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, DEFAULT_WIDGET_CONFIG, createActionManager, createAgentExperience, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createPlainTextParser, createRegexJsonParser, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, initAgentWidget, markdownPostprocessor, mergeWithDefaults, pluginRegistry };
+export { AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetCustomFetch, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type ComponentContext, type ComponentDirective, type ComponentRenderer, DEFAULT_WIDGET_CONFIG, componentRegistry, createActionManager, createAgentExperience, createComponentMiddleware, createComponentStreamParser, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createPlainTextParser, createRegexJsonParser, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, hasComponentDirective, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, pluginRegistry, renderComponentDirective };

package/dist/index.d.ts

@@ -363,10 +363,58 @@ interface AgentWidgetStreamParser {
      */
     close?(): Promise<void> | void;
 }
+/**
+ * Component renderer function signature for custom components
+ */
+type AgentWidgetComponentRenderer = (props: Record<string, unknown>, context: {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    updateProps: (newProps: Record<string, unknown>) => void;
+}) => HTMLElement;
+/**
+ * Result from custom SSE event parser
+ */
+type AgentWidgetSSEEventResult = {
+    /** Text content to display */
+    text?: string;
+    /** Whether the stream is complete */
+    done?: boolean;
+    /** Error message if an error occurred */
+    error?: string;
+} | null;
+/**
+ * Custom SSE event parser function
+ * Allows transforming non-standard SSE event formats to vanilla-agent's expected format
+ */
+type AgentWidgetSSEEventParser = (eventData: unknown) => AgentWidgetSSEEventResult | Promise<AgentWidgetSSEEventResult>;
+/**
+ * Custom fetch function for full control over API requests
+ * Use this for custom authentication, request transformation, etc.
+ */
+type AgentWidgetCustomFetch = (url: string, init: RequestInit, payload: AgentWidgetRequestPayload) => Promise<Response>;
+/**
+ * Dynamic headers function - called before each request
+ */
+type AgentWidgetHeadersFunction = () => Record<string, string> | Promise<Record<string, string>>;
 type AgentWidgetConfig = {
     apiUrl?: string;
     flowId?: string;
+    /**
+     * Static headers to include with each request.
+     * For dynamic headers (e.g., auth tokens), use `getHeaders` instead.
+     */
     headers?: Record<string, string>;
+    /**
+     * Dynamic headers function - called before each request.
+     * Useful for adding auth tokens that may change.
+     * @example
+     * ```typescript
+     * getHeaders: async () => ({
+     *   'Authorization': `Bearer ${await getAuthToken()}`
+     * })
+     * ```
+     */
+    getHeaders?: AgentWidgetHeadersFunction;
     copy?: {
         welcomeTitle?: string;
         welcomeSubtitle?: string;
@@ -398,6 +446,32 @@ type AgentWidgetConfig = {
     actionParsers?: AgentWidgetActionParser[];
     actionHandlers?: AgentWidgetActionHandler[];
     storageAdapter?: AgentWidgetStorageAdapter;
+    /**
+     * Registry of custom components that can be rendered from JSON directives.
+     * Components are registered by name and can be invoked via JSON responses
+     * with the format: `{"component": "ComponentName", "props": {...}}`
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   components: {
+     *     ProductCard: (props, context) => {
+     *       const card = document.createElement("div");
+     *       card.innerHTML = `<h3>${props.title}</h3><p>$${props.price}</p>`;
+     *       return card;
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    components?: Record<string, AgentWidgetComponentRenderer>;
+    /**
+     * Enable component streaming. When true, component props will be updated
+     * incrementally as they stream in from the JSON response.
+     *
+     * @default true
+     */
+    enableComponentStreaming?: boolean;
     /**
      * Custom stream parser for extracting text from streaming structured responses.
      * Handles incremental parsing of JSON, XML, or other formats.
@@ -454,6 +528,68 @@ type AgentWidgetConfig = {
      * ```
      */
     parserType?: "plain" | "json" | "regex-json" | "xml";
+    /**
+     * Custom fetch function for full control over API requests.
+     * Use this for custom authentication, request/response transformation, etc.
+     *
+     * When provided, this function is called instead of the default fetch.
+     * You receive the URL, RequestInit, and the payload that would be sent.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   customFetch: async (url, init, payload) => {
+     *     // Transform request for your API format
+     *     const myPayload = {
+     *       flow: { id: 'my-flow-id' },
+     *       messages: payload.messages,
+     *       options: { stream_response: true }
+     *     };
+     *
+     *     // Add auth header
+     *     const token = await getAuthToken();
+     *
+     *     return fetch('/my-api/dispatch', {
+     *       method: 'POST',
+     *       headers: {
+     *         'Content-Type': 'application/json',
+     *         'Authorization': `Bearer ${token}`
+     *       },
+     *       body: JSON.stringify(myPayload),
+     *       signal: init.signal
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    customFetch?: AgentWidgetCustomFetch;
+    /**
+     * Custom SSE event parser for non-standard streaming response formats.
+     *
+     * Use this when your API returns SSE events in a different format than expected.
+     * Return `{ text }` for text chunks, `{ done: true }` for completion,
+     * `{ error }` for errors, or `null` to ignore the event.
+     *
+     * @example
+     * ```typescript
+     * // For Travrse API format
+     * config: {
+     *   parseSSEEvent: (data) => {
+     *     if (data.type === 'step_chunk' && data.chunk) {
+     *       return { text: data.chunk };
+     *     }
+     *     if (data.type === 'flow_complete') {
+     *       return { done: true };
+     *     }
+     *     if (data.type === 'step_error') {
+     *       return { error: data.error };
+     *     }
+     *     return null; // Ignore other events
+     *   }
+     * }
+     * ```
+     */
+    parseSSEEvent?: AgentWidgetSSEEventParser;
 };
 type AgentWidgetMessageRole = "user" | "assistant" | "system";
 type AgentWidgetReasoning = {
@@ -613,9 +749,17 @@ declare class AgentWidgetClient {
     private readonly createStreamParser;
     private readonly contextProviders;
     private readonly requestMiddleware?;
+    private readonly customFetch?;
+    private readonly parseSSEEvent?;
+    private readonly getHeaders?;
     constructor(config?: AgentWidgetConfig);
     dispatch(options: DispatchOptions, onEvent: SSEHandler): Promise<void>;
     private buildPayload;
+    /**
+     * Handle custom SSE event parsing via parseSSEEvent callback
+     * Returns true if event was handled, false otherwise
+     */
+    private handleCustomSSEEvent;
     private streamResponse;
 }
 
@@ -724,6 +868,138 @@ declare class PluginRegistry {
 }
 declare const pluginRegistry: PluginRegistry;
 
+/**
+ * Context provided to component renderers
+ */
+interface ComponentContext {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    /**
+     * Update component props during streaming
+     */
+    updateProps: (newProps: Record<string, unknown>) => void;
+}
+/**
+ * Component renderer function signature
+ */
+type ComponentRenderer = (props: Record<string, unknown>, context: ComponentContext) => HTMLElement;
+/**
+ * Component registry for managing custom components
+ */
+declare class ComponentRegistry {
+    private components;
+    /**
+     * Register a custom component
+     */
+    register(name: string, renderer: ComponentRenderer): void;
+    /**
+     * Unregister a component
+     */
+    unregister(name: string): void;
+    /**
+     * Get a component renderer by name
+     */
+    get(name: string): ComponentRenderer | undefined;
+    /**
+     * Check if a component is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered component names
+     */
+    getAllNames(): string[];
+    /**
+     * Clear all registered components
+     */
+    clear(): void;
+    /**
+     * Register multiple components at once
+     */
+    registerAll(components: Record<string, ComponentRenderer>): void;
+}
+/**
+ * Global component registry instance
+ */
+declare const componentRegistry: ComponentRegistry;
+
+/**
+ * Represents a component directive extracted from JSON
+ */
+interface ComponentDirective {
+    component: string;
+    props: Record<string, unknown>;
+    raw: string;
+}
+/**
+ * Creates a parser that extracts component directives from JSON streams
+ * This parser looks for objects with a "component" field and extracts
+ * the component name and props incrementally as they stream in.
+ */
+declare function createComponentStreamParser(): {
+    /**
+     * Get the currently extracted component directive
+     */
+    getExtractedDirective: () => ComponentDirective | null;
+    /**
+     * Process a chunk of JSON and extract component directive if present
+     */
+    processChunk: (accumulatedContent: string) => ComponentDirective | null;
+    /**
+     * Reset the parser state
+     */
+    reset: () => void;
+};
+/**
+ * Type guard to check if an object is a component directive
+ */
+declare function isComponentDirectiveType(obj: unknown): obj is ComponentDirective;
+
+type MessageTransform = (context: {
+    text: string;
+    message: AgentWidgetMessage;
+    streaming: boolean;
+    raw?: string;
+}) => string;
+
+/**
+ * Options for component middleware
+ */
+interface ComponentMiddlewareOptions {
+    config: AgentWidgetConfig;
+    message: AgentWidgetMessage;
+    transform: MessageTransform;
+    onPropsUpdate?: (props: Record<string, unknown>) => void;
+}
+/**
+ * Renders a component directive into an HTMLElement
+ */
+declare function renderComponentDirective(directive: ComponentDirective, options: ComponentMiddlewareOptions): HTMLElement | null;
+/**
+ * Creates middleware that processes component directives from streamed JSON
+ */
+declare function createComponentMiddleware(): {
+    /**
+     * Process accumulated content and extract component directive
+     */
+    processChunk: (accumulatedContent: string) => ComponentDirective | null;
+    /**
+     * Get the currently extracted directive
+     */
+    getDirective: () => ComponentDirective | null;
+    /**
+     * Reset the parser state
+     */
+    reset: () => void;
+};
+/**
+ * Checks if a message contains a component directive in its raw content
+ */
+declare function hasComponentDirective(message: AgentWidgetMessage): boolean;
+/**
+ * Extracts component directive from a complete message
+ */
+declare function extractComponentDirectiveFromMessage(message: AgentWidgetMessage): ComponentDirective | null;
+
 /**
  * Default widget configuration
  * Single source of truth for all default values
@@ -735,4 +1011,4 @@ declare const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig>;
  */
 declare function mergeWithDefaults(config?: Partial<AgentWidgetConfig>): Partial<AgentWidgetConfig>;
 
-export { AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, DEFAULT_WIDGET_CONFIG, createActionManager, createAgentExperience, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createPlainTextParser, createRegexJsonParser, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, initAgentWidget, markdownPostprocessor, mergeWithDefaults, pluginRegistry };
+export { AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetCustomFetch, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type ComponentContext, type ComponentDirective, type ComponentRenderer, DEFAULT_WIDGET_CONFIG, componentRegistry, createActionManager, createAgentExperience, createComponentMiddleware, createComponentStreamParser, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createPlainTextParser, createRegexJsonParser, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, hasComponentDirective, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, pluginRegistry, renderComponentDirective };