@nimbusai/webchat-sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,406 @@
+type ChatPosition = "bottom-right" | "bottom-left" | "sidepanel-left" | "sidepanel-right";
+type BubblePosition = "bottom-right" | "bottom-left";
+/** Reusable text configuration used throughout the SDK. */
+interface TextConfig {
+    /** Whether to display this text element. Not used everywhere. */
+    display?: boolean;
+    /** The text value / content. */
+    value?: string;
+    /** Text color (CSS color string). */
+    color?: string;
+    /** Font family override. */
+    font?: string;
+    /** Font size in px. */
+    size?: number;
+}
+/** Unified text element with value and nested styling */
+interface TextElement {
+    /** The text value / content. */
+    value?: string;
+    /** Text styling configuration */
+    text?: TextConfig;
+}
+/** Reusable color pair configuration for primary/secondary colors */
+interface ColorPair {
+    /** Primary color (usually background or main color) */
+    primary?: string;
+    /** Secondary color (usually foreground or accent color) */
+    secondary?: string;
+}
+/**
+ * Icon configuration used throughout the SDK.
+ * Pass `null` to explicitly hide an icon.
+ */
+interface IconConfig {
+    /** Image URL for the icon. */
+    img?: string;
+    /** Size of the icon with width and height in pixels. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /** Icon stroke/fill color (CSS color string). Only applies to Lucide icons, ignored for image URLs. */
+    color?: string;
+}
+interface ThemeConfig {
+    /** Primary theme color — send button bg, header bg, bubble bg. */
+    primary: string;
+    /** Secondary theme color — send button icon, header text, bubble icon. */
+    secondary: string;
+}
+interface HeaderConfig {
+    /** Icon configuration for the header. Not shown if omitted/null. */
+    icon?: IconConfig | null;
+    /** Header text configuration. */
+    text?: TextConfig;
+    /** Header color configuration (primary = background, secondary = close icon). */
+    color?: ColorPair;
+}
+interface WelcomeConfig {
+    /** Whether to display the welcome message. Default: true */
+    display?: boolean;
+    /** Pre-title text (e.g. "Welcome to "). */
+    preTitle?: TextElement | TextConfig;
+    /** Title text (e.g. "Nimbus"). */
+    title?: TextElement | TextConfig;
+    /** Subtitle text (e.g. "Send a message to start a conversation"). */
+    subtitle?: TextElement | TextConfig;
+}
+interface MessageConfig {
+    /** Bubble background color. */
+    background?: string;
+    /** Width of the message bubble (e.g. "90%", "300px"). Default: "70%" */
+    width?: string;
+    /** Text configuration for the message. */
+    text?: TextConfig;
+    /** Avatar icon configuration. Pass null to hide, omit to not show. */
+    icon?: IconConfig | null;
+}
+interface TypingIndicatorConfig {
+    /** Where to display the indicator: "top" = header status area, "bottom" = above input. Default: "top" */
+    position?: "top" | "bottom";
+    /** Title configuration for typing indicator */
+    title?: {
+        value?: string;
+        text?: TextConfig;
+    };
+}
+interface WaitForReplyConfig {
+    /** Timeout in milliseconds. Default: 10000 (10 seconds) */
+    timeout?: number;
+    /** Wait for bot's first message before allowing user to type in new conversation. Default: false */
+    firstReply?: boolean;
+}
+interface MobileConfig {
+    /** Widget position on mobile devices. If not set, uses the regular position. */
+    position?: ChatPosition;
+    /** Viewport width breakpoint to consider as mobile (e.g. "480px"). If set, overrides user-agent detection. */
+    breakpoint?: string;
+}
+interface StyleConfig {
+    /** Width of the chat window/sidepanel (e.g. "380px", "100%"). Default: "380px" */
+    width?: string;
+    /** Height of the chat window (e.g. "560px", "100%"). Only applies to window mode. Default: "560px" */
+    height?: string;
+    /** Widget position on the page. Default: "bottom-right" */
+    position?: ChatPosition;
+    /** Mobile-specific overrides */
+    mobile?: MobileConfig;
+    /** Global font family for the entire chat widget. No default (uses system font). */
+    font?: string;
+    /** Chat body background — can be a CSS color or an image URL. Default: "#ffffff" */
+    background?: string;
+}
+interface ReconnectConfig {
+    /** Maximum number of reconnection attempts. Default: 5 */
+    attempts?: number;
+    /** Delay between reconnection attempts in ms. Default: 5000 (5 seconds) */
+    timeout?: number;
+}
+interface ShowMoreConfig {
+    /** Button text. Default: "Show More" */
+    value?: string;
+    /** Whether button should be sticky at top. Default: true */
+    sticky?: boolean;
+    /** Button background color. Default: theme.secondary */
+    background?: string;
+    /** Text styling for the button */
+    text?: TextConfig;
+    /** Icon configuration for the button */
+    icon?: IconConfig;
+}
+interface UploadConfig {
+    /** Maximum file size in bytes. Default: 5MB */
+    maxFileSize?: number;
+    /** Array of allowed MIME types. */
+    allowedFileTypes?: string[];
+    /** Icon configuration for the upload button. */
+    icon?: IconConfig | null;
+    /** Duration in milliseconds for error message display. Default: 2000 */
+    errorDisplayDuration?: number;
+}
+interface MaxCharactersConfig {
+    /** Maximum number of characters allowed. If null/undefined, unlimited */
+    limit: number;
+    /** Text styling configuration */
+    text?: TextConfig;
+}
+interface InputConfig {
+    /** Placeholder text for the input. Default: "Ask Nimbus" */
+    placeholder?: string;
+    /** If true, the input expands to a textarea. Default: false */
+    expandable?: boolean;
+    /** Text styling for the input field. */
+    text?: TextConfig;
+    /** Background colors for the input (primary = input area, secondary = container). */
+    background?: ColorPair;
+    /** File upload configuration */
+    upload?: UploadConfig;
+    /** Character limit configuration with counter display */
+    maxCharacters?: MaxCharactersConfig;
+}
+interface SendButtonConfig {
+    /** Custom icon configuration. Pass null to hide, omit for default. */
+    icon?: IconConfig | null;
+    /** If true, align input and send button horizontally on the same row. Default: false */
+    align?: boolean;
+}
+interface ErrorButtonConfig {
+    /** Background color of the button */
+    background?: string;
+    /** Text configuration for the button */
+    text?: TextConfig;
+    /** Icon configuration for the button. Pass null to hide. */
+    icon?: IconConfig | null;
+}
+interface ErrorStyleConfig {
+    /** Background color for the error message */
+    background?: string;
+    /** Title configuration for the error message. Pass null to use default. */
+    title?: TextElement | null;
+    /** Subtitle configuration for the error message. Pass null to use default. */
+    subtitle?: TextElement | null;
+    /** Button configuration for the error */
+    button?: ErrorButtonConfig;
+}
+interface ErrorConfig {
+    /** Styling for inactivity timeout errors */
+    inactivity?: ErrorStyleConfig;
+    /** Styling for session conflict errors */
+    conflict?: ErrorStyleConfig;
+    /** Styling for session TTL expiration errors */
+    session_ttl?: ErrorStyleConfig;
+    /** Styling for unauthorized access errors */
+    unauthorized?: ErrorStyleConfig;
+}
+interface BubbleConfig {
+    /** Position of the floating bubble. Default: "bottom-right" */
+    position?: BubblePosition;
+    /** If true, hide the bubble when the chat panel is open. Default: false */
+    autoHide?: boolean;
+    /** Custom icon configuration. Pass null to hide custom, omit for default. */
+    icon?: IconConfig | null;
+}
+interface NimbusChatConfig {
+    /** Required — the agent ID (UUID) for this chat instance */
+    agent_id: string;
+    /** DNS endpoint for chat services. Default: "api.nimbus.ai/api/v1/webchat" */
+    dns?: string;
+    /** Whether to resume previous conversation on reconnect. Default: false */
+    resumeConversation?: boolean;
+    /** Style configuration (position, dimensions, font, background, mobile) */
+    style?: StyleConfig;
+    /** Number of messages to load per page. Default: 10 */
+    messagesPerPage?: number;
+    /** Bubble configuration (position, autoHide, icon) */
+    bubble?: BubbleConfig;
+    /** Theme colors (primary, secondary) */
+    theme?: Partial<ThemeConfig>;
+    /** User message styling */
+    userMessage?: MessageConfig;
+    /** Bot message styling */
+    botMessage?: MessageConfig;
+    /** Header configuration (icon, text, color) */
+    header?: HeaderConfig;
+    /** Input field configuration */
+    input?: InputConfig;
+    /** Send button configuration */
+    sendButton?: SendButtonConfig;
+    /** Welcome message configuration shown when chat is empty. */
+    welcome?: WelcomeConfig;
+    /** Error styling configuration for conflict and inactivity errors */
+    error?: ErrorConfig;
+    /** Enable debug logging to console. Default: false */
+    debug?: boolean;
+    /** Reconnection configuration for unexpected disconnections */
+    reconnect?: ReconnectConfig;
+    /** Show new chat button in header. Default: false */
+    allowNewChat?: boolean;
+    /** Wait for bot reply before allowing next user message */
+    waitForReply?: WaitForReplyConfig;
+    /** Typing indicator configuration. Independent from waitForReply. */
+    isTypingIndicator?: TypingIndicatorConfig;
+    /** Show More button styling */
+    showMore?: ShowMoreConfig;
+}
+interface ResolvedConfig {
+    agent_id: string;
+    dns: string;
+    resumeConversation: boolean;
+    style: {
+        position: ChatPosition;
+        mobile?: {
+            position?: ChatPosition;
+            breakpoint?: string;
+        };
+        width: string;
+        height: string;
+        font?: string;
+        background: string;
+    };
+    messagesPerPage: number;
+    bubble: Required<Pick<BubbleConfig, "position" | "autoHide">> & Pick<BubbleConfig, "icon">;
+    theme: ThemeConfig;
+    userMessage: {
+        background: string;
+        width: string;
+        text: TextConfig;
+        icon?: IconConfig | null;
+    };
+    botMessage: {
+        background: string;
+        width: string;
+        text: TextConfig;
+        icon?: IconConfig | null;
+    };
+    header: HeaderConfig;
+    input: {
+        placeholder: string;
+        expandable: boolean;
+        text?: TextConfig;
+        background?: ColorPair;
+        upload?: UploadConfig;
+        maxCharacters?: MaxCharactersConfig;
+    };
+    sendButton: Required<Pick<SendButtonConfig, "align">> & Pick<SendButtonConfig, "icon">;
+    welcome: WelcomeConfig;
+    error: Required<ErrorConfig>;
+    debug: boolean;
+    reconnect: ReconnectConfig;
+    allowNewChat: boolean;
+    waitForReply?: WaitForReplyConfig;
+    isTypingIndicator?: TypingIndicatorConfig;
+    showMore: ShowMoreConfig;
+}
+/** Standard icon names used throughout the SDK */
+declare const ICON_NAMES: {
+    readonly MESSAGE_CIRCLE: "message-circle";
+    readonly SEND: "send";
+    readonly CLOSE: "x";
+    readonly NEW_CHAT: "rotate-cw";
+    readonly CHEVRON_DOWN: "chevron-down";
+    readonly PAPERCLIP: "paperclip";
+    readonly TYPE: "type";
+};
+/** Standard icon sizes used throughout the SDK */
+declare const ICON_SIZES: {
+    readonly BUTTON_SMALL: 16;
+    readonly BUTTON_MEDIUM: 18;
+    readonly AVATAR: 28;
+    readonly BUBBLE_OPEN: 26;
+};
+
+/**
+ * Main SDK orchestrator.
+ *
+ * Usage (npm):
+ *   const chat = new NimbusChat({ agent_id: "550e8400-e29b-41d4-a716-446655440000" });
+ *   chat.open();
+ *
+ * Usage (CDN):
+ *   NimbusChat.init({ agent_id: "550e8400-e29b-41d4-a716-446655440000" });
+ */
+declare class NimbusChat {
+    private config;
+    private eventBus;
+    private session;
+    private wsManager;
+    private apiClient;
+    private ui;
+    private logger;
+    private destroyed;
+    private messageLimit;
+    private hasMoreMessages;
+    private perf;
+    constructor(config: NimbusChatConfig);
+    private setupEventHandlers;
+    private handleServerEvent;
+    /** Show the chat widget */
+    open(): void;
+    /** Hide the chat widget */
+    close(): void;
+    /** Toggle chat visibility */
+    toggle(): void;
+    /**
+     * Completely remove the widget from the page and disconnect WebSocket.
+     * After calling destroy(), this instance cannot be reused.
+     */
+    destroy(): void;
+    private fetchAndDisplayHistory;
+}
+
+/** Message types supported by the protocol */
+type MessageType = "text" | "file" | "json";
+/** Message direction for history */
+type MessageDirection = "INBOUND" | "OUTBOUND";
+/** Message from server (simplified schema) */
+interface ServerMessage {
+    type: "message";
+    direction: "outbound";
+    content: string;
+}
+/** Base message interface */
+interface BaseUserMessage {
+    type: "message";
+}
+/** Text message sent by user (simplified schema) */
+interface TextUserMessage extends BaseUserMessage {
+    direction: "inbound";
+    content: string;
+}
+/** Union type for all user messages */
+type UserMessage = TextUserMessage;
+/** Chat message used throughout the app */
+interface ChatMessage {
+    id: string;
+    direction: MessageDirection;
+    message_type: MessageType;
+    content: string | object;
+    created_at: number;
+    filename?: string | null;
+    filetype?: string | null;
+    filesize?: number | null;
+    description?: string | null;
+}
+/** Connection states for the WebSocket */
+type ConnectionState = "idle" | "connecting" | "connected" | "disconnected";
+
+/**
+ * Initialize the NimbusChat widget (singleton pattern).
+ * Use this when loading via CDN <script> tag.
+ *
+ *   NimbusChat.init({ agent_id: "550e8400-e29b-41d4-a716-446655440000" });
+ */
+declare function init(config: NimbusChatConfig): NimbusChat;
+/**
+ * Get the existing singleton instance (or null if not initialized).
+ */
+declare function getInstance(): NimbusChat | null;
+
+declare const _default: {
+    NimbusChat: typeof NimbusChat;
+    init: typeof init;
+    getInstance: typeof getInstance;
+};
+
+export { type BubbleConfig, type BubblePosition, type ChatMessage, type ChatPosition, type ColorPair, type ConnectionState, type ErrorButtonConfig, type ErrorConfig, type ErrorStyleConfig, type HeaderConfig, ICON_NAMES, ICON_SIZES, type IconConfig, type InputConfig, type MessageConfig, type MessageType, NimbusChat, type NimbusChatConfig, type ResolvedConfig, type SendButtonConfig, type ServerMessage, type TextConfig, type TextElement, type ThemeConfig, type UserMessage, type WelcomeConfig, _default as default, getInstance, init };