@ihoomanai/chat-widget 2.0.0

package/src/types.ts

@@ -0,0 +1,301 @@
+/**
+ * Type definitions for @ihooman/chat-widget
+ */
+
+/**
+ * Theme configuration for the widget appearance
+ */
+export interface ThemeConfig {
+  /** Primary brand color */
+  primaryColor?: string;
+  /** Gradient start color */
+  gradientFrom?: string;
+  /** Gradient end color */
+  gradientTo?: string;
+  /** Header background color */
+  headerBackground?: string;
+  /** Header text color */
+  headerTextColor?: string;
+  /** User message background */
+  userMessageBg?: string;
+  /** User message text color */
+  userMessageText?: string;
+  /** Bot message background */
+  botMessageBg?: string;
+  /** Bot message text color */
+  botMessageText?: string;
+  /** Font family */
+  fontFamily?: string;
+  /** Border radius for UI elements */
+  borderRadius?: string;
+}
+
+/**
+ * Behavior configuration for widget functionality
+ */
+export interface BehaviorConfig {
+  /** Whether to start with the widget open */
+  startOpen?: boolean;
+  /** Show typing indicator when bot is responding */
+  showTypingIndicator?: boolean;
+  /** Show timestamps on messages */
+  showTimestamps?: boolean;
+  /** Enable notification sounds */
+  enableSounds?: boolean;
+  /** Enable file upload functionality */
+  enableFileUpload?: boolean;
+  /** Persist chat session across page reloads */
+  persistSession?: boolean;
+}
+
+/**
+ * Branding configuration
+ */
+export interface BrandingConfig {
+  /** Custom logo URL */
+  logoUrl?: string | null;
+  /** Custom avatar URL for bot messages */
+  avatarUrl?: string | null;
+  /** Show "Powered by Ihooman" branding */
+  poweredBy?: boolean;
+}
+
+/**
+ * Main widget configuration options
+ */
+export interface WidgetConfig {
+  /** 
+   * Widget ID for initialization (required)
+   * Format: wgt_[12-alphanumeric-characters]
+   * Obtain from your Ihooman dashboard
+   */
+  widgetId: string;
+  
+  /** 
+   * Server URL for the widget API
+   * Defaults to production Ihooman API
+   */
+  serverUrl?: string;
+  
+  /** Widget color theme */
+  theme?: 'light' | 'dark';
+  
+  /** Widget position on the page */
+  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  
+  /** Widget title displayed in header */
+  title?: string;
+  
+  /** Subtitle displayed in header */
+  subtitle?: string;
+  
+  /** Welcome message shown when chat opens */
+  welcomeMessage?: string;
+  
+  /** Placeholder text for input field */
+  placeholder?: string;
+  
+  /** Primary brand color */
+  primaryColor?: string;
+  
+  /** Gradient start color */
+  gradientFrom?: string;
+  
+  /** Gradient end color */
+  gradientTo?: string;
+  
+  /** Show timestamps on messages */
+  showTimestamps?: boolean;
+  
+  /** Show typing indicator */
+  showTypingIndicator?: boolean;
+  
+  /** Enable notification sounds */
+  enableSounds?: boolean;
+  
+  /** Enable file upload */
+  enableFileUpload?: boolean;
+  
+  /** Start with widget open */
+  startOpen?: boolean;
+  
+  /** Persist session across page reloads */
+  persistSession?: boolean;
+  
+  /** Z-index for widget positioning */
+  zIndex?: number;
+  
+  /** Widget width in pixels */
+  width?: number;
+  
+  /** Widget height in pixels */
+  height?: number;
+  
+  /** Toggle button size in pixels */
+  buttonSize?: number;
+  
+  /** Border radius in pixels */
+  borderRadius?: number;
+  
+  /** Font family */
+  fontFamily?: string;
+  
+  /** Custom avatar URL */
+  avatarUrl?: string;
+  
+  /** Show powered by branding */
+  poweredBy?: boolean;
+  
+  /** Callback when widget is ready */
+  onReady?: () => void;
+  
+  /** Callback when widget opens */
+  onOpen?: () => void;
+  
+  /** Callback when widget closes */
+  onClose?: () => void;
+  
+  /** Callback when a message is sent or received */
+  onMessage?: (message: Message) => void;
+  
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * User information for personalization
+ */
+export interface UserInfo {
+  /** User's display name */
+  name?: string;
+  /** User's email address */
+  email?: string;
+  /** Additional metadata */
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Chat message structure
+ */
+export interface Message {
+  /** Unique message ID */
+  id: string;
+  /** Message content */
+  content: string;
+  /** Message sender type */
+  sender: 'user' | 'bot';
+  /** Message timestamp */
+  timestamp: Date;
+  /** Additional message metadata */
+  metadata?: {
+    /** Source documents for RAG responses */
+    sources?: Array<{
+      title: string;
+      url?: string;
+    }>;
+    /** Confidence score for AI responses */
+    confidence?: number;
+  };
+}
+
+/**
+ * Widget state information
+ */
+export interface WidgetState {
+  /** Whether the widget window is open */
+  isOpen: boolean;
+  /** Whether connected to the server */
+  isConnected: boolean;
+  /** Chat message history */
+  messages: Message[];
+  /** Current session ID */
+  sessionId: string | null;
+  /** Visitor ID */
+  visitorId: string | null;
+  /** Number of unread messages */
+  unreadCount: number;
+}
+
+/**
+ * Widget event types
+ */
+export type WidgetEvent = 'ready' | 'open' | 'close' | 'message' | 'error';
+
+/**
+ * Event callback function type
+ */
+export type EventCallback = (data?: unknown) => void;
+
+/**
+ * Public API interface for the Ihooman Chat Widget
+ */
+export interface IhoomanChatAPI {
+  /**
+   * Initialize the widget with configuration
+   * @param config - Widget configuration options
+   * @returns Promise that resolves when widget is ready
+   */
+  init(config: WidgetConfig): Promise<IhoomanChatAPI | null>;
+  
+  /**
+   * Open the chat widget window
+   */
+  open(): void;
+  
+  /**
+   * Close the chat widget window
+   */
+  close(): void;
+  
+  /**
+   * Toggle the chat widget window open/closed
+   */
+  toggle(): void;
+  
+  /**
+   * Destroy the widget and clean up resources
+   */
+  destroy(): void;
+  
+  /**
+   * Send a message programmatically
+   * @param content - Message content to send
+   */
+  sendMessage(content: string): void;
+  
+  /**
+   * Set user information for personalization
+   * @param user - User information
+   */
+  setUser(user: UserInfo): void;
+  
+  /**
+   * Clear chat history and start a new conversation
+   */
+  clearHistory(): void;
+  
+  /**
+   * Subscribe to widget events
+   * @param event - Event type to listen for
+   * @param callback - Callback function
+   */
+  on(event: WidgetEvent, callback: EventCallback): void;
+  
+  /**
+   * Unsubscribe from widget events
+   * @param event - Event type
+   * @param callback - Callback function to remove
+   */
+  off(event: WidgetEvent, callback: EventCallback): void;
+  
+  /**
+   * Get current widget state
+   * @returns Current widget state
+   */
+  getState(): WidgetState;
+  
+  /**
+   * Widget version
+   */
+  readonly version: string;
+}