@ihoomanai/chat-widget 2.5.13 → 3.0.0

package/src/types.ts

@@ -1,7 +1,12 @@
 /**
  * Type definitions for @ihooman/chat-widget
+ * Enhanced with professional features
  */
 
+// ============================================================================
+// Theme Configuration Types
+// ============================================================================
+
 /**
  * Theme configuration for the widget appearance
  */
@@ -58,8 +63,14 @@ export interface BrandingConfig {
   avatarUrl?: string | null;
   /** Show "Powered by Ihooman" branding */
   poweredBy?: boolean;
+  /** Custom CSS for widget styling */
+  customCss?: string;
 }
 
+// ============================================================================
+// Preset Questions & Quick Replies
+// ============================================================================
+
 /**
  * Preset question for quick access
  */
@@ -70,8 +81,156 @@ export interface PresetQuestion {
   text: string;
   /** Optional emoji icon */
   icon?: string;
+  /** Optional emoji (alias for icon) */
+  emoji?: string;
+}
+
+/**
+ * Quick reply suggestion from AI agent
+ */
+export interface QuickReply {
+  id: string;
+  text: string;
+}
+
+// ============================================================================
+// Proactive Messages
+// ============================================================================
+
+/**
+ * Proactive message trigger configuration
+ */
+export interface ProactiveTriggerConfig {
+  type: 'time' | 'scroll' | 'exit_intent' | 'url_pattern';
+  value: number | string;
+}
+
+/**
+ * Proactive message configuration
+ */
+export interface ProactiveMessage {
+  id: string;
+  message: string;
+  trigger: ProactiveTriggerConfig;
+  autoOpen: boolean;
+  cooldownMinutes: number;
+  startDate?: Date;
+  endDate?: Date;
+}
+
+// ============================================================================
+// Survey Configuration
+// ============================================================================
+
+/**
+ * Survey type options
+ */
+export type SurveyType = 'star' | 'nps' | 'emoji';
+
+/**
+ * Survey configuration
+ */
+export interface SurveyConfig {
+  id: string;
+  type: SurveyType;
+  question: string;
+  followUpQuestion?: string;
+  thankYouMessage: string;
+}
+
+/**
+ * Survey response
+ */
+export interface SurveyResponse {
+  surveyId: string;
+  rating: number;
+  comment?: string;
+  sessionId: string;
+  timestamp: Date;
+}
+
+// ============================================================================
+// Rich Message Types
+// ============================================================================
+
+/**
+ * Card button action type
+ */
+export type CardButtonAction = 'link' | 'message' | 'callback';
+
+/**
+ * Card button
+ */
+export interface CardButton {
+  id: string;
+  label: string;
+  action: CardButtonAction;
+  value: string;
+}
+
+/**
+ * Card content for carousel messages
+ */
+export interface CardContent {
+  id: string;
+  imageUrl?: string;
+  title: string;
+  description?: string;
+  buttons: CardButton[];
 }
 
+/**
+ * Form field type
+ */
+export type FormFieldType = 'text' | 'email' | 'phone' | 'select' | 'checkbox' | 'textarea';
+
+/**
+ * Form field validation rule
+ */
+export interface ValidationRule {
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  message: string;
+}
+
+/**
+ * Form field option (for select fields)
+ */
+export interface FormFieldOption {
+  value: string;
+  label: string;
+}
+
+/**
+ * Form field
+ */
+export interface FormField {
+  id: string;
+  type: FormFieldType;
+  label: string;
+  placeholder?: string;
+  required: boolean;
+  options?: FormFieldOption[];
+  validation?: ValidationRule;
+}
+
+/**
+ * Image item for gallery messages
+ */
+export interface GalleryImage {
+  id: string;
+  url: string;
+  thumbnailUrl?: string;
+  alt: string;
+  width?: number;
+  height?: number;
+}
+
+// ============================================================================
+// Main Widget Configuration
+// ============================================================================
+
 /**
  * Main widget configuration options
  */
@@ -90,7 +249,7 @@ export interface WidgetConfig {
   serverUrl?: string;
   
   /** Widget color theme */
-  theme?: 'light' | 'dark';
+  theme?: 'light' | 'dark' | 'auto';
   
   /** Widget position on the page */
   position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
@@ -155,9 +314,39 @@ export interface WidgetConfig {
   /** Custom avatar URL */
   avatarUrl?: string;
   
+  /** Custom logo URL */
+  logoUrl?: string;
+  
   /** Show powered by branding */
   poweredBy?: boolean;
   
+  /** Custom CSS for widget styling */
+  customCss?: string;
+  
+  /** Preset questions for quick access */
+  presetQuestions?: PresetQuestion[];
+  
+  /** Proactive messages configuration */
+  proactiveMessages?: ProactiveMessage[];
+  
+  /** Survey configuration */
+  surveyConfig?: SurveyConfig | null;
+  
+  /** Localization locale */
+  locale?: string;
+  
+  /** Custom translations */
+  translations?: Record<string, string>;
+  
+  /** Right-to-left text direction */
+  rtl?: boolean;
+  
+  /** Allowed domains for security validation */
+  allowedDomains?: string[];
+  
+  /** Allow localhost for development */
+  allowLocalhost?: boolean;
+  
   /** Callback when widget is ready */
   onReady?: () => void;
   
@@ -174,6 +363,10 @@ export interface WidgetConfig {
   onError?: (error: Error) => void;
 }
 
+// ============================================================================
+// User Information
+// ============================================================================
+
 /**
  * User information for personalization
  */
@@ -182,22 +375,73 @@ export interface UserInfo {
   name?: string;
   /** User's email address */
   email?: string;
+  /** User's phone number */
+  phone?: string;
   /** Additional metadata */
-  metadata?: Record<string, string>;
+  metadata?: Record<string, unknown>;
 }
 
+// ============================================================================
+// Message Types
+// ============================================================================
+
+/**
+ * Message sender type
+ */
+export type MessageSender = 'user' | 'bot' | 'assistant' | 'agent' | 'system';
+
+/**
+ * Message delivery status
+ */
+export type MessageStatus = 'pending' | 'sending' | 'sent' | 'delivered' | 'read' | 'error';
+
+/**
+ * Message type
+ */
+export type MessageType = 'text' | 'image' | 'file' | 'carousel' | 'form' | 'buttons' | 'gallery';
+
 /**
  * Chat message structure
  */
 export interface Message {
   /** Unique message ID */
   id: string;
-  /** Message content */
+  /** Message type */
+  type?: MessageType;
+  /** Message content (for text messages) */
   content: string;
   /** Message sender type */
-  sender: 'user' | 'bot';
+  sender: MessageSender;
   /** Message timestamp */
   timestamp: Date;
+  /** Session ID */
+  sessionId?: string;
+  /** Message status */
+  status?: MessageStatus;
+  /** Whether content contains markdown */
+  markdown?: boolean;
+  /** Image URL (for image messages) */
+  imageUrl?: string;
+  /** File URL (for file messages) */
+  fileUrl?: string;
+  /** Filename (for file messages) */
+  filename?: string;
+  /** File size (for file messages) */
+  fileSize?: number;
+  /** Cards (for carousel messages) */
+  cards?: CardContent[];
+  /** Form fields (for form messages) */
+  formFields?: FormField[];
+  /** Form ID (for form messages) */
+  formId?: string;
+  /** Form title (for form messages) */
+  formTitle?: string;
+  /** Submit label (for form messages) */
+  submitLabel?: string;
+  /** Buttons (for button group messages) */
+  buttons?: CardButton[];
+  /** Gallery images (for gallery messages) */
+  images?: GalleryImage[];
   /** Additional message metadata */
   metadata?: {
     /** Source documents for RAG responses */
@@ -215,9 +459,40 @@ export interface Message {
     escalated?: boolean;
     /** Whether this is a system message */
     is_system_message?: boolean;
+    /** Quick replies */
+    quick_replies?: QuickReply[];
   };
 }
 
+// ============================================================================
+// Widget State
+// ============================================================================
+
+/**
+ * Widget initialization status
+ */
+export type WidgetStatus = 'initializing' | 'ready' | 'open' | 'error';
+
+/**
+ * Connection status
+ */
+export type ConnectionStatus = 'connected' | 'connecting' | 'disconnected' | 'offline';
+
+/**
+ * Current view in the widget
+ */
+export type WidgetView = 'chat' | 'ticket' | 'history' | 'survey';
+
+/**
+ * Escalation status
+ */
+export interface EscalationStatus {
+  active: boolean;
+  type: 'live_agent' | 'ticket';
+  queuePosition?: number;
+  estimatedWait?: number;
+}
+
 /**
  * Widget state information
  */
@@ -228,24 +503,82 @@ export interface WidgetState {
   isConnected: boolean;
   /** Chat message history */
   messages: Message[];
+  /** Pending messages (offline queue) */
+  pendingMessages?: Message[];
   /** Current session ID */
   sessionId: string | null;
   /** Visitor ID */
   visitorId: string | null;
   /** Number of unread messages */
   unreadCount: number;
+  /** Current view */
+  view?: WidgetView;
+  /** Connection status */
+  connectionStatus?: ConnectionStatus;
+  /** Typing indicator */
+  typingIndicator?: boolean;
+  /** Sound muted */
+  soundMuted?: boolean;
+  /** Widget dimensions */
+  dimensions?: { width: number; height: number };
+  /** Escalation status */
+  escalationStatus?: EscalationStatus | null;
+  /** Queue position */
+  queuePosition?: number | null;
+  /** User info */
+  userInfo?: UserInfo | null;
 }
 
+// ============================================================================
+// Events
+// ============================================================================
+
 /**
  * Widget event types
  */
-export type WidgetEvent = 'ready' | 'open' | 'close' | 'message' | 'error' | 'connected' | 'disconnected' | 'newConversation';
+export type WidgetEvent = 
+  | 'ready' 
+  | 'open' 
+  | 'close' 
+  | 'message' 
+  | 'message:sent'
+  | 'message:received'
+  | 'error' 
+  | 'connected' 
+  | 'disconnected' 
+  | 'connection:change'
+  | 'newConversation'
+  | 'escalation:start'
+  | 'escalation:end'
+  | 'survey:shown'
+  | 'survey:submitted'
+  | 'proactive:shown'
+  | 'proactive:clicked';
 
 /**
  * Event callback function type
  */
 export type EventCallback = (data?: unknown) => void;
 
+// ============================================================================
+// Conversation History
+// ============================================================================
+
+/**
+ * Conversation summary for history display
+ */
+export interface ConversationSummary {
+  sessionId: string;
+  startTime: Date;
+  lastMessageTime: Date;
+  messageCount: number;
+  preview: string;
+}
+
+// ============================================================================
+// Public API Interface
+// ============================================================================
+
 /**
  * Public API interface for the Ihooman Chat Widget
  */
@@ -272,6 +605,11 @@ export interface IhoomanChatAPI {
    */
   toggle(): void;
   
+  /**
+   * Check if widget is open
+   */
+  isOpen?(): boolean;
+  
   /**
    * Destroy the widget and clean up resources
    */
@@ -289,6 +627,11 @@ export interface IhoomanChatAPI {
    */
   setUser(user: UserInfo): void;
   
+  /**
+   * Clear user information
+   */
+  clearUser?(): void;
+  
   /**
    * Clear chat history and start a new conversation
    */
@@ -314,6 +657,11 @@ export interface IhoomanChatAPI {
    */
   getState(): WidgetState;
   
+  /**
+   * Get current widget configuration
+   */
+  getConfig?(): WidgetConfig;
+  
   /**
    * Widget version
    */

package/src/widget.ts

@@ -275,9 +275,9 @@ function generateStyles(): string {
     .ihooman-toggle.open .ihooman-pulse { display: none; }
     .ihooman-badge { position: absolute; top: -4px; right: -4px; min-width: 20px; height: 20px; padding: 0 6px; background: #ef4444; color: white; font-size: 11px; font-weight: 600; border-radius: 10px; display: flex; align-items: center; justify-content: center; z-index: 2; }
     .ihooman-badge:empty { display: none; }
-    .ihooman-window { position: fixed; ${positionRight ? 'right: 20px' : 'left: 20px'}; ${positionBottom ? 'bottom: 90px' : 'top: 90px'}; width: ${width}px; height: ${height}px; max-height: calc(100vh - 120px); z-index: ${(zIndex ?? 9999) - 1}; display: flex; flex-direction: column; opacity: 0; visibility: hidden; transform: translateY(20px) scale(0.95); transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1); overscroll-behavior: contain; }
+    .ihooman-window { position: fixed; ${positionRight ? 'right: 20px' : 'left: 20px'}; ${positionBottom ? 'bottom: 90px' : 'top: 90px'}; width: ${width}px; height: ${height}px; min-height: ${height}px; max-height: ${height}px; z-index: ${(zIndex ?? 9999) - 1}; display: flex; flex-direction: column; opacity: 0; visibility: hidden; transform: translateY(20px) scale(0.95); transition: opacity 0.3s, visibility 0.3s, transform 0.3s; overscroll-behavior: contain; }
     .ihooman-window.open { opacity: 1; visibility: visible; transform: translateY(0) scale(1); }
-    .ihooman-container { position: relative; width: 100%; height: 100%; display: flex; flex-direction: column; border-radius: ${borderRadius}px; overflow: hidden; }
+    .ihooman-container { position: relative; width: 100%; height: 100%; display: flex; flex-direction: column; border-radius: ${borderRadius}px; overflow: hidden; flex-shrink: 0; }
     .ihooman-container::before { content: ''; position: absolute; inset: 0; background: ${bgColor}; opacity: 0.97; backdrop-filter: blur(20px); -webkit-backdrop-filter: blur(20px); border-radius: ${borderRadius}px; border: 1px solid ${borderColor}; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); }
     .ihooman-container > * { position: relative; z-index: 1; }
     .ihooman-header { padding: 16px 20px; background: linear-gradient(135deg, ${gradientFrom}, ${gradientTo}); color: white; display: flex; align-items: center; gap: 12px; flex-shrink: 0; }
@@ -374,7 +374,7 @@ function generateStyles(): string {
     .ihooman-widget .ihooman-preset-btn { display: inline-flex !important; align-items: center !important; gap: 4px !important; padding: 6px 12px !important; border-radius: 6px !important; border: 1px solid ${borderColor} !important; background: ${isDark ? 'rgba(255,255,255,0.05)' : 'rgba(0,0,0,0.02)'} !important; color: ${textColor} !important; font-size: 12px !important; font-weight: 500 !important; cursor: pointer !important; transition: all 0.2s !important; white-space: nowrap !important; width: auto !important; height: auto !important; min-width: 0 !important; aspect-ratio: auto !important; }
     .ihooman-widget .ihooman-preset-btn:hover { background: ${isDark ? 'rgba(255,255,255,0.1)' : 'rgba(0,0,0,0.05)'} !important; border-color: ${primaryColor} !important; }
     .ihooman-widget .ihooman-preset-btn .icon { font-size: 12px !important; flex-shrink: 0 !important; }
-    @media (max-width: 480px) { .ihooman-window { width: calc(100vw - 20px); height: calc(100vh - 100px); left: 10px; right: 10px; bottom: 80px; max-height: none; } .ihooman-toggle { ${positionRight ? 'right: 16px' : 'left: 16px'}; bottom: 16px; } }
+    @media (max-width: 480px) { .ihooman-window { width: calc(100vw - 20px); height: calc(100vh - 100px); min-height: 400px; max-height: calc(100vh - 100px); left: 10px; right: 10px; bottom: 80px; } .ihooman-toggle { ${positionRight ? 'right: 16px' : 'left: 16px'}; bottom: 16px; } }
   `;
 }