simple-support-chat 0.3.3 → 0.4.1

package/dist/client/index.d.ts

@@ -31,6 +31,10 @@ interface ChatBubbleProps {
     user?: ChatUser;
     /** URL to poll for team replies (e.g., '/api/support/replies'). Enables bidirectional chat. */
     repliesUrl?: string;
+    /** URL for SSE endpoint (optional — enables real-time delivery when provided). */
+    sseUrl?: string;
+    /** Polling interval in milliseconds. Default: 4000 (4 seconds). */
+    pollInterval?: number;
     /**
      * Controlled mode: when provided, overrides internal open/close state.
      * The chat panel is open when `isOpen` is true, closed when false.
@@ -98,6 +102,10 @@ interface SupportChatModalProps {
     user?: ChatUser;
     /** URL to poll for team replies (e.g., '/api/support/replies'). Enables bidirectional chat. */
     repliesUrl?: string;
+    /** URL for SSE endpoint (optional — enables real-time delivery when provided). */
+    sseUrl?: string;
+    /** Polling interval in milliseconds. Default: 4000 (4 seconds). */
+    pollInterval?: number;
 }
 /** Anonymous context collected automatically from the browser */
 interface AnonymousContext {
@@ -120,7 +128,7 @@ interface AnonymousContext {
  * <ChatBubble apiUrl="/api/support" />
  * ```
  */
-declare function ChatBubble({ apiUrl, position, color, title, placeholder, show, user, repliesUrl, isOpen: isOpenProp, onOpenChange, badgeColor, unreadCount, }: ChatBubbleProps): react_jsx_runtime.JSX.Element;
+declare function ChatBubble({ apiUrl, position, color, title, placeholder, show, user, repliesUrl, sseUrl, pollInterval, isOpen: isOpenProp, onOpenChange, badgeColor, unreadCount, }: ChatBubbleProps): react_jsx_runtime.JSX.Element;
 
 /**
  * SupportChatModal -- modal-based support chat.
@@ -152,7 +160,7 @@ declare function ChatBubble({ apiUrl, position, color, title, placeholder, show,
  * }
  * ```
  */
-declare function SupportChatModal({ apiUrl, isOpen, onClose, color, title, placeholder, user, repliesUrl, }: SupportChatModalProps): react_jsx_runtime.JSX.Element | null;
+declare function SupportChatModal({ apiUrl, isOpen, onClose, color, title, placeholder, user, repliesUrl, sseUrl, pollInterval, }: SupportChatModalProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Hook that returns controls for opening/closing the support chat.
@@ -166,6 +174,50 @@ declare function SupportChatModal({ apiUrl, isOpen, onClose, color, title, place
  */
 declare function useSupportChat(): SupportChatState;
 
+/** Transport mode for reply delivery */
+type TransportMode = "sse" | "polling" | "disconnected";
+/** Options for useReplyTransport */
+interface ReplyTransportOptions {
+    /** URL for SSE endpoint (optional — enables SSE transport when provided) */
+    sseUrl?: string;
+    /** URL for polling replies (optional — used as fallback or primary when no sseUrl) */
+    repliesUrl?: string;
+    /** Session identifier for the chat session */
+    sessionId: string;
+    /** Whether the transport should be active (connected/polling) */
+    isActive: boolean;
+    /** Polling interval in milliseconds. Default: 4000 (4 seconds). */
+    pollInterval?: number;
+}
+/** Return value from useReplyTransport */
+interface ReplyTransportState {
+    /** Accumulated replies from the transport */
+    replies: ChatMessage[];
+    /** Current transport mode */
+    transport: TransportMode;
+}
+/**
+ * Internal hook that manages reply delivery via SSE or polling fallback.
+ *
+ * When `sseUrl` is provided and `isActive` is true, connects via EventSource
+ * for real-time reply delivery. If the EventSource connection fails, automatically
+ * falls back to polling via `repliesUrl`.
+ *
+ * When only `repliesUrl` is provided (no `sseUrl`), uses polling directly,
+ * preserving full backward compatibility with existing setups.
+ *
+ * @example
+ * ```ts
+ * const { replies, transport } = useReplyTransport({
+ *   sseUrl: '/api/support/sse',
+ *   repliesUrl: '/api/support/replies',
+ *   sessionId: 'user-123',
+ *   isActive: true,
+ * });
+ * ```
+ */
+declare function useReplyTransport({ sseUrl, repliesUrl, sessionId, isActive, pollInterval, }: ReplyTransportOptions): ReplyTransportState;
+
 /** Options for initializing the chat engine */
 interface ChatEngineOptions {
     /** URL of the support chat API endpoint */
@@ -174,8 +226,12 @@ interface ChatEngineOptions {
     user?: ChatUser;
     /** URL to poll for team replies. When set, polling starts while chat is active. */
     repliesUrl?: string;
+    /** URL for SSE endpoint (optional — enables real-time delivery when provided). */
+    sseUrl?: string;
     /** Whether the chat panel is currently visible (controls polling lifecycle). Defaults to true. */
     isOpen?: boolean;
+    /** Polling interval in milliseconds. Default: 4000 (4 seconds). */
+    pollInterval?: number;
 }
 /** Return value from useChatEngine */
 interface ChatEngineState {
@@ -191,56 +247,64 @@ interface ChatEngineState {
     sendMessage: () => Promise<void>;
     /** Handle keydown on the input (Enter to send) */
     handleKeyDown: (e: React.KeyboardEvent) => void;
+    /** Current transport mode */
+    transport: TransportMode;
 }
 /**
  * Shared chat engine hook used by both ChatBubble and SupportChatModal.
- * Manages message state, input, API communication, and reply polling.
+ * Manages message state, input, API communication, and reply delivery
+ * via useReplyTransport (SSE with polling fallback).
  */
-declare function useChatEngine({ apiUrl, user, repliesUrl, isOpen, }: ChatEngineOptions): ChatEngineState;
+declare function useChatEngine({ apiUrl, user, repliesUrl, sseUrl, isOpen, pollInterval, }: ChatEngineOptions): ChatEngineState;
 
-/** Options for the useUnreadCount hook */
+/** Options for useUnreadCount */
 interface UnreadCountOptions {
-    /** URL to poll for team replies (e.g., '/api/support/replies') */
-    repliesUrl: string;
-    /** Authenticated user info (optional). When provided, user.id is used as sessionId. */
+    /** URL for SSE endpoint (optional — enables real-time delivery when provided). */
+    sseUrl?: string;
+    /** URL to poll for team replies (e.g., '/api/support/replies'). */
+    repliesUrl?: string;
+    /** Authenticated user info (optional — uses user.id as sessionId if provided). */
     user?: ChatUser;
-    /** Whether the chat panel is currently open. Polling pauses when true. */
+    /** Whether the chat panel is currently open. When open, unread count resets to 0. */
     isOpen: boolean;
 }
 /** Return value from useUnreadCount */
 interface UnreadCountState {
-    /** Number of unread reply messages */
+    /** Number of unread replies received while the chat was closed */
     unreadCount: number;
     /** Convenience boolean: true when unreadCount > 0 */
     hasUnread: boolean;
-    /** Pre-fetched reply messages ready to display instantly when chat opens */
+    /** Pre-cached pending replies for instant display when chat opens */
     pendingReplies: ChatMessage[];
     /** Reset unreadCount to 0 and clear pendingReplies */
     markAsRead: () => void;
+    /** Current transport mode */
+    transport: TransportMode;
 }
 /**
- * Hook that tracks unread reply count in the background via polling.
+ * Hook that tracks unread reply count when the chat is closed.
  *
- * Simple count-based model:
- * - On mount, fetches total reply count and records it as the "baseline"
- * - Unread = (current total) - baseline
- * - Page refresh resets to 0 (new baseline)
- * - Opening the chat or calling markAsRead resets baseline to current total
+ * Uses useReplyTransport internally to receive replies via SSE or polling.
+ * The transport stays active even when the chat is closed so replies arrive
+ * in real-time and the unread badge updates immediately.
+ *
+ * When the chat opens (isOpen becomes true), the unread count resets to 0.
+ * The pendingReplies array provides pre-cached replies for instant display.
  *
  * @example
- * ```tsx
- * const { unreadCount, hasUnread, markAsRead } = useUnreadCount({
+ * ```ts
+ * const { unreadCount, hasUnread, pendingReplies, markAsRead } = useUnreadCount({
+ *   sseUrl: '/api/support/sse',
  *   repliesUrl: '/api/support/replies',
- *   user: currentUser,
  *   isOpen: false,
  * });
  * ```
  */
-declare function useUnreadCount({ repliesUrl, user, isOpen, }: UnreadCountOptions): UnreadCountState;
+declare function useUnreadCount({ sseUrl, repliesUrl, user, isOpen, }: UnreadCountOptions): UnreadCountState;
 
 /** Get or create a persistent session ID from localStorage */
 declare function getSessionId(): string;
 /** Collect anonymous browser context */
 declare function collectAnonymousContext(): AnonymousContext;
 
-export { type AnonymousContext, type BubblePosition, ChatBubble, type ChatBubbleProps, type ChatEngineOptions, type ChatEngineState, type ChatMessage, type ChatUser, SupportChatModal, type SupportChatModalProps, type SupportChatState, type UnreadCountOptions, type UnreadCountState, collectAnonymousContext, getSessionId, useChatEngine, useSupportChat, useUnreadCount };
+export { type AnonymousContext, type BubblePosition, ChatBubble, type ChatBubbleProps, type ChatEngineOptions, type ChatEngineState, type ChatMessage, type ChatUser, type ReplyTransportOptions, type ReplyTransportState, SupportChatModal, type SupportChatModalProps, type SupportChatState, type TransportMode, type UnreadCountOptions, type UnreadCountState, collectAnonymousContext, getSessionId, useChatEngine, useReplyTransport, useSupportChat, useUnreadCount };

package/dist/client/index.js

@@ -46,20 +46,183 @@ function collectAnonymousContext() {
     sessionId
   };
 }
+var DEFAULT_POLL_INTERVAL = 4e3;
+function useReplyTransport({
+  sseUrl,
+  repliesUrl,
+  sessionId,
+  isActive,
+  pollInterval = DEFAULT_POLL_INTERVAL
+}) {
+  const [replies, setReplies] = useState([]);
+  const [transport, setTransport] = useState("disconnected");
+  const knownReplyIdsRef = useRef(/* @__PURE__ */ new Set());
+  const lastReplyTimestampRef = useRef(null);
+  const sseFailedRef = useRef(false);
+  const eventSourceRef = useRef(null);
+  const pollIntervalRef = useRef(null);
+  const needsCatchUpRef = useRef(false);
+  const addReplies = useCallback(
+    (newReplies) => {
+      const deduplicated = newReplies.filter(
+        (r) => !knownReplyIdsRef.current.has(r.id)
+      );
+      if (deduplicated.length === 0) return;
+      for (const r of deduplicated) {
+        knownReplyIdsRef.current.add(r.id);
+      }
+      const latestTimestamp = deduplicated.reduce((latest, r) => {
+        return r.timestamp > latest ? r.timestamp : latest;
+      }, lastReplyTimestampRef.current ?? "");
+      lastReplyTimestampRef.current = latestTimestamp;
+      const replyMessages = deduplicated.map((r) => ({
+        id: r.id,
+        text: r.text,
+        sender: "received",
+        timestamp: new Date(r.timestamp).getTime()
+      }));
+      setReplies((prev) => [...prev, ...replyMessages]);
+    },
+    []
+  );
+  const fetchReplies = useCallback(async () => {
+    if (!repliesUrl) return;
+    try {
+      const params = new URLSearchParams({ sessionId });
+      if (lastReplyTimestampRef.current) {
+        params.set("since", lastReplyTimestampRef.current);
+      }
+      const response = await fetch(`${repliesUrl}?${params.toString()}`);
+      if (!response.ok) return;
+      const data = await response.json();
+      if (data.replies.length === 0) return;
+      addReplies(data.replies);
+    } catch {
+    }
+  }, [repliesUrl, sessionId, addReplies]);
+  const startPolling = useCallback(() => {
+    if (!repliesUrl) return;
+    if (pollIntervalRef.current !== null) {
+      clearInterval(pollIntervalRef.current);
+    }
+    setTransport("polling");
+    void fetchReplies();
+    pollIntervalRef.current = setInterval(
+      () => void fetchReplies(),
+      pollInterval
+    );
+  }, [repliesUrl, fetchReplies]);
+  const stopPolling = useCallback(() => {
+    if (pollIntervalRef.current !== null) {
+      clearInterval(pollIntervalRef.current);
+      pollIntervalRef.current = null;
+    }
+  }, []);
+  const connectSSE = useCallback(() => {
+    if (!sseUrl || sseFailedRef.current) return;
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+      eventSourceRef.current = null;
+    }
+    const url = `${sseUrl}?sessionId=${encodeURIComponent(sessionId)}`;
+    const es = new EventSource(url);
+    eventSourceRef.current = es;
+    es.addEventListener("reply", (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        addReplies([data.reply]);
+      } catch {
+      }
+    });
+    es.addEventListener("heartbeat", () => {
+    });
+    es.onopen = () => {
+      setTransport("sse");
+      if (needsCatchUpRef.current) {
+        needsCatchUpRef.current = false;
+        void fetchReplies();
+      }
+    };
+    es.onerror = () => {
+      if (es.readyState === EventSource.CLOSED) {
+        sseFailedRef.current = true;
+        es.close();
+        eventSourceRef.current = null;
+        startPolling();
+      } else {
+        needsCatchUpRef.current = true;
+      }
+    };
+  }, [sseUrl, sessionId, addReplies, fetchReplies, startPolling]);
+  const disconnectSSE = useCallback(() => {
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+      eventSourceRef.current = null;
+    }
+  }, []);
+  useEffect(() => {
+    if (!isActive) {
+      disconnectSSE();
+      stopPolling();
+      setTransport("disconnected");
+      return;
+    }
+    if (!sseUrl && !repliesUrl) {
+      setTransport("disconnected");
+      return;
+    }
+    if (sseUrl && !sseFailedRef.current) {
+      connectSSE();
+    } else if (repliesUrl) {
+      startPolling();
+    }
+    return () => {
+      disconnectSSE();
+      stopPolling();
+    };
+  }, [
+    isActive,
+    sseUrl,
+    repliesUrl,
+    connectSSE,
+    disconnectSSE,
+    startPolling,
+    stopPolling
+  ]);
+  useEffect(() => {
+    sseFailedRef.current = false;
+  }, [sseUrl]);
+  return { replies, transport };
+}
 
 // src/client/useChatEngine.ts
-var POLL_INTERVAL = 4e3;
 function useChatEngine({
   apiUrl,
   user,
   repliesUrl,
-  isOpen = true
+  sseUrl,
+  isOpen = true,
+  pollInterval
 }) {
   const [messages, setMessages] = useState([]);
   const [input, setInput] = useState("");
   const [sending, setSending] = useState(false);
-  const lastReplyTimestampRef = useRef(null);
-  const knownReplyIdsRef = useRef(/* @__PURE__ */ new Set());
+  const sessionId = user?.id ?? getSessionId();
+  const { replies, transport } = useReplyTransport({
+    sseUrl,
+    repliesUrl,
+    sessionId,
+    isActive: isOpen,
+    pollInterval
+  });
+  const processedReplyCountRef = useRef(0);
+  useEffect(() => {
+    if (replies.length > processedReplyCountRef.current) {
+      const newReplies = replies.slice(processedReplyCountRef.current);
+      processedReplyCountRef.current = replies.length;
+      setMessages((prev) => [...prev, ...newReplies]);
+    }
+  }, [replies]);
   const sendMessage = useCallback(async () => {
     const text = input.trim();
     if (!text || sending) return;
@@ -80,7 +243,7 @@ function useChatEngine({
         body: JSON.stringify({
           message: text,
           user: user ?? void 0,
-          sessionId: user?.id ?? getSessionId(),
+          sessionId,
           context
         })
       });
@@ -108,7 +271,7 @@ function useChatEngine({
     } finally {
       setSending(false);
     }
-  }, [input, sending, apiUrl, user]);
+  }, [input, sending, apiUrl, user, sessionId]);
   const handleKeyDown = useCallback(
     (e) => {
       if (e.key === "Enter" && !e.shiftKey) {
@@ -118,45 +281,7 @@ function useChatEngine({
     },
     [sendMessage]
   );
-  useEffect(() => {
-    if (!repliesUrl || !isOpen) return;
-    const sessionId = user?.id ?? getSessionId();
-    const fetchReplies = async () => {
-      try {
-        const params = new URLSearchParams({ sessionId });
-        if (lastReplyTimestampRef.current) {
-          params.set("since", lastReplyTimestampRef.current);
-        }
-        const response = await fetch(`${repliesUrl}?${params.toString()}`);
-        if (!response.ok) return;
-        const data = await response.json();
-        if (data.replies.length === 0) return;
-        const newReplies = data.replies.filter(
-          (r) => !knownReplyIdsRef.current.has(r.id)
-        );
-        if (newReplies.length === 0) return;
-        for (const r of newReplies) {
-          knownReplyIdsRef.current.add(r.id);
-        }
-        const latestTimestamp = newReplies.reduce((latest, r) => {
-          return r.timestamp > latest ? r.timestamp : latest;
-        }, lastReplyTimestampRef.current ?? "");
-        lastReplyTimestampRef.current = latestTimestamp;
-        const replyMessages = newReplies.map((r) => ({
-          id: r.id,
-          text: r.text,
-          sender: "received",
-          timestamp: new Date(r.timestamp).getTime()
-        }));
-        setMessages((prev) => [...prev, ...replyMessages]);
-      } catch {
-      }
-    };
-    void fetchReplies();
-    const intervalId = setInterval(() => void fetchReplies(), POLL_INTERVAL);
-    return () => clearInterval(intervalId);
-  }, [repliesUrl, isOpen, user]);
-  return { messages, input, setInput, sending, sendMessage, handleKeyDown };
+  return { messages, input, setInput, sending, sendMessage, handleKeyDown, transport };
 }
 function useColorScheme() {
   const [scheme, setScheme] = useState(() => {
@@ -231,6 +356,8 @@ function ChatBubble({
   show = true,
   user,
   repliesUrl,
+  sseUrl,
+  pollInterval,
   isOpen: isOpenProp,
   onOpenChange,
   badgeColor = "#eab308",
@@ -253,7 +380,7 @@ function ChatBubble({
   );
   const colorScheme = useColorScheme();
   const theme = useMemo(() => getThemeTokens(colorScheme), [colorScheme]);
-  const { messages, input, setInput, sending, sendMessage, handleKeyDown } = useChatEngine({ apiUrl, user, repliesUrl, isOpen });
+  const { messages, input, setInput, sending, sendMessage, handleKeyDown } = useChatEngine({ apiUrl, user, repliesUrl, sseUrl, isOpen, pollInterval });
   const [panelState, setPanelState] = useState(
     "closed"
   );
@@ -623,9 +750,11 @@ function SupportChatModal({
   title = "Contact Us",
   placeholder = "Type a message...",
   user,
-  repliesUrl
+  repliesUrl,
+  sseUrl,
+  pollInterval
 }) {
-  const { messages, input, setInput, sending, sendMessage, handleKeyDown } = useChatEngine({ apiUrl, user, repliesUrl, isOpen });
+  const { messages, input, setInput, sending, sendMessage, handleKeyDown } = useChatEngine({ apiUrl, user, repliesUrl, sseUrl, isOpen, pollInterval });
   const colorScheme = useColorScheme();
   const theme = useMemo(() => getThemeTokens(colorScheme), [colorScheme]);
   const modalRef = useRef(null);
@@ -908,75 +1037,47 @@ function useSupportChat() {
   const toggle = useCallback(() => setIsOpen((prev) => !prev), []);
   return { open, close, toggle, isOpen };
 }
-var POLL_INTERVAL2 = 4e3;
 function useUnreadCount({
+  sseUrl,
   repliesUrl,
   user,
   isOpen
 }) {
-  const baselineCountRef = useRef(null);
-  const [allReplies, setAllReplies] = useState([]);
-  const totalCountRef = useRef(0);
-  const prevIsOpenRef = useRef(isOpen);
+  const sessionId = user?.id ?? getSessionId();
+  const { replies, transport } = useReplyTransport({
+    sseUrl,
+    repliesUrl,
+    sessionId,
+    isActive: true
+  });
+  const [unreadCount, setUnreadCount] = useState(0);
+  const [pendingReplies, setPendingReplies] = useState([]);
+  const countedReplyCountRef = useRef(0);
+  const wasOpenRef = useRef(isOpen);
   useEffect(() => {
-    if (isOpen && !prevIsOpenRef.current) {
-      baselineCountRef.current = totalCountRef.current;
-      setAllReplies([]);
+    if (isOpen && !wasOpenRef.current) {
+      setUnreadCount(0);
+      setPendingReplies([]);
     }
-    prevIsOpenRef.current = isOpen;
+    wasOpenRef.current = isOpen;
   }, [isOpen]);
   const markAsRead = useCallback(() => {
-    baselineCountRef.current = totalCountRef.current;
-    setAllReplies([]);
+    setUnreadCount(0);
+    setPendingReplies([]);
   }, []);
   useEffect(() => {
-    if (!repliesUrl || isOpen) return;
-    const sessionId = user?.id ?? getSessionId();
-    let cancelled = false;
-    const fetchReplies = async () => {
-      try {
-        const params = new URLSearchParams({ sessionId });
-        const response = await fetch(`${repliesUrl}?${params.toString()}`);
-        if (!response.ok || cancelled) return;
-        const data = await response.json();
-        if (cancelled) return;
-        const currentTotal = data.replies.length;
-        totalCountRef.current = currentTotal;
-        if (baselineCountRef.current === null) {
-          baselineCountRef.current = currentTotal;
-          return;
-        }
-        const newCount = currentTotal - baselineCountRef.current;
-        if (newCount > 0) {
-          const newReplies = data.replies.slice(-newCount);
-          setAllReplies(
-            newReplies.map((r) => ({
-              id: r.id,
-              text: r.text,
-              sender: "received",
-              timestamp: new Date(r.timestamp).getTime()
-            }))
-          );
-        }
-      } catch {
+    if (replies.length > countedReplyCountRef.current) {
+      const newReplies = replies.slice(countedReplyCountRef.current);
+      countedReplyCountRef.current = replies.length;
+      if (!isOpen) {
+        setUnreadCount((prev) => prev + newReplies.length);
+        setPendingReplies((prev) => [...prev, ...newReplies]);
       }
-    };
-    void fetchReplies();
-    const intervalId = setInterval(() => void fetchReplies(), POLL_INTERVAL2);
-    return () => {
-      cancelled = true;
-      clearInterval(intervalId);
-    };
-  }, [repliesUrl, isOpen, user]);
-  const unreadCount = baselineCountRef.current !== null ? Math.max(0, totalCountRef.current - baselineCountRef.current) : 0;
-  return {
-    unreadCount,
-    hasUnread: unreadCount > 0,
-    pendingReplies: allReplies,
-    markAsRead
-  };
+    }
+  }, [replies, isOpen]);
+  return { unreadCount, hasUnread: unreadCount > 0, pendingReplies, markAsRead, transport };
 }
 
-export { ChatBubble, SupportChatModal, collectAnonymousContext, getSessionId, useChatEngine, useSupportChat, useUnreadCount };
+export { ChatBubble, SupportChatModal, collectAnonymousContext, getSessionId, useChatEngine, useReplyTransport, useSupportChat, useUnreadCount };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map