@peopl-health/nexus 2.4.12 → 2.5.0

package/examples/basic-usage.js

@@ -9,8 +9,59 @@ app.use(express.json());
 class GeneralAssistant extends BaseAssistant {
   constructor(options = {}) {
     super(options);
-    // You can add custom tools or setup here
-    // Example: this.registerTool('toolName', schema, handler);
+    // Register the reportUnresolvedRequests tool for testing
+    this.registerTool({
+      name: 'reportUnresolvedRequests',
+      definition: {
+        description: 'Identifica preguntas o síntomas que no se resolvieron completamente o que fueron escaladas al equipo médico.',
+        strict: false,
+        parameters: {
+          type: 'object',
+          required: [
+            'unresolvedQuestion',
+            'escalationDetails'
+          ],
+          properties: {
+            unresolvedQuestion: {
+              type: 'string',
+              description: 'La pregunta o síntoma que quedó sin resolver.'
+            },
+            escalationDetails: {
+              type: 'string',
+              description: 'Detalles sobre por qué se escaló o a quién fue escalada (equipo médico, etc.).'
+            },
+            resolutionAttempted: {
+              type: 'boolean',
+              description: 'Indica si se intentó ofrecer una resolución antes de escalar.'
+            },
+            triggerConditions: {
+              type: 'object',
+              description: 'Condiciones que activan la función cuando se detecta una pregunta o síntoma no resuelto en su totalidad.',
+              properties: {
+                responseAnalysis: {
+                  type: 'string',
+                  description: 'Análisis de la respuesta para determinar si es suficientemente específica o resuelve la pregunta.',
+                  default: 'La respuesta contiene palabras como \'depende\', \'consulte a su equipo médico\', \'varía según el caso\', \'haremos las consultas al equipo médico de PEOPL\', \'puedo comunicarme con el equipo médico de PEOPL para ti\', \'Voy a escalar la consulta al equipo médico\' o no proporciona un plan de acción claro.'
+                }
+              },
+              required: [
+                'responseAnalysis'
+              ]
+            }
+          },
+          additionalProperties: false
+        }
+      },
+      handler: async (args) => {
+        // Handler for testing - logs the unresolved request information
+        console.log('🔍 [reportUnresolvedRequests] Tool called with:', JSON.stringify(args, null, 2));
+        return {
+          success: true,
+          message: 'Unresolved request reported successfully',
+          data: args
+        };
+      }
+    });
   }
 }
 
@@ -35,7 +86,7 @@ async function startServer() {
     providerConfig: {
       accountSid: process.env.TWILIO_ACCOUNT_SID,
       authToken: process.env.TWILIO_AUTH_TOKEN,
-      whatsappNumber: process.env.TWILIO_WHATSAPP_NUMBER
+      whatsappNumber: process.env.TWILIO_WHATSAPP_NUMBER,
     },
 
     // Media configuration for AWS S3 upload
@@ -56,6 +107,8 @@ async function startServer() {
         // Register the general assistant with its OpenAI assistant ID
         'asst_O6mAXAhf0xyVj3t4DHRs26uT': GeneralAssistant,
         'pmpt_68f844cd975481979c080431bde74f6e0adf01a52110813b': GeneralAssistant,
+        'pmpt_68f8059adc7881938477ddbfb6e0d1970c2ed91d30c64be6': GeneralAssistant,
+        'pmpt_68f649ce39ec81908fade27434c167e6014528b0dc5469c6': GeneralAssistant,
       }
     }
   });
@@ -75,6 +128,25 @@ async function startServer() {
     }
   });
 
+  // Add status callback endpoint for Twilio message status updates
+  // Twilio sends form-encoded data, so we need urlencoded middleware
+  const { handleStatusCallback } = require('../lib/helpers/messageStatusHelper');
+  app.use('/twilio/status_callback', express.urlencoded({ extended: true }));
+  app.post('/twilio/status_callback', async (req, res) => {
+    try {
+      const updated = await handleStatusCallback(req.body);
+      if (updated) {
+        console.log('✅ Status updated:', req.body.MessageSid, req.body.MessageStatus);
+        res.status(200).json({ success: true, message: 'Status updated' });
+      } else {
+        res.status(200).json({ success: false, message: 'Message not found' });
+      }
+    } catch (error) {
+      console.error('Status callback error:', error);
+      res.status(500).json({ success: false, error: error.message });
+    }
+  });
+
   // Custom endpoint example
   app.get('/status', (req, res) => {
     res.json({
@@ -107,6 +179,7 @@ async function startServer() {
     console.log('Available endpoints:');
     console.log('- POST /webhook - Webhook for incoming messages');
     console.log('- POST /twilio/webhook - Twilio webhook for incoming messages');
+    console.log('- POST /twilio/status_callback - Twilio status callback for message delivery status');
     console.log('- GET /status - Connection status');
     console.log('- GET /airtable-test - Test Airtable connection');
     console.log('- GET /media-test - Test AWS media upload configuration');
@@ -117,6 +190,11 @@ async function startServer() {
     console.log('   - Multiple messages from same sender will be batched');
     console.log('   - Use test-batching.js to test the functionality');
     console.log('');
+    console.log('🧪 Assistant Testing:');
+    console.log('   - Use test-assistant.js to test assistant functionality');
+    console.log('   - Run: node examples/test-assistant.js');
+    console.log('   - Tests basic messages, responses, batching, and retry logic');
+    console.log('');
     console.log('📸 Media Upload Setup:');
     console.log('   Add these to your .env file for media upload:');
     console.log('   - AWS_ACCESS_KEY_ID=your_access_key');

package/lib/adapters/TwilioProvider.js

@@ -18,6 +18,7 @@ class TwilioProvider extends MessageProvider {
     this.accountSid = config.accountSid;
     this.authToken = config.authToken;
     this.whatsappNumber = config.whatsappNumber;
+    this.statusCallbackUrl = config.statusCallbackUrl || null;
   }
 
   async initialize() {
@@ -61,6 +62,17 @@ class TwilioProvider extends MessageProvider {
       to: formattedCode
     };
 
+    if (this.statusCallbackUrl) {
+      messageParams.statusCallback = this.statusCallbackUrl;
+      messageParams.statusCallbackMethod = messageData.statusCallbackMethod || 'POST';
+      logger.info('[TwilioProvider] Message will use status callback', {
+        callbackUrl: this.statusCallbackUrl,
+        method: messageParams.statusCallbackMethod
+      });
+    } else {
+      logger.debug('[TwilioProvider] No status callback URL configured');
+    }
+
     // Handle template messages
     if (contentSid) {
       const renderedMessage = await this.renderTemplate(contentSid, variables);
@@ -118,17 +130,23 @@ class TwilioProvider extends MessageProvider {
             provider: 'twilio',
             timestamp: new Date(),
             fromMe: true,
-            processed: messageData.processed !== undefined ? messageData.processed : false
+            processed: messageData.processed !== undefined ? messageData.processed : false,
+            statusInfo: {
+              status: result.status ? result.status.toLowerCase() : null,
+              updatedAt: result.dateCreated || new Date()
+            }
           });
           logger.info('[TwilioProvider] Message persisted successfully', { messageId: result.sid });
         } catch (storageError) {
           logger.error('TwilioProvider storage failed:', storageError);
         }
       }
+      
       return {
         success: true,
         messageId: result.sid,
         provider: 'twilio',
+        status: result.status,
         result
       };
     } catch (error) {
@@ -215,7 +233,6 @@ class TwilioProvider extends MessageProvider {
         const payload = scheduledMessage.toObject ? scheduledMessage.toObject() : { ...scheduledMessage };
         delete payload.__nexusSend;
         
-        // Map message field to body for consistency (scheduled messages use 'message' field)
         if (payload.message && !payload.body) {
           payload.body = payload.message;
         }
@@ -681,6 +698,30 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
+  /**
+   * Check the status of a sent message using its SID
+   */
+  async getMessageStatus(messageSid) {
+    if (!this.isConnected || !this.twilioClient) {
+      throw new Error('Twilio provider not initialized');
+    }
+    if (!messageSid) {
+      throw new Error('Message SID is required');
+    }
+
+    try {
+      const message = await this.twilioClient.messages(messageSid).fetch();
+      // Returns the complete Twilio message object with all status information
+      // Status-related fields: status, errorCode, errorMessage, dateCreated, dateSent, dateUpdated
+      return message;
+    } catch (error) {
+      if (error.status === 404) {
+        throw new Error(`Message with SID ${messageSid} not found`);
+      }
+      throw new Error(`Failed to fetch message status: ${error.message}`);
+    }
+  }
+
 }
 
 module.exports = { TwilioProvider };

package/lib/controllers/conversationController.js

@@ -117,10 +117,8 @@ const getConversationMessagesController = async (req, res) => {
       }
     }
     
-    logger.info('Fetching conversation messages with query:', JSON.stringify(query));
-    logger.info('Using limit:', limit);
-        
-    logger.info('About to execute Message.find with query:', JSON.stringify(query));
+    logger.info('Fetching conversation messages', { query, limit });
+    logger.info('Executing Message.find', { query });
     let messages = [];
     
     try {
@@ -242,7 +240,7 @@ const getConversationReplyController = async (req, res) => {
       messageData.contentSid = contentSid;
       
       if (variables && Object.keys(variables).length > 0) {
-        logger.info('Template variables:', JSON.stringify(variables));
+        logger.info('Template variables', { variables });
         messageData.variables = variables;
       }
       
@@ -275,7 +273,7 @@ const getConversationReplyController = async (req, res) => {
       messageData.body = message;
     }
         
-    logger.info('Sending message with data:', JSON.stringify(messageData));
+    logger.info('Sending message', { messageData });
     await sendMessage(messageData);
     logger.info('Message sent successfully');
         
@@ -285,7 +283,7 @@ const getConversationReplyController = async (req, res) => {
     });
   } catch (error) {
     logger.error('Error sending reply:', error);
-    logger.info('Request body:', JSON.stringify(req.body || {}));
+    logger.info('Request body', { body: req.body || {} });
     const errorMsg = error.message || 'Failed to send reply';
     logger.error('Responding with error:', errorMsg);
     res.status(500).json({
@@ -615,7 +613,7 @@ const sendTemplateToNewNumberController = async (req, res) => {
     
     if (variables && Object.keys(variables).length > 0) {
       messageData.variables = variables;
-      logger.info('Template variables:', JSON.stringify(variables));
+      logger.info('Template variables', { variables });
     }
     
     const message = await sendMessage(messageData);

package/lib/controllers/messageStatusController.js

@@ -0,0 +1,92 @@
+const { handleStatusCallback, getMessageStatus } = require('../helpers/messageStatusHelper');
+const { logger } = require('../utils/logger');
+
+/**
+ * Handle Twilio status callback webhook
+ * POST /api/message/status-callback
+ */
+async function messageStatusCallbackController(req, res) {
+  try {
+    logger.info('[MessageStatusController] Received status callback', {
+      method: req.method,
+      path: req.path,
+      headers: req.headers['content-type'],
+      bodyKeys: Object.keys(req.body || {}),
+      body: req.body
+    });
+    
+    const updated = await handleStatusCallback(req.body);
+
+    if (updated) {
+      logger.info('[MessageStatusController] Status updated successfully', {
+        messageSid: req.body.MessageSid,
+        status: req.body.MessageStatus
+      });
+      res.status(200).json({
+        success: true,
+        message: 'Status updated',
+        messageSid: req.body.MessageSid,
+        status: req.body.MessageStatus
+      });
+    } else {
+      res.status(200).json({
+        success: false,
+        message: 'Message not found or invalid data',
+        messageSid: req.body.MessageSid
+      });
+    }
+  } catch (error) {
+    logger.error('[MessageStatusController] Error handling status callback', {
+      error: error.message,
+      body: req.body
+    });
+    res.status(500).json({
+      success: false,
+      error: 'Failed to process status callback'
+    });
+  }
+}
+
+/**
+ * Get message status from database
+ * GET /api/message/status/:messageSid
+ */
+async function getMessageStatusController(req, res) {
+  try {
+    const { messageSid } = req.params;
+    
+    const message = await getMessageStatus(messageSid);
+
+    if (message) {
+      res.status(200).json({
+        success: true,
+        message: {
+          messageSid: message.message_id,
+          statusInfo: message.statusInfo || null,
+          numero: message.numero,
+          body: message.body
+        }
+      });
+    } else {
+      res.status(404).json({
+        success: false,
+        error: 'Message not found'
+      });
+    }
+  } catch (error) {
+    logger.error('[MessageStatusController] Error fetching message status', {
+      error: error.message,
+      messageSid: req.params.messageSid
+    });
+    res.status(500).json({
+      success: false,
+      error: 'Failed to fetch message status'
+    });
+  }
+}
+
+module.exports = {
+  messageStatusCallbackController,
+  getMessageStatusController
+};
+

package/lib/helpers/llmsHelper.js

@@ -71,7 +71,7 @@ async function analyzeImage(imagePath, isSticker = false, contentType = null) {
 
     // Description of the image (for both stickers and regular images)
     const imageDescription = 'Describe the image in detail.';
-    const messageDescription = await anthropicClient.messages.create({
+    const descriptionPromise = anthropicClient.messages.create({
       model: 'claude-sonnet-4-5',
       max_tokens: 1024,
       messages: [
@@ -94,11 +94,13 @@ async function analyzeImage(imagePath, isSticker = false, contentType = null) {
         },
       ],
     });
-    logger.info('[analyzeImage] Description received');
-    const description = messageDescription.content[0].text;
 
     // For stickers, skip medical analysis and table extraction
     if (isSticker) {
+      const messageDescription = await descriptionPromise;
+      const description = messageDescription.content[0].text;
+      logger.info('[analyzeImage] Description received (sticker)');
+      
       return {
         description: description,
         medical_analysis: 'NOT_MEDICAL',
@@ -108,7 +110,9 @@ async function analyzeImage(imagePath, isSticker = false, contentType = null) {
       };
     }
 
-    // Create a more specific prompt for table detection and extraction
+    // Run all analysis calls in parallel
+    logger.info('[analyzeImage] Starting parallel analysis calls');
+        
     const tablePrompt = `Please analyze this image and respond in the following format:
 1. First, determine if there is a table in the image.
 2. If there is NO table, respond with exactly "NONE"
@@ -126,32 +130,6 @@ async function analyzeImage(imagePath, isSticker = false, contentType = null) {
 
 Only extract tables - ignore any other content in the image.`;
 
-    // Create the message with the image
-    const messageTable = await anthropicClient.messages.create({
-      model: 'claude-3-7-sonnet-20250219',
-      max_tokens: 1024,
-      messages: [
-        {
-          role: 'user',
-          content: [
-            {
-              type: 'image',
-              source: {
-                type: 'base64',
-                media_type: mimeType,
-                data: base64Image,
-              },
-            },
-            {
-              type: 'text',
-              text: tablePrompt,
-            },
-          ],
-        },
-      ],
-    });
-
-    // Create a more specific prompt for table detection and extraction
     const medImagePrompt = `
 Eres un oncólogo clínico con experiencia. Se te proporcionará una imagen médica o laboratorio. Analízala y responde exactamente en este formato:
 
@@ -193,59 +171,48 @@ Ejemplo 1:
 </EJEMPLOS>
 `;
 
-    // Create the message with the image
-    const messageMedImage = await anthropicClient.messages.create({
-      model: 'claude-3-7-sonnet-20250219',
-      max_tokens: 1024,
-      messages: [
-        {
-          role: 'user',
-          content: [
-            {
-              type: 'image',
-              source: {
-                type: 'base64',
-                media_type: mimeType,
-                data: base64Image,
-              },
-            },
-            {
-              type: 'text',
-              text: medImagePrompt,
-            },
-          ],
-        },
-      ],
-    });
-
     const relevancePrompt = `Please analyze this image and respond in this format: 
         Medical Relevance: [YES/NO]`;
 
-    // Create the message with the image
-    const messageRelevance = await anthropicClient.messages.create({
-      model: 'claude-3-7-sonnet-20250219',
-      max_tokens: 1024,
-      messages: [
-        {
+    // Execute all 4 API calls in parallel
+    const [messageDescription, messageTable, messageMedImage, messageRelevance] = await Promise.all([
+      descriptionPromise,
+      anthropicClient.messages.create({
+        model: 'claude-3-7-sonnet-20250219',
+        max_tokens: 1024,
+        messages: [{
           role: 'user',
           content: [
-            {
-              type: 'image',
-              source: {
-                type: 'base64',
-                media_type: mimeType,
-                data: base64Image,
-              },
-            },
-            {
-              type: 'text',
-              text: relevancePrompt,
-            },
-          ],
-        },
-      ],
-    });
+            { type: 'image', source: { type: 'base64', media_type: mimeType, data: base64Image } },
+            { type: 'text', text: tablePrompt }
+          ]
+        }]
+      }),
+      anthropicClient.messages.create({
+        model: 'claude-3-7-sonnet-20250219',
+        max_tokens: 1024,
+        messages: [{
+          role: 'user',
+          content: [
+            { type: 'image', source: { type: 'base64', media_type: mimeType, data: base64Image } },
+            { type: 'text', text: medImagePrompt }
+          ]
+        }]
+      }),
+      anthropicClient.messages.create({
+        model: 'claude-3-7-sonnet-20250219',
+        max_tokens: 1024,
+        messages: [{
+          role: 'user',
+          content: [
+            { type: 'image', source: { type: 'base64', media_type: mimeType, data: base64Image } },
+            { type: 'text', text: relevancePrompt }
+          ]
+        }]
+      })
+    ]);
 
+    const description = messageDescription.content[0].text;
     const messageTableStr = messageTable.content[0].text;
     const messageRelevanceStr = messageRelevance.content[0].text;
     const messageAnalysisStr = messageMedImage.content[0].text;

package/lib/helpers/messageStatusHelper.js

@@ -0,0 +1,97 @@
+const { Message } = require('../models/messageModel');
+const { logger } = require('../utils/logger');
+
+/**
+ * Update message delivery status in the database based on Twilio status callback data
+ */
+async function updateMessageStatus(messageSid, status, errorCode = null, errorMessage = null) {
+  try {
+    const statusInfo = {
+      status,
+      updatedAt: new Date()
+    };
+
+    if (errorCode) {
+      statusInfo.errorCode = errorCode;
+    }
+
+    if (errorMessage) {
+      statusInfo.errorMessage = errorMessage;
+    }
+
+    const updated = await Message.findOneAndUpdate(
+      { message_id: messageSid },
+      { $set: { statusInfo } },
+      { new: true }
+    );
+
+    if (updated) {
+      logger.info('[MessageStatus] Updated message status', {
+        messageSid,
+        status,
+        errorCode,
+        errorMessage
+      });
+    } else {
+      logger.warn('[MessageStatus] Message not found for status update', { messageSid });
+    }
+
+    return updated;
+  } catch (error) {
+    logger.error('[MessageStatus] Error updating message status', {
+      messageSid,
+      error: error.message
+    });
+    throw error;
+  }
+}
+
+/**
+ * Handle Twilio status callback webhook
+ */
+async function handleStatusCallback(twilioStatusData) {
+  const {
+    MessageSid,
+    MessageStatus,
+    ErrorCode,
+    ErrorMessage
+  } = twilioStatusData;
+
+  if (!MessageSid || !MessageStatus) {
+    logger.warn('[MessageStatus] Invalid status callback data', twilioStatusData);
+    return null;
+  }
+
+  return await updateMessageStatus(
+    MessageSid,
+    MessageStatus.toLowerCase(),
+    ErrorCode || null,
+    ErrorMessage || null
+  );
+}
+
+/**
+ * Get message status from database
+ */
+async function getMessageStatus(messageSid) {
+  try {
+    const message = await Message.findOne({ message_id: messageSid })
+      .select('statusInfo message_id numero body')
+      .lean();
+
+    return message;
+  } catch (error) {
+    logger.error('[MessageStatus] Error fetching message status from DB', {
+      messageSid,
+      error: error.message
+    });
+    return null;
+  }
+}
+
+module.exports = {
+  updateMessageStatus,
+  handleStatusCallback,
+  getMessageStatus
+};
+

package/lib/models/messageModel.js

@@ -63,6 +63,25 @@ const messageSchema = new mongoose.Schema({
   read: {
     type: Boolean,
     default: false
+  },
+  statusInfo: {
+    status: {
+      type: String,
+      enum: ['queued', 'sending', 'sent', 'delivered', 'undelivered', 'failed', 'read', null],
+      default: null
+    },
+    errorCode: {
+      type: String,
+      default: null
+    },
+    errorMessage: {
+      type: String,
+      default: null
+    },
+    updatedAt: {
+      type: Date,
+      default: null
+    }
   }
 }, { timestamps: true });
 
@@ -118,7 +137,13 @@ async function insertMessage(values) {
       clinical_context: clinical_context,
       origin: values.origin,
       tools_executed: values.tools_executed || [],
-      raw: values.raw || null
+      raw: values.raw || null,
+      statusInfo: values.statusInfo || (values.delivery_status ? {
+        status: values.delivery_status,
+        errorCode: values.delivery_error_code || null,
+        errorMessage: values.delivery_error_message || null,
+        updatedAt: values.delivery_status_updated_at || null
+      } : null)
     };
 
     await Message.findOneAndUpdate(

package/lib/routes/index.js

@@ -1,5 +1,6 @@
 // Export route definitions for customer servers to import
 // These are the route patterns without controller dependencies
+const express = require('express');
 
 const assistantRouteDefinitions = {
   'POST /active': 'activeAssistantController',
@@ -65,7 +66,6 @@ const templateRouteDefinitions = {
 
 // Helper function to create Express router from route definitions
 const createRouter = (routeDefinitions, controllers) => {
-  const express = require('express');
   const router = express.Router();
   
   for (const [route, controllerName] of Object.entries(routeDefinitions)) {

package/lib/services/conversationService.js

@@ -135,8 +135,8 @@ const fetchConversationData = async (filter, skip, limit) => {
     }
     return map;
   }, {}) || {};
-  logger.info('unreadMap', JSON.stringify(unreadMap));
-  logger.info('Number of conversations found:', conversations?.length || 0);
+  logger.info('Unread map calculated', { unreadMap });
+  logger.info('Conversations found', { count: conversations?.length || 0 });
       
   // Calculate total count for pagination
   let totalFilterConditions = { is_group: false };

package/lib/services/twilioService.js

@@ -49,6 +49,11 @@ const TwilioService = {
     return await nexusProvider.createTemplate(templateData);
   },
 
+  async getMessageStatus(messageSid) {
+    checkTwilioSupport();
+    return await nexusProvider.getMessageStatus(messageSid);
+  },
+
   // Add any other Twilio operations as needed
   configureNexusProvider
 };

package/lib/storage/MongoStorage.js

@@ -187,7 +187,13 @@ class MongoStorage {
       template_variables: messageData.variables ? JSON.stringify(messageData.variables) : null,
       raw: messageData.raw || null,
       origin,
-      tools_executed: messageData.tools_executed || []
+      tools_executed: messageData.tools_executed || [],
+      statusInfo: messageData.statusInfo || (messageData.delivery_status ? {
+        status: messageData.delivery_status,
+        errorCode: messageData.delivery_error_code || null,
+        errorMessage: messageData.delivery_error_message || null,
+        updatedAt: messageData.delivery_status_updated_at || null
+      } : null)
     };
   }
 

package/package.json

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