keystone-design-bootstrap 1.0.104 → 1.0.105-dev.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keystone-design-bootstrap",
-  "version": "1.0.104",
+  "version": "1.0.105-dev.0",
   "description": "Keystone Design Bootstrap - Sections, Elements, and Theme System for customer websites",
   "type": "module",
   "main": "./src/index.ts",

package/src/design_system/components/ChatWidget.tsx

@@ -7,6 +7,7 @@ import { cx } from '../../utils/cx';
 import { captureEvent } from '../../tracking/captureEvent';
 import { useRealtimeReplyOrchestrator, type RealtimeSubscriptionData } from '../chat/useRealtimeReplyOrchestrator';
 import { error as logError } from '../../tracking/logging';
+import { RAILS_BACKEND, SOR_BACKEND, type ChatBackend } from '../../lib/chat-backend';
 
 interface Message {
   id: string;
@@ -25,6 +26,18 @@ interface TeamMember {
 
 interface ChatWidgetProps {
   position?: 'bottom-right' | 'bottom-left';
+  /**
+   * Which backend the site's `/api/chat` proxy talks to. The two backends have
+   * architecturally different reply delivery: 'rails' (keystone-mono-proto)
+   * pushes replies over ActionCable realtime; 'sor' (sor-service) has no
+   * realtime channel and the widget polls for the reply instead. The paths are
+   * mutually exclusive — a 'sor' widget never probes/subscribes realtime, a
+   * 'rails' widget never polls.
+   *
+   * TODO(webchat): default is 'rails' while keystone-mono-proto is still a live
+   * backend; flip the default to 'sor' once the Rails backend is scrapped.
+   */
+  chatBackend?: ChatBackend;
   primaryColor?: string;
   /**
    * Anonymous session identifier. Used when the visitor is not authenticated.
@@ -66,6 +79,7 @@ const formatTime = (isoString: string) => {
 export function ChatWidget({
   position = 'bottom-right',
   primaryColor,
+  chatBackend = RAILS_BACKEND,
   sessionId: providedSessionId,
   contactId,
   displayName: providedDisplayName,
@@ -146,7 +160,10 @@ export function ChatWidget({
     );
   }, []);
 
+  const isSorBackend = chatBackend === SOR_BACKEND;
+
   const fetchRealtimeData = useCallback(async (): Promise<RealtimeSubscriptionData | null> => {
+    if (isSorBackend) return null; // sor has no realtime channel — never probe
     if (!contactId && !sessionId) return null;
     const query = contactId
       ? `contact_id=${encodeURIComponent(contactId)}`
@@ -159,7 +176,7 @@ export function ChatWidget({
     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]);
+  }, [contactId, isSorBackend, sessionId]);
 
   const {
     beginReplyWait,
@@ -179,13 +196,48 @@ export function ChatWidget({
 
   const hasPersistedMessages = messages.some((message) => !String(message.id).startsWith('temp_'));
 
+  // rails reply delivery: ActionCable realtime subscription.
   useEffect(() => {
+    if (isSorBackend) return;
     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]);
+  }, [contactId, ensureRealtimeSubscription, hasPersistedMessages, isOpen, isSorBackend, sessionId]);
+
+  // sor reply delivery: no realtime channel exists, so while waiting for the
+  // agent reply, poll the thread and resolve as soon as an agent message with
+  // a body lands (or after a timeout). Never runs for the rails backend.
+  useEffect(() => {
+    if (!isSorBackend || !waitingForReply) return;
+    let cancelled = false;
+    let inFlight = false; // don't stack requests when a poll outlives the interval
+    let attempts = 0;
+    const maxAttempts = 40; // ~60s at 1.5s
+    const interval = setInterval(async () => {
+      if (inFlight) return;
+      inFlight = true;
+      attempts += 1;
+      try {
+        const msgs = await loadMessages();
+        if (cancelled) return;
+        if (hasAgentReplyWithBody(msgs) || attempts >= maxAttempts) {
+          clearInterval(interval);
+          setWaitingForReply(false);
+          setIsLoading(false);
+        }
+      } catch {
+        // transient — keep polling until maxAttempts
+      } finally {
+        inFlight = false;
+      }
+    }, 1500);
+    return () => {
+      cancelled = true;
+      clearInterval(interval);
+    };
+  }, [isSorBackend, waitingForReply, loadMessages, hasAgentReplyWithBody]);
 
   const sendMessage = async () => {
     if (!inputValue.trim() || (!contactId && !sessionId)) return;
@@ -220,15 +272,19 @@ export function ChatWidget({
         captureEvent('chat_message_sent', { is_authenticated: Boolean(contactId) });
 
         if (result.data?.job_id) {
+          // setWaitingForReply arms the sor polling effect; rails additionally
+          // subscribes to the realtime channel for push delivery.
           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 });
+          if (!isSorBackend) {
+            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);

package/src/lib/chat-backend.ts

@@ -0,0 +1,36 @@
+/**
+ * Which chat backend the site's /api/chat proxy targets.
+ *
+ * The two backends have architecturally different webchat contracts:
+ * - 'rails' (keystone-mono-proto): /public/messages + ActionCable realtime.
+ * - 'sor'   (sor-service): /public/chat/* + widget long-polling.
+ *
+ * Resolution order:
+ * 1. CHAT_BACKEND env ('rails' | 'sor') — explicit override; needed for
+ *    custom domains or local dev, where the API_URL hostname carries no signal.
+ * 2. Derived from API_URL: a hostname containing a `sor` label
+ *    (sor.localkeystone.com, sor.dev.localkeystone.com, …) ⇒ 'sor'.
+ * 3. Default 'rails'.
+ *
+ * TODO(webchat): default is 'rails' while keystone-mono-proto is still a live
+ * backend; flip the default to 'sor' once the Rails backend is scrapped.
+ */
+import { serverError } from './server-log';
+
+export const RAILS_BACKEND = 'rails' as const;
+export const SOR_BACKEND = 'sor' as const;
+export type ChatBackend = typeof RAILS_BACKEND | typeof SOR_BACKEND;
+
+export function resolveChatBackend(): ChatBackend {
+  const explicit = process.env.CHAT_BACKEND;
+  if (explicit === SOR_BACKEND || explicit === RAILS_BACKEND) return explicit;
+
+  const apiUrl = process.env.API_URL || '';
+  try {
+    const host = new URL(apiUrl).hostname;
+    if (host.split('.').includes(SOR_BACKEND)) return SOR_BACKEND;
+  } catch (error) {
+    serverError('CHAT_BACKEND_API_URL_PARSE_ERROR', error, { apiUrl });
+  }
+  return RAILS_BACKEND;
+}

package/src/next/layouts/root-layout.tsx

@@ -11,6 +11,7 @@ import {
   KeystoneAnalyticsTracker,
 } from '../../tracking';
 import { ChatWidget } from '../../design_system/components/ChatWidget';
+import { resolveChatBackend } from '../../lib/chat-backend';
 import { FormDefinitionsProvider } from '../contexts/form-definitions';
 import { KeystoneSSRProvider } from '../providers/ssr-provider';
 import {
@@ -182,6 +183,9 @@ j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
   const portalUrl = ci?.portal_url?.trim() || null;
   const bookingHref = portalUrl ?? externalManagementUrl ?? null;
   const chatEnabled = Boolean(ci?.chat_enabled);
+  // Which backend the site's /api/chat proxy targets — same resolution as the
+  // route handlers (CHAT_BACKEND override, else derived from API_URL).
+  const chatBackend = resolveChatBackend();
 
   const headerOverrides = options?.headerOverrides;
   const posthogHost = options?.posthogHost?.trim() || undefined;
@@ -229,6 +233,7 @@ j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
             {chatEnabled ? (
               <ChatWidget
                 position={options?.chatPosition || 'bottom-right'}
+                chatBackend={chatBackend}
                 teamMembers={teamMembers}
               />
             ) : null}

package/src/next/routes/chat.ts

@@ -5,13 +5,27 @@
  *   // app/api/chat/route.ts
  *   export { GET, POST } from 'keystone-design-bootstrap/next/routes/chat';
  *
- * Supports both anonymous (session-based) and authenticated (contact-driven) flows.
- * Both flows hit the same backend endpoint (`/public/messages`); the discriminator
- * is whether `identifier` (session string) or `contact_id` (integer) is supplied.
+ * Supports TWO backends, selected per site (default: 'rails', so existing
+ * consumers are unaffected):
+ *
+ *   createChatRouteHandlers({ backend: 'sor' })   // explicit option
+ *   CHAT_BACKEND=sor                              // env override
+ *   (otherwise derived from API_URL — a `sor` hostname label ⇒ 'sor';
+ *    see lib/chat-backend.ts)
+ *
+ * - 'rails' (keystone-mono-proto): anonymous (`identifier`) and authenticated
+ *   (`contact_id`) flows against `/public/messages`, plus the
+ *   `action=realtime_token` + `cable_url` flow that feeds ActionCable.
+ * - 'sor' (sor-service): anonymous webchat against `/public/chat/*` —
+ *   `session_id` (first-party cookie) + `{ messages, cursor }`, translated to
+ *   the widget's existing wire shape. No realtime; the widget's polling
+ *   fallback covers reply delivery. The `realtime_token` action returns an
+ *   empty payload (no `cable_url`) so the widget knows realtime is unavailable.
  *
  * Env (server-side only):
- * - API_URL (default: http://localhost:3000/api/v1)
- * - API_KEY
+ * - API_URL (default: http://localhost:3000/api/v1) — backend base, includes /api/v1
+ * - API_KEY                                          — business public key (X-API-Key)
+ * - CHAT_BACKEND ('rails' | 'sor', default 'rails')
  */
 
 // IMPORTANT:
@@ -23,28 +37,31 @@
 
 import { clientContextHeaders } from './proxy-headers';
 import { serverError } from '../../lib/server-log';
+import { resolveChatBackend, SOR_BACKEND, type ChatBackend } from '../../lib/chat-backend';
 
 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';
+const SESSION_COOKIE = 'ks_chat_session';
+
+export type { ChatBackend };
 
 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;
+function readCookie(request: Request, name: string): string | null {
+  const header = request.headers.get('cookie') || '';
+  for (const part of header.split(';')) {
+    const [k, ...v] = part.trim().split('=');
+    if (k === name) return decodeURIComponent(v.join('='));
+  }
+  return null;
 }
 
-export function createChatRouteHandlers(deps?: { NextResponse?: { json: JsonResponder } }) {
-  const json: JsonResponder = deps?.NextResponse?.json ?? ((body, init) => Response.json(body, init));
+/* ------------------------------------------------------------------------ *
+ * rails backend (keystone-mono-proto)
+ * ------------------------------------------------------------------------ */
 
+function createRailsHandlers(json: JsonResponder) {
   return {
     // POST /api/chat — send a message (session-based or contact-driven)
     POST: async (request: Request): Promise<Response> => {
@@ -103,7 +120,7 @@ export function createChatRouteHandlers(deps?: { NextResponse?: { json: JsonResp
 
           const response = contactId
             ? await (async () => {
-                const consumerToken = cookieValue(request.headers.get('cookie'), CONSUMER_TOKEN_COOKIE);
+                const consumerToken = readCookie(request, CONSUMER_TOKEN_COOKIE);
                 if (!consumerToken) {
                   return new Response(JSON.stringify({ error: 'Unauthorized' }), {
                     status: 401,
@@ -163,3 +180,183 @@ export function createChatRouteHandlers(deps?: { NextResponse?: { json: JsonResp
     },
   };
 }
+
+/* ------------------------------------------------------------------------ *
+ * sor backend (sor-service)
+ * ------------------------------------------------------------------------ */
+
+/**
+ * Real browser signals to forward upstream. sor-service reads the visitor IP
+ * from X-Forwarded-For, the user-agent from User-Agent, and fbp/fbc from the
+ * POST body — so we set the headers and return fbp/fbc for the body.
+ */
+function clientContext(request: Request): {
+  headers: Record<string, string>;
+  fbp?: string;
+  fbc?: string;
+} {
+  const ip =
+    request.headers.get('x-real-ip') ||
+    request.headers.get('x-forwarded-for')?.split(',')[0]?.trim();
+  const ua = request.headers.get('user-agent') || undefined;
+  const headers: Record<string, string> = {};
+  if (ip) headers['X-Forwarded-For'] = ip;
+  if (ua) headers['User-Agent'] = ua;
+  return {
+    headers,
+    fbp: readCookie(request, '_fbp') || undefined,
+    fbc: readCookie(request, '_fbc') || undefined,
+  };
+}
+
+function sessionCookieHeader(sessionId: string): string {
+  // First-party (set by the site's own origin via this proxy), so it survives
+  // third-party-cookie blocking. 1-year, lax, http-only.
+  return `${SESSION_COOKIE}=${encodeURIComponent(sessionId)}; Path=/; Max-Age=31536000; SameSite=Lax; HttpOnly`;
+}
+
+interface SorMessage {
+  id: string;
+  direction?: string;
+  sender_type?: string;
+  body?: string | null;
+  created_at?: string | null;
+}
+
+/** Translate a sor-service message to the widget's flat shape. */
+function toWidgetMessage(m: SorMessage) {
+  const isAgent = m.direction === 'OUTBOUND' || (!!m.sender_type && m.sender_type !== 'CONSUMER');
+  return {
+    id: m.id,
+    body: m.body ?? '',
+    sender_type: isAgent ? 'agent' : 'contact',
+    sender_display_name: isAgent ? 'Assistant' : 'You',
+    created_at: m.created_at ?? new Date().toISOString(),
+  };
+}
+
+function createSorHandlers(json: JsonResponder) {
+  return {
+    // POST /api/chat — send a message (anonymous session flow)
+    POST: async (request: Request): Promise<Response> => {
+      try {
+        const body = await request.json();
+        const {
+          identifier,
+          session_id,
+          body: messageBody,
+          display_name,
+          email,
+          phone,
+          first_name,
+          last_name,
+          page_url,
+        } = body;
+
+        if (!messageBody || !String(messageBody).trim()) {
+          return json({ success: false, error: 'Message body is required.' }, { status: 400 });
+        }
+        const sessionId = identifier || session_id || readCookie(request, SESSION_COOKIE);
+        if (!sessionId) {
+          return json({ success: false, error: 'identifier (session) is required.' }, { status: 400 });
+        }
+
+        const ctx = clientContext(request);
+        const response = await fetch(`${API_URL}/public/chat/messages`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'X-API-Key': API_KEY,
+            ...ctx.headers,
+          },
+          body: JSON.stringify({
+            session_id: sessionId,
+            body: messageBody,
+            display_name,
+            email,
+            phone,
+            first_name,
+            last_name,
+            page_url,
+            fbp: ctx.fbp,
+            fbc: ctx.fbc,
+          }),
+        });
+
+        const data = await response.json().catch(() => ({}));
+        if (!response.ok) {
+          return json(
+            { success: false, error: data?.message || 'Failed to send message. Please try again.' },
+            { status: response.status }
+          );
+        }
+
+        // Return a truthy `job_id` so the widget long-polls for the async AI
+        // reply — sentinel fallback because a falsy job_id would silently skip
+        // the reply wait (sor always dispatches the AI async).
+        const cursor = data?.data?.cursor ?? null;
+        return json(
+          { success: true, data: { job_id: cursor ?? 'pending', cursor } },
+          { headers: { 'Set-Cookie': sessionCookieHeader(sessionId) } }
+        );
+      } catch (error) {
+        serverError('CHAT_ROUTE_POST_ERROR', error);
+        return json({ success: false, error: 'Network error. Please try again later.' }, { status: 500 });
+      }
+    },
+
+    // GET /api/chat?identifier=... — load message history (flat array, widget shape)
+    GET: async (request: Request): Promise<Response> => {
+      try {
+        const { searchParams } = new URL(request.url);
+
+        // No ActionCable on sor-service: answer the widget's realtime probe with
+        // an empty payload (no cable_url) so it falls back to polling.
+        if (searchParams.get('action') === 'realtime_token') {
+          return json({ success: true, data: {} });
+        }
+
+        const sessionId =
+          searchParams.get('identifier') ||
+          searchParams.get('session_id') ||
+          readCookie(request, SESSION_COOKIE);
+
+        if (!sessionId) {
+          return json({ success: true, data: [] });
+        }
+
+        const query = new URLSearchParams({ session_id: sessionId, wait: '0' });
+        const since = searchParams.get('since');
+        if (since) query.set('since', since);
+
+        const response = await fetch(`${API_URL}/public/chat/messages?${query.toString()}`, {
+          headers: { 'X-API-Key': API_KEY },
+        });
+
+        const data = await response.json().catch(() => ({}));
+        if (!response.ok) {
+          return json(
+            { success: false, error: data?.message || 'Failed to load messages.' },
+            { status: response.status }
+          );
+        }
+
+        const messages = (data?.data?.messages ?? []) as SorMessage[];
+        return json({ success: true, data: messages.map(toWidgetMessage) });
+      } catch (error) {
+        serverError('CHAT_ROUTE_GET_ERROR', error);
+        return json({ success: false, error: 'Network error. Please try again later.' }, { status: 500 });
+      }
+    },
+  };
+}
+
+export function createChatRouteHandlers(deps?: {
+  NextResponse?: { json: JsonResponder };
+  backend?: ChatBackend;
+}) {
+  const json: JsonResponder = deps?.NextResponse?.json ?? ((body, init) => Response.json(body, init));
+  const backend: ChatBackend = deps?.backend ?? resolveChatBackend();
+
+  return backend === SOR_BACKEND ? createSorHandlers(json) : createRailsHandlers(json);
+}