@ihoomanai/react-chat 2.0.0

package/src/types.ts

@@ -0,0 +1,175 @@
+/**
+ * Type definitions for @ihooman/react-chat
+ * 
+ * Re-exports core types from @ihooman/chat-widget and defines
+ * React-specific types for components and hooks.
+ */
+
+// Re-export core types for convenience
+export type {
+  WidgetConfig,
+  UserInfo,
+  Message,
+  WidgetState,
+  WidgetEvent,
+  EventCallback,
+  ThemeConfig,
+  BehaviorConfig,
+  BrandingConfig,
+  IhoomanChatAPI,
+} from '@ihooman/chat-widget';
+
+/**
+ * Props for the ChatWidget React component
+ */
+export interface ChatWidgetProps {
+  /**
+   * 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';
+
+  /** Start with widget open */
+  startOpen?: boolean;
+
+  /** User information for personalization */
+  user?: {
+    name?: string;
+    email?: string;
+    metadata?: Record<string, string>;
+  };
+
+  /** 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;
+
+  /** 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: import('@ihooman/chat-widget').Message) => void;
+
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Return type for the useChatWidget hook
+ */
+export interface UseChatWidgetReturn {
+  /** Whether the widget window is currently open */
+  isOpen: boolean;
+
+  /** Whether the widget is initialized and ready */
+  isReady: boolean;
+
+  /** Whether connected to the server */
+  isConnected: boolean;
+
+  /** Open the chat widget window */
+  open: () => void;
+
+  /** Close the chat widget window */
+  close: () => void;
+
+  /** Toggle the chat widget window open/closed */
+  toggle: () => void;
+
+  /** Send a message programmatically */
+  sendMessage: (content: string) => void;
+
+  /** Set user information for personalization */
+  setUser: (user: { name?: string; email?: string; metadata?: Record<string, string> }) => void;
+
+  /** Clear chat history and start a new conversation */
+  clearHistory: () => void;
+
+  /** Current chat messages */
+  messages: import('@ihooman/chat-widget').Message[];
+
+  /** Number of unread messages */
+  unreadCount: number;
+}
+
+/**
+ * Props for the ChatWidgetProvider component
+ */
+export interface ChatWidgetProviderProps {
+  /** Child components */
+  children: React.ReactNode;
+}

package/src/useChatWidget.ts

@@ -0,0 +1,149 @@
+/**
+ * useChatWidget Hook
+ * 
+ * Provides programmatic control over the Ihooman Chat Widget
+ * from any component within the ChatWidgetProvider.
+ * 
+ * @module @ihooman/react-chat
+ */
+
+import { useCallback } from 'react';
+import { useChatWidgetContext, isWidgetAvailable } from './context';
+import type { UseChatWidgetReturn } from './types';
+
+/**
+ * Hook for controlling the Ihooman Chat Widget
+ * 
+ * Must be used within a ChatWidgetProvider. Provides access to
+ * widget state and control functions.
+ * 
+ * @returns Object containing widget state and control functions
+ * 
+ * @example Basic usage
+ * ```tsx
+ * import { useChatWidget } from '@ihooman/react-chat';
+ * 
+ * function SupportButton() {
+ *   const { open, isReady } = useChatWidget();
+ * 
+ *   return (
+ *     <button onClick={open} disabled={!isReady}>
+ *       Need Help?
+ *     </button>
+ *   );
+ * }
+ * ```
+ * 
+ * @example Sending messages programmatically
+ * ```tsx
+ * function QuickActions() {
+ *   const { sendMessage, isReady } = useChatWidget();
+ * 
+ *   const handleOrderHelp = () => {
+ *     sendMessage('I need help with my order');
+ *   };
+ * 
+ *   return (
+ *     <button onClick={handleOrderHelp} disabled={!isReady}>
+ *       Order Help
+ *     </button>
+ *   );
+ * }
+ * ```
+ * 
+ * @example Accessing widget state
+ * ```tsx
+ * function ChatStatus() {
+ *   const { isOpen, isConnected, unreadCount } = useChatWidget();
+ * 
+ *   return (
+ *     <div>
+ *       <span>Chat: {isOpen ? 'Open' : 'Closed'}</span>
+ *       <span>Status: {isConnected ? 'Connected' : 'Disconnected'}</span>
+ *       {unreadCount > 0 && <span>({unreadCount} unread)</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useChatWidget(): UseChatWidgetReturn {
+  const context = useChatWidgetContext();
+
+  /**
+   * Open the chat widget window
+   */
+  const open = useCallback(() => {
+    if (isWidgetAvailable(context.widgetRef)) {
+      context.widgetRef.open();
+    }
+  }, [context.widgetRef]);
+
+  /**
+   * Close the chat widget window
+   */
+  const close = useCallback(() => {
+    if (isWidgetAvailable(context.widgetRef)) {
+      context.widgetRef.close();
+    }
+  }, [context.widgetRef]);
+
+  /**
+   * Toggle the chat widget window open/closed
+   */
+  const toggle = useCallback(() => {
+    if (isWidgetAvailable(context.widgetRef)) {
+      context.widgetRef.toggle();
+    }
+  }, [context.widgetRef]);
+
+  /**
+   * Send a message programmatically
+   */
+  const sendMessage = useCallback(
+    (content: string) => {
+      if (isWidgetAvailable(context.widgetRef)) {
+        context.widgetRef.sendMessage(content);
+      }
+    },
+    [context.widgetRef]
+  );
+
+  /**
+   * Set user information for personalization
+   */
+  const setUser = useCallback(
+    (user: { name?: string; email?: string; metadata?: Record<string, string> }) => {
+      if (isWidgetAvailable(context.widgetRef)) {
+        context.widgetRef.setUser(user);
+      }
+    },
+    [context.widgetRef]
+  );
+
+  /**
+   * Clear chat history and start a new conversation
+   */
+  const clearHistory = useCallback(() => {
+    if (isWidgetAvailable(context.widgetRef)) {
+      context.widgetRef.clearHistory();
+      context.setMessages([]);
+      context.setUnreadCount(0);
+    }
+  }, [context]);
+
+  return {
+    isOpen: context.isOpen,
+    isReady: context.isReady,
+    isConnected: context.isConnected,
+    open,
+    close,
+    toggle,
+    sendMessage,
+    setUser,
+    clearHistory,
+    messages: context.messages,
+    unreadCount: context.unreadCount,
+  };
+}
+
+export default useChatWidget;