@peopl-health/nexus 1.3.1 → 1.4.0

package/README.md

@@ -24,8 +24,23 @@ await nexus.initialize({
     authToken: process.env.TWILIO_AUTH_TOKEN,
     phoneNumber: process.env.TWILIO_PHONE_NUMBER
   },
-  storage: 'mongo',                 // or 'noop', or your custom adapter/instance
-  storageConfig: { mongoUri: process.env.MONGODB_URI }
+  // Storage (MongoStorage) and Mongo convenience
+  storage: 'mongo',
+  storageConfig: { dbName: 'nexus' },   // other options
+  mongoUri: process.env.MONGODB_URI,    // convenience: passed into storageConfig.mongoUri
+
+  // Media convenience (inject only bucket name)
+  media: { bucketName: process.env.AWS_S3_BUCKET_NAME },
+
+  // Airtable convenience (pick default base or pass a Base ID)
+  airtable: {
+    base: 'calendar',                   // friendly key or base ID
+    apiKey: process.env.AIRTABLE_API_KEY
+  },
+
+  // Optional LLM (OpenAI)
+  llm: 'openai',
+  llmConfig: { apiKey: process.env.OPENAI_API_KEY }
 });
 
 // Built‑in routes (assistant, conversation, media, message, template)
@@ -130,3 +145,64 @@ See:
 - examples/basic-usage.js
 - examples/assistants/
 
+
+
+## Configuration
+
+You can configure Nexus via environment variables or at runtime using simple injection helpers. For production apps, prefer passing options or DI, and use envs as a fallback.
+
+- Providers/AI
+  - TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER
+  - OPENAI_API_KEY
+
+- Mongo
+  - MONGODB_URI (or pass `mongoUri` when calling `initializeMongoDB()`)
+
+- Airtable
+  - AIRTABLE_API_KEY
+  - AIRTABLE_BASE_ID (or specific IDs below)
+  - AIRTABLE_CALENDAR_ID, AIRTABLE_CONFIG_ID, AIRTABLE_HISTORIAL_CLINICO_ID
+  - AIRTABLE_LOGGING_ID, AIRTABLE_MONITOREO_ID, AIRTABLE_PROGRAMA_JUNTAS_ID
+  - AIRTABLE_SYMPTOMS_ID, AIRTABLE_WEBINARS_LEADS_ID
+
+- AWS (S3)
+  - AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION (default: us-east-1)
+  - AWS_S3_BUCKET_NAME (or inject via `configureMediaController`)
+
+- Misc
+  - NODE_ENV (affects logging and helpers)
+  - USER_DB_MONGO (used as author in message controller)
+
+Injection points (dependency injection)
+
+- Message scheduling (use your Agenda/Bull model + scheduler):
+```js
+const { configureMessageController } = require('@peopl-health/nexus/lib/controllers/messageController');
+const { AgendaMessage } = require('./src/models/agendaMessageModel');
+const { sendScheduledMessage: appSchedule } = require('./src/messaging/scheduledMessageService');
+
+const provider = nexus.getMessaging().getProvider(); // e.g., TwilioProvider
+configureMessageController({
+  ScheduledMessage: AgendaMessage, // must expose create/find/findById/deleteOne
+  sendScheduledMessage: (saved) => appSchedule(provider.twilioClient, saved),
+  // Optional: only if you use bulk‑airtable
+  getRecordByFilter: require('@peopl-health/nexus/lib/services/airtableService').getRecordByFilter
+});
+```
+
+- Media (inject only your bucket name; AWS SDK is loaded by the lib):
+```js
+const { configureMediaController } = require('@peopl-health/nexus/lib/controllers/mediaController');
+configureMediaController({ bucketName: process.env.AWS_S3_BUCKET_NAME });
+```
+
+- Storage settings (MongoStorage only):
+```js
+// Store once; Nexus auto-injects media bucket from storage at startup
+await nexus.getStorage().setConfig('media.bucketName', process.env.AWS_S3_BUCKET_NAME);
+```
+
+Tips
+- Connect Mongo before `app.listen()` to avoid Mongoose buffering timeouts.
+- If you initialize OpenAI, pass `llm: 'openai'` and `llmConfig: { apiKey }` to `nexus.initialize`.
+- Use the event bus + middleware for custom routing and transformations without forking the default handlers.

package/lib/adapters/TwilioProvider.js

@@ -161,7 +161,7 @@ class TwilioProvider extends MessageProvider {
       const links = (content && content.links) || {};
       let approvalsUrl = links.approvals || links.approvalRequests || links.approval_requests;
       if (!approvalsUrl) {
-        approvalsUrl = 'https://content.twilio.com/v1/Content/' + sid + '/ApprovalRequests';
+        return { content, approvalRequest: null, warning: 'Approval endpoint not provided by Twilio' };
       }
       const resp = await axios.get(approvalsUrl, { auth: { username: this.accountSid, password: this.authToken } });
       const data = resp && resp.data ? resp.data : null;
@@ -188,7 +188,11 @@ class TwilioProvider extends MessageProvider {
       const links = (content && content.links) || {};
       let approvalsUrl = links.approvals || links.approvalRequests || links.approval_requests;
       if (!approvalsUrl) {
-        approvalsUrl = 'https://content.twilio.com/v1/Content/' + contentSid + '/ApprovalRequests';
+        return {
+          success: false,
+          contentSid,
+          warning: 'Twilio account does not expose an approvals endpoint. Approval must be handled manually in the Console.'
+        };
       }
       const payload = {
         name,
@@ -200,7 +204,11 @@ class TwilioProvider extends MessageProvider {
       const resp = await axios.post(approvalsUrl, payload, { auth: { username: this.accountSid, password: this.authToken } });
       return { success: true, contentSid, approvalRequest: resp.data || null };
     } catch (error) {
-      throw new Error(`Failed to submit for approval: ${error.message}`);
+      return {
+        success: false,
+        contentSid,
+        warning: `Failed to submit for approval via API: ${error.message}`
+      };
     }
   }
 

package/lib/config/airtableConfig.js

@@ -1,18 +1,19 @@
 const Airtable = require('airtable');
+const runtimeConfig = require('./runtimeConfig');
 
 const airtableConfig = {
-  apiKey: process.env.AIRTABLE_API_KEY,
+  apiKey: runtimeConfig.get('AIRTABLE_API_KEY'),
 };
 
 // Configurable base IDs - users can override via environment variables
-const Calendar_ID = process.env.AIRTABLE_CALENDAR_ID || 'appIjEstWR6972tbF';
-const Config_ID = process.env.AIRTABLE_CONFIG_ID || 'app9K4EvGI8McC8jF';
-const Historial_Clinico_ID = process.env.AIRTABLE_HISTORIAL_CLINICO_ID || 'appdUpGUS06XIzVnY';
-const Logging_ID = process.env.AIRTABLE_LOGGING_ID || 'appQ7YhzfebRDbSPJ';
-const Monitoreo_ID = process.env.AIRTABLE_MONITOREO_ID || 'appdvraKSdp0XVn5n';
-const Programa_Juntas_ID = process.env.AIRTABLE_PROGRAMA_JUNTAS_ID || 'appKFWzkcDEWlrXBE';
-const Symptoms_ID = process.env.AIRTABLE_SYMPTOMS_ID || 'appQRhZlQ9tMfYZWJ';
-const Webinars_Leads_ID = process.env.AIRTABLE_WEBINARS_LEADS_ID || 'appzjpVXTI0TgqGPq';
+const Calendar_ID = require('./runtimeConfig').get('AIRTABLE_CALENDAR_ID') || 'appIjEstWR6972tbF';
+const Config_ID = require('./runtimeConfig').get('AIRTABLE_CONFIG_ID') || 'app9K4EvGI8McC8jF';
+const Historial_Clinico_ID = require('./runtimeConfig').get('AIRTABLE_HISTORIAL_CLINICO_ID') || 'appdUpGUS06XIzVnY';
+const Logging_ID = require('./runtimeConfig').get('AIRTABLE_LOGGING_ID') || 'appQ7YhzfebRDbSPJ';
+const Monitoreo_ID = require('./runtimeConfig').get('AIRTABLE_MONITOREO_ID') || 'appdvraKSdp0XVn5n';
+const Programa_Juntas_ID = require('./runtimeConfig').get('AIRTABLE_PROGRAMA_JUNTAS_ID') || 'appKFWzkcDEWlrXBE';
+const Symptoms_ID = require('./runtimeConfig').get('AIRTABLE_SYMPTOMS_ID') || 'appQRhZlQ9tMfYZWJ';
+const Webinars_Leads_ID = require('./runtimeConfig').get('AIRTABLE_WEBINARS_LEADS_ID') || 'appzjpVXTI0TgqGPq';
 
 // Initialize Airtable only if API key is provided
 let airtable = null;
@@ -20,6 +21,17 @@ if (airtableConfig.apiKey) {
   airtable = new Airtable({ apiKey: airtableConfig.apiKey });
 }
 
+const BASE_MAP = {
+  calendar: Calendar_ID,
+  config: Config_ID,
+  historial: Historial_Clinico_ID,
+  logging: Logging_ID,
+  monitoreo: Monitoreo_ID,
+  programa: Programa_Juntas_ID,
+  symptoms: Symptoms_ID,
+  webinars: Webinars_Leads_ID
+};
+
 module.exports = {
   airtable,
   config: airtableConfig,
@@ -33,13 +45,17 @@ module.exports = {
   Webinars_Leads_ID,
   
   // Helper function to get base by ID
-  getBase: (baseId = process.env.AIRTABLE_BASE_ID) => {
+  getBase: (baseKeyOrId = require('./runtimeConfig').get('AIRTABLE_BASE_ID')) => {
     if (!airtable) {
       throw new Error('Airtable not configured. Please set AIRTABLE_API_KEY environment variable.');
     }
-    if (!baseId) {
-      throw new Error('Airtable base ID not provided. Please set AIRTABLE_BASE_ID environment variable or pass baseId parameter.');
+    let resolved = baseKeyOrId;
+    if (resolved && BASE_MAP[String(resolved).toLowerCase()]) {
+      resolved = BASE_MAP[String(resolved).toLowerCase()];
+    }
+    if (!resolved) {
+      throw new Error('Airtable base identifier not provided. Pass a base ID or one of: ' + Object.keys(BASE_MAP).join(', ') + '.');
     }
-    return airtable.base(baseId);
+    return airtable.base(resolved);
   }
 };

package/lib/config/runtimeConfig.js

@@ -0,0 +1,15 @@
+const overrides = new Map();
+
+function set(key, value) {
+  if (!key) return;
+  overrides.set(String(key), value);
+}
+
+function get(key, fallback = undefined) {
+  const k = String(key);
+  if (overrides.has(k)) return overrides.get(k);
+  return process.env[k] !== undefined ? process.env[k] : fallback;
+}
+
+module.exports = { set, get };
+

package/lib/controllers/conversationController.js

@@ -1,4 +1,3 @@
-// Use mongoose models directly to avoid conflicts
 const mongoose = require('mongoose');
 const { fetchConversationData, processConversations } = require('../services/conversationService');
 const { sendMessage } = require('../core/NexusMessaging');  

package/lib/controllers/mediaController.js

@@ -1,11 +1,4 @@
-// Optional AWS config - will be undefined if not available
-let downloadFileFromS3, s3;
-try {
-  downloadFileFromS3 = require('../config/awsConfig')?.downloadFileFromS3;
-  s3 = require('../config/awsConfig')?.s3;
-} catch (e) {
-  // AWS config not available
-}
+const { s3, downloadFileFromS3 } = require('../config/awsConfig');
 const bucketName = process.env.AWS_S3_BUCKET_NAME;
 
 
@@ -24,6 +17,14 @@ const getMediaController = async (req, res) => {
       });
     }
         
+    // Validate configuration
+    if (!downloadFileFromS3 || typeof downloadFileFromS3 !== 'function') {
+      return res.status(500).json({ success: false, error: 'downloadFileFromS3 not configured. Call configureMediaController() to inject it.' });
+    }
+    if (!bucketName) {
+      return res.status(500).json({ success: false, error: 'AWS_S3_BUCKET_NAME not configured. Pass bucketName to configureMediaController() or set env.' });
+    }
+
     let mediaKey = key;
         
     console.log(`[MediaController] Final S3 key to fetch: ${mediaKey}`);
@@ -32,36 +33,37 @@ const getMediaController = async (req, res) => {
         
     if (!fileData || !fileData.Body) {
       console.error(`[MediaController] Media not found in S3: ${key}`);
-            
-      try {
-        const prefix = key.split('/')[0];
-        console.log(`[MediaController] Checking S3 for objects with prefix: ${prefix}/`);
-                
-        s3.listObjectsV2({
-          Bucket: bucketName,
-          Prefix: prefix + '/',
-          MaxKeys: 10
-        }).promise()
-          .then(listData => {
-            if (listData.Contents && listData.Contents.length > 0) {
-              console.log(`[MediaController] Found ${listData.Contents.length} objects with similar prefix:`);
-              listData.Contents.forEach(item => {
-                console.log(`[MediaController] - ${item.Key} (${item.Size} bytes)`);
-                if (item.Key.includes(key.split('/').pop().substring(0, 10))) {
-                  console.log(`[MediaController] !!! POTENTIAL MATCH: ${item.Key}`);
-                }
-              });
-            } else {
-              console.log(`[MediaController] No objects found with prefix: ${prefix}/`);
-            }
-          })
-          .catch(listErr => {
-            console.error(`[MediaController] Error listing objects: ${listErr.message}`);
-          });
-      } catch (listErr) {
-        console.error(`[MediaController] Error setting up bucket listing: ${listErr.message}`);
+
+      if (s3) {
+        try {
+          const prefix = key.split('/') [0];
+          console.log(`[MediaController] Checking S3 for objects with prefix: ${prefix}/`);
+          s3.listObjectsV2({
+            Bucket: bucketName,
+            Prefix: prefix + '/',
+            MaxKeys: 10
+          }).promise()
+            .then(listData => {
+              if (listData.Contents && listData.Contents.length > 0) {
+                console.log(`[MediaController] Found ${listData.Contents.length} objects with similar prefix:`);
+                listData.Contents.forEach(item => {
+                  console.log(`[MediaController] - ${item.Key} (${item.Size} bytes)`);
+                  if (item.Key.includes(key.split('/').pop().substring(0, 10))) {
+                    console.log(`[MediaController] !!! POTENTIAL MATCH: ${item.Key}`);
+                  }
+                });
+              } else {
+                console.log(`[MediaController] No objects found with prefix: ${prefix}/`);
+              }
+            })
+            .catch(listErr => {
+              console.error(`[MediaController] Error listing objects: ${listErr.message}`);
+            });
+        } catch (listErr) {
+          console.error(`[MediaController] Error setting up bucket listing: ${listErr.message}`);
+        }
       }
-            
+
       return res.status(404).json({
         success: false,
         error: 'Media not found in S3',
@@ -102,4 +104,4 @@ const getMediaController = async (req, res) => {
 
 module.exports = {
   getMediaController
-};
+};

package/lib/controllers/messageController.js

@@ -1,23 +1,84 @@
 const { Message } = require('../models/messageModel.js');
+const { ScheduledMessage: DefaultScheduledMessage } = require('../models/agendaMessageModel.js');
+const {
+  sendMessage: defaultSendMessage,
+  sendScheduledMessage: defaultSendScheduledMessage
+} = require('../core/NexusMessaging');
+const { getRecordByFilter: defaultGetRecordByFilter } = require('../services/airtableService');
+const runtimeConfig = require('../config/runtimeConfig');
+const moment = require('moment-timezone');
 
-// Import from Nexus core
-const { sendMessage } = require('../core/NexusMessaging');
+const dependencies = {
+  ScheduledMessage: DefaultScheduledMessage,
+  getRecordByFilter: defaultGetRecordByFilter,
+  sendScheduledMessage: defaultSendScheduledMessage,
+  sendMessage: defaultSendMessage
+};
 
-// Injectable dependencies with safe defaults
-let injected = {
-  ScheduledMessage: null,
-  getRecordByFilter: null,
-  sendScheduledMessage: null
+const configureMessageController = (overrides = {}) => {
+  if (overrides.ScheduledMessage) dependencies.ScheduledMessage = overrides.ScheduledMessage;
+  if (overrides.getRecordByFilter) dependencies.getRecordByFilter = overrides.getRecordByFilter;
+  if (overrides.sendScheduledMessage) dependencies.sendScheduledMessage = overrides.sendScheduledMessage;
+  if (overrides.sendMessage) dependencies.sendMessage = overrides.sendMessage;
+  return { ...dependencies };
 };
 
-// Allow consumers to inject their model and services
-const configureMessageController = ({ ScheduledMessage, getRecordByFilter, sendScheduledMessage } = {}) => {
-  if (ScheduledMessage) injected.ScheduledMessage = ScheduledMessage;
-  if (getRecordByFilter) injected.getRecordByFilter = getRecordByFilter;
-  if (sendScheduledMessage) injected.sendScheduledMessage = sendScheduledMessage;
+const ensureDependency = (res, condition, errorMessage) => {
+  if (condition) return true;
+  res.status(500).json({ success: false, error: errorMessage });
+  return false;
 };
 
-const moment = require('moment-timezone');
+const persistScheduledMessage = async (Model, payload) => {
+  if (Model && typeof Model.create === 'function') {
+    return await Model.create(payload);
+  }
+  if (typeof Model === 'function') {
+    const instance = new Model(payload);
+    if (typeof instance.save === 'function') {
+      await instance.save();
+      return instance;
+    }
+  }
+  throw new Error('ScheduledMessage model must expose create() or constructor+save()');
+};
+
+const pickMessageId = (result, fallbackDoc) => {
+  if (result) {
+    const id = result.sid || result.messageId || result.id || result._id;
+    if (id) return id;
+  }
+
+  if (fallbackDoc) {
+    const docId = fallbackDoc.wa_id || fallbackDoc.sid || fallbackDoc.id || fallbackDoc._id;
+    if (docId) return typeof docId === 'object' && docId.toString ? docId.toString() : docId;
+  }
+
+  return null;
+};
+
+const normalizeCode = (code) => {
+  if (!code || typeof code !== 'string') return code;
+
+  const trimmed = code.trim();
+  if (trimmed.startsWith('whatsapp:')) {
+    return trimmed;
+  }
+
+  if (trimmed.includes('@')) {
+    return trimmed;
+  }
+
+  if (trimmed.startsWith('+')) {
+    return `whatsapp:${trimmed}`;
+  }
+
+  if (/^\d+$/.test(trimmed)) {
+    return `whatsapp:+${trimmed}`;
+  }
+
+  return trimmed;
+};
 
 const sendMessageController = async (req, res) => {
   const {
@@ -31,38 +92,43 @@ const sendMessageController = async (req, res) => {
     contentSid = null,
     variables = null
   } = req.body || {};
-  const author = process.env.USER_DB_MONGO;
+  const author = runtimeConfig.get('USER_DB_MONGO');
   const sendMoment = sendTime ? moment.tz(sendTime, timeZone) + 2500 : new Date();
 
+  const ScheduledMessageModel = dependencies.ScheduledMessage;
+  if (!ensureDependency(res, ScheduledMessageModel, 'ScheduledMessage model not configured. Call configureMessageController() to inject it.')) return;
+
+  const hasScheduler = typeof dependencies.sendScheduledMessage === 'function';
+  const hasDirectSend = typeof dependencies.sendMessage === 'function';
+  if (!ensureDependency(res, hasScheduler || hasDirectSend, 'No messaging provider configured. Ensure Nexus.initialize() completed before using the message controllers.')) return;
+
   try {
-    if (!injected.ScheduledMessage || typeof injected.ScheduledMessage.create !== 'function') {
-      return res.status(500).json({ success: false, error: 'ScheduledMessage model not configured. Call configureMessageController() to inject it.' });
-    }
-    const messageData = {
+    const payload = {
       fileUrl,
       message,
       fileType,
       timeZone: timeZone === '' ? null : timeZone,
       sendTime: sendMoment,
-      contentSid: contentSid,
+      contentSid,
       hidePreview,
-      code,
+      code: normalizeCode(code),
       author,
       extraDelay: 0,
       variables
     };
-    await injected.ScheduledMessage.create(messageData);
-    console.log('Sending message with data:', messageData);
-    
-    const result = await sendMessage(messageData);
-    
+
+    const scheduledRecord = await persistScheduledMessage(ScheduledMessageModel, payload);
+    const result = hasScheduler
+      ? await dependencies.sendScheduledMessage(scheduledRecord)
+      : await dependencies.sendMessage(payload);
+
     res.status(200).json({
-      success: true,
-      message: 'Message sent successfully',
-      messageId: result?.sid || result?.id
+      status: 200,
+      response: hasScheduler ? 'Message scheduled to be sent once!' : 'Message sent successfully',
+      messageId: pickMessageId(result, scheduledRecord)
     });
   } catch (err) {
-    console.error('Error scheduling individual message:', err.message);
+    console.error('Error scheduling individual message:', err);
     res.status(500).json({ status: false, error: err.message });
   }
 };
@@ -72,70 +138,71 @@ const sendBulkMessageController = async (req, res) => {
     fileUrl,
     message,
     fileType,
-    codes,
+    codes = [],
     sendTime = new Date(),
     timeZone = 'Etc/GMT',
     hidePreview = false,
     contentSid = null,
     variables = null
   } = req.body || {};
-  const author = process.env.USER_DB_MONGO;
-  const sendMoment = sendTime ? moment.tz(sendTime, timeZone) + 20*1000 : new Date();
+  const author = runtimeConfig.get('USER_DB_MONGO');
+  const sendMoment = sendTime ? moment.tz(sendTime, timeZone) + 20 * 1000 : new Date();
+
+  const ScheduledMessageModel = dependencies.ScheduledMessage;
+  if (!ensureDependency(res, ScheduledMessageModel, 'ScheduledMessage model not configured. Call configureMessageController() to inject it.')) return;
+
+  const hasScheduler = typeof dependencies.sendScheduledMessage === 'function';
+  const hasDirectSend = typeof dependencies.sendMessage === 'function';
+  if (!ensureDependency(res, hasScheduler || hasDirectSend, 'No messaging provider configured. Ensure Nexus.initialize() completed before using the message controllers.')) return;
 
   try {
-    if (!injected.ScheduledMessage || typeof injected.ScheduledMessage.create !== 'function') {
-      return res.status(500).json({ success: false, error: 'ScheduledMessage model not configured. Call configureMessageController() to inject it.' });
-    }
-    if (!injected.sendScheduledMessage || typeof injected.sendScheduledMessage !== 'function') {
-      return res.status(500).json({ success: false, error: 'sendScheduledMessage not configured. Call configureMessageController() to inject it.' });
-    }
     let numSend = 0;
     let extraDelay = 0;
-    let curMessage = message;
-    const scheduledMessages = [];
-    for (const code of codes) {
-      const scheduledMessage = new injected.ScheduledMessage({
+    const scheduledPayloads = [];
+
+    for (const recipient of codes) {
+      const payload = {
         fileUrl,
-        message: curMessage,
+        message,
         fileType,
         timeZone: timeZone === '' ? null : timeZone,
         sendTime: new Date(sendMoment + extraDelay),
-        contentSid: contentSid,
+        contentSid,
         hidePreview,
-        code,
+        code: normalizeCode(recipient),
         author,
         extraDelay,
         variables
-      });
-
-      // Add to scheduledMessages for both saving and scheduling
-      scheduledMessages.push(scheduledMessage);
+      };
 
-      // Increment delay and message counter
+      scheduledPayloads.push(payload);
       extraDelay += Math.floor(Math.random() * 5001) + 5000;
       numSend += 1;
     }
 
-    // Schedule all messages with Agenda in parallel
     const sentMessages = await Promise.all(
-      scheduledMessages.map(async (message) => {
-        const savedMessage = await injected.ScheduledMessage.create(message);
-        return injected.sendScheduledMessage(savedMessage);
+      scheduledPayloads.map(async (payload) => {
+        const savedMessage = await persistScheduledMessage(ScheduledMessageModel, payload);
+        const result = hasScheduler
+          ? await dependencies.sendScheduledMessage(savedMessage)
+          : await dependencies.sendMessage(payload);
+        return { result, scheduled: savedMessage };
       })
     );
 
     console.log(`Send bulk of ${numSend} messages`);
 
-    // Extract message IDs
-    const messageIds = sentMessages.map(msg => msg ? msg.sid : null).filter(id => id !== null);
+    const messageIds = sentMessages
+      .map(({ result, scheduled }) => pickMessageId(result, scheduled))
+      .filter((id) => id !== null);
 
-    res.status(200).json({ 
-      status: true, 
+    res.status(200).json({
+      status: true,
       response: 'Bulk message sent',
-      messageIds: messageIds
+      messageIds
     });
   } catch (err) {
-    console.log(err.message);
+    console.error('Error sending bulk messages:', err);
     res.status(500).send(err.message);
   }
 };
@@ -155,8 +222,18 @@ const sendBulkMessageAirtableController = async (req, res) => {
     condition = '1',
     variables = null
   } = req.body || {};
-  const author = process.env.USER_DB_MONGO;
-  const sendMoment = sendTime ? moment.tz(sendTime, timeZone) + 20*1000 : new Date();
+  const author = runtimeConfig.get('USER_DB_MONGO');
+  const sendMoment = sendTime ? moment.tz(sendTime, timeZone) + 20 * 1000 : new Date();
+
+  const ScheduledMessageModel = dependencies.ScheduledMessage;
+  if (!ensureDependency(res, ScheduledMessageModel, 'ScheduledMessage model not configured. Call configureMessageController() to inject it.')) return;
+
+  const hasScheduler = typeof dependencies.sendScheduledMessage === 'function';
+  const hasDirectSend = typeof dependencies.sendMessage === 'function';
+  if (!ensureDependency(res, hasScheduler || hasDirectSend, 'No messaging provider configured. Ensure Nexus.initialize() completed before using the message controllers.')) return;
+
+  const airtableFetcher = dependencies.getRecordByFilter;
+  if (!ensureDependency(res, typeof airtableFetcher === 'function', 'Airtable getRecordByFilter not configured. Call configureMessageController() to inject it.')) return;
 
   const regex = /\[(.*?)\]/g;
   const envVariables = [];
@@ -166,24 +243,14 @@ const sendBulkMessageAirtableController = async (req, res) => {
   }
 
   try {
-    if (!injected.getRecordByFilter || typeof injected.getRecordByFilter !== 'function') {
-      return res.status(500).json({ success: false, error: 'Airtable getRecordByFilter not configured. Call configureMessageController() to inject it.' });
-    }
-    if (!injected.ScheduledMessage || typeof injected.ScheduledMessage.create !== 'function') {
-      return res.status(500).json({ success: false, error: 'ScheduledMessage model not configured. Call configureMessageController() to inject it.' });
-    }
-    if (!injected.sendScheduledMessage || typeof injected.sendScheduledMessage !== 'function') {
-      return res.status(500).json({ success: false, error: 'sendScheduledMessage not configured. Call configureMessageController() to inject it.' });
-    }
-    const rows = await injected.getRecordByFilter(baseId, tableName, condition);
+    const rows = await airtableFetcher(baseId, tableName, condition);
     let extraDelay = 0;
-    let curMessage = message;
     const sentPhones = new Set();
-    const scheduledMessages = [];
+    const scheduledPayloads = [];
+
+    for (const row of rows || []) {
+      let customMessage = message;
 
-    for (const row of rows) {
-      let customMessage = curMessage;
-            
       for (const envVar of envVariables) {
         let value = row[envVar];
         if (Array.isArray(value)) value = value[0];
@@ -195,54 +262,57 @@ const sendBulkMessageAirtableController = async (req, res) => {
       let code = row[columnPhone];
       if (Array.isArray(code)) code = code[0];
       if (!code) continue;
-      if (!code.includes('@g.us')) code = `${code}@s.whatsapp.net`;
+      code = normalizeCode(code);
 
       if (sentPhones.has(code)) continue;
       sentPhones.add(code);
 
-      // Prepare message object
-      const scheduledMessage = {
+      const payload = {
         fileUrl,
         message: customMessage,
         fileType,
         timeZone: timeZone === '' ? null : timeZone,
         sendTime: new Date(sendMoment + extraDelay),
-        contentSid: contentSid,
+        contentSid,
         hidePreview,
         code,
         author,
         variables
       };
-            
-      scheduledMessages.push(scheduledMessage);
+
+      scheduledPayloads.push(payload);
       extraDelay += Math.floor(Math.random() * 5001) + 5000;
     }
 
     const sentMessages = await Promise.all(
-      scheduledMessages.map(async (message) => {
-        const savedMessage = await injected.ScheduledMessage.create(message);
-        return injected.sendScheduledMessage(savedMessage);
+      scheduledPayloads.map(async (payload) => {
+        const savedMessage = await persistScheduledMessage(ScheduledMessageModel, payload);
+        const result = hasScheduler
+          ? await dependencies.sendScheduledMessage(savedMessage)
+          : await dependencies.sendMessage(payload);
+        return { result, scheduled: savedMessage };
       })
     );
 
-    // Extract message IDs
-    const messageIds = sentMessages.map(msg => msg ? msg.sid : null).filter(id => id !== null);
+    const messageIds = sentMessages
+      .map(({ result, scheduled }) => pickMessageId(result, scheduled))
+      .filter((id) => id !== null);
 
-    console.log(`Iterate over ${rows.length} rows`);
+    console.log(`Iterate over ${(rows || []).length} rows`);
 
-    res.status(200).json({ 
-      status: true, 
+    res.status(200).json({
+      status: true,
       response: 'Airtable message sent',
-      messageIds: messageIds
+      messageIds
     });
   } catch (err) {
-    console.log(err.message);
+    console.error('Error sending Airtable bulk messages:', err);
     res.status(500).send(err.message);
   }
 };
 
 const getLastInteractionController = async (req, res) => {
-  const { code } = req.body;
+  const { code } = req.query;
 
   try {
     const lastMessage = await Message.findOne({
@@ -255,7 +325,7 @@ const getLastInteractionController = async (req, res) => {
     if (!lastMessage) {
       return res.status(404).send({ message: 'No messages found for the provided code.' });
     }
-      
+
     const createdAt = new Date(lastMessage.createdAt);
     const now = new Date();
     const timeDiffMs = now - createdAt;
@@ -274,4 +344,4 @@ module.exports = {
   sendBulkMessageAirtableController,
   getLastInteractionController,
   configureMessageController
-};
+};

package/lib/controllers/templateController.js

@@ -1,11 +1,3 @@
-// Nexus provider will be injected - templates only work with Twilio
-let nexusProvider = null;
-
-// Configure Nexus provider
-const configureNexusProvider = (provider) => {
-  nexusProvider = provider;
-};
-
 // Check if provider supports templates
 const checkTemplateSupport = () => {
   if (!nexusProvider) {
@@ -20,10 +12,29 @@ const checkTemplateSupport = () => {
 
 const { handleApiError } = require('../utils/errorHandler');
 
-const { Template } = require('../templates/templateStructure');
+const {
+  Template,
+  configureNexusProvider: configureTemplateProvider
+} = require('../templates/templateStructure');
 const predefinedTemplates = require('../templates/predefinedTemplates');
 
 
+// Nexus provider will be injected - templates only work with Twilio
+let nexusProvider = null;
+
+// Configure Nexus provider
+const configureNexusProvider = (provider) => {
+  nexusProvider = provider;
+  if (typeof configureTemplateProvider === 'function') {
+    try {
+      configureTemplateProvider(provider);
+    } catch (err) {
+      console.warn('[templateController] Failed to propagate provider to template structure:', err?.message || err);
+    }
+  }
+};
+
+
 const getTemplateModel = () => {
   // Require the concrete model; enforce presence instead of stubbing
   try {

package/lib/core/NexusMessaging.js

@@ -441,7 +441,25 @@ class NexusMessaging {
   }
 }
 
-const defaultInstance = new NexusMessaging();
+let defaultInstance = new NexusMessaging();
+
+const setDefaultInstance = (instance) => {
+  if (!instance) {
+    throw new Error('setDefaultInstance requires a NexusMessaging instance');
+  }
+
+  const isCompatible = typeof instance.sendMessage === 'function' &&
+    typeof instance.sendScheduledMessage === 'function' &&
+    typeof instance.processIncomingMessage === 'function';
+
+  if (!isCompatible) {
+    throw new Error('setDefaultInstance received an incompatible object');
+  }
+
+  defaultInstance = instance;
+};
+
+const getDefaultInstance = () => defaultInstance;
 
 const sendMessage = async (messageData) => {
   return await defaultInstance.sendMessage(messageData);
@@ -454,5 +472,7 @@ const sendScheduledMessage = async (scheduledMessage) => {
 module.exports = { 
   NexusMessaging,
   sendMessage,
-  sendScheduledMessage
+  sendScheduledMessage,
+  setDefaultInstance,
+  getDefaultInstance
 };

package/lib/helpers/assistantHelper.js

@@ -1,5 +1,5 @@
 const { downloadFileFromS3, generatePresignedUrl } = require('../config/awsConfig.js');
-const { openaiClient } = require('../config/llmConfig.js');
+const llmConfig = require('../config/llmConfig.js');
 
 const { Message } = require('../models/messageModel.js');
 
@@ -16,7 +16,9 @@ const mode = process.env.NODE_ENV || 'dev';
 
 async function checkRunStatus(assistant, thread_id, run_id, retryCount = 0, maxRetries = 30) {
   try {
-    const run = await openaiClient.beta.threads.runs.retrieve(thread_id, run_id);
+    const client = llmConfig.openaiClient;
+    if (!client) throw new Error('OpenAI client not configured');
+    const run = await client.beta.threads.runs.retrieve(thread_id, run_id);
     console.log(`Status: ${run.status} ${thread_id} ${run_id} (attempt ${retryCount + 1})`);
 
     if (run.status === 'failed' || run.status === 'expired' || run.status === 'incomplete') {
@@ -47,7 +49,9 @@ async function checkRunStatus(assistant, thread_id, run_id, retryCount = 0, maxR
 
 async function checkIfFinished(text) {
   try {
-    const completion = await openaiClient.chat.completions.create({
+    const client = llmConfig.openaiClient;
+    if (!client) throw new Error('OpenAI client not configured');
+    const completion = await client.chat.completions.create({
       model: 'gpt-4o-mini',
       messages: [
         {
@@ -210,7 +214,9 @@ async function processMessage(code, reply, thread) {
           const imageAnalysis = await analyzeImage(fileName);
           console.log(imageAnalysis);
           const invalidAnalysis = ['NOT_MEDICAL', 'QUALITY_INSUFFICIENT'];
-          url = await generatePresignedUrl(reply.media.bucketName, reply.media.key);
+          if (imageAnalysis.medical_relevance) {
+            url = await generatePresignedUrl(reply.media.bucketName, reply.media.key);            
+          }
           if (imageAnalysis.has_table) {
             messagesChat.push({
               type: 'text',
@@ -223,7 +229,9 @@ async function processMessage(code, reply, thread) {
             });
           } else {
             console.log('Add attachment');
-            const file = await openaiClient.files.create({
+            const client = llmConfig.openaiClient;
+            if (!client) throw new Error('OpenAI client not configured');
+            const file = await client.files.create({
               file: fs.createReadStream(fileName),
               purpose: 'vision',
             });
@@ -233,7 +241,9 @@ async function processMessage(code, reply, thread) {
             });
           }
         } else if (fileName.includes('audio')) {
-          const audioTranscript = await openaiClient.audio.transcriptions.create({
+          const client = llmConfig.openaiClient;
+          if (!client) throw new Error('OpenAI client not configured');
+          const audioTranscript = await client.audio.transcriptions.create({
             model: 'whisper-1',
             file: fs.createReadStream(fileName),
             response_format: 'text',
@@ -251,7 +261,9 @@ async function processMessage(code, reply, thread) {
     console.log('messagesChat', messagesChat);
     console.log('attachments', attachments);
 
-    await openaiClient.beta.threads.messages.create(thread.thread_id, {
+    const client = llmConfig.openaiClient;
+    if (!client) throw new Error('OpenAI client not configured');
+    await client.beta.threads.messages.create(thread.thread_id, {
       role: 'user',
       content: messagesChat,
       attachments: attachments

package/lib/index.js

@@ -1,4 +1,4 @@
-const { NexusMessaging } = require('./core/NexusMessaging');
+const { NexusMessaging, setDefaultInstance } = require('./core/NexusMessaging');
 const { MongoStorage } = require('./storage/MongoStorage');
 const { MessageParser } = require('./utils/messageParser');
 const { DefaultLLMProvider } = require('./utils/defaultLLMProvider');
@@ -6,6 +6,8 @@ const { loadNexusConfig } = require('./config/configLoader');
 const templateController = require('./controllers/templateController');
 const templateFlowController = require('./controllers/templateFlowController');
 const interactive = require('./interactive');
+const runtimeConfig = require('./config/runtimeConfig');
+const llmConfigModule = require('./config/llmConfig');
 const {
   configureLLMProvider: configureAssistantsLLM,
   registerAssistant,
@@ -22,6 +24,11 @@ class Nexus {
   constructor(config = {}) {
     this.config = config;
     this.messaging = new NexusMessaging(config.messaging || {});
+    try {
+      setDefaultInstance(this.messaging);
+    } catch (err) {
+      console.warn('[Nexus] Failed to set default messaging instance:', err?.message || err);
+    }
     this.storage = null;
     this.messageParser = null;
     this.llmProvider = null;
@@ -75,6 +82,23 @@ class Nexus {
       console.warn('Warning: failed to auto-configure template providers:', e?.message || e);
     }
 
+
+    // Convenience: handle mongoUri early (before storage connect)
+    try {
+      if (options.mongoUri) {
+        if (storage === 'mongo') {
+          if (typeof storageConfig === 'object' && !storageConfig.mongoUri) {
+            storageConfig.mongoUri = options.mongoUri;
+          }
+        } else {
+          // If not using MongoStorage but a URI is provided, initialize default mongoose connection
+          await this.messaging.initializeMongoDB(options.mongoUri);
+        }
+      }
+    } catch (dbErr) {
+      console.warn('[Nexus] mongo convenience warning:', dbErr?.message || dbErr);
+    }
+
     // Initialize storage if provided
     if (storage) {
       try {
@@ -104,6 +128,39 @@ class Nexus {
     // Initialize default LLM provider if requested
     if (llm === 'openai') {
       this.llmProvider = new DefaultLLMProvider(llmConfig);
+      try {
+        if (this.llmProvider && typeof this.llmProvider.getClient === 'function') {
+          llmConfigModule.openaiClient = this.llmProvider.getClient();
+        }
+      } catch (err) {
+        console.warn('[Nexus] Failed to expose OpenAI client:', err?.message || err);
+      }
+
+    // Convenience: handle common top-level config for mongo, media bucket, airtable
+    try {
+      // Mongo URI passthrough for storage=mongo
+      if (options.mongoUri && storage === 'mongo') {
+        if (typeof storageConfig === 'object') {
+          storageConfig.mongoUri = storageConfig.mongoUri || options.mongoUri;
+        }
+      }
+
+      // Media bucket (overrides storage setting)
+      if (options.media && options.media.bucketName) {
+        runtimeConfig.set('AWS_S3_BUCKET_NAME', options.media.bucketName);
+      }
+
+      // Airtable base default (accepts alias like 'calendar' or an ID)
+      if (options.airtable && options.airtable.base) {
+        runtimeConfig.set('AIRTABLE_BASE_ID', options.airtable.base);
+      }
+      if (options.airtable && options.airtable.apiKey) {
+        runtimeConfig.set('AIRTABLE_API_KEY', options.airtable.apiKey);
+      }
+    } catch (cfgErr) {
+      console.warn('[Nexus] convenience config warning:', cfgErr?.message || cfgErr);
+    }
+
     }
 
 

package/lib/interactive/twilioMapper.js

@@ -25,6 +25,7 @@ function toTwilioContent(spec) {
 
   if (type === 'flow') {
     content.types['twilio/flows'] = {
+      type: flow?.type || spec.flowType || 'FLOW',
       body: flow?.body || body || '',
       button_text: flow?.buttonText || spec.buttonText || undefined,
       subtitle: flow?.subtitle || spec.subtitle || undefined,

package/lib/models/messageModel.js

@@ -52,9 +52,40 @@ messageSchema.pre('save', function (next) {
 const Message = mongoose.model('Message', messageSchema);
 
 async function insertMessage(values) {
-  const msg = new Message(values);
-  await msg.save();
-  return msg;
+  try {
+    const skipNumbers = [
+      '5215592261426@s.whatsapp.net',
+      '5215547411345@s.whatsapp.net',
+      '51985959446@s.whatsapp.net'
+    ];
+    const messageData = {
+      nombre_whatsapp: values.nombre_whatsapp,
+      numero: values.numero,
+      body: values.body,
+      timestamp: values.timestamp,
+      message_id: values.message_id,
+      is_group: values.is_group,
+      is_media: values.is_media,
+      group_id: values.group_id,
+      reply_id: values.reply_id,
+      from_me: values.from_me,
+      processed: skipNumbers.includes(values.numero),
+      media: values.media ? values.media : null,
+      content_sid: values.content_sid || null,
+      template_variables: values.template_variables || null
+    };
+
+    await Message.findOneAndUpdate(
+      { message_id: values.message_id, body: values.body },
+      { $setOnInsert: messageData },
+      { upsert: true, new: true }
+    );
+
+    console.log('Message inserted or updated successfully');
+  } catch (err) {
+    console.error('Error inserting message:', err);
+    throw err;
+  }
 }
 
 function formatTimestamp(unixTimestamp) {
@@ -62,7 +93,7 @@ function formatTimestamp(unixTimestamp) {
   return date.toLocaleString('sv-MX', {
     timeZone: 'America/Mexico_City',
     hour12: false,
-  }).replace(' ', 'T').slice(0, 19);  
+  }).replace(' ', 'T').slice(0, 19);
 }
 
 function getMessageValues(message, content, reply, is_media) {
@@ -90,10 +121,27 @@ function getMessageValues(message, content, reply, is_media) {
   };
 }
 
+async function getContactDisplayName(contactNumber) {
+  try {
+    const latestMessage = await Message.findOne({ numero: contactNumber })
+      .sort({ timestamp: -1 })
+      .select('nombre_whatsapp');
+
+    if (latestMessage && latestMessage.nombre_whatsapp && latestMessage.nombre_whatsapp.trim() !== '') {
+      return latestMessage.nombre_whatsapp;
+    } else {
+      return contactNumber;
+    }
+  } catch (error) {
+    console.error(`Error fetching display name for ${contactNumber}:`, error);
+    return contactNumber;
+  }
+}
+
 module.exports = {
   Message,
-  // Backward-compatible helper used by helpers
   insertMessage,
   getMessageValues,
-  formatTimestamp
+  formatTimestamp,
+  getContactDisplayName
 };

package/lib/routes/index.js

@@ -32,7 +32,7 @@ const messageRouteDefinitions = {
   'POST /send': 'sendMessageController',
   'POST /send-bulk': 'sendBulkMessageController',
   'POST /send-bulk-airtable': 'sendBulkMessageAirtableController',
-  'POST /get-last': 'getLastInteractionController'
+  'GET /last': 'getLastInteractionController'
 };
 
 const templateRouteDefinitions = {

package/lib/services/assistantService.js

@@ -1,4 +1,8 @@
-const { Historial_Clinico_ID } = require('../config/airtableConfig.js');
+const { Historial_Clinico_ID, Monitoreo_ID } = require('../config/airtableConfig.js');
+const AWS = require('../config/awsConfig.js');
+const { combineImagesToPDF, cleanupFiles } = require('../helpers/filesHelper.js');
+const { addRecord } = require('../services/airtableService.js');
+const runtimeConfig = require('../config/runtimeConfig');
 
 let llmProvider = null;
 const configureLLMProvider = (provider) => {
@@ -243,6 +247,25 @@ const replyAssistant = async function (code, message_ = null, thread_ = null, ru
        
     if (urls.length > 0) {
       console.log('urls', urls);
+      const { pdfBuffer, processedFiles } = await combineImagesToPDF({ code });
+      console.log('AFTER COMBINED IN BUFFER', processedFiles);
+      const key = `${code}-${Date.now()}-combined.pdf`;
+      const bucket = runtimeConfig.get('AWS_S3_BUCKET_NAME');
+      if (bucket && pdfBuffer) {
+        await AWS.uploadBufferToS3(pdfBuffer, bucket, key, 'application/pdf');
+        const url = await AWS.generatePresignedUrl(bucket, key);
+        const curRow = await getCurRow(Monitoreo_ID, code);
+        const customer_id = curRow?.[0]?.recordID || curRow?.[0]?.record_id || curRow?.[0]?.id || null;
+        console.log('customer_id:', customer_id);
+        try {
+          await addRecord(Monitoreo_ID, 'estudios', [{ fields: { estudios: urls, combined_estudios: [{ url }], patient_id: customer_id ? [customer_id] : [] } }]);
+        } catch (e) {
+          console.warn('Failed to add Airtable estudios record:', e?.message || e);
+        }
+      }
+      if (processedFiles && processedFiles.length) {
+        await cleanupFiles(processedFiles);
+      }
     }
 
     thread = await getThread(code);

package/lib/storage/MongoStorage.js

@@ -1,4 +1,5 @@
 const mongoose = require('mongoose');
+const runtimeConfig = require('../config/runtimeConfig');
 
 /**
  * MongoDB storage interface for messages and interactions
@@ -16,21 +17,7 @@ class MongoStorage {
   }
 
   createSchemas() {
-    const messageSchema = new mongoose.Schema({
-      messageId: String,
-      numero: String,
-      body: String,
-      timestamp: String,
-      isGroup: { type: Boolean, default: false },
-      isMedia: { type: Boolean, default: false },
-      fromMe: { type: Boolean, default: false },
-      contentSid: String,
-      isTemplate: { type: Boolean, default: false },
-      templateVariables: String,
-      provider: String,
-      createdAt: { type: Date, default: Date.now }
-    });
-
+    const { Message } = require('../models/messageModel');
     const interactionSchema = new mongoose.Schema({
       messageId: String,
       numero: String,
@@ -54,7 +41,7 @@ class MongoStorage {
     });
 
     return {
-      Message: mongoose.models.Message || mongoose.model('Message', messageSchema),
+      Message,
       Interaction: mongoose.models.Interaction || mongoose.model('Interaction', interactionSchema),
       Thread: mongoose.models.Thread || mongoose.model('Thread', threadSchema)
     };
@@ -74,28 +61,52 @@ class MongoStorage {
 
   async saveMessage(messageData) {
     try {
-      const message = new this.schemas.Message({
-        messageId: messageData.messageId,
-        numero: messageData.to || messageData.from,
-        body: messageData.message || messageData.body,
-        timestamp: this.formatTimestamp(messageData.timestamp),
-        isGroup: messageData.isGroup || false,
-        isMedia: messageData.fileType && messageData.fileType !== 'text',
-        fromMe: messageData.fromMe || false,
-        contentSid: messageData.contentSid,
-        isTemplate: !!messageData.contentSid,
-        templateVariables: messageData.variables ? JSON.stringify(messageData.variables) : null,
-        provider: messageData.provider
-      });
-
-      await message.save();
-      return message;
+      const values = this.buildLegacyMessageValues(messageData);
+      const { insertMessage } = require('../models/messageModel');
+      await insertMessage(values);
+      return values;
     } catch (error) {
       console.error('Error saving message:', error);
       throw error;
     }
   }
 
+  buildLegacyMessageValues(messageData = {}) {
+    const numero = messageData.to || messageData.code || messageData.numero || messageData.from;
+    const normalizedNumero = typeof numero === 'string' ? numero : '';
+    const isGroup = normalizedNumero.includes('@g.us');
+    const isMedia = messageData.isMedia === true || (messageData.fileType && messageData.fileType !== 'text');
+    const now = new Date();
+    const timestamp = now.toISOString();
+    const nombre = messageData.nombre_whatsapp || messageData.author || messageData.fromName || runtimeConfig.get('USER_DB_MONGO') || process.env.USER_DB_MONGO || 'Nexus';
+    const textBody = messageData.message || messageData.body || (messageData.contentSid ? `[Template:${messageData.contentSid}]` : isMedia ? `[Media:${messageData.fileType || 'attachment'}]` : '');
+    const providerId = messageData.messageId || messageData.sid || messageData.id || messageData._id || `pending-${now.getTime()}-${Math.floor(Math.random()*1000)}`;
+
+    const media = messageData.media || (messageData.fileUrl ? {
+      url: messageData.fileUrl,
+      mediaType: messageData.fileType === 'text' ? null : (messageData.fileType || 'document'),
+      fileName: messageData.fileName || null,
+      contentType: messageData.contentType || null,
+      metadata: messageData.mediaMetadata || null
+    } : null);
+
+    return {
+      nombre_whatsapp: nombre,
+      numero: normalizedNumero,
+      body: textBody,
+      timestamp,
+      message_id: providerId,
+      is_group: isGroup,
+      is_media: isMedia,
+      group_id: isGroup ? normalizedNumero : null,
+      reply_id: messageData.reply_id || messageData.replyId || null,
+      from_me: messageData.fromMe !== undefined ? messageData.fromMe : true,
+      media,
+      content_sid: messageData.contentSid || null,
+      template_variables: messageData.variables ? JSON.stringify(messageData.variables) : null
+    };
+  }
+
   async saveInteractive(interactionData) {
     try {
       const interaction = new this.schemas.Interaction({

package/lib/templates/templateStructure.js

@@ -43,19 +43,21 @@ class Template {
   }
 
   addBodyVariation(text, variableDescriptions = []) {
+    const normalizedVariables = Template.normalizeVariables(variableDescriptions);
     this.variations.push({
       text: text,
-      variables: variableDescriptions
+      variables: normalizedVariables
     });
     return this;
   }
     
   setBody(text, variableDescriptions = []) {
-    this.addBodyVariation(text, variableDescriptions);
+    const normalizedVariables = Template.normalizeVariables(variableDescriptions);
+    this.addBodyVariation(text, normalizedVariables);
         
     const selectedVariation = this.variations.length > 1 ?
       this.variations[Math.floor(Math.random() * this.variations.length)] :
-      { text, variables: variableDescriptions };
+      { text, variables: normalizedVariables };
         
     const enhancedText = `${selectedVariation.text}`;
         
@@ -196,6 +198,49 @@ class Template {
     const createdTemplate = await nexusProvider.createTemplate(twilioFormat);
     return createdTemplate;
   }
+
+  static normalizeVariables(variableDescriptions = []) {
+    if (!variableDescriptions) return [];
+
+    if (Array.isArray(variableDescriptions)) {
+      return variableDescriptions;
+    }
+
+    if (typeof variableDescriptions === 'object') {
+      return Object.entries(variableDescriptions)
+        .sort(([a], [b]) => {
+          const na = Number(a);
+          const nb = Number(b);
+          if (!Number.isNaN(na) && !Number.isNaN(nb)) {
+            return na - nb;
+          }
+          return a.localeCompare(b);
+        })
+        .map(([key, value], index) => {
+          if (typeof value === 'string') {
+            return {
+              name: `var_${key}`,
+              description: value,
+              example: `Ejemplo ${key}`
+            };
+          }
+          if (value && typeof value === 'object') {
+            return {
+              name: value.name || `var_${key}`,
+              description: value.description || `Variable ${key}`,
+              example: value.example || value.default || `Ejemplo ${key}`
+            };
+          }
+          return {
+            name: `var_${key}`,
+            description: `Variable ${key}`,
+            example: `Ejemplo ${key}`
+          };
+        });
+    }
+
+    return [];
+  }
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "publishConfig": {
     "access": "public"