@knowbl_ai/nexus-chat 1.0.0

package/dist/types/types/index.d.ts

@@ -0,0 +1,1456 @@
+import type { ChatStore } from "../store/chatStore";
+export interface VoiceConfig {
+    enabled: boolean;
+    language?: string;
+    continuous?: boolean;
+    interimResults?: boolean;
+    maxAlternatives?: number;
+}
+export interface SpeechSynthesisConfig {
+    engine?: "elevenlabs" | "openai" | "google" | "aws" | "browser";
+    voiceId?: string;
+    modelId?: string;
+    greetingText?: string;
+    language?: string;
+    volume?: number;
+    stability?: number;
+    similarityBoost?: number;
+    style?: number;
+    useSpeakerBoost?: boolean;
+    speed?: number;
+    rate?: number;
+    pitch?: number;
+    outputFormat?: string;
+}
+export interface TTSConfig {
+    enabled: boolean;
+    defaultOn?: boolean;
+    /**
+     * Speech synthesis configuration (used for both server and fallback browser)
+     * @internal
+     */
+    synthesisConfig?: SpeechSynthesisConfig;
+}
+export interface CopyButtonConfig {
+    enabled: boolean;
+    position?: "top" | "bottom" | "inline" | "top-right";
+    showLabel?: boolean;
+    showIcon?: boolean;
+    style?: "default" | "minimal" | "outline" | "ghost";
+    size?: "small" | "medium" | "large";
+    className?: string;
+    iconColor?: string;
+    textColor?: string;
+    backgroundColor?: string;
+    hoverBackgroundColor?: string;
+    copyIcon?: string;
+    copiedIcon?: string;
+    copiedDuration?: number;
+    tooltipText?: string;
+    copiedText?: string;
+}
+export interface FeedbackConfig {
+    enabled: boolean;
+    position?: "inline" | "bottom" | "top";
+    style?: "thumbs" | "stars" | "emoji" | "custom";
+    showOnAssistantMessages?: boolean;
+    showOnAgentMessages?: boolean;
+    requireComment?: boolean;
+    commentPrompt?: string;
+    buttons?: {
+        size?: "small" | "medium" | "large";
+        spacing?: string;
+        showLabels?: boolean;
+        animation?: "none" | "scale" | "fade";
+        positive?: {
+            icon?: string;
+            label?: string;
+            color?: string;
+            activeColor?: string;
+            hoverColor?: string;
+            backgroundColor?: string;
+            activeBackgroundColor?: string;
+        };
+        negative?: {
+            icon?: string;
+            label?: string;
+            color?: string;
+            activeColor?: string;
+            hoverColor?: string;
+            backgroundColor?: string;
+            activeBackgroundColor?: string;
+        };
+        starCount?: number;
+        starColor?: string;
+        starActiveColor?: string;
+        emojis?: Array<{
+            value: string;
+            icon: string;
+            label?: string;
+        }>;
+    };
+    behavior?: {
+        allowChange?: boolean;
+        showConfirmation?: boolean;
+        confirmationMessage?: string;
+        confirmationDuration?: number;
+        persistFeedback?: boolean;
+    };
+    api?: {
+        endpoint?: string;
+        includeContext?: boolean;
+        additionalData?: Record<string, any>;
+    };
+}
+/**
+ * Font weight presets for text styling
+ */
+export type FontWeight = "light" | "normal" | "medium" | "semibold" | "bold";
+/**
+ * Font size presets for text styling
+ * Maps to common CSS font-size values
+ * Accepts preset values: "xs" (12px), "sm" (14px), "base" (16px), "lg" (18px), "xl" (20px)
+ * Or any custom CSS value: "14px", "1.5rem", "1.2em", etc.
+ */
+export type FontSize = string;
+/**
+ * Avatar size: preset or custom CSS value
+ * Accepts preset values: "xs" (20px), "sm" (24px), "md" (32px), "lg" (40px), "xl" (48px)
+ * Or any custom CSS value: "32px", "2rem", etc.
+ * @example "md"
+ * @example "xs"
+ * @example "32px"
+ * @example "2rem"
+ */
+export type AvatarSize = string;
+/**
+ * Avatar border radius: preset or custom CSS value
+ * Accepts preset values: "circle" (fully rounded), "rounded" (8px), "square" (0px)
+ * Or any custom CSS value: "8px", "50%", etc.
+ * @example "circle"
+ * @example "rounded"
+ * @example "8px"
+ * @example "50%"
+ */
+export type AvatarBorderRadius = string;
+/**
+ * Avatar styling configuration
+ */
+export interface AvatarConfig {
+    /**
+     * Whether to show the avatar
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Avatar image URL
+     * If not provided, falls back to default avatar icon
+     * @example "https://api.dicebear.com/7.x/avataaars/svg?seed=agent"
+     */
+    url?: string;
+    /**
+     * Avatar size
+     * Presets: "xs" (20px), "sm" (24px), "md" (32px), "lg" (40px), "xl" (48px)
+     * Or provide custom CSS value: "40px", "2.5rem", etc.
+     */
+    size?: AvatarSize;
+    /**
+     * Avatar border radius
+     * Presets: "circle" (fully rounded), "rounded" (8px), "square" (0px)
+     * Or provide custom CSS value: "50%", "12px", etc.
+     */
+    borderRadius?: AvatarBorderRadius;
+    /**
+     * Avatar border (shorthand)
+     * @example "2px solid #e5e7eb"
+     */
+    border?: string;
+    /**
+     * Avatar border width (granular)
+     * @example "2px"
+     */
+    borderWidth?: string;
+    /**
+     * Avatar border color (granular)
+     * @example "#10b981"
+     */
+    borderColor?: string;
+    /**
+     * Avatar border style (granular)
+     * @example "solid", "dashed", "dotted"
+     */
+    borderStyle?: string;
+    /**
+     * Avatar margin (spacing around avatar)
+     * @example "0 12px 0 0"
+     * @default "0 12px 0 0" (message bubbles)
+     */
+    margin?: string;
+}
+/**
+ * Shared styling configuration for event rendering
+ * Applies to sessionStart, sessionEnd, and agentHandover events
+ */
+export interface EventStylingConfig {
+    /** Font size for event text (preset or custom CSS value) */
+    fontSize?: FontSize;
+    /** Font family for event text */
+    fontFamily?: string;
+    /** Font style for event text (normal, italic, oblique) */
+    fontStyle?: "normal" | "italic" | "oblique";
+    /** Text color for event content */
+    textColor?: string;
+    /** Background color for event container */
+    backgroundColor?: string;
+    /** Border radius for event container */
+    borderRadius?: string;
+    /** Padding inside event container (CSS shorthand) */
+    padding?: string;
+    /**
+     * Default avatar styling for all events
+     */
+    avatar?: AvatarConfig;
+}
+/**
+ * Configuration for the send button styling
+ */
+export interface SendButtonConfig {
+    /**
+     * Base color for the send button (used for background in filled mode, text in text mode)
+     * @example "#3B82F6"
+     */
+    color?: string;
+    /**
+     * Custom text label for the send button (replaces default icon)
+     * @example "Send"
+     */
+    text?: string;
+    /**
+     * Font family for send button text
+     * @example "Arial, sans-serif"
+     */
+    fontFamily?: string;
+    /**
+     * Font size for send button text
+     * @example "base"
+     * @example "14px"
+     */
+    fontSize?: FontSize;
+    /**
+     * Font weight for send button text
+     * @example "semibold"
+     */
+    fontWeight?: FontWeight;
+    /**
+     * Padding inside the send button
+     * @example "8px 16px"
+     */
+    padding?: string;
+    /**
+     * Button appearance mode
+     * - "filled": Solid background with contrasting text (default)
+     * - "text": Transparent background with colored text
+     * @default "filled"
+     */
+    style?: "filled" | "text";
+    /**
+     * Background color (overrides color for filled mode, allows transparent)
+     * @example "#3B82F6"
+     * @example "transparent"
+     */
+    backgroundColor?: string;
+    /**
+     * Border for send button
+     * @example "1px solid #ccc"
+     * @example "none"
+     */
+    border?: string;
+    /**
+     * Border radius for send button
+     * Falls back to input.borderRadius if not specified
+     * @example "8px"
+     * @example "50%"
+     */
+    borderRadius?: string;
+    /**
+     * Text/icon color for send button
+     * @example "#ffffff"
+     */
+    textColor?: string;
+    /**
+     * Opacity when button is disabled
+     * @default "0.5"
+     */
+    disabledOpacity?: string;
+    /**
+     * Text/icon color when button is disabled
+     * @example "rgba(0, 0, 0, 0.3)"
+     */
+    disabledTextColor?: string;
+}
+/**
+ * Configuration for link styling in markdown content
+ */
+export interface LinkConfig {
+    /**
+     * Link text color (CSS color value)
+     * @example "#0066cc"
+     * @example "rgb(0, 102, 204)"
+     */
+    color?: string;
+    /**
+     * Link hover state color (CSS color value)
+     * Defaults to the same color as `color` if not specified
+     * @example "#0052a3"
+     */
+    hoverColor?: string;
+    /**
+     * Whether to underline links
+     * @default true
+     */
+    underline?: boolean;
+    /**
+     * Whether links should open in a new tab
+     * @default true
+     */
+    openInNewTab?: boolean;
+    /**
+     * Font weight for link text
+     * Uses named presets that map to standard CSS font-weight values
+     * @example "bold"
+     * @example "normal"
+     * @default undefined (inherits from parent styles)
+     */
+    fontWeight?: FontWeight;
+    /**
+     * Font size for link text
+     * Uses named presets or custom CSS values
+     * @example "sm"
+     * @example "16px"
+     * @example "1.25rem"
+     * @default undefined (inherits base font size)
+     */
+    fontSize?: FontSize;
+}
+export interface InputConfig {
+    placeholder?: string;
+    placeholderColor?: string;
+    placeholderFontStyle?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    borderColor?: string;
+    borderRadius?: string;
+    borderWidth?: string;
+    fontFamily?: string;
+    /**
+     * Font size for input text
+     * @example "base"
+     * @example "14px"
+     * @default undefined (inherits base font size)
+     */
+    fontSize?: FontSize;
+    /**
+     * Send button configuration
+     * Groups all send button styling properties
+     */
+    sendButton?: SendButtonConfig;
+    /**
+     * @deprecated Use `sendButton.color` instead
+     */
+    sendButtonColor?: string;
+    /**
+     * Color for microphone button (not yet implemented)
+     */
+    micButtonColor?: string;
+    /**
+     * @deprecated Use `sendButton.text` instead
+     */
+    sendButtonText?: string;
+    /**
+     * @deprecated Use `sendButton.fontFamily` instead
+     */
+    sendButtonFontFamily?: string;
+    /**
+     * Font size for send button text (when sendButtonText is set)
+     * @deprecated Use `sendButton.fontSize` instead
+     * @example "base"
+     * @example "14px"
+     * @example "1.5rem"
+     */
+    sendButtonFontSize?: FontSize;
+    /**
+     * Font weight for send button text (when sendButtonText is set)
+     * @deprecated Use `sendButton.fontWeight` instead
+     * @example "bold"
+     * @example "semibold"
+     */
+    sendButtonFontWeight?: FontWeight;
+    maxRows?: number;
+    maxHeight?: string;
+    minRows?: number;
+    padding?: string;
+    gap?: string;
+    /**
+     * @deprecated Use `sendButton.padding` instead
+     */
+    sendButtonPadding?: string;
+    /**
+     * @deprecated Use `sendButton.style` instead
+     */
+    sendButtonStyle?: "filled" | "text";
+    /**
+     * @deprecated Use `sendButton.backgroundColor` instead
+     */
+    sendButtonBackgroundColor?: string;
+    /**
+     * @deprecated Use `sendButton.border` instead
+     */
+    sendButtonBorder?: string;
+    /**
+     * @deprecated Use `sendButton.textColor` instead
+     */
+    sendButtonTextColor?: string;
+    /**
+     * @deprecated Use `sendButton.disabledOpacity` instead
+     */
+    sendButtonDisabledOpacity?: string;
+    /**
+     * @deprecated Use `sendButton.disabledTextColor` instead
+     */
+    sendButtonDisabledTextColor?: string;
+    integratedButton?: boolean;
+    /**
+     * Configuration for the border above the input area.
+     * - Set to `false` to hide the border
+     * - Set to `true` or omit to show the default border (maintains current behavior)
+     * - Set to object for full customization
+     * @default true
+     */
+    topBorder?: boolean | {
+        /**
+         * Whether to show the border
+         * @default true
+         */
+        show?: boolean;
+        /**
+         * Custom border color (CSS color value)
+         * @default Theme-based gray (#e5e7eb in light mode, #374151 in dark mode)
+         */
+        color?: string;
+        /**
+         * Border width (CSS width value)
+         * @default "1px"
+         */
+        width?: string;
+    };
+    /**
+     * Whether to autofocus the input field when the widget first loads.
+     * @default false
+     */
+    autofocusOnLoad?: boolean;
+    /**
+     * Whether to autofocus the input field after receiving a bot response.
+     * Useful to disable on demo pages with multiple widgets to prevent focus conflicts.
+     * @default true
+     */
+    autofocusAfterResponse?: boolean;
+}
+/**
+ * Configuration for scrollbar styling in the message container.
+ * All properties are optional. When not provided, browser default scrollbar is used.
+ *
+ * @example
+ * ```typescript
+ * scrollbar: {
+ *   width: "8px",
+ *   trackColor: "#f1f1f1",
+ *   thumbColor: "#888",
+ *   thumbHoverColor: "#555",
+ *   borderRadius: "4px",
+ *   autoHide: true,
+ *   autoHideDelay: 1000
+ * }
+ * ```
+ */
+export interface ScrollbarConfig {
+    /**
+     * Width of the scrollbar. Can be a pixel value (e.g., "8px") or "thin".
+     * Maps to custom scrollbar size across all browsers.
+     * @default Browser default
+     */
+    width?: string;
+    /**
+     * Background color of the scrollbar track.
+     * Works consistently across all browsers.
+     * @default Browser default
+     */
+    trackColor?: string;
+    /**
+     * Color of the scrollbar thumb.
+     * Works consistently across all browsers.
+     * @default Browser default
+     */
+    thumbColor?: string;
+    /**
+     * Color of the scrollbar thumb on hover.
+     * Works consistently across all browsers.
+     * @default thumbColor or browser default
+     */
+    thumbHoverColor?: string;
+    /**
+     * Border radius of the scrollbar thumb and track.
+     * Works consistently across all browsers.
+     * @default Browser default
+     */
+    borderRadius?: string;
+    /**
+     * Enable auto-hide scrollbar behavior.
+     * When enabled, scrollbar automatically hides after a period of inactivity
+     * and reappears on scroll or hover.
+     * Works consistently across all browsers via JavaScript implementation.
+     * @default false
+     */
+    autoHide?: boolean;
+    /**
+     * Delay in milliseconds before auto-hiding the scrollbar.
+     * Only applies when autoHide is enabled.
+     * @default 1000
+     */
+    autoHideDelay?: number;
+}
+export interface WidgetConfig {
+    experienceId: string;
+    apiUrl: string;
+    accessToken?: string;
+    theme?: "light" | "dark";
+    /**
+     * Global typography settings
+     * These provide base values that can be overridden by component-specific settings
+     */
+    typography?: {
+        /**
+         * Base font size for the entire widget
+         * This sets the root font size from which all relative sizes are calculated
+         * @example "base" (16px)
+         * @example "14px"
+         * @example "1rem"
+         * @default "base" (16px)
+         */
+        baseFontSize?: FontSize;
+    };
+    embedded?: boolean;
+    /**
+     * Enable Shadow DOM for complete CSS isolation.
+     * When true, the widget renders inside a Shadow DOM boundary, providing:
+     * - Complete bidirectional CSS isolation
+     * - No selector conflicts with host page
+     * - Protection from hostile CSS overrides
+     *
+     * Trade-offs:
+     * - Some third-party tools may not work (analytics that query DOM)
+     * - Inherited CSS properties (color, font-family) still cascade in
+     *
+     * @default false
+     */
+    useShadowDOM?: boolean;
+    /**
+     * Disable cross-tab synchronization.
+     * When false (the default), the widget synchronizes session, messages, and state
+     * across multiple browser tabs using BroadcastChannel API with localStorage fallback.
+     *
+     * Set to true when:
+     * - Different pages serve different purposes (multi-context applications)
+     * - Testing widget behavior in isolation
+     * - Users may have different accounts open in different tabs
+     * - Privacy requirements prevent state sharing between tabs
+     *
+     * @default false
+     */
+    disableTabSync?: boolean;
+    button?: {
+        position?: "bottom-right" | "bottom-left";
+        text?: string;
+        backgroundColor?: string;
+        textColor?: string;
+        hoverBackgroundColor?: string;
+        borderRadius?: string;
+        size?: "small" | "medium" | "large";
+        iconUrl?: string;
+    };
+    window?: {
+        width?: string;
+        height?: string;
+        backgroundColor?: string;
+        borderRadius?: string;
+        boxShadow?: string;
+        topAccentColor?: string;
+        topAccentHeight?: string;
+        sizing?: {
+            allowResize?: boolean;
+            modes?: Array<{
+                name: string;
+                width: string;
+                height: string;
+                icon?: string;
+            }>;
+            defaultMode?: string;
+            showToggle?: boolean;
+            rememberSize?: boolean;
+            disableAutoMobile?: boolean;
+        };
+        header?: {
+            show?: boolean;
+            backgroundColor?: string;
+            textColor?: string;
+            fontFamily?: string;
+            /**
+             * Font size for header title text
+             * @example "lg"
+             * @example "18px"
+             * @default undefined (inherits base font size)
+             */
+            fontSize?: FontSize;
+            iconColor?: string;
+            title?: string;
+            showCloseButton?: boolean;
+            showSizeToggle?: boolean;
+            padding?: string;
+            /**
+             * Header bottom border shorthand
+             * Set to "none" to remove border entirely
+             * @example "1px solid #e5e7eb"
+             * @example "none"
+             */
+            border?: string;
+            /**
+             * Header bottom border color
+             * @example "#e5e7eb"
+             * @example "transparent"
+             */
+            borderColor?: string;
+            /**
+             * Header bottom border width
+             * @default "1px"
+             * @example "2px"
+             * @example "0"
+             */
+            borderWidth?: string;
+        };
+    };
+    bubbles?: {
+        defaultMaxWidth?: string;
+        /**
+         * Default avatar styling for all message bubbles
+         * Can be overridden by role-specific avatar configs
+         */
+        defaultAvatar?: AvatarConfig;
+        user?: {
+            backgroundColor?: string;
+            backgroundColorHover?: string;
+            enableHoverEffect?: boolean;
+            textColor?: string;
+            fontFamily?: string;
+            /**
+             * Font size for user message text
+             * @example "base"
+             * @example "15px"
+             * @default undefined (inherits base font size)
+             */
+            fontSize?: FontSize;
+            borderRadius?: string;
+            border?: string;
+            borderWidth?: string;
+            borderColor?: string;
+            borderStyle?: string;
+            alignment?: "left" | "right";
+            maxWidth?: string;
+            padding?: string;
+        };
+        assistant?: {
+            backgroundColor?: string;
+            backgroundColorHover?: string;
+            enableHoverEffect?: boolean;
+            textColor?: string;
+            fontFamily?: string;
+            /**
+             * Font size for assistant message text
+             * @example "base"
+             * @example "15px"
+             * @default undefined (inherits base font size)
+             */
+            fontSize?: FontSize;
+            borderRadius?: string;
+            border?: string;
+            borderWidth?: string;
+            borderColor?: string;
+            borderStyle?: string;
+            /**
+             * @deprecated Use `avatar.enabled` instead
+             */
+            showAvatar?: boolean;
+            /**
+             * @deprecated Use `avatar.url` instead
+             */
+            avatarUrl?: string;
+            avatar?: AvatarConfig;
+            maxWidth?: string;
+            padding?: string;
+        };
+        agent?: {
+            backgroundColor?: string;
+            backgroundColorHover?: string;
+            enableHoverEffect?: boolean;
+            textColor?: string;
+            fontFamily?: string;
+            /**
+             * Font size for agent message text
+             * @example "base"
+             * @example "15px"
+             * @default undefined (inherits base font size)
+             */
+            fontSize?: FontSize;
+            borderRadius?: string;
+            border?: string;
+            borderWidth?: string;
+            borderColor?: string;
+            borderStyle?: string;
+            /**
+             * @deprecated Use `avatar.enabled` instead
+             */
+            showAvatar?: boolean;
+            /**
+             * @deprecated Use `avatar.url` instead
+             */
+            avatarUrl?: string;
+            avatar?: AvatarConfig;
+            showAgentBadge?: boolean;
+            badgeText?: string;
+            badgeColor?: string;
+            maxWidth?: string;
+            padding?: string;
+        };
+        spacing?: string;
+        animation?: "fade" | "slide" | "none";
+        showTimestamps?: boolean;
+    };
+    input?: InputConfig;
+    messages?: {
+        welcomeMessage?: string;
+        welcomeMessageDisplay?: "static" | "bubble";
+        welcomeMessageShowAvatar?: boolean;
+        welcomeMessagePersistent?: boolean;
+        welcomeActions?: ActionsConfig;
+        errorMessage?: string;
+        offlineMessage?: string;
+        typingIndicatorText?: string;
+        loadingAnimation?: "dots" | "pulse" | "typing";
+        loadingAnimationColor?: string;
+        /**
+         * Link styling configuration
+         * Applies to all links in markdown content across all message types
+         */
+        links?: LinkConfig;
+        /**
+         * Markdown rendering configuration
+         */
+        markdown?: {
+            /**
+             * Apply semantic typography sizes to markdown elements (headings, code)
+             * When true: h1 uses xl, h2 uses lg, h3 uses base, h4-h6 use sm, code uses sm
+             * When false: all elements inherit the bubble's fontSize configuration
+             * @default false
+             */
+            applyTypographySizes?: boolean;
+        };
+        /**
+         * Whether to automatically scroll to the bottom when new messages are added.
+         * Useful to disable on demo pages with multiple widgets to prevent unexpected scrolling.
+         * @default true
+         */
+        autoscroll?: boolean;
+    };
+    disclaimer?: {
+        content?: string;
+        contentFormat?: "markdown" | "html" | "text";
+        /**
+         * Display mode for the disclaimer.
+         * - "footer": Fixed at bottom of widget (default, current behavior)
+         * - "modal": Blocking overlay requiring acceptance (when required: true)
+         * - "event": Scrollable event at top of message stream
+         * @default "footer"
+         */
+        displayMode?: "footer" | "modal" | "event";
+        collapsible?: boolean;
+        defaultExpanded?: boolean;
+        backgroundColor?: string;
+        textColor?: string;
+        borderColor?: string;
+        acceptButton?: boolean;
+        acceptButtonText?: string;
+        /**
+         * When true, displays a blocking modal that requires acceptance before interaction.
+         * Acceptance is persisted per-experience in localStorage.
+         * @default false
+         */
+        required?: boolean;
+        /**
+         * Title displayed at the top of the blocking modal.
+         * Only applies when required is true.
+         * @default "Disclaimer"
+         */
+        requiredTitle?: string;
+        /**
+         * Text for the accept button in the blocking modal.
+         * Only applies when required is true.
+         * @default "I Accept"
+         */
+        requiredAcceptButtonText?: string;
+        /**
+         * When displayMode is "event" and this is true, input is disabled
+         * until the disclaimer is accepted. Similar to required modal but inline.
+         * @default false
+         */
+        eventRequiresAcceptance?: boolean;
+    };
+    branding?: {
+        show?: boolean;
+        text?: string;
+        logoUrl?: string;
+        position?: "header" | "footer";
+    };
+    features?: {
+        voice?: VoiceConfig;
+        tts?: TTSConfig;
+        /**
+         * Not yet implemented
+         * @internal
+         */
+        fileUpload?: boolean;
+        emoji?: boolean;
+        copyButton?: CopyButtonConfig;
+        feedback?: FeedbackConfig;
+        format?: "markdown" | "html" | "text";
+        /**
+         * Clear Conversation menu option configuration
+         */
+        clearConversation?: {
+            /**
+             * Whether to show the "Clear Conversation" menu option
+             * @default true
+             */
+            enabled?: boolean;
+            /**
+             * Custom label text for the menu option
+             * @default "Clear Conversation"
+             */
+            label?: string;
+        };
+    };
+    events?: {
+        /**
+         * Default styling configuration for all events
+         * Can be overridden by individual event type configurations
+         */
+        default?: EventStylingConfig;
+        sessionStart?: EventStylingConfig & {
+            enabled?: boolean;
+            showBadge?: boolean;
+            showTimestamp?: boolean;
+            layout?: "vertical" | "horizontal";
+            message?: string;
+            messageFormat?: "markdown" | "html" | "text";
+            badgeColor?: string;
+            badgeTextColor?: string;
+            badgeText?: string;
+            iconColor?: string;
+        };
+        sessionEnd?: EventStylingConfig & {
+            enabled?: boolean;
+            showBadge?: boolean;
+            showTimestamp?: boolean;
+            showDuration?: boolean;
+            layout?: "vertical" | "horizontal";
+            message?: string;
+            messageFormat?: "markdown" | "html" | "text";
+            badgeColor?: string;
+            badgeTextColor?: string;
+            iconColor?: string;
+        };
+        agentHandover?: EventStylingConfig & {
+            enabled?: boolean;
+            showCard?: boolean;
+            /**
+             * @deprecated Use `avatar.enabled` instead
+             */
+            showAvatar?: boolean;
+            showTimestamp?: boolean;
+            layout?: "vertical" | "horizontal";
+            message?: string;
+            messageFormat?: "markdown" | "html" | "text";
+            cardBackgroundColor?: string;
+            cardBorderColor?: string;
+            cardTextColor?: string;
+            /**
+             * Avatar styling for agent handover events
+             * Overrides events.default.avatar if specified
+             */
+            avatar?: AvatarConfig;
+        };
+        typing?: {
+            enabled?: boolean;
+            text?: string;
+        };
+        system?: {
+            enabled?: boolean;
+            showIcon?: boolean;
+        };
+        disclaimer?: {
+            enabled?: boolean;
+            showIcon?: boolean;
+            iconColor?: string;
+            backgroundColor?: string;
+            textColor?: string;
+            borderColor?: string;
+            borderRadius?: string;
+            padding?: string;
+            fontSize?: string;
+            acceptButtonBackgroundColor?: string;
+            acceptButtonTextColor?: string;
+            acceptButtonBorderRadius?: string;
+            acceptButtonPadding?: string;
+            acceptButtonFontSize?: string;
+            showAcknowledged?: boolean;
+            acknowledgedText?: string;
+            acknowledgedTextColor?: string;
+        };
+    };
+    /**
+     * Scrollbar styling configuration for the message container.
+     * Allows customization of scrollbar appearance (width, colors, border-radius)
+     * and auto-hide behavior.
+     *
+     * When not provided, browser default scrollbar is used.
+     *
+     * @example
+     * ```typescript
+     * scrollbar: {
+     *   width: "8px",
+     *   thumbColor: "#888",
+     *   trackColor: "#f1f1f1",
+     *   autoHide: true
+     * }
+     * ```
+     */
+    scrollbar?: ScrollbarConfig;
+    advanced?: {
+        widgetId?: string;
+        /**
+         * Optional user identifier to associate with the session.
+         * Accepts flexible formats: UUID, email address, numeric ID, or custom string (max 255 characters).
+         * Normalized to lowercase for storage and comparison.
+         * @example "user@example.com", "550e8400-e29b-41d4-a716-446655440000", "customer-123"
+         */
+        userId?: string;
+        /**
+         * Optional session ID to initialize the widget with an existing session.
+         * Must be a valid UUID v4 format.
+         * Use this to resume a session across page reloads or coordinate multiple widgets.
+         * @example "550e8400-e29b-41d4-a716-446655440000"
+         */
+        sessionId?: string;
+        metadata?: Record<string, any>;
+        readOnly?: boolean;
+        initialEvents?: ChatEvent[];
+        /**
+         * not used or implemented
+         * @internal
+         */
+        maxMessageLength?: number;
+        persistStore?: boolean;
+        storeKey?: string;
+        /**
+         * Message interceptor function for custom routing
+         * Called before each message is sent to Nexus backend
+         */
+        messageInterceptor?: MessageInterceptor;
+        /**
+         * Timeout for message interceptor in milliseconds
+         * @default 30000 (30 seconds)
+         */
+        interceptorTimeout?: number;
+        /**
+         * Timeout for all message operations (including backend requests) in milliseconds
+         * @default 60000 (60 seconds)
+         */
+        messageTimeout?: number;
+    };
+}
+export type EventKind = "message" | "session_start" | "agent_handover" | "session_end" | "typing" | "system" | "disclaimer";
+export interface BaseEvent {
+    id: string;
+    kind: EventKind;
+    timestamp: Date;
+    metadata?: Record<string, any>;
+}
+export interface MessageEvent extends BaseEvent {
+    kind: "message";
+    role: "user" | "assistant" | "agent";
+    content: string;
+    format?: "markdown" | "html" | "text";
+    isStreaming?: boolean;
+    feedback?: {
+        value: string | number;
+        comment?: string;
+        timestamp?: Date;
+    };
+    metadata?: {
+        citations?: Array<{
+            content_id: string;
+            title: string;
+            url?: string;
+            excerpt: string;
+        }>;
+        intent?: string;
+        confidence?: number;
+        actions?: ActionsConfig;
+        actionStates?: ActionState[];
+        confirmationMessage?: string;
+        confirmationMessageFormat?: "markdown" | "html" | "text";
+        confirmationMessageAlignment?: "left" | "center" | "right";
+        confirmationMessageColor?: string;
+        confirmationIcon?: ActionIcon;
+        showConfirmationIcon?: boolean;
+        isWelcomeBubble?: boolean;
+        isPersistentWelcome?: boolean;
+    };
+}
+export interface SessionStartEvent extends BaseEvent {
+    kind: "session_start";
+    sessionId: string;
+    message?: string;
+    metadata?: {
+        userId?: string;
+        source?: string;
+        initialContext?: Record<string, any>;
+    };
+}
+export interface AgentHandoverEvent extends BaseEvent {
+    kind: "agent_handover";
+    agentInfo?: {
+        id?: string;
+        name?: string;
+        avatarUrl?: string;
+    };
+    reason?: string;
+    message?: string;
+}
+export interface SessionEndEvent extends BaseEvent {
+    kind: "session_end";
+    reason?: "user_initiated" | "agent_initiated" | "timeout" | "error";
+    message?: string;
+    metadata?: {
+        duration?: number;
+        messageCount?: number;
+        resolved?: boolean;
+    };
+}
+export interface TypingEvent extends BaseEvent {
+    kind: "typing";
+    role: "user" | "assistant" | "agent";
+    isTyping: boolean;
+}
+export interface SystemEvent extends BaseEvent {
+    kind: "system";
+    type: "info" | "warning" | "error" | "success";
+    message: string;
+    details?: any;
+}
+export interface DisclaimerEvent extends BaseEvent {
+    kind: "disclaimer";
+    content: string;
+    contentFormat?: "markdown" | "html" | "text";
+    metadata?: {
+        isPersistentDisclaimer: true;
+        requiresAcceptance?: boolean;
+        accepted?: boolean;
+        acceptedAt?: string;
+        acceptButtonText?: string;
+    };
+}
+export type ChatEvent = MessageEvent | SessionStartEvent | AgentHandoverEvent | SessionEndEvent | TypingEvent | SystemEvent | DisclaimerEvent;
+export interface ChatSession {
+    id: string;
+    experienceId: string;
+    events: ChatEvent[];
+    createdAt: Date;
+    lastMessageAt: Date;
+}
+/**
+ * Context provided to message interceptor with access to widget state
+ */
+export interface MessageInterceptorContext {
+    /** Current session ID (null if no session started yet) */
+    sessionId: string | null;
+    /** Experience ID from widget config */
+    experienceId: string;
+    /** Optional user ID from widget config */
+    userId?: string;
+    /** Direct access to chat store for reading/writing state */
+    store: ChatStore;
+    /** Optional metadata from widget config */
+    metadata?: Record<string, any>;
+    /** Whether the message is being sent during an agent handover */
+    inAgentHandover: boolean;
+}
+/**
+ * Message object passed to interceptor
+ */
+export interface InterceptorMessage {
+    /** Message text content */
+    text: string;
+    /** Timestamp when message was created */
+    timestamp: Date;
+    /** Turn index */
+    turnIndex: number;
+}
+export interface InterceptorPassthroughMessage {
+    /** Message text content */
+    text: string;
+    /** Optional metadata to include with message */
+    metadata?: Record<string, any>;
+}
+/**
+ * Assistant/agent message returned by interceptor
+ */
+export interface InterceptorAssistantMessage {
+    /** Response text to display */
+    text: string;
+    /** Message role (assistant or agent) */
+    role: "assistant" | "agent";
+    /** Optional metadata (citations, confidence, etc.) */
+    metadata?: Record<string, any>;
+    /** Optional format override */
+    format?: "markdown" | "html" | "text";
+    /** NEW: Interceptor can provide actions */
+    actions?: ActionsConfig;
+}
+/**
+ * Result returned by interceptor to control message flow
+ */
+export type MessageInterceptorResult = {
+    /** Interceptor handled the message completely */
+    handled: true;
+    /** Custom response to display in widget */
+    response: InterceptorAssistantMessage;
+} | {
+    /** Interceptor handled the message but encountered error */
+    handled: true;
+    /** Error message to display, or true to use config.messages?.errorMessage */
+    error: string | true;
+    /** Optional format for error message */
+    format?: "markdown" | "html" | "text";
+} | {
+    /** Interceptor modified message, continue with default Nexus routing */
+    handled: false;
+    /** Modified message to send to Nexus (optional) */
+    message?: InterceptorPassthroughMessage;
+};
+/**
+ * Message interceptor function type
+ *
+ * Called before every message is sent to Nexus backend.
+ * Can intercept and handle messages, modify them, or let them pass through.
+ *
+ * @param message - The message about to be sent
+ * @param context - Context with session ID, store access, etc.
+ * @returns Result indicating how to handle the message, or null/undefined to use default
+ */
+export type MessageInterceptor = (message: InterceptorMessage, context: MessageInterceptorContext) => Promise<MessageInterceptorResult | null | undefined>;
+/**
+ * Return type of the initWidget function
+ */
+export interface WidgetAPI {
+    destroy: () => void;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    clearChat: () => void;
+    /**
+     * Start a new session, optionally with a specific session ID
+     * @param sessionId - Optional UUID v4 to use for the new session. If not provided, generates a new UUID.
+     * @returns The sessionId of the newly created session
+     * @throws Error if sessionId is provided but not a valid UUID
+     */
+    startNewSession: (sessionId?: string) => string;
+    updateAccessToken: (token: string | undefined) => void;
+    store: ChatStore;
+    on: <T extends WidgetEventName>(eventName: T, callback: WidgetEventListener<T>) => void;
+    once: <T extends WidgetEventName>(eventName: T, callback: WidgetEventListener<T>) => void;
+    off: <T extends WidgetEventName>(eventName: T, callback: WidgetEventListener<T>) => void;
+    removeAllListeners: (eventName?: WidgetEventName) => void;
+}
+/**
+ * Event names that can be emitted by the widget
+ */
+export type WidgetEventName = "open" | "close" | "minimize" | "maximize" | "sessionStart" | "sessionEnd" | "sessionClear" | "messageStart" | "messageComplete" | "messageChunk" | "typing" | "typingStop" | "feedback" | "copy" | "actionClick" | "handover" | "customAction" | "sendQuery" | "disclaimerAccept" | "voiceStart" | "voiceEnd" | "ttsStart" | "ttsEnd" | "error";
+/**
+ * Base interface for all widget events
+ */
+export interface WidgetEventBase {
+    timestamp: string;
+    sessionId?: string | null;
+}
+/**
+ * Event data structures for each event type
+ */
+export interface WidgetEventData {
+    open: WidgetEventBase;
+    close: WidgetEventBase;
+    minimize: WidgetEventBase & {
+        previousMode: string;
+    };
+    maximize: WidgetEventBase & {
+        previousMode: string;
+    };
+    sessionStart: WidgetEventBase & {
+        sessionId: string;
+    };
+    sessionEnd: WidgetEventBase & {
+        sessionId: string;
+        duration?: number;
+        messageCount?: number;
+    };
+    sessionClear: WidgetEventBase & {
+        messageCount?: number;
+    };
+    messageStart: WidgetEventBase & {
+        message: string;
+    };
+    messageComplete: WidgetEventBase & {
+        queryId?: string;
+        answer: string;
+        duration?: number;
+    };
+    messageChunk: WidgetEventBase & {
+        text: string;
+        complete: boolean;
+    };
+    typing: WidgetEventBase & {
+        text: string;
+        length: number;
+    };
+    typingStop: WidgetEventBase;
+    feedback: WidgetEventBase & {
+        rating: string | number;
+        queryId?: string;
+        messageId: string;
+        comment?: string;
+    };
+    copy: WidgetEventBase & {
+        content: string;
+        messageId: string;
+    };
+    actionClick: WidgetEventBase & {
+        messageId: string;
+        actionId: string;
+        actionType: string;
+        actionLabel: string;
+    };
+    handover: WidgetEventBase & {
+        reason: string;
+        priority: "low" | "normal" | "high";
+        metadata?: Record<string, unknown>;
+    };
+    customAction: WidgetEventBase & {
+        actionId: string;
+        eventName: string;
+        eventData: Record<string, unknown>;
+    };
+    sendQuery: WidgetEventBase & {
+        actionId: string;
+        queryText: string;
+        displayText?: string;
+    };
+    disclaimerAccept: WidgetEventBase & {
+        experienceId: string;
+    };
+    voiceStart: WidgetEventBase & {
+        language?: string;
+    };
+    voiceEnd: WidgetEventBase & {
+        transcript?: string;
+        duration?: number;
+    };
+    ttsStart: WidgetEventBase & {
+        text: string;
+        messageId: string;
+    };
+    ttsEnd: WidgetEventBase & {
+        messageId: string;
+        duration?: number;
+    };
+    error: WidgetEventBase & {
+        type: string;
+        message: string;
+        stack?: string;
+        details?: any;
+    };
+}
+/**
+ * Event listener callback type
+ */
+export type WidgetEventListener<T extends WidgetEventName> = (data: WidgetEventData[T]) => void;
+/**
+ * Generic event listener (for wildcard listeners if implemented)
+ */
+export type GenericEventListener = (eventName: WidgetEventName, data: WidgetEventData[WidgetEventName]) => void;
+export type ActionType = "trigger_handover" | "open_url" | "send_event" | "send_query";
+export type ActionIconType = "svg" | "url" | "emoji";
+export interface ActionIcon {
+    type: ActionIconType;
+    content: string;
+}
+export interface ActionStyle {
+    size?: "small" | "medium" | "large";
+    backgroundColor?: string;
+    disabledBackgroundColor?: string;
+    iconColor?: string;
+    textColor?: string;
+    hoverBackgroundColor?: string;
+    borderRadius?: string;
+    /**
+     * Action button border (shorthand)
+     * @example "2px solid #e5e7eb"
+     */
+    border?: string;
+    /**
+     * Action button border width (granular)
+     * @example "2px"
+     */
+    borderWidth?: string;
+    /**
+     * Action button border color (granular)
+     * @example "#10b981"
+     */
+    borderColor?: string;
+    /**
+     * Action button border style (granular)
+     * @example "solid", "dashed", "dotted"
+     */
+    borderStyle?: string;
+}
+export interface ActionBehavior {
+    oneTimeUse?: boolean;
+    disableAllOnClick?: boolean;
+    expiresAfterTurns?: number;
+    disabled?: boolean;
+    disabledReason?: string;
+    postClickBehavior?: PostClickBehavior;
+}
+/**
+ * Configuration for action button post-click behavior
+ */
+export interface PostClickBehavior {
+    /** Remove all action buttons after this action is clicked */
+    removeOnClick?: boolean;
+    /** Confirmation message to display after action click */
+    confirmationMessage?: string;
+    /** Format of the confirmation message (default: "markdown") */
+    confirmationMessageFormat?: "markdown" | "html" | "text";
+    /** Alignment of confirmation message (default: "center") */
+    confirmationMessageAlignment?: "left" | "center" | "right";
+    /** Text color for confirmation message (CSS color value) */
+    confirmationMessageColor?: string;
+    /** Icon to display with confirmation message */
+    confirmationIcon?: ActionIcon;
+    /** Whether to show the icon (default: true if confirmationIcon provided) */
+    showIcon?: boolean;
+    /** Show a system event in the chat history (default: false) */
+    showSystemEvent?: boolean;
+    /** Custom message for the system event (defaults to action-specific message) */
+    systemEventMessage?: string;
+    /** Type of system event to show (default: "info") */
+    systemEventType?: "info" | "success" | "warning" | "error";
+}
+/**
+ * Default green checkmark icon for confirmation messages
+ */
+export declare const DEFAULT_CONFIRMATION_ICON: ActionIcon;
+export interface ActionVisibility {
+    showLabel?: boolean;
+    showIcon?: boolean;
+    showTooltip?: boolean;
+    tooltipText?: string;
+}
+export interface TriggerHandoverAction {
+    type: "trigger_handover";
+    payload?: {
+        reason?: string;
+        priority?: "low" | "normal" | "high";
+        metadata?: Record<string, unknown>;
+        message?: string;
+    };
+}
+export interface OpenUrlAction {
+    type: "open_url";
+    url: string;
+    target?: "_blank" | "_self" | "_parent" | "_top";
+}
+export interface SendEventAction {
+    type: "send_event";
+    eventName: string;
+    eventData?: Record<string, unknown>;
+}
+export interface SendQueryAction {
+    type: "send_query";
+    queryText: string;
+    displayText?: string;
+}
+export type ActionDefinition = TriggerHandoverAction | OpenUrlAction | SendEventAction | SendQueryAction;
+export interface ActionConfig {
+    id: string;
+    label: string;
+    icon?: ActionIcon;
+    action: ActionDefinition;
+    style?: ActionStyle;
+    behavior?: ActionBehavior;
+    visibility?: ActionVisibility;
+}
+export type ActionAlignment = "left" | "center" | "right";
+export interface ActionsConfig {
+    position?: "bottom";
+    alignment?: ActionAlignment;
+    spacing?: string;
+    actions: ActionConfig[];
+}
+export interface ActionState {
+    actionId: string;
+    messageId: string;
+    disabled: boolean;
+    disabledReason?: "used" | "expired" | "outdated" | "manual";
+    loading?: boolean;
+    error?: string;
+    usedAt?: Date;
+}
+/**
+ * Global NexusChatWidget object available on window
+ */
+export interface NexusChatWidgetGlobal {
+    init: (config: WidgetConfig) => WidgetAPI;
+    storeManager: {
+        getStore: (key: string) => ChatStore;
+        hasStore: (key: string) => boolean;
+        clearStore: (key: string) => void;
+        clearAllStores: () => void;
+    };
+}
+/**
+ * Global window interface extensions for NexusChatWidget
+ */
+declare global {
+    interface Window {
+        NexusChatWidget?: NexusChatWidgetGlobal;
+        "nexus-chat"?: (action: string, config: WidgetConfig) => void;
+    }
+}
+//# sourceMappingURL=index.d.ts.map