@peopl-health/nexus 3.6.2 → 3.7.0

package/examples/basic-usage.js

@@ -81,12 +81,28 @@ async function startServer() {
     apiVersion: process.env.META_API_VERSION || 'v21.0'
   });
 
+  // Example: postBatch hooks for running classifiers after each batch completes
+  async function classifySymptoms({ chatId }) {
+    console.log(`[symptomClassifier] Running for ${chatId}`);
+    // Replace with actual classifier logic: check eligibility, fetch messages, classify via LLM, persist results
+    console.log(`[symptomClassifier] Done for ${chatId}`);
+  }
+
+  async function classifyEscalation({ chatId }) {
+    console.log(`[escalationRouting] Running for ${chatId}`);
+    // Replace with actual classifier logic: extract batch, resolve active assistant, classify and route
+    console.log(`[escalationRouting] Done for ${chatId}`);
+  }
+
   // Initialize Nexus with check-after processing (immediate response, checks for new messages after)
   const nexus = new Nexus({
     messaging: {
       messageBatching: {
         enabled: true,           // Enable check-after processing
-        checkDelayMs: 100        // Delay before checking for new messages (ms)
+        checkDelayMs: 100,       // Delay before checking for new messages (ms)
+        hooks: {
+          postBatch: [classifySymptoms, classifyEscalation],
+        }
       }
     }
   });

package/lib/core/BatchingManager.js

@@ -1,8 +1,10 @@
 const { logger } = require('../utils/logger');
 const { Message } = require('../models/messageModel');
 
+const VALID_HOOKS = ['preBatch', 'postBatch', 'onBatchError'];
+
 /**
- * Manages message batching, processing locks, and run abandonment.
+ * Manages message batching, processing locks, run abandonment, and lifecycle hooks.
  */
 class BatchingManager {
   constructor({ provider = null, config = {} }) {
@@ -18,6 +20,32 @@ class BatchingManager {
     this.activeRequests = new Map();
     this.abandonedRuns = new Set();
     this.typingIntervals = new Map();
+
+    this._hooks = {
+      preBatch: [],
+      postBatch: [],
+      onBatchError: [],
+    };
+
+    if (config.hooks) {
+      for (const [name, handlers] of Object.entries(config.hooks)) {
+        const fns = Array.isArray(handlers) ? handlers : [handlers];
+        for (const fn of fns) {
+          this.addHook(name, fn);
+        }
+      }
+    }
+  }
+
+  addHook(name, fn) {
+    if (!VALID_HOOKS.includes(name)) {
+      throw new Error(`[BatchingManager] Unknown hook: "${name}". Valid hooks: ${VALID_HOOKS.join(', ')}`);
+    }
+    if (typeof fn !== 'function') {
+      throw new Error(`[BatchingManager] Hook "${name}" must be a function`);
+    }
+    this._hooks[name].push(fn);
+    return this;
   }
 
   setProvider(provider) {
@@ -57,6 +85,12 @@ class BatchingManager {
     this.activeRequests.set(chatId, runId);
 
     try {
+      const pre = await this._runSequentialHooks(chatId, runId);
+      if (pre?.skip) {
+        logger.debug('[BatchingManager] Batch skipped by preBatch hook', { chatId, runId });
+        return;
+      }
+
       await this._startTypingRefresh(chatId, runId);
       if (this._checkAbandoned(runId)) return;
 
@@ -66,9 +100,11 @@ class BatchingManager {
       if (sendResponseFn && result) await sendResponseFn(result);
     } catch (error) {
       logger.error('[BatchingManager] Error processing messages', { chatId, error: error.message });
+      this._runDeferredHooks('onBatchError', chatId, error);
     } finally {
       if (this.activeRequests.get(chatId) === runId) {
         this._clearProcessingState(chatId);
+        this._runDeferredHooks('postBatch', chatId);
       }
       if (this.abandonedRuns.size > 100) {
         const toKeep = [...this.abandonedRuns].slice(-20);
@@ -84,6 +120,39 @@ class BatchingManager {
     this._stopTyping(chatId);
   }
 
+  async _runSequentialHooks(chatId, runId) {
+    const hooks = this._hooks.preBatch;
+    if (hooks.length === 0) return;
+
+    const context = { chatId, runId, metadata: {} };
+
+    for (const fn of hooks) {
+      const result = await fn(context);
+      if (result?.skip) return { skip: true };
+    }
+  }
+
+  _runDeferredHooks(name, chatId, error) {
+    const hooks = this._hooks[name];
+    if (hooks.length === 0) return;
+
+    setImmediate(() => {
+      if (this.isProcessing(chatId)) return;
+
+      const context = { chatId };
+      if (error) context.error = error;
+
+      Promise.allSettled(hooks.map(fn => fn(context)))
+        .then(results => {
+          for (const result of results) {
+            if (result.status === 'rejected') {
+              logger.error(`[BatchingManager] ${name} hook failed`, { chatId, error: result.reason?.message });
+            }
+          }
+        });
+    });
+  }
+
   _stopTyping(chatId) {
     const interval = this.typingIntervals.get(chatId);
     if (interval) {

package/lib/core/NexusMessaging.js

@@ -59,7 +59,8 @@ class NexusMessaging {
       enabled: config.messageBatching?.enabled ?? true,
       abortOnNewMessage: config.messageBatching?.abortOnNewMessage ?? true,
       immediateRestart: config.messageBatching?.immediateRestart ?? true,
-      typingIndicator: config.messageBatching?.typingIndicator ?? false
+      typingIndicator: config.messageBatching?.typingIndicator ?? false,
+      hooks: config.messageBatching?.hooks || {},
     };
 
     this.batchingManager = new BatchingManager({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "3.6.2",
+  "version": "3.7.0",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",