@ingridsandev/chatbot-widget/index.d.ts

A framework-agnostic chatbot widget using Web Components

// Type definitions for chatbot-widget
// Project: chatbot-widget
// Definitions by: Your Organization

export interface ChatMessage {
  text: string;
  sender: 'user' | 'assistant' | 'system';
  timestamp: number;
  agent?: string;
  metadata?: Record<string, any>;
}

export interface ChatAgent {
  id: string;
  name: string;
  description?: string;
  avatar?: string;
  endpoint?: string;
}

export interface ChatbotConfig {
  apiEndpoint?: string;
  theme?: 'light' | 'dark' | 'auto' | 'custom';
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  primaryColor?: string;
  secondaryColor?: string;
  maxHeight?: string;
  placeholder?: string;
  welcomeMessage?: string;
  agents?: ChatAgent[];
  defaultAgent?: string;
  autoOpen?: boolean;
  persistChat?: boolean;
  persistPreferences?: boolean;
}

export interface ChatbotEventDetail {
  message?: ChatMessage;
  agent?: ChatAgent;
  error?: Error;
  config?: ChatbotConfig;
}

export interface ChatbotCustomEvent extends CustomEvent {
  detail: ChatbotEventDetail;
}

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'chatbot-widget': React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement> & {
          'api-endpoint'?: string;
          'theme'?: 'light' | 'dark' | 'auto' | 'custom';
          'position'?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
          'primary-color'?: string;
          'secondary-color'?: string;
          'max-height'?: string;
          'placeholder'?: string;
          'welcome-message'?: string;
          'agents'?: string;
          'default-agent'?: string;
          'auto-open'?: boolean;
          'persist-chat'?: boolean;
          'persist-preferences'?: boolean;
          'onmessageSend'?: (event: ChatbotCustomEvent) => void;
          'onmessageReceived'?: (event: ChatbotCustomEvent) => void;
          'onchatToggle'?: (event: ChatbotCustomEvent) => void;
          'onagentSwitch'?: (event: ChatbotCustomEvent) => void;
          'onerror'?: (event: ChatbotCustomEvent) => void;
        },
        HTMLElement
      >;
    }
  }

  interface HTMLElementTagNameMap {
    'chatbot-widget': ChatbotWidget;
  }

  interface HTMLElement {
    // Allow dynamic property access for custom elements
    [key: string]: any;
  }
}

export declare class ChatbotWidget extends HTMLElement {
  // Properties
  apiEndpoint: string;
  theme: 'light' | 'dark' | 'auto' | 'custom';
  position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  primaryColor: string;
  secondaryColor: string;
  maxHeight: string;
  placeholder: string;
  welcomeMessage: string;
  agents: ChatAgent[];
  defaultAgent: string;
  autoOpen: boolean;
  persistChat: boolean;
  persistPreferences: boolean;

  // Read-only properties
  readonly isOpen: boolean;

  // Methods
  sendMessage(message: string, agent?: string): Promise<void>;
  addMessage(message: ChatMessage): void;
  clearChat(): void;
  open(): void;
  close(): void;
  toggle(): void;
  setTheme(theme: 'light' | 'dark' | 'auto' | 'custom'): void;
  getMessages(): ChatMessage[];
  getCurrentAgent(): ChatAgent | null;
  setConfig(config: Partial<ChatbotConfig>): void;

  // Event listeners
  addEventListener(
    type: 'messageSend',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | AddEventListenerOptions
  ): void;
  addEventListener(
    type: 'messageReceived',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | AddEventListenerOptions
  ): void;
  addEventListener(
    type: 'chatToggle',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | AddEventListenerOptions
  ): void;
  addEventListener(
    type: 'agentSwitch',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | AddEventListenerOptions
  ): void;
  addEventListener(
    type: 'error',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | AddEventListenerOptions
  ): void;
  addEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | AddEventListenerOptions
  ): void;

  removeEventListener(
    type: 'messageSend',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | EventListenerOptions
  ): void;
  removeEventListener(
    type: 'messageReceived',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | EventListenerOptions
  ): void;
  removeEventListener(
    type: 'chatToggle',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | EventListenerOptions
  ): void;
  removeEventListener(
    type: 'agentSwitch',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | EventListenerOptions
  ): void;
  removeEventListener(
    type: 'error',
    listener: (event: ChatbotCustomEvent) => void,
    options?: boolean | EventListenerOptions
  ): void;
  removeEventListener(
    type: string,
    listener: EventListenerOrEventListenerObject,
    options?: boolean | EventListenerOptions
  ): void;
}

// Module declaration for importing the component
declare module '*/chatbot-widget.js' {
  export { ChatbotWidget };
}

declare module '@your-org/chatbot-widget' {
  export {
    ChatbotWidget,
    ChatMessage,
    ChatAgent,
    ChatbotConfig,
    ChatbotEventDetail,
    ChatbotCustomEvent
  };
}

// Augment the global Window interface for direct script inclusion
declare global {
  interface Window {
    ChatbotWidget: typeof ChatbotWidget;
  }
}