@peopl-health/nexus 1.7.5 → 1.7.7

package/examples/basic-usage.js

@@ -19,6 +19,12 @@ async function startServer() {
       accountSid: process.env.TWILIO_ACCOUNT_SID,
       authToken: process.env.TWILIO_AUTH_TOKEN,
       whatsappNumber: process.env.TWILIO_WHATSAPP_NUMBER
+    },
+
+    // Media configuration for AWS S3 upload
+    media: {
+      bucketName: process.env.AWS_S3_BUCKET_NAME,
+      region: process.env.AWS_REGION || 'us-east-1'
     }
   });
 
@@ -28,7 +34,7 @@ async function startServer() {
   // Add webhook endpoint for incoming messages
   app.post('/webhook', async (req, res) => {
     try {
-      await nexus.messaging.processIncomingMessage(req.body);
+      await nexus.processMessage(req.body);
       res.status(200).send('OK');
     } catch (error) {
       console.error('Webhook error:', error);
@@ -42,7 +48,12 @@ async function startServer() {
       connected: nexus.messaging.isConnected(),
       provider: 'twilio',
       mongodb: nexus.messaging.mongodb?.readyState === 1,
-      airtable: !!nexus.messaging.airtable
+      airtable: !!nexus.messaging.airtable,
+      aws: {
+        configured: !!(process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY),
+        bucket: process.env.AWS_S3_BUCKET_NAME || 'not configured',
+        region: process.env.AWS_REGION || 'us-east-1'
+      }
     });
   });
 
@@ -64,7 +75,14 @@ async function startServer() {
     console.log('- POST /webhook - Webhook for incoming messages');
     console.log('- GET /status - Connection status');
     console.log('- GET /airtable-test - Test Airtable connection');
+    console.log('- GET /media-test - Test AWS media upload configuration');
     console.log('- All Nexus API routes under /api/*');
+    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');
+    console.log('   - AWS_SECRET_ACCESS_KEY=your_secret_key');
+    console.log('   - AWS_S3_BUCKET_NAME=your-bucket-name');
   });
 }
 

package/lib/adapters/BaileysProvider.js

@@ -84,19 +84,19 @@ class BaileysProvider extends MessageProvider {
       throw new Error('Baileys provider not connected');
     }
 
-    const { code, message, fileUrl, fileType, hidePreview = false } = messageData;
+    const { code, body, fileUrl, fileType, hidePreview = false } = messageData;
     
     if (!code) {
       throw new Error('Recipient is required');
     }
 
-    if (!message && !fileUrl) {
+    if (!body && !fileUrl) {
       throw new Error('Message or file URL is required');
     }
 
     const formattedCode = this.formatCode(code);
     let sendOptions = {};
-    let formattedMessage = this.formatMessage(message || '');
+    let formattedMessage = this.formatMessage(body || '');
 
     // Handle mentions
     const regex = /@\d+/g;

package/lib/adapters/TwilioProvider.js

@@ -44,7 +44,7 @@ class TwilioProvider extends MessageProvider {
       throw new Error('Twilio provider not initialized');
     }
 
-    const { code, message, fileUrl, fileType, variables, contentSid } = messageData;
+    const { code, body, fileUrl, fileType, variables, contentSid } = messageData;
 
     const formattedFrom = this.ensureWhatsAppFormat(this.whatsappNumber);
     const formattedCode = this.ensureWhatsAppFormat(code);
@@ -77,8 +77,8 @@ class TwilioProvider extends MessageProvider {
         });
         messageParams.contentVariables = JSON.stringify(formattedVariables);
       }
-    } else if (message) {
-      messageParams.body = message;
+    } else if (body) {
+      messageParams.body = body;
     }
 
     // Handle media messages
@@ -154,6 +154,65 @@ class TwilioProvider extends MessageProvider {
       hasContentSid: Boolean(scheduledMessage.contentSid)
     });
 
+    const updateStatus = async (status, messageId = null, error = null) => {
+      if (!scheduledMessage) return;
+
+      const now = new Date();
+      const errorCode = error?.code || error?.status || error?.errorCode || null;
+      const errorMessage = error?.message || error?.statusMessage || null;
+      const statusEntry = { status, at: now, errorCode, errorMessage };
+      const baseUpdate = {
+        status,
+        lastStatus: status,
+        lastStatusAt: now,
+        errorCode,
+        errorMessage
+      };
+
+      if (messageId) baseUpdate.wa_id = messageId;
+
+      const ScheduledMessageModel = (() => {
+        if (scheduledMessage.constructor && typeof scheduledMessage.constructor.updateOne === 'function') {
+          return scheduledMessage.constructor;
+        }
+        try {
+          return require('../models/agendaMessageModel').ScheduledMessage;
+        } catch (e) {
+          return null;
+        }
+      })();
+
+      if (!ScheduledMessageModel) {
+        console.warn('[TwilioProvider] Scheduled message model unavailable for status update');
+        return;
+      }
+
+      const query = (() => {
+        if (scheduledMessage._id) return { _id: scheduledMessage._id };
+        if (messageId) return { wa_id: messageId };
+        if (scheduledMessage.wa_id) return { wa_id: scheduledMessage.wa_id };
+        return null;
+      })();
+
+      if (!query) {
+        console.warn('[TwilioProvider] Scheduled message status update skipped: no identifier', {
+          hasId: Boolean(scheduledMessage._id),
+          messageId,
+          existingWaId: scheduledMessage.wa_id
+        });
+        return;
+      }
+
+      try {
+        await ScheduledMessageModel.updateOne(query, {
+          $set: baseUpdate,
+          $push: { statusHistory: statusEntry }
+        });
+      } catch (statusErr) {
+        console.warn('[TwilioProvider] Failed to update scheduled message status', statusErr?.message || statusErr);
+      }
+    };
+
     setTimeout(async () => {
       try {
         // Convert Mongoose document to plain object if needed
@@ -164,9 +223,11 @@ class TwilioProvider extends MessageProvider {
           hasMessage: Boolean(payload.message || payload.body),
           hasMedia: Boolean(payload.fileUrl)
         });
-        await sender(payload);
-        console.log('Scheduled message sent successfully');
+        const response = await sender(payload);
+        const messageId = response?.result?.sid || null;
+        await updateStatus('sent', messageId);
       } catch (error) {
+        await updateStatus('failed', null, error);
         console.error(`Scheduled message failed: ${error.message}`);
       }
     }, delay);
@@ -253,7 +314,7 @@ class TwilioProvider extends MessageProvider {
         mediaType,
         fileName: existingFileName || `${sanitizedBase}.${extension}`,
         fileSize: buffer.length,
-        caption: messageData.message || '',
+        caption: messageData.body || '',
         metadata: {
           originalUrl: fileUrl,
           uploadedAt: new Date().toISOString()

package/lib/controllers/conversationController.js

@@ -260,12 +260,12 @@ const getConversationReplyController = async (req, res) => {
       }
       
       if (message && message.trim() !== '') {
-        messageData.message = message;
+        messageData.body = message;
       }
     }
     // Handle text message
     else if (message) {
-      messageData.message = message;
+      messageData.body = message;
     }
         
     console.log('Sending message with data:', JSON.stringify(messageData));

package/lib/core/MessageProvider.js

@@ -28,7 +28,7 @@ class MessageProvider {
    * Send a message
    * @param {Object} messageData - Message data
    * @param {string} messageData.code - Recipient
-   * @param {string} messageData.message - Message text
+   * @param {string} messageData.body - Message text
    * @param {string} messageData.fileUrl - Optional file URL
    * @param {string} messageData.fileType - File type (text, image, document, audio)
    * @param {Object} messageData.variables - Template variables

package/lib/core/NexusMessaging.js

@@ -364,7 +364,7 @@ class NexusMessaging {
 
   _extractAssistantInputs(messageData) {
     if (!messageData || typeof messageData !== 'object') {
-      return { from: null, message: null };
+      return { from: null, body: null };
     }
 
     const from = [
@@ -380,7 +380,7 @@ class NexusMessaging {
     ].find((value) => typeof value === 'string' && value.trim().length > 0) || null;
 
     const message = [
-      typeof messageData.message === 'string' ? messageData.message : null,
+      typeof messageData.body === 'string' ? messageData.body : null, // Unified body field for all message types
       typeof messageData.message?.conversation === 'string' ? messageData.message.conversation : null,
       typeof messageData.Body === 'string' ? messageData.Body : null,
       typeof messageData.raw?.message?.conversation === 'string' ? messageData.raw.message.conversation : null,
@@ -392,7 +392,7 @@ class NexusMessaging {
         : null
     ].find((value) => typeof value === 'string' && value.trim().length > 0) || null;
 
-    return { from, message };
+    return { from, body: message };
   }
 
   async handleMessage(messageData) {
@@ -403,19 +403,25 @@ class NexusMessaging {
 
   async handleMessageWithAssistant(messageData) {
     try {
-      const { from, message } = this._extractAssistantInputs(messageData);
+      const { from, body } = this._extractAssistantInputs(messageData);
 
-      if (!from || !message) {
+      // Skip assistant processing for all interactive messages to avoid conflicts with predefined flows
+      if (messageData.isInteractive) {
+        return;
+      }
+
+      if (!from || !body) {
         console.warn('Unable to resolve assistant inputs from message, skipping automatic reply.');
         return;
       }
 
-      const response = await replyAssistant(from, message);
+      const response = await replyAssistant(from, body);
 
       if (response) {
         await this.sendMessage({
           code: from,
-          message: response
+          body: response,
+          processed: true
         });
       }
     } catch (error) {
@@ -427,7 +433,24 @@ class NexusMessaging {
     if (this.messageStorage) {
       await this.messageStorage.saveInteractive(messageData);
     }
-    return await this._handleWithPipeline('interactive', 'onInteractive', messageData);
+
+    this.events.emit('interactive:received', messageData);
+    
+    // Run interactive handler if available
+    const result = await this._runPipeline('interactive', messageData, async (ctx) => {
+      const handler = this.handlers.onInteractive;
+      if (handler) {
+        return await handler(ctx, this);
+      }
+  
+      // Interactive messages are handled by specific flows on other servers
+      // No assistant processing to avoid conflicts with predefined flows
+      
+      return null;
+    });
+    
+    this.events.emit('interactive:handled', messageData);
+    return result;
   }
 
   async handleMedia(messageData) {
@@ -440,7 +463,7 @@ class NexusMessaging {
 
   async handleMediaWithAssistant(messageData) {
     try {
-      const { from, message } = this._extractAssistantInputs(messageData);
+      const { from, body } = this._extractAssistantInputs(messageData);
 
       if (!from) {
         console.warn('Unable to resolve sender for media message, skipping automatic reply.');
@@ -456,8 +479,8 @@ class NexusMessaging {
         return null;
       })();
 
-      const fallbackMessage = message && message.trim().length > 0
-        ? message
+      const fallbackMessage = body && body.trim().length > 0
+        ? body
         : `Media received (${mediaDescriptor || 'attachment'})`;
 
       const response = await replyAssistant(from, fallbackMessage);
@@ -465,7 +488,7 @@ class NexusMessaging {
       if (response) {
         await this.sendMessage({
           code: from,
-          message: response
+          body: response
         });
       }
     } catch (error) {
@@ -507,8 +530,8 @@ class NexusMessaging {
       messageData.fileUrl = messageData.fileUrl || mediaPayload.metadata?.presignedUrl || null;
       messageData.fileType = messageData.fileType || mediaPayload.mediaType;
       messageData.caption = messageData.caption || primary.caption;
-      if (!messageData.message && messageData.caption) {
-        messageData.message = messageData.caption;
+      if (!messageData.body && messageData.caption) {
+        messageData.body = messageData.caption;
       }
       messageData.isMedia = true;
 
@@ -519,7 +542,7 @@ class NexusMessaging {
         const messageObj = convertTwilioToInternalFormat(raw);
         const values = getMessageValues(
           messageObj,
-          messageData.message || messageData.caption || '',
+          messageData.body || messageData.caption || '',
           null,
           true
         );
@@ -604,8 +627,9 @@ class NexusMessaging {
       if (botResponse && this.provider) {
         await this.provider.sendMessage({
           to: chatId,
-          message: botResponse,
-          type: 'text'
+          body: botResponse,
+          type: 'text',
+          processed: true
         });
       }
       

package/lib/index.js

@@ -212,7 +212,7 @@ class Nexus {
    * Send a message
    * @param {Object} messageData - Message data
    * @param {string} messageData.code - Recipient phone number
-   * @param {string} messageData.message - Message text
+   * @param {string} messageData.body - Message text
    * @param {string} [messageData.fileUrl] - Optional file URL
    * @param {string} [messageData.fileType] - File type
    * @param {Object} [messageData.variables] - Template variables

package/lib/models/messageModel.js

@@ -10,6 +10,12 @@ const messageSchema = new mongoose.Schema({
   message_id: { type: String, required: true },
   is_group: { type: Boolean, required: true },
   is_media: { type: Boolean, required: true },
+  is_interactive: { type: Boolean, default: false },
+  interaction_type: { 
+    type: String, 
+    enum: ['button', 'list', 'flow', 'quick_reply'], 
+    default: null 
+  },
   group_id: { type: String, default: null },
   reply_id: { type: String, default: null },
   processed: { type: Boolean, default: false },
@@ -64,6 +70,8 @@ async function insertMessage(values) {
       message_id: values.message_id,
       is_group: values.is_group,
       is_media: values.is_media,
+      is_interactive: values.is_interactive || false,
+      interaction_type: values.interaction_type || null,
       group_id: values.group_id,
       reply_id: values.reply_id,
       from_me: values.from_me,

package/lib/storage/MongoStorage.js

@@ -21,7 +21,7 @@ class MongoStorage {
     const interactionSchema = new mongoose.Schema({
       messageId: String,
       numero: String,
-      interactionType: String, // 'button', 'list', 'flow'
+      interaction_type: String, // 'button', 'list', 'flow'
       payload: mongoose.Schema.Types.Mixed,
       timestamp: String,
       createdAt: { type: Date, default: Date.now }
@@ -67,7 +67,9 @@ class MongoStorage {
         provider: messageData?.provider || 'unknown',
         hasRaw: Boolean(messageData?.raw),
         hasMedia: Boolean(messageData?.media || messageData?.fileUrl),
-        hasContentSid: Boolean(messageData?.contentSid)
+        hasContentSid: Boolean(messageData?.contentSid),
+        is_interactive: messageData.isInteractive,
+        interaction_type: messageData.interactionType
       });
       const enrichedMessage = await this._enrichTwilioMedia(messageData);
       const values = this.buildMessageValues(enrichedMessage);
@@ -135,7 +137,7 @@ class MongoStorage {
         fileUrl: undefined,
         fileType: mediaPayload.mediaType || messageData.fileType,
         isMedia: true,
-        message: messageData.message || rawMessage.Body || primary.caption || '',
+        message: messageData.body || rawMessage.Body || primary.caption || '',
         caption: primary.caption || messageData.caption
       };
     } catch (error) {
@@ -179,7 +181,7 @@ class MongoStorage {
     const nombre = messageData.nombre_whatsapp || messageData.author || messageData.fromName || runtimeConfig.get('USER_DB_MONGO') || process.env.USER_DB_MONGO || 'Nexus';
     
     // Use message body directly (template rendering is now handled by the provider)
-    let textBody = messageData.message || messageData.body;
+    let textBody = messageData.body;
     
     if (!textBody && isMedia) {
       textBody = `[Media:${messageData.fileType || 'attachment'}]`;
@@ -205,6 +207,8 @@ class MongoStorage {
       message_id: providerId,
       is_group: isGroup,
       is_media: isMedia,
+      is_interactive: messageData.isInteractive || false,
+      interaction_type: messageData.interactionType || null,
       group_id: isGroup ? normalizedNumero : null,
       reply_id: messageData.reply_id || messageData.replyId || null,
       from_me: messageData.fromMe !== undefined ? messageData.fromMe : true,
@@ -219,7 +223,7 @@ class MongoStorage {
       const interaction = new this.schemas.Interaction({
         messageId: interactionData.messageId,
         numero: interactionData.from,
-        interactionType: interactionData.type, // 'button', 'list', 'flow'
+        interaction_type: interactionData.type, // 'button', 'list', 'flow'
         payload: interactionData.payload,
         timestamp: this.formatTimestamp(interactionData.timestamp)
       });

package/lib/utils/messageParser.js

@@ -16,7 +16,7 @@ class MessageParser {
    */
   parseMessage(rawMessage) {
     const messageData = {
-      id: rawMessage.id || rawMessage.key?.id,
+      id: rawMessage.id || rawMessage.key?.id || rawMessage.MessageSid,
       from: this.extractSender(rawMessage),
       timestamp: rawMessage.timestamp || Date.now(),
       raw: rawMessage
@@ -24,20 +24,34 @@ class MessageParser {
 
     // Check for interactive messages (buttons, lists, flows)
     if (this.isInteractiveMessage(rawMessage)) {
+      const interactive = this.parseInteractive(rawMessage);
+      const interactionText = this.extractInteractionText(interactive);
+      
       return {
         ...messageData,
+        body: interactionText,
         type: 'interactive',
-        interactive: this.parseInteractive(rawMessage)
+        interactive: interactive,
+        isInteractive: true,      // Flag to indicate this is an interactive message
+        interactionType: interactive.type // Store the specific interaction type
       };
     }
 
     // Check for media messages
     if (this.isMediaMessage(rawMessage)) {
-      return {
+      const mediaResult = {
         ...messageData,
         type: 'media',
         media: this.parseMedia(rawMessage)
       };
+
+      // Check if media message also has text content (caption)
+      const textContent = this.extractTextContent(rawMessage);
+      if (textContent) {
+        mediaResult.body = textContent;
+      }
+
+      return mediaResult;
     }
 
     // Parse text content
@@ -46,7 +60,7 @@ class MessageParser {
       return { ...messageData, type: 'unknown' };
     }
 
-    messageData.message = textContent;
+    messageData.body = textContent;
 
     // Check for commands
     if (this.isCommand(textContent)) {
@@ -117,12 +131,19 @@ class MessageParser {
   }
 
   isInteractiveMessage(rawMessage) {
-    // Twilio interactive messages
-    return !!(rawMessage.ButtonPayload || rawMessage.ListId || rawMessage.FlowData || rawMessage.InteractiveData);
+    // Twilio interactive messages - check for any interactive indicators
+    return !!(
+      rawMessage.ButtonPayload || 
+      rawMessage.ListId || 
+      rawMessage.FlowData || 
+      rawMessage.InteractiveData || 
+      rawMessage.ButtonText
+    );
   }
 
   parseInteractive(rawMessage) {
-    if (rawMessage.ButtonPayload) {
+    if (rawMessage.ButtonPayload !== undefined && rawMessage.ButtonPayload !== null && rawMessage.ButtonPayload.trim() !== '') {
+      // Non-empty payload = regular button
       return {
         type: 'button',
         payload: rawMessage.ButtonPayload,
@@ -130,6 +151,14 @@ class MessageParser {
       };
     }
 
+    if (rawMessage.ButtonText) {
+      return {
+        type: 'quick_reply',
+        title: rawMessage.ButtonText,
+        payload: rawMessage.ButtonText
+      };
+    }
+
     if (rawMessage.ListId) {
       return {
         type: 'list',
@@ -149,6 +178,33 @@ class MessageParser {
     return null;
   }
 
+  /**
+   * Extract interaction text for body field from interactive message
+   * @param {Object} interactive - Parsed interactive data
+   * @returns {string} Human-readable interaction text
+   */
+  extractInteractionText(interactive) {
+    if (!interactive) return '';
+
+    switch (interactive.type) {
+    case 'button':
+      return interactive.title || interactive.payload || '[Button clicked]';
+      
+    case 'quick_reply':
+      return interactive.title || interactive.payload || '[Quick reply]';
+      
+    case 'list':
+      return interactive.title || interactive.description || '[List item selected]';
+      
+    case 'flow':
+      // Flows contain complex JSON data that doesn't need assistant processing
+      return '';
+      
+    default:
+      return '[Interactive message]';
+    }
+  }
+
   isMediaMessage(rawMessage) {
     // Twilio format
     if (rawMessage.NumMedia && parseInt(rawMessage.NumMedia) > 0) {

package/package.json

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