keystone-design-bootstrap 1.0.85 → 1.0.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keystone-design-bootstrap",
-  "version": "1.0.85",
+  "version": "1.0.86",
   "description": "Keystone Design Bootstrap - Sections, Elements, and Theme System for customer websites",
   "type": "module",
   "main": "./src/index.ts",
@@ -64,6 +64,7 @@
     "@fontsource/montserrat": "^5.2.8",
     "@fontsource/playfair-display": "^5.2.8",
     "@fontsource/poppins": "^5.2.7",
+    "@rails/actioncable": "^8.1.300",
     "@untitledui/file-icons": "^0.0.9",
     "@untitledui/icons": "^0.0.20",
     "clsx": "^2.1.1",
@@ -79,6 +80,7 @@
   },
   "devDependencies": {
     "@types/node": "^20",
+    "@types/rails__actioncable": "^8.0.3",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "eslint": "^9",

package/src/design_system/chat/useRealtimeReplyOrchestrator.ts

@@ -0,0 +1,127 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+import { createConsumer } from '@rails/actioncable';
+
+export interface RealtimeSubscriptionData {
+  token: string;
+  contact_id: number;
+  cable_url: string;
+}
+
+interface UseRealtimeReplyOrchestratorOptions {
+  debugLabel: string;
+  fetchRealtimeData: () => Promise<RealtimeSubscriptionData | null>;
+  loadLatestHasReply: () => Promise<boolean>;
+  onReplyResolved: () => void;
+  onAgentThinking?: () => void;
+}
+
+export function useRealtimeReplyOrchestrator({
+  debugLabel,
+  fetchRealtimeData,
+  loadLatestHasReply,
+  onReplyResolved,
+  onAgentThinking,
+}: UseRealtimeReplyOrchestratorOptions) {
+  const cableRef = useRef<ReturnType<typeof createConsumer> | null>(null);
+  const subscriptionRef = useRef<{ unsubscribe: () => void } | null>(null);
+  const subscribedContactRef = useRef<number | null>(null);
+
+  const clearRealtime = useCallback(() => {
+    if (subscriptionRef.current) {
+      subscriptionRef.current.unsubscribe();
+      subscriptionRef.current = null;
+    }
+    if (cableRef.current) {
+      cableRef.current.disconnect();
+      cableRef.current = null;
+    }
+    subscribedContactRef.current = null;
+  }, []);
+
+  const resolveReply = useCallback(() => {
+    onReplyResolved();
+  }, [onReplyResolved]);
+
+  const subscribeRealtime = useCallback((realtime: RealtimeSubscriptionData) => {
+    const token = realtime.token;
+    const contactIdForStream = realtime.contact_id;
+    const cableUrl = realtime.cable_url;
+    if (!token || !contactIdForStream || !cableUrl) return;
+
+    if (
+      subscribedContactRef.current === contactIdForStream &&
+      subscriptionRef.current &&
+      cableRef.current
+    ) {
+      return;
+    }
+
+    clearRealtime();
+
+    const cable = createConsumer(`${cableUrl}?token=${encodeURIComponent(token)}`);
+    cableRef.current = cable;
+    subscribedContactRef.current = contactIdForStream;
+    subscriptionRef.current = cable.subscriptions.create(
+      { channel: 'ContactCommunicationsChannel', contact_id: String(contactIdForStream) },
+      {
+        connected: () => {
+          console.info(`[${debugLabel}] realtime connected contact_id=${contactIdForStream}`);
+        },
+        disconnected: () => {
+          console.warn(`[${debugLabel}] realtime disconnected contact_id=${contactIdForStream}`);
+        },
+        rejected: () => {
+          console.warn(`[${debugLabel}] realtime rejected contact_id=${contactIdForStream}`);
+        },
+        received: async (data: { type?: string }) => {
+          console.info(`[${debugLabel}] realtime received type=${data?.type ?? 'unknown'} contact_id=${contactIdForStream}`);
+          if (data?.type === 'agent_thinking') {
+            onAgentThinking?.();
+            return;
+          }
+          if (data?.type !== 'new_communication') return;
+          try {
+            const hasReply = await loadLatestHasReply();
+            if (hasReply) {
+              resolveReply();
+            }
+          } catch (error) {
+            console.error(`[${debugLabel}] realtime receive handling error`, error);
+          }
+        },
+      }
+    );
+  }, [clearRealtime, debugLabel, loadLatestHasReply, onAgentThinking, resolveReply]);
+
+  const ensureRealtimeSubscription = useCallback(async () => {
+    try {
+      const realtime = await fetchRealtimeData();
+      if (!realtime) return;
+      subscribeRealtime(realtime);
+    } catch {
+      // Realtime is best-effort; UI remains in waiting state until connection succeeds.
+    }
+  }, [fetchRealtimeData, subscribeRealtime]);
+
+  const beginReplyWait = useCallback((options?: { realtimeData?: RealtimeSubscriptionData | null }) => {
+    if (options?.realtimeData) {
+      subscribeRealtime(options.realtimeData);
+    } else {
+      void ensureRealtimeSubscription();
+    }
+  }, [ensureRealtimeSubscription, subscribeRealtime]);
+
+  useEffect(() => {
+    return () => {
+      clearRealtime();
+    };
+  }, [clearRealtime]);
+
+  return {
+    ensureRealtimeSubscription,
+    subscribeRealtime,
+    beginReplyWait,
+  };
+}

package/src/design_system/components/ChatWidget.tsx

@@ -5,6 +5,7 @@ import { X, MessageChatSquare } from '@untitledui/icons';
 import { Avatar } from '../elements/avatar/avatar';
 import { cx } from '../../utils/cx';
 import { captureEvent } from '../../tracking/captureEvent';
+import { useRealtimeReplyOrchestrator, type RealtimeSubscriptionData } from '../chat/useRealtimeReplyOrchestrator';
 
 interface Message {
   id: string;
@@ -126,47 +127,55 @@ export function ChatWidget({
     messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
   }, [messages]);
 
-  // Poll for agent reply (simpler than WebSockets for public widget)
-  const pollIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
-
-  // Clear any in-flight poll on unmount
-  useEffect(() => {
-    return () => {
-      if (pollIntervalRef.current !== null) {
-        clearInterval(pollIntervalRef.current);
-      }
-    };
+  const hasAgentReplyWithBody = useCallback((list: Message[]) => {
+    const latest = list[list.length - 1];
+    return (
+      latest?.sender_type === 'agent' &&
+      latest?.body != null &&
+      String(latest.body).trim() !== ''
+    );
   }, []);
 
-  const pollForAgentReply = () => {
-    setWaitingForReply(true);
-
-    let attempts = 0;
-    const maxAttempts = 30;
-
-    pollIntervalRef.current = setInterval(async () => {
-      attempts++;
+  const fetchRealtimeData = useCallback(async (): Promise<RealtimeSubscriptionData | null> => {
+    if (!contactId && !sessionId) return null;
+    const query = contactId
+      ? `contact_id=${encodeURIComponent(contactId)}`
+      : `identifier=${encodeURIComponent(sessionId)}`;
+    const response = await fetch(`/api/chat/?action=realtime_token&${query}`);
+    if (!response.ok) return null;
+    const result = await response.json();
+    const token = result?.data?.token as string | undefined;
+    const contactIdForStream = result?.data?.contact_id as number | undefined;
+    const cableUrl = result?.data?.cable_url as string | undefined;
+    if (!token || !contactIdForStream || !cableUrl) return null;
+    return { token, contact_id: contactIdForStream, cable_url: cableUrl };
+  }, [contactId, sessionId]);
 
-      try {
-        const newMessages = await loadMessages();
+  const {
+    beginReplyWait,
+    ensureRealtimeSubscription,
+  } = useRealtimeReplyOrchestrator({
+    debugLabel: 'ChatWidget',
+    fetchRealtimeData,
+    loadLatestHasReply: async () => hasAgentReplyWithBody(await loadMessages()),
+    onReplyResolved: () => {
+      setWaitingForReply(false);
+      setIsLoading(false);
+    },
+    onAgentThinking: () => {
+      setWaitingForReply(true);
+    },
+  });
 
-        const latest = newMessages[newMessages.length - 1];
-        const hasAgentReplyWithBody =
-          latest?.sender_type === 'agent' &&
-          latest?.body != null &&
-          String(latest.body).trim() !== '';
+  const hasPersistedMessages = messages.some((message) => !String(message.id).startsWith('temp_'));
 
-        if (hasAgentReplyWithBody || attempts >= maxAttempts) {
-          clearInterval(pollIntervalRef.current!);
-          pollIntervalRef.current = null;
-          setWaitingForReply(false);
-          setIsLoading(false);
-        }
-      } catch (error) {
-        console.error('[ChatWidget] Error polling for messages:', error);
-      }
-    }, 1000);
-  };
+  useEffect(() => {
+    if (!isOpen || (!contactId && !sessionId)) return;
+    // Anonymous sessions do not have a contact row until the first message is sent.
+    // Ignore optimistic temp rows to avoid pre-contact token probes (404 noise).
+    if (!contactId && !hasPersistedMessages) return;
+    ensureRealtimeSubscription();
+  }, [contactId, ensureRealtimeSubscription, hasPersistedMessages, isOpen, sessionId]);
 
   const sendMessage = async () => {
     if (!inputValue.trim() || (!contactId && !sessionId)) return;
@@ -201,24 +210,36 @@ export function ChatWidget({
         captureEvent('chat_message_sent', { is_authenticated: Boolean(contactId) });
 
         if (result.data?.job_id) {
-          pollForAgentReply();
+          setWaitingForReply(true);
+          const realtimeFromSend = result.data?.realtime_token && result.data?.contact_id && result.data?.cable_url
+            ? {
+              token: result.data.realtime_token,
+              contact_id: result.data.contact_id,
+              cable_url: result.data.cable_url,
+            }
+            : null;
+          beginReplyWait({ realtimeData: realtimeFromSend });
         } else if (result.data?.status === 'agent_unavailable' || result.data?.status === 'no_auto_reply') {
           setIsLoading(false);
+          setWaitingForReply(false);
         } else {
           await loadMessages();
           setIsLoading(false);
+          setWaitingForReply(false);
         }
       } else {
         setMessages(prev => prev.filter(m => m.id !== tempMessage.id));
         captureEvent('chat_message_failed', { error: 'send_failed' });
         console.error('Failed to send message');
         setIsLoading(false);
+        setWaitingForReply(false);
       }
     } catch (error) {
       setMessages(prev => prev.filter(m => m.id !== tempMessage.id));
       captureEvent('chat_message_failed', { error: 'network_error' });
       console.error('Failed to send message:', error);
       setIsLoading(false);
+      setWaitingForReply(false);
     }
   };
 

package/src/design_system/portal/MessageComposer.tsx

@@ -1,7 +1,8 @@
 'use client';
 
-import React, { useState, useTransition, useRef, useEffect } from 'react';
+import React, { useState, useTransition, useRef, useEffect, useCallback } from 'react';
 import { useRouter } from 'next/navigation';
+import { useRealtimeReplyOrchestrator, type RealtimeSubscriptionData } from '../chat/useRealtimeReplyOrchestrator';
 
 export function MessageComposer({ contactId }: { contactId: number }) {
   const [body, setBody] = useState('');
@@ -10,6 +11,42 @@ export function MessageComposer({ contactId }: { contactId: number }) {
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const router = useRouter();
 
+  const hasAgentReplyWithBody = useCallback(async () => {
+    const response = await fetch(`/api/chat/?contact_id=${encodeURIComponent(contactId)}`);
+    if (!response.ok) return false;
+    const result = await response.json();
+    const messages = (result?.data || []) as Array<{ sender_type?: string; body?: string | null }>;
+    const latest = messages[messages.length - 1];
+    return (
+      latest?.sender_type === 'agent' &&
+      latest?.body != null &&
+      String(latest.body).trim() !== ''
+    );
+  }, [contactId]);
+
+  const fetchRealtimeData = useCallback(async (): Promise<RealtimeSubscriptionData | null> => {
+    const response = await fetch(`/api/chat/?action=realtime_token&contact_id=${encodeURIComponent(contactId)}`);
+    if (!response.ok) return null;
+    const result = await response.json();
+    const token = result?.data?.token as string | undefined;
+    const streamContactId = result?.data?.contact_id as number | undefined;
+    const cableUrl = result?.data?.cable_url as string | undefined;
+    if (!token || !streamContactId || !cableUrl) return null;
+    return { token, contact_id: streamContactId, cable_url: cableUrl };
+  }, [contactId]);
+
+  const {
+    beginReplyWait,
+    ensureRealtimeSubscription,
+  } = useRealtimeReplyOrchestrator({
+    debugLabel: 'MessageComposer',
+    fetchRealtimeData,
+    loadLatestHasReply: hasAgentReplyWithBody,
+    onReplyResolved: () => {
+      router.refresh();
+    },
+  });
+
   // Auto-resize textarea
   useEffect(() => {
     const el = textareaRef.current;
@@ -18,6 +55,10 @@ export function MessageComposer({ contactId }: { contactId: number }) {
     el.style.height = `${Math.min(el.scrollHeight, 120)}px`;
   }, [body]);
 
+  useEffect(() => {
+    void ensureRealtimeSubscription();
+  }, [ensureRealtimeSubscription]);
+
   function submit() {
     if (!body.trim() || isPending) return;
     setError(null);
@@ -34,6 +75,17 @@ export function MessageComposer({ contactId }: { contactId: number }) {
         } else {
           setBody('');
           router.refresh();
+          const hasBackgroundReplyJob = Boolean(result?.data?.job_id);
+          if (hasBackgroundReplyJob) {
+            const realtimeFromSend = result?.data?.realtime_token && result?.data?.contact_id && result?.data?.cable_url
+              ? {
+                token: result.data.realtime_token,
+                contact_id: result.data.contact_id,
+                cable_url: result.data.cable_url,
+              }
+              : null;
+            beginReplyWait({ realtimeData: realtimeFromSend });
+          }
         }
       } catch {
         setError('Failed to send message.');

package/src/next/routes/chat.ts

@@ -25,9 +25,22 @@ import { clientContextHeaders } from './proxy-headers';
 
 const API_URL = process.env.API_URL || 'http://localhost:3000/api/v1';
 const API_KEY = process.env.API_KEY || '';
+const CONSUMER_TOKEN_COOKIE = 'ks_consumer_token';
 
 type JsonResponder = (body: unknown, init?: ResponseInit) => Response;
 
+function cookieValue(cookieHeader: string | null, key: string): string | null {
+  if (!cookieHeader) return null;
+  const token = cookieHeader
+    .split(';')
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${key}=`))
+    ?.split('=')
+    .slice(1)
+    .join('=');
+  return token ? decodeURIComponent(token) : null;
+}
+
 export function createChatRouteHandlers(deps?: { NextResponse?: { json: JsonResponder } }) {
   const json: JsonResponder = deps?.NextResponse?.json ?? ((body, init) => Response.json(body, init));
 
@@ -65,7 +78,9 @@ export function createChatRouteHandlers(deps?: { NextResponse?: { json: JsonResp
             { status: response.status }
           );
         }
-        return json({ success: true, data: data.data });
+        const responseData = data.data || {};
+        const cableUrl = API_URL.replace(/\/api\/v1\/?$/, '').replace(/^http/, 'ws') + '/cable';
+        return json({ success: true, data: { ...responseData, cable_url: cableUrl } });
       } catch (error) {
         console.error('Chat message error:', error);
         return json({ success: false, error: 'Network error. Please try again later.' }, { status: 500 });
@@ -76,9 +91,50 @@ export function createChatRouteHandlers(deps?: { NextResponse?: { json: JsonResp
     GET: async (request: Request): Promise<Response> => {
       try {
         const { searchParams } = new URL(request.url);
+        const action = searchParams.get('action');
         const identifier = searchParams.get('identifier');
         const contactId = searchParams.get('contact_id');
 
+        if (action === 'realtime_token') {
+          if (!identifier && !contactId) {
+            return json({ success: false, error: 'identifier or contact_id is required for realtime token.' }, { status: 400 });
+          }
+
+          const response = contactId
+            ? await (async () => {
+                const consumerToken = cookieValue(request.headers.get('cookie'), CONSUMER_TOKEN_COOKIE);
+                if (!consumerToken) {
+                  return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+                    status: 401,
+                    headers: { 'Content-Type': 'application/json' },
+                  });
+                }
+                return fetch(
+                  `${API_URL}/consumer/me/contacts/${encodeURIComponent(contactId)}/realtime_token`,
+                  {
+                    headers: {
+                      Authorization: `Bearer ${consumerToken}`,
+                      ...(API_KEY ? { 'X-API-Key': API_KEY } : {}),
+                    },
+                  }
+                );
+              })()
+            : await fetch(
+                `${API_URL}/public/messages/realtime_token?identifier=${encodeURIComponent(identifier!)}`,
+                { headers: { 'X-API-Key': API_KEY } }
+              );
+          const data = await response.json();
+          if (!response.ok) {
+            return json(
+              { success: false, error: data.error || 'Failed to create realtime token.' },
+              { status: response.status }
+            );
+          }
+
+          const cableUrl = API_URL.replace(/\/api\/v1\/?$/, '').replace(/^http/, 'ws') + '/cable';
+          return json({ success: true, data: { ...(data.data || {}), cable_url: cableUrl } });
+        }
+
         if (!identifier && !contactId) {
           return json({ success: false, error: 'identifier or contact_id is required.' }, { status: 400 });
         }