@wallavi/widget 1.6.8 → 1.7.1

package/dist/index.d.mts

@@ -66,6 +66,36 @@ interface UserContext {
     pageContext?: PageContext;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Plug-in backend for non-AI modes (e.g. human support chat).
+ * When provided, ChatWidget/useChat skip all Wallavi AI API calls and
+ * use these values directly — same UI, different message source.
+ */
+interface CustomBackend {
+    messages: Message[];
+    streaming: boolean;
+    send: (text: string, attachments?: AttachmentPayload[]) => Promise<void>;
+    reset?: () => void;
+    /** Current chat mode — used to display a status indicator in the widget. */
+    mode?: "ai" | "human";
+    /** Optional action button rendered between messages and input (e.g. "Talk to a human"). */
+    footerAction?: {
+        label: string;
+        sublabel?: string;
+        icon?: "human" | "ai";
+        onClick: () => Promise<void>;
+        loading?: boolean;
+    };
+    voiceCall?: {
+        active: boolean;
+        token: string | null;
+        serverUrl: string | null;
+        start: () => Promise<void>;
+        stop: () => void;
+        loading: boolean;
+        error: string | null;
+    };
+}
 interface ChatWidgetConfig {
     agentId: string;
     workspaceId?: string;
@@ -95,6 +125,7 @@ interface ChatWidgetConfig {
      */
     hideCloseButton?: boolean;
     source?: string;
+    envId?: string;
     userContext?: UserContext;
     /** Per-session tool overrides used by Playground (not persisted) */
     playgroundOverrides?: {
@@ -120,6 +151,10 @@ interface ChatWidgetConfig {
      * Default: false.
      */
     enableAttachments?: boolean;
+    /** When set, bypasses Wallavi AI and routes messages through this backend instead. */
+    customBackend?: CustomBackend;
+    /** Callback fired when a debug-trace event arrives from the pipeline. Only emitted for source="playground". */
+    onDebugTrace?: (trace: Record<string, unknown>) => void;
 }
 interface ChatWidgetProps extends ChatWidgetConfig {
     className?: string;
@@ -129,6 +164,8 @@ interface ChatWidgetProps extends ChatWidgetConfig {
     onExpand?: () => void;
     /** Controls which icon the expand button shows (expand vs minimize). */
     expanded?: boolean;
+    /** When true, removes border-radius, border, and shadow — use when ChatWidget is rendered inside an iframe whose container already provides those styles. */
+    embedded?: boolean;
 }
 type AttachmentContentType = "text" | "image" | "unsupported";
 /** Wire-format DTO included in /api/chat/stream request when files are attached. */
@@ -159,7 +196,18 @@ interface Attachment {
 declare function getContrastColor(hex: string): string;
 declare function formatToolName(name: string): string;
 
-interface BubbleWidgetProps extends ChatWidgetConfig {
+interface BubbleWidgetProps extends Partial<ChatWidgetConfig> {
+    /**
+     * Inbox token from Wallavi Support dashboard.
+     * When provided, the widget connects to the support inbox (human agents + optional AI)
+     * instead of a direct AI agent. Mutually exclusive with agentId.
+     */
+    inboxToken?: string;
+    /**
+     * Base URL of the Wallavi app. Only needed when using inboxToken from an external domain.
+     * @default "https://app.wallavi.com"
+     */
+    supportApiBase?: string;
     /** Where the bubble is anchored. Default: "bottom-right" */
     position?: "bottom-right" | "bottom-left";
     /** Chat panel width in px. Default: 360 */
@@ -213,14 +261,26 @@ interface BubbleWidgetProps extends ChatWidgetConfig {
      * Use together with isOpen to fully control open/close from outside.
      */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Label for the footer button shown while AI mode is active (prompts user to escalate).
+     * @default "Hablar con un agente"
+     */
+    requestHumanLabel?: string;
+    /**
+     * Label for the footer button shown while a human agent is handling the chat.
+     * When omitted the button is not rendered and the user cannot return to AI.
+     * @example "Volver a chatear con la IA"
+     */
+    returnToAiLabel?: string;
 }
-declare function BubbleWidget({ position: positionProp, width: widthProp, height: heightProp, expandedWidth, expandedHeight, keyboardShortcut: keyboardShortcutProp, shortcutKey, autoOpen: autoOpenProp, bubbleIconUrl: bubbleIconUrlProp, bubbleSize: bubbleSizeProp, panelClassName, autoConfig, hideBubble, isOpen: isOpenProp, onOpenChange, ...chatProps }: BubbleWidgetProps): react_jsx_runtime.JSX.Element;
+declare function BubbleWidget({ inboxToken, supportApiBase, requestHumanLabel, returnToAiLabel, position: positionProp, width: widthProp, height: heightProp, expandedWidth, expandedHeight, keyboardShortcut: keyboardShortcutProp, shortcutKey, autoOpen: autoOpenProp, bubbleIconUrl: bubbleIconUrlProp, bubbleSize: bubbleSizeProp, panelClassName, autoConfig, hideBubble, isOpen: isOpenProp, onOpenChange, ...chatProps }: BubbleWidgetProps): react_jsx_runtime.JSX.Element;
 
-declare function ChatWidget({ agentId, workspaceId, agentName, displayName, profilePicture, userMessageColor, initialMessages, suggestedMessages, messagePlaceholder, watermark, watermarkLogoUrl, footer, theme, showThinking, regenerateMessage, persist, onNavigate, hideCloseButton, source, userContext, playgroundOverrides, enableVoice, voiceAutoSend, enableAttachments, className, onClose, onReset, onExpand, expanded, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+declare function ChatWidget({ agentId, workspaceId, agentName, displayName, profilePicture, userMessageColor, initialMessages, suggestedMessages, messagePlaceholder, watermark, watermarkLogoUrl, footer, theme, showThinking, regenerateMessage, persist, onNavigate, hideCloseButton, source, userContext, playgroundOverrides, enableVoice, voiceAutoSend, enableAttachments, customBackend, className, onClose, onReset, onExpand, expanded, embedded, envId, onDebugTrace, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface UseChatOptions {
     agentId: string;
     workspaceId?: string;
+    envId?: string;
     source?: string;
     userContext?: UserContext;
     persist?: boolean;
@@ -230,6 +290,7 @@ interface UseChatOptions {
         mcpIds?: string[];
         actionIds?: string[];
     };
+    customBackend?: CustomBackend;
 }
 interface UseChatReturn {
     messages: Message[];
@@ -243,8 +304,93 @@ interface UseChatReturn {
     regenerate: () => Promise<void>;
     reset: () => void;
     selectPickerOption: (pickerId: string, paramName: string, value: string, label: string) => Promise<void>;
+    /** Pipeline debug traces — only populated when source="playground" */
+    debugTraces: DebugTrace[];
+    voiceCall?: {
+        active: boolean;
+        token: string | null;
+        serverUrl: string | null;
+        start: () => Promise<void>;
+        stop: () => void;
+        loading: boolean;
+        error: string | null;
+    };
+}
+/** Structured pipeline execution data emitted per-turn from the backend */
+interface DebugTrace {
+    threadId: string;
+    agentId: string;
+    sessionId: string;
+    turn: number;
+    timestamp: number;
+    durationMs: number;
+    userMessage: string;
+    assistantResponse: string;
+    router: {
+        intent: string;
+        capability: string;
+        complexity?: string;
+    };
+    tools: {
+        available: number;
+        selected: number;
+        executed: string[];
+        targetTool?: string;
+        selectedNames?: string[];
+    };
+    params: {
+        available: Record<string, string>;
+        missing: string[];
+    };
+    provider: {
+        name: string;
+        model: string;
+        fallbackCount: number;
+    };
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    executionStatus: string;
+    flags: string[];
+}
+declare function useChat({ agentId, workspaceId, envId, source, userContext, persist, onNavigate, playgroundOverrides, customBackend, }: UseChatOptions): UseChatReturn;
+
+declare function PlanCard({ part, onSend, disabled, }: {
+    part: PlanPart;
+    onSend?: (text: string) => void;
+    disabled?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+declare function ToolCallBadge({ part }: {
+    part: ToolPart;
+}): react_jsx_runtime.JSX.Element;
+declare function ReasoningBlock({ text }: {
+    text: string;
+}): react_jsx_runtime.JSX.Element;
+
+interface UseSupportChatOptions {
+    /** Inbox token from Wallavi Support dashboard. */
+    inboxToken: string;
+    /**
+     * Base URL of the Wallavi app that hosts the support-chat API routes.
+     * @default "https://app.wallavi.com"
+     */
+    apiBase?: string;
+    /**
+     * Label for the footer button shown when AI mode is active.
+     * @default "Hablar con un agente"
+     */
+    requestHumanLabel?: string;
+    /**
+     * Label for the footer button shown when human agent mode is active.
+     * If not set, no "return to AI" button is shown.
+     * @example "Volver a chatear con la IA"
+     */
+    returnToAiLabel?: string;
 }
-declare function useChat({ agentId, workspaceId, source, userContext, persist, onNavigate, playgroundOverrides, }: UseChatOptions): UseChatReturn;
+declare function useSupportChat({ inboxToken, apiBase, requestHumanLabel, returnToAiLabel, }: UseSupportChatOptions): CustomBackend;
 
 type VoiceState = "idle" | "recording" | "transcribing" | "error";
 interface UseVoiceOptions {
@@ -262,7 +408,7 @@ interface UseVoiceReturn {
     start: () => Promise<void>;
     stop: () => void;
 }
-declare function useVoice({ agentId, apiUrl, onTranscript, onError }: UseVoiceOptions): UseVoiceReturn;
+declare function useVoice({ agentId, apiUrl, onTranscript, onError, }: UseVoiceOptions): UseVoiceReturn;
 
 interface UseAttachmentsOptions {
     agentId: string;
@@ -284,4 +430,4 @@ interface UseAttachmentsReturn {
 }
 declare function useAttachments({ agentId, apiUrl, maxFiles, }: UseAttachmentsOptions): UseAttachmentsReturn;
 
-export { type Attachment, type AttachmentContentType, type AttachmentPayload, type AttachmentStatus, BubbleWidget, type BubbleWidgetProps, ChatWidget, type ChatWidgetConfig, type ChatWidgetProps, type Message, type MessagePart, type PageContext, type ToolPart, type UseAttachmentsOptions, type UseAttachmentsReturn, type UseVoiceOptions, type UseVoiceReturn, type UserContext, type VoiceState, formatToolName, getContrastColor, useAttachments, useChat, useVoice };
+export { type Attachment, type AttachmentContentType, type AttachmentPayload, type AttachmentStatus, BubbleWidget, type BubbleWidgetProps, ChatWidget, type ChatWidgetConfig, type ChatWidgetProps, type CustomBackend, type DebugTrace, type Message, type MessagePart, type PageContext, PlanCard, type PlanPart, ReasoningBlock, ToolCallBadge, type ToolPart, type UseAttachmentsOptions, type UseAttachmentsReturn, type UseChatOptions, type UseChatReturn, type UseSupportChatOptions, type UseVoiceOptions, type UseVoiceReturn, type UserContext, type VoiceState, formatToolName, getContrastColor, useAttachments, useChat, useSupportChat, useVoice };

package/dist/index.d.ts

@@ -66,6 +66,36 @@ interface UserContext {
     pageContext?: PageContext;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Plug-in backend for non-AI modes (e.g. human support chat).
+ * When provided, ChatWidget/useChat skip all Wallavi AI API calls and
+ * use these values directly — same UI, different message source.
+ */
+interface CustomBackend {
+    messages: Message[];
+    streaming: boolean;
+    send: (text: string, attachments?: AttachmentPayload[]) => Promise<void>;
+    reset?: () => void;
+    /** Current chat mode — used to display a status indicator in the widget. */
+    mode?: "ai" | "human";
+    /** Optional action button rendered between messages and input (e.g. "Talk to a human"). */
+    footerAction?: {
+        label: string;
+        sublabel?: string;
+        icon?: "human" | "ai";
+        onClick: () => Promise<void>;
+        loading?: boolean;
+    };
+    voiceCall?: {
+        active: boolean;
+        token: string | null;
+        serverUrl: string | null;
+        start: () => Promise<void>;
+        stop: () => void;
+        loading: boolean;
+        error: string | null;
+    };
+}
 interface ChatWidgetConfig {
     agentId: string;
     workspaceId?: string;
@@ -95,6 +125,7 @@ interface ChatWidgetConfig {
      */
     hideCloseButton?: boolean;
     source?: string;
+    envId?: string;
     userContext?: UserContext;
     /** Per-session tool overrides used by Playground (not persisted) */
     playgroundOverrides?: {
@@ -120,6 +151,10 @@ interface ChatWidgetConfig {
      * Default: false.
      */
     enableAttachments?: boolean;
+    /** When set, bypasses Wallavi AI and routes messages through this backend instead. */
+    customBackend?: CustomBackend;
+    /** Callback fired when a debug-trace event arrives from the pipeline. Only emitted for source="playground". */
+    onDebugTrace?: (trace: Record<string, unknown>) => void;
 }
 interface ChatWidgetProps extends ChatWidgetConfig {
     className?: string;
@@ -129,6 +164,8 @@ interface ChatWidgetProps extends ChatWidgetConfig {
     onExpand?: () => void;
     /** Controls which icon the expand button shows (expand vs minimize). */
     expanded?: boolean;
+    /** When true, removes border-radius, border, and shadow — use when ChatWidget is rendered inside an iframe whose container already provides those styles. */
+    embedded?: boolean;
 }
 type AttachmentContentType = "text" | "image" | "unsupported";
 /** Wire-format DTO included in /api/chat/stream request when files are attached. */
@@ -159,7 +196,18 @@ interface Attachment {
 declare function getContrastColor(hex: string): string;
 declare function formatToolName(name: string): string;
 
-interface BubbleWidgetProps extends ChatWidgetConfig {
+interface BubbleWidgetProps extends Partial<ChatWidgetConfig> {
+    /**
+     * Inbox token from Wallavi Support dashboard.
+     * When provided, the widget connects to the support inbox (human agents + optional AI)
+     * instead of a direct AI agent. Mutually exclusive with agentId.
+     */
+    inboxToken?: string;
+    /**
+     * Base URL of the Wallavi app. Only needed when using inboxToken from an external domain.
+     * @default "https://app.wallavi.com"
+     */
+    supportApiBase?: string;
     /** Where the bubble is anchored. Default: "bottom-right" */
     position?: "bottom-right" | "bottom-left";
     /** Chat panel width in px. Default: 360 */
@@ -213,14 +261,26 @@ interface BubbleWidgetProps extends ChatWidgetConfig {
      * Use together with isOpen to fully control open/close from outside.
      */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Label for the footer button shown while AI mode is active (prompts user to escalate).
+     * @default "Hablar con un agente"
+     */
+    requestHumanLabel?: string;
+    /**
+     * Label for the footer button shown while a human agent is handling the chat.
+     * When omitted the button is not rendered and the user cannot return to AI.
+     * @example "Volver a chatear con la IA"
+     */
+    returnToAiLabel?: string;
 }
-declare function BubbleWidget({ position: positionProp, width: widthProp, height: heightProp, expandedWidth, expandedHeight, keyboardShortcut: keyboardShortcutProp, shortcutKey, autoOpen: autoOpenProp, bubbleIconUrl: bubbleIconUrlProp, bubbleSize: bubbleSizeProp, panelClassName, autoConfig, hideBubble, isOpen: isOpenProp, onOpenChange, ...chatProps }: BubbleWidgetProps): react_jsx_runtime.JSX.Element;
+declare function BubbleWidget({ inboxToken, supportApiBase, requestHumanLabel, returnToAiLabel, position: positionProp, width: widthProp, height: heightProp, expandedWidth, expandedHeight, keyboardShortcut: keyboardShortcutProp, shortcutKey, autoOpen: autoOpenProp, bubbleIconUrl: bubbleIconUrlProp, bubbleSize: bubbleSizeProp, panelClassName, autoConfig, hideBubble, isOpen: isOpenProp, onOpenChange, ...chatProps }: BubbleWidgetProps): react_jsx_runtime.JSX.Element;
 
-declare function ChatWidget({ agentId, workspaceId, agentName, displayName, profilePicture, userMessageColor, initialMessages, suggestedMessages, messagePlaceholder, watermark, watermarkLogoUrl, footer, theme, showThinking, regenerateMessage, persist, onNavigate, hideCloseButton, source, userContext, playgroundOverrides, enableVoice, voiceAutoSend, enableAttachments, className, onClose, onReset, onExpand, expanded, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+declare function ChatWidget({ agentId, workspaceId, agentName, displayName, profilePicture, userMessageColor, initialMessages, suggestedMessages, messagePlaceholder, watermark, watermarkLogoUrl, footer, theme, showThinking, regenerateMessage, persist, onNavigate, hideCloseButton, source, userContext, playgroundOverrides, enableVoice, voiceAutoSend, enableAttachments, customBackend, className, onClose, onReset, onExpand, expanded, embedded, envId, onDebugTrace, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface UseChatOptions {
     agentId: string;
     workspaceId?: string;
+    envId?: string;
     source?: string;
     userContext?: UserContext;
     persist?: boolean;
@@ -230,6 +290,7 @@ interface UseChatOptions {
         mcpIds?: string[];
         actionIds?: string[];
     };
+    customBackend?: CustomBackend;
 }
 interface UseChatReturn {
     messages: Message[];
@@ -243,8 +304,93 @@ interface UseChatReturn {
     regenerate: () => Promise<void>;
     reset: () => void;
     selectPickerOption: (pickerId: string, paramName: string, value: string, label: string) => Promise<void>;
+    /** Pipeline debug traces — only populated when source="playground" */
+    debugTraces: DebugTrace[];
+    voiceCall?: {
+        active: boolean;
+        token: string | null;
+        serverUrl: string | null;
+        start: () => Promise<void>;
+        stop: () => void;
+        loading: boolean;
+        error: string | null;
+    };
+}
+/** Structured pipeline execution data emitted per-turn from the backend */
+interface DebugTrace {
+    threadId: string;
+    agentId: string;
+    sessionId: string;
+    turn: number;
+    timestamp: number;
+    durationMs: number;
+    userMessage: string;
+    assistantResponse: string;
+    router: {
+        intent: string;
+        capability: string;
+        complexity?: string;
+    };
+    tools: {
+        available: number;
+        selected: number;
+        executed: string[];
+        targetTool?: string;
+        selectedNames?: string[];
+    };
+    params: {
+        available: Record<string, string>;
+        missing: string[];
+    };
+    provider: {
+        name: string;
+        model: string;
+        fallbackCount: number;
+    };
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    executionStatus: string;
+    flags: string[];
+}
+declare function useChat({ agentId, workspaceId, envId, source, userContext, persist, onNavigate, playgroundOverrides, customBackend, }: UseChatOptions): UseChatReturn;
+
+declare function PlanCard({ part, onSend, disabled, }: {
+    part: PlanPart;
+    onSend?: (text: string) => void;
+    disabled?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+declare function ToolCallBadge({ part }: {
+    part: ToolPart;
+}): react_jsx_runtime.JSX.Element;
+declare function ReasoningBlock({ text }: {
+    text: string;
+}): react_jsx_runtime.JSX.Element;
+
+interface UseSupportChatOptions {
+    /** Inbox token from Wallavi Support dashboard. */
+    inboxToken: string;
+    /**
+     * Base URL of the Wallavi app that hosts the support-chat API routes.
+     * @default "https://app.wallavi.com"
+     */
+    apiBase?: string;
+    /**
+     * Label for the footer button shown when AI mode is active.
+     * @default "Hablar con un agente"
+     */
+    requestHumanLabel?: string;
+    /**
+     * Label for the footer button shown when human agent mode is active.
+     * If not set, no "return to AI" button is shown.
+     * @example "Volver a chatear con la IA"
+     */
+    returnToAiLabel?: string;
 }
-declare function useChat({ agentId, workspaceId, source, userContext, persist, onNavigate, playgroundOverrides, }: UseChatOptions): UseChatReturn;
+declare function useSupportChat({ inboxToken, apiBase, requestHumanLabel, returnToAiLabel, }: UseSupportChatOptions): CustomBackend;
 
 type VoiceState = "idle" | "recording" | "transcribing" | "error";
 interface UseVoiceOptions {
@@ -262,7 +408,7 @@ interface UseVoiceReturn {
     start: () => Promise<void>;
     stop: () => void;
 }
-declare function useVoice({ agentId, apiUrl, onTranscript, onError }: UseVoiceOptions): UseVoiceReturn;
+declare function useVoice({ agentId, apiUrl, onTranscript, onError, }: UseVoiceOptions): UseVoiceReturn;
 
 interface UseAttachmentsOptions {
     agentId: string;
@@ -284,4 +430,4 @@ interface UseAttachmentsReturn {
 }
 declare function useAttachments({ agentId, apiUrl, maxFiles, }: UseAttachmentsOptions): UseAttachmentsReturn;
 
-export { type Attachment, type AttachmentContentType, type AttachmentPayload, type AttachmentStatus, BubbleWidget, type BubbleWidgetProps, ChatWidget, type ChatWidgetConfig, type ChatWidgetProps, type Message, type MessagePart, type PageContext, type ToolPart, type UseAttachmentsOptions, type UseAttachmentsReturn, type UseVoiceOptions, type UseVoiceReturn, type UserContext, type VoiceState, formatToolName, getContrastColor, useAttachments, useChat, useVoice };
+export { type Attachment, type AttachmentContentType, type AttachmentPayload, type AttachmentStatus, BubbleWidget, type BubbleWidgetProps, ChatWidget, type ChatWidgetConfig, type ChatWidgetProps, type CustomBackend, type DebugTrace, type Message, type MessagePart, type PageContext, PlanCard, type PlanPart, ReasoningBlock, ToolCallBadge, type ToolPart, type UseAttachmentsOptions, type UseAttachmentsReturn, type UseChatOptions, type UseChatReturn, type UseSupportChatOptions, type UseVoiceOptions, type UseVoiceReturn, type UserContext, type VoiceState, formatToolName, getContrastColor, useAttachments, useChat, useSupportChat, useVoice };