@peopl-health/nexus 3.13.7 → 3.13.10

package/examples/basic-usage.js

@@ -81,7 +81,7 @@ async function startServer() {
     apiVersion: process.env.META_API_VERSION || 'v21.0'
   });
 
-  // Example: postBatch hooks for running classifiers after each batch completes
+  // Example: postProcess 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
@@ -94,7 +94,7 @@ async function startServer() {
     console.log(`[escalationRouting] Done for ${chatId}`);
   }
 
-  // Example: prePromptBuild hook for per-turn context injection. Runs right
+  // Example: preProcess hook for per-turn context injection. Runs right
   // before the assistant prompt is sent to the model. Use this to inject
   // per-turn instructions, escalation acknowledgments, runtime feature flags, etc.
   // Return { additionalInstructions, additionalMessages } to inject context,
@@ -104,7 +104,7 @@ async function startServer() {
   // salience option (developer message at the end of history). To test the
   // others, comment the active `return` and uncomment one of the alternatives.
   async function injectPromptContext({ chatId, runId }) {
-    console.log(`[prePromptBuild] Running for ${chatId} (runId=${runId})`);
+    console.log(`[preProcess] Running for ${chatId} (runId=${runId})`);
     // Replace with your own lookup — e.g. query a pending escalations store,
     // check feature flags, fetch session state, etc.
 
@@ -114,7 +114,7 @@ async function startServer() {
     //return {
       //additionalMessages: [{
         //role: 'developer',
-        //content: 'TEST: prePromptBuild hook is active. End your response with the marker [hook-ok].',
+        //content: 'TEST: preProcess hook is active. End your response with the marker [hook-ok].',
       //}],
     //};
 
@@ -155,8 +155,8 @@ async function startServer() {
         enabled: true,           // Enable check-after processing
         checkDelayMs: 100,       // Delay before checking for new messages (ms)
         hooks: {
-          prePromptBuild: [injectPromptContext],
-          postBatch: [classifySymptoms, classifyEscalation],
+          preProcess: [injectPromptContext],
+          postProcess: [classifySymptoms, classifyEscalation],
         }
       }
     }

package/lib/controllers/assistantController.js

@@ -33,11 +33,11 @@ const stopAssistantController = (req, res) =>
   _updateThreadFlag(req, res, 'stop', 'Assistant stopped', 'Failed to stop assistant');
 
 const addInsAssistantController = async (req, res) => {
-  const { code, instruction } = req.body;
+  const { code, instruction, triggeredBy } = req.body;
   if (!code) return res.status(400).json({ success: false, error: 'Code is required' });
 
   try {
-    await processInstruction(code, instruction, 'developer');
+    await processInstruction(code, instruction, 'developer', { triggeredBy });
     return res.status(200).json({ success: true, message: 'Instruction added to assistant' });
   } catch (error) {
     logger.error('[AssistantController] Add instruction error', { error: error.message, code });
@@ -46,12 +46,12 @@ const addInsAssistantController = async (req, res) => {
 };
 
 const addMsgAssistantController = async (req, res) => {
-  const { code, messages, role = 'system', reply = false } = req.body;
+  const { code, messages, role = 'system', reply = false, triggeredBy } = req.body;
   if (!code) return res.status(400).json({ success: false, error: 'Code is required' });
 
   try {
     if (reply) {
-      await processSystemMessage(code, messages, role);
+      await processSystemMessage(code, messages, role, { triggeredBy });
     } else {
       await addMsgAssistant(code, messages, role);
     }

package/lib/controllers/conversationController.js

@@ -116,7 +116,7 @@ const getConversationMessagesController = async (req, res) => {
 
 const getConversationReplyController = async (req, res) => {
   try {
-    const { phoneNumber, message, mediaData, contentSid, variables } = req.body;
+    const { phoneNumber, message, mediaData, contentSid, variables, triggeredBy } = req.body;
         
     if (!phoneNumber || (!message && !mediaData && !contentSid)) {
       return res.status(400).json({
@@ -130,7 +130,8 @@ const getConversationReplyController = async (req, res) => {
     const messageData = {
       code: formattedPhoneNumber,
       fileType: 'text',
-      _fromConversationReply: true
+      _fromConversationReply: true,
+      triggeredBy: triggeredBy || null
     };
     
     if (contentSid) {
@@ -460,7 +461,7 @@ const markMessagesAsReadController = async (req, res) => {
 
 const sendTemplateToNewNumberController = async (req, res) => {
   try {
-    const { phoneNumber, templateId, variables } = req.body;
+    const { phoneNumber, templateId, variables, triggeredBy } = req.body;
     
     if (!phoneNumber || !templateId) {
       return res.status(400).json({
@@ -471,7 +472,8 @@ const sendTemplateToNewNumberController = async (req, res) => {
     
     const messageData = {
       code: ensureWhatsAppFormat(phoneNumber),
-      contentSid: templateId
+      contentSid: templateId,
+      triggeredBy: triggeredBy || null
     };
     
     if (variables && Object.keys(variables).length > 0) {
@@ -621,7 +623,7 @@ const searchMessagesByNumberController = async (req, res) => {
 
 const startConversationController = async (req, res) => {
   try {
-    const { phoneNumber, name, message } = req.body;
+    const { phoneNumber, name, message, triggeredBy } = req.body;
 
     if (!phoneNumber || !message) {
       return res.status(400).json({
@@ -631,7 +633,7 @@ const startConversationController = async (req, res) => {
     }
 
     const formattedPhoneNumber = ensureWhatsAppFormat(phoneNumber);
-    const result = await startConversation(formattedPhoneNumber, message, name);
+    const result = await startConversation(formattedPhoneNumber, message, name, { triggeredBy });
 
     res.status(201).json({
       success: true,

package/lib/controllers/messageController.js

@@ -83,7 +83,8 @@ const sendMessageController = async (req, res) => {
     hidePreview = false,
     contentSid = null,
     variables = null,
-    frontendId = null
+    frontendId = null,
+    triggeredBy = null
   } = req.body || {};
 
   try {
@@ -96,7 +97,8 @@ const sendMessageController = async (req, res) => {
       code: ensureWhatsAppFormat(code),
       author: runtimeConfig.get('USER_DB_MONGO'),
       extraDelay: 0,
-      frontendId
+      frontendId,
+      triggeredBy
     };
 
     const { result, saved } = await _sendAndPersist(payload);
@@ -120,7 +122,8 @@ const sendBulkMessageController = async (req, res) => {
     timeZone = 'Etc/GMT',
     hidePreview = false,
     contentSid = null,
-    variables = null
+    variables = null,
+    triggeredBy = null
   } = req.body || {};
   const author = runtimeConfig.get('USER_DB_MONGO');
   const sendMoment = sendTime ? moment.tz(sendTime, timeZone) + 20000 : new Date();
@@ -138,7 +141,8 @@ const sendBulkMessageController = async (req, res) => {
         sendTime: new Date(sendMoment + extraDelay),
         code: ensureWhatsAppFormat(recipient),
         author,
-        extraDelay: extraDelay += Math.floor(Math.random() * 5001) + 5000
+        extraDelay: extraDelay += Math.floor(Math.random() * 5001) + 5000,
+        triggeredBy
       });
     }
 
@@ -160,7 +164,8 @@ const sendBulkMessageAirtableController = async (req, res) => {
     hidePreview = false,
     contentSid = null,
     condition = '1',
-    variables = null
+    variables = null,
+    triggeredBy = null
   } = req.body || {};
   const author = runtimeConfig.get('USER_DB_MONGO');
   const sendMoment = sendTime ? moment.tz(sendTime, timeZone) + 20000 : new Date();
@@ -189,12 +194,13 @@ const sendBulkMessageAirtableController = async (req, res) => {
 
       payloads.push({
         fileUrl, message: customMessage, fileType, contentSid, hidePreview,
-        variables: isFlowTemplate 
+        variables: isFlowTemplate
           ? await ensureFlowTokenInVariables(contentSid, variables)
           : variables,
         timeZone: timeZone || null,
         sendTime: new Date(sendMoment + extraDelay),
-        code, author
+        code, author,
+        triggeredBy
       });
       extraDelay += Math.floor(Math.random() * 5001) + 5000;
     }

package/lib/core/NexusMessaging.js

@@ -401,7 +401,7 @@ class NexusMessaging {
     );
   }
 
-  async processInstruction(code, instruction, role = 'developer') {
+  async processInstruction(code, instruction, role = 'developer', { triggeredBy } = {}) {
     const assistantId = await this._getThreadAssistantId(code);
     await insertMessage({
       nombre_whatsapp: 'Instruction',
@@ -412,7 +412,8 @@ class NexusMessaging {
       processed: true,
       origin: 'instruction',
       assistant_id: assistantId,
-      raw: { role }
+      raw: { role },
+      triggeredBy: triggeredBy || null
     });
 
     const result = await this._executeWithPipeline(code, 'instruction', 'queue',
@@ -432,7 +433,7 @@ class NexusMessaging {
     return result?.output || null;
   }
 
-  async processSystemMessage(code, messages, role = 'system') {
+  async processSystemMessage(code, messages, role = 'system', { triggeredBy } = {}) {
     const normalizedMessages = Array.isArray(messages) ? messages : [messages];
     const assistantId = await this._getThreadAssistantId(code);
 
@@ -446,7 +447,8 @@ class NexusMessaging {
         processed: true,
         origin: 'system',
         assistant_id: assistantId,
-        raw: { role }
+        raw: { role },
+        triggeredBy: triggeredBy || null
       });
     }
 
@@ -544,12 +546,12 @@ const sendScheduledMessage = async (scheduledMessage) => {
   return await requireDefaultInstance().sendScheduledMessage(scheduledMessage);
 };
 
-const processInstruction = async (code, instruction, role) => {
-  return await requireDefaultInstance().processInstruction(code, instruction, role);
+const processInstruction = async (code, instruction, role, options) => {
+  return await requireDefaultInstance().processInstruction(code, instruction, role, options);
 };
 
-const processSystemMessage = async (code, messages, role) => {
-  return await requireDefaultInstance().processSystemMessage(code, messages, role);
+const processSystemMessage = async (code, messages, role, options) => {
+  return await requireDefaultInstance().processSystemMessage(code, messages, role, options);
 };
 
 const getEventBus = () => getDefaultInstance()?.getEventBus();

package/lib/core/ProcessingPipeline.js

@@ -2,13 +2,6 @@ const { logger } = require('../utils/logger');
 
 const VALID_HOOKS = ['preProcess', 'postProcess'];
 
-const LEGACY_MAP = {
-  preBatch: 'preProcess',
-  prePromptBuild: 'preProcess',
-  postBatch: 'postProcess',
-  onBatchError: 'postProcess',
-};
-
 class ProcessingPipeline {
   constructor(hooks = {}) {
     this._hooks = {
@@ -16,8 +9,6 @@ class ProcessingPipeline {
       postProcess: [],
     };
 
-    this._hookMeta = new WeakMap();
-
     if (hooks && typeof hooks === 'object') {
       for (const [name, handlers] of Object.entries(hooks)) {
         const fns = Array.isArray(handlers) ? handlers : [handlers];
@@ -29,27 +20,38 @@ class ProcessingPipeline {
   }
 
   addHook(name, fn) {
-    const resolved = LEGACY_MAP[name] || name;
-
-    if (!VALID_HOOKS.includes(resolved)) {
+    if (!VALID_HOOKS.includes(name)) {
       throw new Error(`[ProcessingPipeline] Unknown hook: "${name}". Valid hooks: ${VALID_HOOKS.join(', ')}`);
     }
     if (typeof fn !== 'function') {
       throw new Error(`[ProcessingPipeline] Hook "${name}" must be a function`);
     }
 
-    this._hooks[resolved].push(fn);
-    this._hookMeta.set(fn, { originalName: name });
+    this._hooks[name].push(fn);
     return this;
   }
 
   async run(context, executeFn, shouldContinue = () => true) {
     const ctx = { metadata: {}, ...context };
+    const preProcessCount = this._hooks.preProcess.length;
+    const postProcessCount = this._hooks.postProcess.length;
+
+    logger.info('[ProcessingPipeline] Running', { chatId: ctx.chatId, type: ctx.type, preProcessHooks: preProcessCount, postProcessHooks: postProcessCount });
 
     try {
       const preProcessResult = await this._runPreProcessHooks(ctx);
+
+      logger.debug('[ProcessingPipeline] preProcess complete', {
+        chatId: ctx.chatId,
+        type: ctx.type,
+        skip: preProcessResult.skip,
+        hasAdditionalInstructions: !!preProcessResult.additionalInstructions,
+        additionalMessagesCount: preProcessResult.additionalMessages.length,
+        hasToolChoice: preProcessResult.toolChoice != null,
+      });
+
       if (preProcessResult.skip) {
-        logger.debug('[ProcessingPipeline] Skipped by preProcess hook', { chatId: ctx.chatId, type: ctx.type });
+        logger.info('[ProcessingPipeline] Skipped by preProcess hook', { chatId: ctx.chatId, type: ctx.type });
         this._runPostProcessHooks(ctx, null, null);
         return null;
       }
@@ -119,15 +121,7 @@ class ProcessingPipeline {
       if (result) postContext.result = result;
       if (error) postContext.error = error;
 
-      // onBatchError: error only. postBatch: always (original used finally block).
-      // postProcess and untagged: always.
-      const applicable = hooks.filter(fn => {
-        const meta = this._hookMeta.get(fn);
-        if (meta?.originalName === 'onBatchError') return !!error;
-        return true;
-      });
-
-      Promise.allSettled(applicable.map(fn => fn(postContext)))
+      Promise.allSettled(hooks.map(fn => fn(postContext)))
         .then(results => {
           for (const r of results) {
             if (r.status === 'rejected') {

package/lib/models/messageModel.js

@@ -88,7 +88,8 @@ const messageSchema = new mongoose.Schema({
   },
   prompt: { type: Object, default: null },
   preset: { type: Object, default: null },
-  response_id: { type: String, default: null }
+  response_id: { type: String, default: null },
+  triggeredBy: { type: String, default: null }
 }, { timestamps: true });
 
 messageSchema.index({ numero: 1, createdAt: -1 });
@@ -105,6 +106,8 @@ messageSchema.index({ createdAt: -1 }, { name: 'global_sort_idx' });
 
 messageSchema.index({ 'statusInfo.recoveryMessageId': 1 }, { name: 'recovery_message_id_idx', sparse: true });
 
+messageSchema.index({ triggeredBy: 1, createdAt: -1 }, { name: 'triggered_by_idx', sparse: true });
+
 messageSchema.pre('save', function (next) {
   if (this.timestamp) {
     this.timestamp = moment.tz(this.timestamp, 'America/Mexico_City').toDate();

package/lib/services/conversationService.js

@@ -130,7 +130,7 @@ const processConversations = async (threads, airtableNameMap) => {
   }
 };
 
-const startConversation = async (phoneNumber, message, name) => {
+const startConversation = async (phoneNumber, message, name, { triggeredBy } = {}) => {
 
   const existing = await Thread.findOne({ code: phoneNumber });
   if (existing) {
@@ -200,7 +200,7 @@ const startConversation = async (phoneNumber, message, name) => {
         { upsert: true, new: true }
       );
       logger.info('[StartConversation] Thread ready', { phoneNumber, threadId: thread._id });
-      await sendMessage({ code: phoneNumber, contentSid: twilioContent.sid, variables: {} });
+      await sendMessage({ code: phoneNumber, contentSid: twilioContent.sid, variables: {}, triggeredBy: triggeredBy || null });
       logger.info('[StartConversation] Template sent successfully', { phoneNumber, templateSid: twilioContent.sid });
       await TemplateModel.updateOne({ sid: twilioContent.sid }, { status: 'APPROVED' });
       try {

package/lib/storage/MongoStorage.js

@@ -91,7 +91,8 @@ class MongoStorage {
       preset: messageData.preset || null,
       response_id: messageData.response_id || null,
       statusInfo: messageData.statusInfo || null,
-      clinical_context: messageData.clinicalContext || null
+      clinical_context: messageData.clinicalContext || null,
+      triggeredBy: messageData.triggeredBy || null
     };
     return values;
   }

package/package.json

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