@aslaluroba/help-center-react 3.2.4 → 3.2.5

package/package.json

@@ -3,7 +3,7 @@
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
-  "version": "3.2.4",
+  "version": "3.2.5",
   "description": "BabylAI Help Center Widget for React and Next.js",
   "private": false,
   "exports": {

package/src/core/AblyService.ts

@@ -1,13 +1,22 @@
 import * as Ably from 'ably';
 
+type ActionHandlerCallback = (actionType: string | undefined | null, messageData: any) => void | Promise<void>;
+
 export class ClientAblyService {
   private static client: Ably.Realtime | null = null;
   private static channel: Ably.RealtimeChannel | null = null;
   private static isConnected: boolean = false;
   private static sessionId: string | null = null;
   private static messageUnsubscribe: (() => void) | null = null;
-
-  static async startConnection(sessionId: string, ablyToken: string, onMessageReceived: Function, tenantId: string) {
+  private static onActionReceived: ActionHandlerCallback | null = null;
+
+  static async startConnection(
+    sessionId: string,
+    ablyToken: string,
+    onMessageReceived: Function,
+    tenantId: string,
+    onActionReceived?: ActionHandlerCallback
+  ) {
     // Prevent multiple connections
     if (this.isConnected && this.sessionId === sessionId) {
       return;
@@ -73,6 +82,9 @@ export class ClientAblyService {
         }, 10000);
       });
 
+      // Store optional action handler for this connection
+      this.onActionReceived = onActionReceived ?? null;
+
       // Subscribe to the session room
       await this.joinChannel(sessionId, onMessageReceived, tenantId);
     } catch (error) {
@@ -108,11 +120,17 @@ export class ClientAblyService {
       this.channel.subscribe('ReceiveMessage', (message) => {
         try {
           // Ensure messageContent is always a string (default to empty string if undefined)
+          const rawData = message.data;
+
           const messageContent =
-            typeof message.data === 'string' ? message.data : message.data?.content ?? message.data?.message ?? '';
-          const senderType = message.data?.senderType || 3; // Assistant
-          const needsAgent = message.data?.needsAgent || message.data?.actionType == 'needs_agent' || false;
-          const attachments = message.data?.attachments || [];
+            typeof rawData === 'string' ? rawData : rawData?.content ?? rawData?.message ?? '';
+          const senderType = rawData?.senderType || 3; // Assistant
+          const needsAgent = rawData?.needsAgent || rawData?.actionType == 'needs_agent' || false;
+          const attachments = rawData?.attachments || [];
+          const actionType = (rawData && typeof rawData.actionType === 'string' ? rawData.actionType : '') as
+            | string
+            | undefined
+            | null;
 
           // Extract downloadUrl from attachments (Ably now returns downloadUrl directly)
           // Attachments can be: strings (URLs), objects with downloadUrl, or objects with id
@@ -133,6 +151,19 @@ export class ClientAblyService {
             })
             .filter((url: string | null): url is string => url !== null);
 
+          // Invoke optional action handler first (non-blocking for message processing)
+          if (this.onActionReceived && actionType !== undefined) {
+            try {
+              void this.onActionReceived(actionType, rawData);
+            } catch (actionError) {
+              console.error('[AblyService] Error in action handler callback', {
+                error: actionError,
+                actionType,
+                rawData,
+              });
+            }
+          }
+
           onMessageReceived(messageContent, senderType, needsAgent, attachmentUrls);
         } catch (error) {
           console.error('[AblyService] Error processing message', { error, message });
@@ -166,6 +197,7 @@ export class ClientAblyService {
 
       this.isConnected = false;
       this.sessionId = null;
+      this.onActionReceived = null;
     } catch (error) {
       console.error('[AblyService] Error in stopConnection', { error });
       // Reset state even if there's an error

package/src/lib/custom-hooks/useActionHandler.ts

@@ -0,0 +1,102 @@
+import { useCallback, useRef } from 'react';
+
+export type ActionHandler = (messageData: unknown) => void | Promise<void>;
+
+export interface ActionHandlerService {
+  registerHandler(actionType: string, handler: ActionHandler): void;
+  unregisterHandler(actionType: string): void;
+  handleAction(actionType: string | undefined | null, messageData: unknown): Promise<void>;
+  getRegisteredActions(): string[];
+}
+
+export const useActionHandler = (): ActionHandlerService => {
+  const handlersRef = useRef<Map<string, ActionHandler>>(new Map());
+
+  const defaultHandlerRef = useRef<ActionHandler>((messageData) => {
+    const message = (messageData as { actionType?: string } | undefined) ?? {};
+    const actionType = message.actionType || '';
+
+    if (actionType) {
+      // Log unknown actions for debugging but do not crash
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[ActionHandler] Unknown action type received: "${actionType}". Message data:`,
+        messageData
+      );
+    }
+  });
+
+  const registerHandler = useCallback((actionType: string, handler: ActionHandler) => {
+    if (!actionType) {
+      // eslint-disable-next-line no-console
+      console.warn('[ActionHandler] Attempted to register handler with empty action type. Ignored.');
+      return;
+    }
+
+    if (handlersRef.current.has(actionType)) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[ActionHandler] Handler for action type "${actionType}" already exists. Overwriting with new handler.`
+      );
+    }
+
+    handlersRef.current.set(actionType, handler);
+  }, []);
+
+  const unregisterHandler = useCallback((actionType: string) => {
+    if (!actionType) {
+      return;
+    }
+    handlersRef.current.delete(actionType);
+  }, []);
+
+  const handleAction = useCallback(
+    async (actionType: string | undefined | null, messageData: unknown) => {
+      // Ignore empty, null, or undefined action types (no-op)
+      if (!actionType || actionType === '') {
+        return;
+      }
+
+      const handler = handlersRef.current.get(actionType);
+
+      if (handler) {
+        try {
+          await handler(messageData);
+        } catch (error) {
+          // eslint-disable-next-line no-console
+          console.error(
+            `[ActionHandler] Error executing handler for action type "${actionType}":`,
+            error
+          );
+        }
+        return;
+      }
+
+      const defaultHandler = defaultHandlerRef.current;
+      if (defaultHandler) {
+        try {
+          await Promise.resolve(defaultHandler(messageData));
+        } catch (error) {
+          // eslint-disable-next-line no-console
+          console.error(
+            `[ActionHandler] Error executing default handler for unknown action type "${actionType}":`,
+            error
+          );
+        }
+      }
+    },
+    []
+  );
+
+  const getRegisteredActions = useCallback(() => {
+    return Array.from(handlersRef.current.keys());
+  }, []);
+
+  return {
+    registerHandler,
+    unregisterHandler,
+    handleAction,
+    getRegisteredActions,
+  };
+};
+

package/src/lib/index.ts

@@ -1,3 +1,4 @@
 export * from "./LanguageContext";
 export * from "./utils";
 export * from "./theme-utils";
+export * from "./custom-hooks/useActionHandler";

package/src/ui/help-center.tsx

@@ -1,5 +1,5 @@
 import ReviewDialog from '@/ui/review-dialog';
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { apiRequest } from '../core/api';
 import { ClientAblyService } from '../core/AblyService';
 import { useLocalTranslation } from '../useLocalTranslation';
@@ -11,6 +11,7 @@ import HelpPopup from './help-popup';
 import { defaultLanguage } from '@/i18n';
 import { LanguageProvider } from '@/lib/LanguageContext';
 import { getThemeStyles } from '@/lib/theme-utils';
+import { useActionHandler } from '@/lib/custom-hooks/useActionHandler';
 
 interface HelpCenterProps {
   helpScreenId: string;
@@ -57,6 +58,8 @@ const HelpCenterContent = ({
   const [assistantStatus, setAssistantStatus] = useState('idle');
   const [isReviewDialogOpen, setIsReviewDialogOpen] = useState(false);
 
+  const actionHandler = useActionHandler();
+
   const handleTogglePopup = () => {
     setIsOpen(!isOpen);
     setShowArrowAnimation(isOpen);
@@ -93,7 +96,7 @@ const HelpCenterContent = ({
     setAssistantStatus('idle');
   };
 
-  const handleEndChat = async () => {
+  const handleEndChat = useCallback(async () => {
     if (!sessionId || !selectedOption) return;
 
     try {
@@ -123,7 +126,7 @@ const HelpCenterContent = ({
       setSessionId(null);
       setSelectedOption(null);
     }
-  };
+  }, [language, selectedOption, sessionId]);
 
   const handleSendChatReview = async ({ comment, rating }: ReviewProps) => {
     if (!reviewSessionId) return;
@@ -195,7 +198,10 @@ const HelpCenterContent = ({
         newSessionId,
         responseData.ablyToken,
         handleReceiveMessage,
-        responseData.chatSession.tenantId
+        responseData.chatSession.tenantId,
+        (actionType, messageData) => {
+          void actionHandler.handleAction(actionType, messageData);
+        }
       );
 
       // Verify the connection is actually active
@@ -297,6 +303,25 @@ const HelpCenterContent = ({
     }
   };
 
+  // Register known action handlers for realtime messages
+  useEffect(() => {
+    // "needs_agent" → trigger handoff / needs agent UI flow
+    actionHandler.registerHandler('needs_agent', () => {
+      setNeedsAgent(true);
+    });
+
+    // "end_session" → gracefully close the chat session and show review dialog
+    actionHandler.registerHandler('end_session', () => {
+      // Reuse existing end chat logic
+      void handleEndChat();
+    });
+
+    return () => {
+      actionHandler.unregisterHandler('needs_agent');
+      actionHandler.unregisterHandler('end_session');
+    };
+  }, [actionHandler, handleEndChat]);
+
   useEffect(() => {
     if (isOpen && helpScreenId) {
       setStatus('loading');