vanilla-agent 1.22.0 → 1.24.0

package/dist/index.d.ts

@@ -89,6 +89,7 @@ type AgentWidgetRequestPayload = {
     messages: AgentWidgetRequestPayloadMessage[];
     flowId?: string;
     context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
 };
 type AgentWidgetRequestMiddlewareContext = {
     payload: AgentWidgetRequestPayload;
@@ -145,6 +146,23 @@ type AgentWidgetMessageFeedback = {
 };
 /**
  * Configuration for message action buttons (copy, upvote, downvote)
+ *
+ * **Client Token Mode**: When using `clientToken`, feedback is automatically
+ * sent to your Travrse backend. Just enable the buttons and you're done!
+ * The `onFeedback` and `onCopy` callbacks are optional for additional local handling.
+ *
+ * @example
+ * ```typescript
+ * // With clientToken - feedback is automatic!
+ * config: {
+ *   clientToken: 'ct_live_...',
+ *   messageActions: {
+ *     showUpvote: true,
+ *     showDownvote: true,
+ *     // No onFeedback needed - sent to backend automatically
+ *   }
+ * }
+ * ```
  */
 type AgentWidgetMessageActionsConfig = {
     /**
@@ -158,13 +176,15 @@ type AgentWidgetMessageActionsConfig = {
      */
     showCopy?: boolean;
     /**
-     * Show upvote button
-     * @default false (requires backend)
+     * Show upvote button.
+     * When using `clientToken`, feedback is sent to the backend automatically.
+     * @default false
      */
     showUpvote?: boolean;
     /**
-     * Show downvote button
-     * @default false (requires backend)
+     * Show downvote button.
+     * When using `clientToken`, feedback is sent to the backend automatically.
+     * @default false
      */
     showDownvote?: boolean;
     /**
@@ -185,11 +205,19 @@ type AgentWidgetMessageActionsConfig = {
      */
     layout?: "pill-inside" | "row-inside";
     /**
-     * Callback when user submits feedback (upvote/downvote)
+     * Callback when user submits feedback (upvote/downvote).
+     *
+     * **Note**: When using `clientToken`, feedback is AUTOMATICALLY sent to your
+     * backend via `/v1/client/feedback`. This callback is called IN ADDITION to
+     * the automatic submission, useful for updating local UI or analytics.
      */
     onFeedback?: (feedback: AgentWidgetMessageFeedback) => void;
     /**
-     * Callback when user copies a message
+     * Callback when user copies a message.
+     *
+     * **Note**: When using `clientToken`, copy events are AUTOMATICALLY tracked
+     * via `/v1/client/feedback`. This callback is called IN ADDITION to the
+     * automatic tracking.
      */
     onCopy?: (message: AgentWidgetMessage) => void;
 };
@@ -569,9 +597,31 @@ type ClientInitResponse = {
 type ClientChatRequest = {
     session_id: string;
     messages: Array<{
+        id?: string;
         role: 'user' | 'assistant' | 'system';
         content: string;
     }>;
+    /** ID for the expected assistant response message */
+    assistant_message_id?: string;
+    metadata?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+};
+/**
+ * Feedback types supported by the API
+ */
+type ClientFeedbackType = 'upvote' | 'downvote' | 'copy' | 'csat' | 'nps';
+/**
+ * Request payload for /v1/client/feedback endpoint
+ */
+type ClientFeedbackRequest = {
+    session_id: string;
+    /** Required for upvote, downvote, copy feedback types */
+    message_id?: string;
+    type: ClientFeedbackType;
+    /** Required for csat (1-5) and nps (0-10) feedback types */
+    rating?: number;
+    /** Optional comment for any feedback type */
+    comment?: string;
 };
 /**
  * Context provided to header render functions
@@ -1358,6 +1408,132 @@ type AgentWidgetInitOptions = {
     debugTools?: boolean;
 };
 
+type DispatchOptions = {
+    messages: AgentWidgetMessage[];
+    signal?: AbortSignal;
+    /** Pre-generated ID for the expected assistant response (for feedback tracking) */
+    assistantMessageId?: string;
+};
+type SSEHandler = (event: AgentWidgetEvent) => void;
+declare class AgentWidgetClient {
+    private config;
+    private readonly apiUrl;
+    private readonly headers;
+    private readonly debug;
+    private readonly createStreamParser;
+    private readonly contextProviders;
+    private readonly requestMiddleware?;
+    private readonly customFetch?;
+    private readonly parseSSEEvent?;
+    private readonly getHeaders?;
+    private clientSession;
+    private sessionInitPromise;
+    constructor(config?: AgentWidgetConfig);
+    /**
+     * Check if running in client token mode
+     */
+    isClientTokenMode(): boolean;
+    /**
+     * Get the appropriate API URL based on mode
+     */
+    private getClientApiUrl;
+    /**
+     * Get the current client session (if any)
+     */
+    getClientSession(): ClientSession | null;
+    /**
+     * Initialize session for client token mode.
+     * Called automatically on first message if not already initialized.
+     */
+    initSession(): Promise<ClientSession>;
+    private _doInitSession;
+    /**
+     * Clear the current client session
+     */
+    clearClientSession(): void;
+    /**
+     * Get the feedback API URL
+     */
+    private getFeedbackApiUrl;
+    /**
+     * Send feedback for a message (client token mode only).
+     * Supports upvote, downvote, copy, csat, and nps feedback types.
+     *
+     * @param feedback - The feedback request payload
+     * @returns Promise that resolves when feedback is sent successfully
+     * @throws Error if not in client token mode or if session is invalid
+     *
+     * @example
+     * ```typescript
+     * // Message feedback (upvote/downvote/copy)
+     * await client.sendFeedback({
+     *   session_id: sessionId,
+     *   message_id: messageId,
+     *   type: 'upvote'
+     * });
+     *
+     * // CSAT feedback (1-5 rating)
+     * await client.sendFeedback({
+     *   session_id: sessionId,
+     *   type: 'csat',
+     *   rating: 5,
+     *   comment: 'Great experience!'
+     * });
+     *
+     * // NPS feedback (0-10 rating)
+     * await client.sendFeedback({
+     *   session_id: sessionId,
+     *   type: 'nps',
+     *   rating: 9
+     * });
+     * ```
+     */
+    sendFeedback(feedback: ClientFeedbackRequest): Promise<void>;
+    /**
+     * Submit message feedback (upvote, downvote, or copy).
+     * Convenience method for sendFeedback with message-level feedback.
+     *
+     * @param messageId - The ID of the message to provide feedback for
+     * @param type - The feedback type: 'upvote', 'downvote', or 'copy'
+     */
+    submitMessageFeedback(messageId: string, type: 'upvote' | 'downvote' | 'copy'): Promise<void>;
+    /**
+     * Submit CSAT (Customer Satisfaction) feedback.
+     * Convenience method for sendFeedback with CSAT feedback.
+     *
+     * @param rating - Rating from 1 to 5
+     * @param comment - Optional comment
+     */
+    submitCSATFeedback(rating: number, comment?: string): Promise<void>;
+    /**
+     * Submit NPS (Net Promoter Score) feedback.
+     * Convenience method for sendFeedback with NPS feedback.
+     *
+     * @param rating - Rating from 0 to 10
+     * @param comment - Optional comment
+     */
+    submitNPSFeedback(rating: number, comment?: string): Promise<void>;
+    /**
+     * Send a message - handles both proxy and client token modes
+     */
+    dispatch(options: DispatchOptions, onEvent: SSEHandler): Promise<void>;
+    /**
+     * Client token mode dispatch
+     */
+    private dispatchClientToken;
+    /**
+     * Proxy mode dispatch (original implementation)
+     */
+    private dispatchProxy;
+    private buildPayload;
+    /**
+     * Handle custom SSE event parsing via parseSSEEvent callback
+     * Returns true if event was handled, false otherwise
+     */
+    private handleCustomSSEEvent;
+    private streamResponse;
+}
+
 type AgentWidgetSessionStatus = "idle" | "connecting" | "connected" | "error";
 type SessionCallbacks = {
     onMessagesChanged: (messages: AgentWidgetMessage[]) => void;
@@ -1402,6 +1578,34 @@ declare class AgentWidgetSession {
      * Clear session (on expiry or error)
      */
     clearClientSession(): void;
+    /**
+     * Get the underlying client instance (for advanced use cases like feedback)
+     */
+    getClient(): AgentWidgetClient;
+    /**
+     * Submit message feedback (upvote, downvote, or copy) to the API.
+     * Only available in client token mode.
+     *
+     * @param messageId - The ID of the message to provide feedback for
+     * @param type - The feedback type: 'upvote', 'downvote', or 'copy'
+     */
+    submitMessageFeedback(messageId: string, type: 'upvote' | 'downvote' | 'copy'): Promise<void>;
+    /**
+     * Submit CSAT (Customer Satisfaction) feedback to the API.
+     * Only available in client token mode.
+     *
+     * @param rating - Rating from 1 to 5
+     * @param comment - Optional comment
+     */
+    submitCSATFeedback(rating: number, comment?: string): Promise<void>;
+    /**
+     * Submit NPS (Net Promoter Score) feedback to the API.
+     * Only available in client token mode.
+     *
+     * @param rating - Rating from 0 to 10
+     * @param comment - Optional comment
+     */
+    submitNPSFeedback(rating: number, comment?: string): Promise<void>;
     updateConfig(next: AgentWidgetConfig): void;
     getMessages(): AgentWidgetMessage[];
     getStatus(): AgentWidgetSessionStatus;
@@ -1423,6 +1627,62 @@ declare class AgentWidgetSession {
     private sortMessages;
 }
 
+/**
+ * Feedback UI components for CSAT and NPS collection
+ */
+type CSATFeedbackOptions = {
+    /** Callback when user submits CSAT feedback */
+    onSubmit: (rating: number, comment?: string) => void | Promise<void>;
+    /** Callback when user dismisses the feedback form */
+    onDismiss?: () => void;
+    /** Title text */
+    title?: string;
+    /** Subtitle/question text */
+    subtitle?: string;
+    /** Placeholder for optional comment field */
+    commentPlaceholder?: string;
+    /** Submit button text */
+    submitText?: string;
+    /** Skip button text */
+    skipText?: string;
+    /** Show comment field */
+    showComment?: boolean;
+    /** Rating labels (5 items for ratings 1-5) */
+    ratingLabels?: [string, string, string, string, string];
+};
+type NPSFeedbackOptions = {
+    /** Callback when user submits NPS feedback */
+    onSubmit: (rating: number, comment?: string) => void | Promise<void>;
+    /** Callback when user dismisses the feedback form */
+    onDismiss?: () => void;
+    /** Title text */
+    title?: string;
+    /** Subtitle/question text */
+    subtitle?: string;
+    /** Placeholder for optional comment field */
+    commentPlaceholder?: string;
+    /** Submit button text */
+    submitText?: string;
+    /** Skip button text */
+    skipText?: string;
+    /** Show comment field */
+    showComment?: boolean;
+    /** Low label (left side) */
+    lowLabel?: string;
+    /** High label (right side) */
+    highLabel?: string;
+};
+/**
+ * Create a CSAT (Customer Satisfaction) feedback form
+ * Rating scale: 1-5
+ */
+declare function createCSATFeedback(options: CSATFeedbackOptions): HTMLElement;
+/**
+ * Create an NPS (Net Promoter Score) feedback form
+ * Rating scale: 0-10
+ */
+declare function createNPSFeedback(options: NPSFeedbackOptions): HTMLElement;
+
 type Controller = {
     update: (config: AgentWidgetConfig) => void;
     destroy: () => void;
@@ -1444,6 +1704,10 @@ type Controller = {
     isOpen: () => boolean;
     isVoiceActive: () => boolean;
     getState: () => AgentWidgetStateSnapshot;
+    showCSATFeedback: (options?: Partial<CSATFeedbackOptions>) => void;
+    showNPSFeedback: (options?: Partial<NPSFeedbackOptions>) => void;
+    submitCSATFeedback: (rating: number, comment?: string) => Promise<void>;
+    submitNPSFeedback: (rating: number, comment?: string) => Promise<void>;
 };
 declare const createAgentExperience: (mount: HTMLElement, initialConfig?: AgentWidgetConfig, runtimeOptions?: {
     debugTools?: boolean;
@@ -1455,68 +1719,6 @@ type AgentWidgetInitHandle = AgentWidgetController & {
 };
 declare const initAgentWidget: (options: AgentWidgetInitOptions) => AgentWidgetInitHandle;
 
-type DispatchOptions = {
-    messages: AgentWidgetMessage[];
-    signal?: AbortSignal;
-};
-type SSEHandler = (event: AgentWidgetEvent) => void;
-declare class AgentWidgetClient {
-    private config;
-    private readonly apiUrl;
-    private readonly headers;
-    private readonly debug;
-    private readonly createStreamParser;
-    private readonly contextProviders;
-    private readonly requestMiddleware?;
-    private readonly customFetch?;
-    private readonly parseSSEEvent?;
-    private readonly getHeaders?;
-    private clientSession;
-    private sessionInitPromise;
-    constructor(config?: AgentWidgetConfig);
-    /**
-     * Check if running in client token mode
-     */
-    isClientTokenMode(): boolean;
-    /**
-     * Get the appropriate API URL based on mode
-     */
-    private getClientApiUrl;
-    /**
-     * Get the current client session (if any)
-     */
-    getClientSession(): ClientSession | null;
-    /**
-     * Initialize session for client token mode.
-     * Called automatically on first message if not already initialized.
-     */
-    initSession(): Promise<ClientSession>;
-    private _doInitSession;
-    /**
-     * Clear the current client session
-     */
-    clearClientSession(): void;
-    /**
-     * Send a message - handles both proxy and client token modes
-     */
-    dispatch(options: DispatchOptions, onEvent: SSEHandler): Promise<void>;
-    /**
-     * Client token mode dispatch
-     */
-    private dispatchClientToken;
-    /**
-     * Proxy mode dispatch (original implementation)
-     */
-    private dispatchProxy;
-    private buildPayload;
-    /**
-     * Handle custom SSE event parsing via parseSSEEvent callback
-     * Returns true if event was handled, false otherwise
-     */
-    private handleCustomSSEEvent;
-    private streamResponse;
-}
-
 declare const createLocalStorageAdapter: (key?: string) => AgentWidgetStorageAdapter;
 
 type ActionManagerProcessContext = {
@@ -1652,6 +1854,26 @@ declare const createFlexibleJsonStreamParser: (textExtractor?: (parsed: any) =>
  */
 declare const createXmlParser: () => AgentWidgetStreamParser;
 
+/**
+ * Message ID utilities for client-side message tracking
+ * Used for feedback integration with the Travrse API
+ */
+/**
+ * Generate a unique message ID for tracking
+ * Format: msg_{timestamp_base36}_{random_8chars}
+ */
+declare function generateMessageId(): string;
+/**
+ * Generate a unique user message ID
+ * Format: usr_{timestamp_base36}_{random_8chars}
+ */
+declare function generateUserMessageId(): string;
+/**
+ * Generate a unique assistant message ID
+ * Format: ast_{timestamp_base36}_{random_8chars}
+ */
+declare function generateAssistantMessageId(): string;
+
 type CodeFormat = "esm" | "script-installer" | "script-manual" | "script-advanced" | "react-component" | "react-advanced";
 declare function generateCodeSnippet(config: any, format?: CodeFormat): string;
 
@@ -1928,4 +2150,4 @@ declare const getHeaderLayout: (layoutName: string) => HeaderLayoutRenderer;
  */
 declare const buildHeaderWithLayout: (config: AgentWidgetConfig, layoutConfig?: AgentWidgetHeaderLayoutConfig, context?: Partial<HeaderLayoutContext>) => HeaderElements;
 
-export { type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetCustomFetch, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type ClientChatRequest, type ClientInitResponse, type ClientSession, type CodeFormat, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComposerBuildContext, type ComposerElements, DEFAULT_WIDGET_CONFIG, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageRenderContext, type MessageTransform, type SlotRenderContext, type SlotRenderer, type WidgetLayoutSlot, attachHeaderToContainer, buildComposer, buildDefaultHeader, buildExpandedHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, componentRegistry, createActionManager, createAgentExperience, createBubbleWithLayout, createComponentMiddleware, createComponentStreamParser, createDirectivePostprocessor, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createPlainTextParser, createRegexJsonParser, createStandardBubble, createTypingIndicator, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, generateCodeSnippet, getHeaderLayout, hasComponentDirective, headerLayouts, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, pluginRegistry, renderComponentDirective };
+export { type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetCustomFetch, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetMarkdownConfig, type AgentWidgetMarkdownOptions, type AgentWidgetMarkdownRendererOverrides, type AgentWidgetMessage, type AgentWidgetMessageActionsConfig, type AgentWidgetMessageFeedback, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type CSATFeedbackOptions, type ClientChatRequest, type ClientFeedbackRequest, type ClientFeedbackType, type ClientInitResponse, type ClientSession, type CodeFormat, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComposerBuildContext, type ComposerElements, DEFAULT_WIDGET_CONFIG, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type MarkdownProcessorOptions, type MessageActionCallbacks, type MessageRenderContext, type MessageTransform, type NPSFeedbackOptions, type SlotRenderContext, type SlotRenderer, type WidgetLayoutSlot, attachHeaderToContainer, buildComposer, buildDefaultHeader, buildExpandedHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, componentRegistry, createActionManager, createAgentExperience, createBubbleWithLayout, createCSATFeedback, createComponentMiddleware, createComponentStreamParser, createDirectivePostprocessor, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createMarkdownProcessor, createMarkdownProcessorFromConfig, createMessageActions, createNPSFeedback, createPlainTextParser, createRegexJsonParser, createStandardBubble, createTypingIndicator, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, generateAssistantMessageId, generateCodeSnippet, generateMessageId, generateUserMessageId, getHeaderLayout, hasComponentDirective, headerLayouts, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, pluginRegistry, renderComponentDirective };