@peopl-health/nexus 3.3.10 → 3.3.12

package/lib/config/airtableConfig.js

@@ -6,16 +6,16 @@ const airtableConfig = {
   apiKey: runtimeConfig.get('AIRTABLE_API_KEY'),
 };
 
-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 Follow_Up_ID = require('./runtimeConfig').get('AIRTABLE_FOLLOW_UP_ID') || 'appBjKw1Ub0KkbZf0';
-const Webinars_Leads_ID = require('./runtimeConfig').get('AIRTABLE_WEBINARS_LEADS_ID') || 'appzjpVXTI0TgqGPq';
-const Product_ID = require('./runtimeConfig').get('AIRTABLE_PRODUCT_ID') || 'appu2YDW2pKDYLL5H';
+const Calendar_ID = runtimeConfig.get('AIRTABLE_CALENDAR_ID') || 'appIjEstWR6972tbF';
+const Config_ID = runtimeConfig.get('AIRTABLE_CONFIG_ID') || 'app9K4EvGI8McC8jF';
+const Historial_Clinico_ID = runtimeConfig.get('AIRTABLE_HISTORIAL_CLINICO_ID') || 'appdUpGUS06XIzVnY';
+const Logging_ID = runtimeConfig.get('AIRTABLE_LOGGING_ID') || 'appQ7YhzfebRDbSPJ';
+const Monitoreo_ID = runtimeConfig.get('AIRTABLE_MONITOREO_ID') || 'appdvraKSdp0XVn5n';
+const Programa_Juntas_ID = runtimeConfig.get('AIRTABLE_PROGRAMA_JUNTAS_ID') || 'appKFWzkcDEWlrXBE';
+const Symptoms_ID = runtimeConfig.get('AIRTABLE_SYMPTOMS_ID') || 'appQRhZlQ9tMfYZWJ';
+const Follow_Up_ID = runtimeConfig.get('AIRTABLE_FOLLOW_UP_ID') || 'appBjKw1Ub0KkbZf0';
+const Webinars_Leads_ID = runtimeConfig.get('AIRTABLE_WEBINARS_LEADS_ID') || 'appzjpVXTI0TgqGPq';
+const Product_ID = runtimeConfig.get('AIRTABLE_PRODUCT_ID') || 'appu2YDW2pKDYLL5H';
 
 let airtable = null;
 if (airtableConfig.apiKey) {
@@ -48,7 +48,7 @@ module.exports = {
   Follow_Up_ID,
   Webinars_Leads_ID,
   Product_ID,
-  getBase: (baseKeyOrId = require('./runtimeConfig').get('AIRTABLE_BASE_ID')) => {
+  getBase: (baseKeyOrId = runtimeConfig.get('AIRTABLE_BASE_ID')) => {
     if (!airtable) {
       throw new Error('Airtable not configured. Please set AIRTABLE_API_KEY environment variable.');
     }

package/lib/core/AssistantProcessor.js

@@ -0,0 +1,41 @@
+/**
+ * Handles assistant message processing with local or queue modes.
+ */
+class AssistantProcessor {
+  constructor({ mode = 'local', queueAdapter = null, sendMessage = null, replyAssistant = null }) {
+    Object.assign(this, { mode, queueAdapter, sendMessage, replyAssistant });
+    if (mode === 'queue' && queueAdapter) {
+      queueAdapter.process('assistant.process', (payload) => this._processLocal(payload));
+    }
+  }
+
+  setReplyAssistant(fn) { this.replyAssistant = fn; }
+  setSendMessage(fn) { this.sendMessage = fn; }
+
+  async process({ code, body = null, runOptions = {} }) {
+    if (!code) throw new Error('code is required for assistant processing');
+    if (this.mode === 'queue') return await this._processViaQueue({ code, body, runOptions });
+    return await this._processLocal({ code, body, runOptions });
+  }
+
+  async _processLocal({ code, body = null, runOptions = {} }) {
+    if (!this.replyAssistant) throw new Error('replyAssistant function not configured');
+    return await this.replyAssistant(code, body, null, runOptions);
+  }
+
+  async _processViaQueue({ code, body, runOptions }) {
+    if (!this.queueAdapter) throw new Error('queueAdapter is required for queue mode');
+    const jobId = await this.queueAdapter.enqueue('assistant.process', { code, body, runOptions });
+    return await this.queueAdapter.waitForResult(jobId, 120000);
+  }
+
+  async sendResponse(code, result) {
+    if (!this.sendMessage) throw new Error('sendMessage function not configured');
+    if (!result?.output) return null;
+    await this.sendMessage({ code, body: result.output, processed: true, origin: 'assistant', tools_executed: result.tools_executed, prompt: result.prompt, response_id: result.response_id });
+    return result.output;
+  }
+
+}
+
+module.exports = { AssistantProcessor };

package/lib/core/BatchingManager.js

@@ -0,0 +1,122 @@
+const { logger } = require('../utils/logger');
+const { Message } = require('../models/messageModel');
+
+/**
+ * Manages message batching, processing locks, and run abandonment.
+ */
+class BatchingManager {
+  constructor({ provider = null, config = {} }) {
+    this.provider = provider;
+    this.config = {
+      enabled: config.enabled ?? true,
+      abortOnNewMessage: config.abortOnNewMessage ?? true,
+      immediateRestart: config.immediateRestart ?? true,
+      typingIndicator: config.typingIndicator ?? false
+    };
+
+    this.processingLocks = new Map();
+    this.activeRequests = new Map();
+    this.abandonedRuns = new Set();
+    this.typingIntervals = new Map();
+  }
+
+  setProvider(provider) {
+    this.provider = provider;
+  }
+
+  isProcessing(chatId) {
+    return this.processingLocks.has(chatId);
+  }
+
+  isActiveRun(chatId, runId) {
+    return this.activeRequests.get(chatId) === runId && !this.abandonedRuns.has(runId);
+  }
+
+  async handleBatchedProcessing(chatId, processingFn, sendResponseFn) {
+    if (this.processingLocks.has(chatId)) {
+      if (this.config.abortOnNewMessage && this.activeRequests.has(chatId)) {
+        const runId = this.activeRequests.get(chatId);
+        this.abandonedRuns.add(runId);
+        logger.info('[BatchingManager] Marked run as abandoned', { runId, chatId });
+
+        if (this.config.immediateRestart) {
+          this._clearProcessingState(chatId);
+          await this._processWithLock(chatId, processingFn, sendResponseFn);
+        }
+      }
+      return;
+    }
+
+    this.processingLocks.set(chatId, true);
+    await this._processWithLock(chatId, processingFn, sendResponseFn);
+  }
+
+  async _processWithLock(chatId, processingFn, sendResponseFn) {
+    this.processingLocks.set(chatId, true);
+    const runId = `run_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+    this.activeRequests.set(chatId, runId);
+
+    try {
+      await this._startTypingRefresh(chatId, runId);
+      if (this._checkAbandoned(runId)) return;
+
+      const result = await processingFn(runId);
+      if (this._checkAbandoned(runId)) return;
+
+      if (sendResponseFn && result) await sendResponseFn(result);
+    } catch (error) {
+      logger.error('[BatchingManager] Error processing messages', { chatId, error: error.message });
+    } finally {
+      if (this.activeRequests.get(chatId) === runId) {
+        this._clearProcessingState(chatId);
+      }
+      if (this.abandonedRuns.size > 100) {
+        const toKeep = [...this.abandonedRuns].slice(-20);
+        this.abandonedRuns.clear();
+        toKeep.forEach(id => this.abandonedRuns.add(id));
+      }
+    }
+  }
+
+  _clearProcessingState(chatId) {
+    this.processingLocks.delete(chatId);
+    this.activeRequests.delete(chatId);
+    this._stopTyping(chatId);
+  }
+
+  _stopTyping(chatId) {
+    const interval = this.typingIntervals.get(chatId);
+    if (interval) {
+      clearInterval(interval);
+      this.typingIntervals.delete(chatId);
+    }
+  }
+
+  _checkAbandoned(runId) {
+    if (this.abandonedRuns.has(runId)) {
+      this.abandonedRuns.delete(runId);
+      logger.debug('[BatchingManager] Run was abandoned', { runId });
+      return true;
+    }
+    return false;
+  }
+
+  async _startTypingRefresh(chatId, runId) {
+    if (!this.config.typingIndicator || !this.provider?.sendTypingIndicator) return;
+
+    const lastMessage = await Message.findOne({
+      numero: chatId, from_me: false, processed: false,
+      message_id: { $exists: true, $ne: null, $not: /^pending-/ }
+    }).sort({ createdAt: -1 });
+
+    if (!lastMessage?.message_id || this.activeRequests.get(chatId) !== runId) return;
+
+    this.typingIntervals.set(chatId, setInterval(() => {
+      this.provider.sendTypingIndicator(lastMessage.message_id)
+        .catch(err => logger.debug('[BatchingManager] Typing indicator failed', { chatId, error: err.message }));
+    }, 5000));
+  }
+
+}
+
+module.exports = { BatchingManager };

package/lib/core/MessageParser.js

@@ -1,5 +1,8 @@
 const MEDIA_TYPE_REGEX = /(image|audio|video|document)/;
 
+/**
+ * Parses raw messages into normalized MessageData format.
+ */
 class MessageParser {
   constructor(config = {}) {
     this.config = config;

package/lib/core/NexusMessaging.js

@@ -19,11 +19,15 @@ const { createMessagingProvider } = require('../adapters/registry');
 const { addMsgAssistant, replyAssistant } = require('../services/assistantService');
 const { hasPreprocessingHandler, invokePreprocessingHandler } = require('../services/preprocessingService');
 
-class NexusMessaging {
-  /*
-   * INITIALIZATION
-   */
+const { BatchingManager } = require('../core/BatchingManager');
+const { AssistantProcessor } = require('../core/AssistantProcessor');
+
+const { createQueueAdapter } = require('../queue');
 
+/**
+ * Core messaging orchestrator for providers, storage, and assistant processing.
+ */
+class NexusMessaging {
   constructor(config = {}) {
     this.config = config;
     this.provider = null;
@@ -49,18 +53,28 @@ class NexusMessaging {
       keyword: [],
       flow: []
     };
-    this.processingLocks = new Map();
-    this.activeRequests = new Map();
-    this.abandonedRuns = new Set();
-    this.typingIntervals = new Map();
+
     this.batchingConfig = {
       enabled: config.messageBatching?.enabled ?? true,
       abortOnNewMessage: config.messageBatching?.abortOnNewMessage ?? true,
       immediateRestart: config.messageBatching?.immediateRestart ?? true,
-      batchWindowMs: config.messageBatching?.batchWindowMs ?? 2000,
-      maxBatchWait: config.messageBatching?.maxBatchWait ?? 5000,
       typingIndicator: config.messageBatching?.typingIndicator ?? false
     };
+
+    this.batchingManager = new BatchingManager({
+      config: this.batchingConfig
+    });
+
+    const queueType = config.queue?.type || 'local';
+    const queueConfig = config.queue?.config || {};
+    this.queueAdapter = createQueueAdapter(queueType, queueConfig);
+
+    this.assistantProcessor = new AssistantProcessor({
+      mode: config.assistant?.mode || 'local',
+      queueAdapter: this.queueAdapter,
+      sendMessage: this.sendMessage.bind(this),
+      replyAssistant
+    });
   }
 
   async initialize(options = {}) {
@@ -108,6 +122,7 @@ class NexusMessaging {
       this.provider.setMessageStorage(this.messageStorage);
     }
     await this.provider.initialize();
+    this.batchingManager.setProvider(this.provider);
   }
 
   /*
@@ -139,8 +154,11 @@ class NexusMessaging {
   getProvider() { return this.provider; }
   getLLMProvider() { return this.llmProvider; }
   getEventBus() { return this.events; }
+  getBatchingManager() { return this.batchingManager; }
+  getAssistantProcessor() { return this.assistantProcessor; }
+  getQueueAdapter() { return this.queueAdapter; }
   isConnected() { return this.provider?.getConnectionStatus() ?? false; }
-  isProcessing(chatId) { return this.processingLocks.has(chatId); }
+  isProcessing(chatId) { return this.batchingManager.isProcessing(chatId); }
 
   /*
    * MIDDLEWARE
@@ -309,64 +327,32 @@ class NexusMessaging {
    */
 
   async handleMessageWithAssistant(messageData) {
-    if (messageData.isInteractive) return;
-    const { from, body } = this._extractAssistantInputs(messageData);
-    if (!from || !body) return;
+    const { from, body, isInteractive } = messageData;
+    if (isInteractive || !from || !body) return;
 
     try {
-      const result = await this._processMessages(from, () => replyAssistant(from, body));
-      await this._sendAssistantResponse(from, result);
+      const result = await this._processMessages(from, () => this.assistantProcessor.process({ code: from, body }));
+      await this.assistantProcessor.sendResponse(from, result);
     } catch (error) {
       logger.error('Error in handleMessageWithAssistant', { error: error.message });
     }
   }
 
   async handleMediaWithAssistant(messageData) {
-    const { from, body } = this._extractAssistantInputs(messageData);
+    const { from, body } = messageData;
     if (!from) return;
 
     const media = Array.isArray(messageData.media) ? messageData.media[0] : messageData.media;
     const message = body?.trim() || `Media received (${media?.mediaType || media?.type || 'attachment'})`;
 
     try {
-      const result = await this._processMessages(from, () => replyAssistant(from, message));
-      await this._sendAssistantResponse(from, result);
+      const result = await this._processMessages(from, () => this.assistantProcessor.process({ code: from, body: message }));
+      await this.assistantProcessor.sendResponse(from, result);
     } catch (error) {
       logger.error('Error in handleMediaWithAssistant', { error: error.message });
     }
   }
 
-  _extractAssistantInputs(messageData) {
-    if (!messageData || typeof messageData !== 'object') return { from: null, body: null };
-
-    const findFirst = (candidates) => candidates.find(v => typeof v === 'string' && v.trim().length > 0) || null;
-
-    const from = findFirst([
-      messageData.from, messageData.sender, messageData.numero, messageData.code, messageData.From,
-      messageData.key?.remoteJid, messageData.raw?.from, messageData.raw?.From, messageData.raw?.key?.remoteJid
-    ]);
-
-    const body = findFirst([
-      messageData.body, messageData.message?.conversation, messageData.Body,
-      messageData.raw?.message?.conversation, messageData.raw?.Body,
-      messageData.caption, messageData.media?.caption,
-      Array.isArray(messageData.media) ? messageData.media[0]?.caption : null
-    ]);
-
-    return { from, body };
-  }
-
-  async _sendAssistantResponse(code, result) {
-    const response = typeof result === 'string' ? result : result?.output;
-    if (!response) return null;
-
-    await this.sendMessage({
-      code, body: response, processed: true, origin: 'assistant',
-      tools_executed: result?.tools_executed, prompt: result?.prompt, response_id: result?.response_id
-    });
-    return response;
-  }
-
   /*
    * MEDIA PROCESSING
    */
@@ -412,137 +398,42 @@ class NexusMessaging {
    */
 
   async _handleWithCheckAfter(chatId) {
-    if (this.processingLocks.has(chatId)) {
-      if (this.batchingConfig.abortOnNewMessage && this.activeRequests.has(chatId)) {
-        const runId = this.activeRequests.get(chatId);
-        this.abandonedRuns.add(runId);
-        logger.info(`[CheckAfter] Marked run ${runId} as abandoned for ${chatId}`);
-
-        if (this.batchingConfig.immediateRestart) {
-          this._clearProcessingState(chatId);
-          await this._processWithLock(chatId, null);
-        }
-      }
-      return;
-    }
-    await this._processWithLock(chatId, await this._startTypingRefresh(chatId));
-  }
-
-  async _processWithLock(chatId, typingInterval = null) {
-    this.processingLocks.set(chatId, true);
-    if (typingInterval) {
-      this.typingIntervals.set(chatId, typingInterval);
-    }
-
-    const runId = `run_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
-    this.activeRequests.set(chatId, runId);
-
-    try {
-      if (!typingInterval) {
-        typingInterval = await this._startTypingRefresh(chatId);
-        if (typingInterval) {
-          this.typingIntervals.set(chatId, typingInterval);
-        }
-      }
-
-      const startTime = Date.now();
-      let lastCount = await this._getUnprocessedMessageCount(chatId);
-
-      while (Date.now() - startTime < this.batchingConfig.batchWindowMs) {
-        if (this._checkAbandoned(runId)) return;
-
-        await new Promise(r => setTimeout(r, 500));
-        const newCount = await this._getUnprocessedMessageCount(chatId);
-        if (newCount > lastCount) lastCount = newCount;
-        if (Date.now() - startTime >= this.batchingConfig.maxBatchWait) break;
-      }
-
-      if (this._checkAbandoned(runId)) return;
-
-      const result = await this._processMessages(chatId, () => replyAssistant(chatId, null, null, { runId }));
-      if (this._checkAbandoned(runId)) return;
-
-      if (typingInterval) {
-        clearInterval(typingInterval);
-        typingInterval = null;
-        this.typingIntervals.delete(chatId);
-      }
-
-      const response = await this._sendAssistantResponse(chatId, result);
-      this.events.emit('messages:processed', { chatId, response });
-    } catch (error) {
-      logger.error('[Batching] Error processing messages', { chatId, error: error.message });
-    } finally {
-      if (typingInterval) clearInterval(typingInterval);
-      this.typingIntervals.delete(chatId);
-      if (this.activeRequests.get(chatId) === runId) {
-        this.processingLocks.delete(chatId);
-        this.activeRequests.delete(chatId);
-      }
-      if (this.abandonedRuns.size > 100) this.abandonedRuns.clear();
-    }
-  }
-
-  _clearProcessingState(chatId) {
-    this.processingLocks.delete(chatId);
-    this.activeRequests.delete(chatId);
-    const interval = this.typingIntervals.get(chatId);
-    if (interval) {
-      clearInterval(interval);
-      this.typingIntervals.delete(chatId);
-    }
-  }
+    const processingFn = async (runId) => {
+      const shouldFinalize = () => this.batchingManager.isActiveRun(chatId, runId);
+      return await this._processMessages(chatId, () => this.assistantProcessor.process({ code: chatId, runOptions: { runId } }), shouldFinalize);
+    };
 
-  _checkAbandoned(runId) {
-    if (this.abandonedRuns.has(runId)) {
-      this.abandonedRuns.delete(runId);
-      return true;
-    }
-    return false;
-  }
+    const sendResponseFn = async (result) => {
+      await this.assistantProcessor.sendResponse(chatId, result);
+    };
 
-  async _getUnprocessedMessageCount(chatId) {
-    return Message.countDocuments({ numero: chatId, processed: false, from_me: false });
+    await this.batchingManager.handleBatchedProcessing(chatId, processingFn, sendResponseFn);
   }
 
-  async _processMessages(chatId, processingFn) {
+  async _processMessages(chatId, processingFn, shouldFinalize = () => true) {
     const query = { numero: chatId, from_me: false, processed: false };
     const unprocessed = await Message.find(query).select('_id');
 
     try {
       const result = await processingFn();
-      if (unprocessed.length > 0) {
+      if (unprocessed.length > 0 && shouldFinalize()) {
         await Message.updateMany({ _id: { $in: unprocessed.map(m => m._id) } }, { $set: { processed: true } });
-        logger.info(`[_processMessages] Marked ${unprocessed.length} messages as processed for ${chatId}`);
+        logger.info('[_processMessages] Marked messages as processed', { count: unprocessed.length, chatId });
       }
       return result;
     } catch (error) {
-      logger.debug(`[_processMessages] Processing failed for ${chatId}`);
+      logger.debug('[_processMessages] Processing failed', { chatId });
       throw error;
     }
   }
 
-  async _startTypingRefresh(chatId) {
-    if (!this.batchingConfig.typingIndicator || !this.provider?.sendTypingIndicator) return null;
-
-    const lastMessage = await Message.findOne({
-      numero: chatId, from_me: false, processed: false,
-      message_id: { $exists: true, $ne: null, $not: /^pending-/ }
-    }).sort({ createdAt: -1 });
-
-    if (!lastMessage?.message_id) return null;
-
-    return setInterval(() =>
-      this.provider.sendTypingIndicator(lastMessage.message_id).catch(() => {}), 5000
-    );
-  }
-
   /*
    * LIFECYCLE
    */
 
   async disconnect() {
     if (this.provider) await this.provider.disconnect();
+    if (this.queueAdapter) await this.queueAdapter.shutdown();
   }
 }
 

package/lib/helpers/twilioHelper.js

@@ -2,6 +2,9 @@ const axios = require('axios');
 const { v4: uuidv4 } = require('uuid');
 
 const runtimeConfig = require('../config/runtimeConfig');
+const { isAllowedUrl, redactUrl } = require('../utils/sanitizerUtils');
+
+const TWILIO_CDN_DOMAINS = ['api.twilio.com', 'mms.twiliocdn.com', 'media.twiliocdn.com'];
 
 function convertTwilioToInternalFormat(twilioMessage) {
   const from = twilioMessage.From || '';
@@ -23,29 +26,59 @@ function convertTwilioToInternalFormat(twilioMessage) {
 }
 
 async function downloadMediaFromTwilio(mediaUrl, logger, maxRetries = 5) {
+  if (!isAllowedUrl(mediaUrl, TWILIO_CDN_DOMAINS)) {
+    throw new Error('Invalid media URL domain');
+  }
+
   const accountSid = runtimeConfig.get('TWILIO_ACCOUNT_SID');
   const authToken = runtimeConfig.get('TWILIO_AUTH_TOKEN');
   const authorization = `Basic ${Buffer.from(`${accountSid}:${authToken}`).toString('base64')}`;
 
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
     try {
-      logger.debug('[TwilioMedia] Download attempt', { attempt, maxRetries });
+      logger.debug('[TwilioMedia] Download attempt', { attempt, maxRetries, url: redactUrl(mediaUrl) });
       
-      const response = await axios.get(mediaUrl, {
+      const redirectResponse = await axios.get(mediaUrl, {
         headers: {
           'Authorization': authorization,
           'User-Agent': 'Nexus-Media-Processor/1.0'
         },
+        maxRedirects: 0,
+        validateStatus: status => status >= 200 && status < 400,
+        responseType: 'arraybuffer',
+        timeout: 30000
+      });
+
+      if (redirectResponse.status === 200) {
+        return Buffer.from(redirectResponse.data);
+      }
+      
+      const cdnUrl = redirectResponse.headers.location;
+      if (!cdnUrl) {
+        throw new Error('No redirect URL in response');
+      }
+
+      if (!isAllowedUrl(cdnUrl, TWILIO_CDN_DOMAINS)) {
+        throw new Error('Redirect URL not in allowed domains');
+      }
+
+      logger.debug('[TwilioMedia] Following redirect', { url: redactUrl(cdnUrl) });
+
+      const response = await axios.get(cdnUrl, {
+        headers: { 'User-Agent': 'Nexus-Media-Processor/1.0' },
         responseType: 'arraybuffer',
         timeout: 30000
       });
       return Buffer.from(response.data);
     } catch (error) {
       const is404 = error.response?.status === 404;
+      const isDnsError = error.code === 'ENOTFOUND';
       const isLastAttempt = attempt === maxRetries;
 
-      if (is404 && !isLastAttempt) {
-        await new Promise(r => setTimeout(r, Math.pow(2, attempt - 1) * 1000));
+      if ((is404 || isDnsError) && !isLastAttempt) {
+        const delay = Math.pow(2, attempt - 1) * 1000;
+        logger.warn('[TwilioMedia] Download failed, retrying', { error: error.message, attempt, delay });
+        await new Promise(r => setTimeout(r, delay));
         continue;
       }
 
@@ -54,7 +87,7 @@ async function downloadMediaFromTwilio(mediaUrl, logger, maxRetries = 5) {
         return null;
       }
 
-      logger.error('[TwilioMedia] Download failed', { error: error.message, status: error.response?.status, attempt });
+      logger.error('[TwilioMedia] Download failed', { error: error.message, attempt });
       throw error;
     }
   }

package/lib/index.d.ts

@@ -335,4 +335,101 @@ declare module '@peopl-health/nexus' {
     getMessageValues: typeof getMessageValues;
     formatTimestamp: typeof formatTimestamp;
   };
+
+  // Queue Adapters
+  export interface QueueJobOptions {
+    priority?: number;
+    delay?: number;
+    attempts?: number;
+    backoff?: { type: 'fixed' | 'exponential'; delay: number };
+  }
+
+  export interface QueueJobStatus {
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'not_found';
+    result?: any;
+    error?: string;
+  }
+
+  export abstract class QueueAdapter {
+    constructor(config?: any);
+    abstract enqueue(jobType: string, payload: any, options?: QueueJobOptions): Promise<string>;
+    abstract process(jobType: string, handler: (payload: any) => Promise<any>): Promise<void>;
+    abstract getJobStatus(jobId: string): Promise<QueueJobStatus>;
+    abstract cancelJob(jobId: string): Promise<boolean>;
+    abstract waitForResult(jobId: string, timeout?: number): Promise<any>;
+    abstract shutdown(): Promise<void>;
+  }
+
+  export class LocalQueueAdapter extends QueueAdapter {
+    constructor(config?: any);
+    enqueue(jobType: string, payload: any, options?: QueueJobOptions): Promise<string>;
+    process(jobType: string, handler: (payload: any) => Promise<any>): Promise<void>;
+    getJobStatus(jobId: string): Promise<QueueJobStatus>;
+    cancelJob(jobId: string): Promise<boolean>;
+    waitForResult(jobId: string, timeout?: number): Promise<any>;
+    shutdown(): Promise<void>;
+  }
+
+  export interface RedisQueueConfig {
+    redis?: { host: string; port: number; password?: string };
+    defaultJobOptions?: QueueJobOptions;
+  }
+
+  export class RedisQueueAdapter extends QueueAdapter {
+    constructor(config?: RedisQueueConfig);
+    enqueue(jobType: string, payload: any, options?: QueueJobOptions): Promise<string>;
+    process(jobType: string, handler: (payload: any) => Promise<any>): Promise<void>;
+    getJobStatus(jobId: string): Promise<QueueJobStatus>;
+    cancelJob(jobId: string): Promise<boolean>;
+    waitForResult(jobId: string, timeout?: number): Promise<any>;
+    shutdown(): Promise<void>;
+  }
+
+  export function createQueueAdapter(type: 'local' | 'redis' | string, config?: any): QueueAdapter;
+  export function registerQueueAdapter(name: string, AdapterClass: typeof QueueAdapter): void;
+
+  // BatchingManager
+  export interface BatchingConfig {
+    enabled?: boolean;
+    abortOnNewMessage?: boolean;
+    immediateRestart?: boolean;
+    typingIndicator?: boolean;
+  }
+
+  export class BatchingManager {
+    constructor(options: {
+      provider?: MessageProvider;
+      config?: BatchingConfig;
+    });
+    setProvider(provider: MessageProvider): void;
+    isProcessing(chatId: string): boolean;
+    handleBatchedProcessing(
+      chatId: string,
+      processingFn: (runId: string) => Promise<any>,
+      sendResponseFn: (result: any) => Promise<void>
+    ): Promise<void>;
+  }
+
+  // AssistantProcessor
+  export interface AssistantProcessorConfig {
+    mode?: 'local' | 'queue';
+    queueAdapter?: QueueAdapter;
+    sendMessage?: (messageData: MessageData) => Promise<any>;
+    replyAssistant?: (code: string, body?: string, thread?: any, options?: any) => Promise<any>;
+  }
+
+  export interface ProcessInput {
+    code: string;
+    messageData: MessageData;
+    thread?: any;
+    runOptions?: Record<string, any>;
+  }
+
+  export class AssistantProcessor {
+    constructor(config: AssistantProcessorConfig);
+    setReplyAssistant(fn: AssistantProcessorConfig['replyAssistant']): void;
+    setSendMessage(fn: AssistantProcessorConfig['sendMessage']): void;
+    process(input: ProcessInput): Promise<{ output: string; tools_executed?: any[]; prompt?: string; response_id?: string } | null>;
+    sendResponse(code: string, result: any): Promise<string | null>;
+  }
 }

package/lib/index.js

@@ -2,6 +2,8 @@ const { NexusMessaging, setDefaultInstance } = require('./core/NexusMessaging');
 const { MongoStorage } = require('./storage/MongoStorage');
 const { createStorage } = require('./storage/registry');
 const { MessageParser } = require('./core/MessageParser');
+const { BatchingManager } = require('./core/BatchingManager');
+const { AssistantProcessor } = require('./core/AssistantProcessor');
 const { logger } = require('./utils/logger');
 const { createLLMProvider } = require('./providers/createLLMProvider');
 const { OpenAIAssistantsProvider } = require('./providers/OpenAIAssistantsProvider');
@@ -24,6 +26,8 @@ const {
 } = require('./services/preprocessingService');
 const { requestIdMiddleware, getRequestId } = require('./middleware/requestId');
 
+const { QueueAdapter, LocalQueueAdapter, RedisQueueAdapter, createQueueAdapter, registerQueueAdapter } = require('./queue');
+
 class Nexus {
   constructor(config = {}) {
     this.config = config;
@@ -221,6 +225,8 @@ module.exports = {
   BaileysProvider,
   MongoStorage,
   MessageParser,
+  BatchingManager,
+  AssistantProcessor,
   createLLMProvider,
   OpenAIAssistantsProvider,
   OpenAIResponsesProvider,
@@ -239,5 +245,11 @@ module.exports = {
   logger,
   setModelDatabases,
   setModelDatabase,
-  getModelDatabase
+  getModelDatabase,
+
+  QueueAdapter,
+  LocalQueueAdapter,
+  RedisQueueAdapter,
+  createQueueAdapter,
+  registerQueueAdapter
 };

package/lib/models/messageModel.js

@@ -101,13 +101,39 @@ messageSchema.pre('save', function (next) {
 
 const Message = mongoose.model('Message', messageSchema);
 
+const CLINICAL_CONTEXT_CACHE = new Map();
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes TTL
+const MAX_CACHE_SIZE = 1000;
+
 async function getClinicalContext(whatsappId) {
+  const now = Date.now();
+  const cached = CLINICAL_CONTEXT_CACHE.get(whatsappId);
+
+  if (cached && (now - cached.timestamp < CACHE_TTL)) {
+    logger.debug('[getClinicalContext] Returning cached clinical context', { whatsappId });
+    return cached.data;
+  }
+
   try {
     const records = await getRecordByFilter(Monitoreo_ID, 'estado_general', `{whatsapp_id}='${whatsappId}'`);
+    let clinicalContext = null;
+
     if (records && records.length > 0 && records[0]['clinical-context-json']) {
-      return JSON.parse(records[0]['clinical-context-json']);
+      clinicalContext = JSON.parse(records[0]['clinical-context-json']);
     }
-    return null;
+
+    // Cache the result (even if null)
+    if (CLINICAL_CONTEXT_CACHE.size >= MAX_CACHE_SIZE) {
+      const firstKey = CLINICAL_CONTEXT_CACHE.keys().next().value;
+      CLINICAL_CONTEXT_CACHE.delete(firstKey);
+    }
+
+    CLINICAL_CONTEXT_CACHE.set(whatsappId, {
+      data: clinicalContext,
+      timestamp: now
+    });
+
+    return clinicalContext;
   } catch (error) {
     logger.error('Error fetching clinical context from Airtable:', error);
     return null;
@@ -187,10 +213,15 @@ async function getContactDisplayName(contactNumber) {
   }
 }
 
+function _clearClinicalContextCache() {
+  CLINICAL_CONTEXT_CACHE.clear();
+}
+
 module.exports = {
   Message,
   insertMessage,
   getMessageValues,
   formatTimestamp,
-  getContactDisplayName
+  getContactDisplayName,
+  _clearClinicalContextCache
 };

package/lib/queue/LocalQueueAdapter.js

@@ -0,0 +1,104 @@
+const EventEmitter = require('events');
+const { QueueAdapter } = require('./QueueAdapter');
+
+class LocalQueueAdapter extends QueueAdapter {
+  constructor(config = {}) {
+    super(config);
+    this.jobs = new Map();
+    this.handlers = new Map();
+    this.events = new EventEmitter();
+    this.jobCounter = 0;
+  }
+
+  async enqueue(jobType, payload, options = {}) {
+    const jobId = `local_${++this.jobCounter}_${Date.now()}`;
+    const job = {
+      id: jobId,
+      type: jobType,
+      payload,
+      options,
+      status: 'pending',
+      result: null,
+      error: null,
+      createdAt: new Date(),
+      completedAt: null
+    };
+
+    this.jobs.set(jobId, job);
+
+    setImmediate(async () => {
+      const handler = this.handlers.get(jobType);
+      if (!handler) {
+        job.status = 'failed';
+        job.error = `No handler registered for job type: ${jobType}`;
+        this.events.emit(`job:${jobId}`, job);
+        return;
+      }
+
+      job.status = 'running';
+      try {
+        job.result = await handler(payload);
+        job.status = 'completed';
+        job.completedAt = new Date();
+      } catch (err) {
+        job.status = 'failed';
+        job.error = err.message;
+      }
+      this.events.emit(`job:${jobId}`, job);
+      this.jobs.delete(jobId);
+    });
+
+    return jobId;
+  }
+
+  async process(jobType, handler) {
+    this.handlers.set(jobType, handler);
+  }
+
+  async getJobStatus(jobId) {
+    const job = this.jobs.get(jobId);
+    if (!job) return { status: 'not_found' };
+    return { status: job.status, result: job.result, error: job.error };
+  }
+
+  async cancelJob(jobId) {
+    const job = this.jobs.get(jobId);
+    if (!job || job.status !== 'pending') return false;
+    job.status = 'cancelled';
+    this.events.emit(`job:${jobId}`, job);
+    this.jobs.delete(jobId);
+    return true;
+  }
+
+  async waitForResult(jobId, timeout = 60000) {
+    const job = this.jobs.get(jobId);
+    if (!job) throw new Error(`Job not found: ${jobId}`);
+
+    if (job.status === 'completed') return job.result;
+    if (job.status === 'failed') throw new Error(job.error);
+    if (job.status === 'cancelled') throw new Error('Job was cancelled');
+
+    return new Promise((resolve, reject) => {
+      const onComplete = (completedJob) => {
+        clearTimeout(timer);
+        if (completedJob.status === 'completed') resolve(completedJob.result);
+        else if (completedJob.status === 'failed') reject(new Error(completedJob.error));
+        else if (completedJob.status === 'cancelled') reject(new Error('Job was cancelled'));
+        else reject(new Error(`Unexpected job status: ${completedJob.status}`));
+      };
+      const timer = setTimeout(() => {
+        this.events.removeListener(`job:${jobId}`, onComplete);
+        reject(new Error(`Job timed out after ${timeout}ms`));
+      }, timeout);
+      this.events.once(`job:${jobId}`, onComplete);
+    });
+  }
+
+  async shutdown() {
+    this.jobs.clear();
+    this.handlers.clear();
+    this.events.removeAllListeners();
+  }
+}
+
+module.exports = { LocalQueueAdapter };

package/lib/queue/QueueAdapter.js

@@ -0,0 +1,34 @@
+class QueueAdapter {
+  constructor(config = {}) {
+    this.config = config;
+    if (this.constructor === QueueAdapter) {
+      throw new Error('QueueAdapter is abstract and cannot be instantiated directly');
+    }
+  }
+
+  async enqueue(jobType, payload, options = {}) {
+    throw new Error('enqueue() must be implemented by subclass');
+  }
+
+  async process(jobType, handler) {
+    throw new Error('process() must be implemented by subclass');
+  }
+
+  async getJobStatus(jobId) {
+    throw new Error('getJobStatus() must be implemented by subclass');
+  }
+
+  async cancelJob(jobId) {
+    throw new Error('cancelJob() must be implemented by subclass');
+  }
+
+  async waitForResult(jobId, timeout = 60000) {
+    throw new Error('waitForResult() must be implemented by subclass');
+  }
+
+  async shutdown() {
+    throw new Error('shutdown() must be implemented by subclass');
+  }
+}
+
+module.exports = { QueueAdapter };

package/lib/queue/RedisQueueAdapter.js

@@ -0,0 +1,114 @@
+const { logger } = require('../utils/logger');
+
+const { QueueAdapter } = require('../queue/QueueAdapter');
+
+class RedisQueueAdapter extends QueueAdapter {
+  constructor(config = {}) {
+    super(config);
+    this.queues = new Map();
+    this.Bull = null;
+    this.redisConfig = config.redis || { host: 'localhost', port: 6379 };
+    this.defaultJobOptions = config.defaultJobOptions || {
+      attempts: 3,
+      backoff: { type: 'exponential', delay: 1000 },
+      removeOnComplete: 100,
+      removeOnFail: 50
+    };
+  }
+
+  _loadBull() {
+    if (this.Bull) return this.Bull;
+    try {
+      this.Bull = require('bull');
+      return this.Bull;
+    } catch (err) {
+      throw new Error('bull package is required for RedisQueueAdapter. Install with: npm install bull ioredis');
+    }
+  }
+
+  _getQueue(jobType) {
+    if (this.queues.has(jobType)) return this.queues.get(jobType);
+
+    const Bull = this._loadBull();
+    const queue = new Bull(jobType, { redis: this.redisConfig });
+
+    queue.on('error', (err) => logger.error('[RedisQueueAdapter] Queue error', { jobType, error: err.message }));
+    queue.on('failed', (job, err) => logger.error('[RedisQueueAdapter] Job failed', { jobId: job.id, error: err.message }));
+
+    this.queues.set(jobType, queue);
+    return queue;
+  }
+
+  async enqueue(jobType, payload, options = {}) {
+    const queue = this._getQueue(jobType);
+    const jobOptions = { ...this.defaultJobOptions, ...options };
+    const job = await queue.add(payload, jobOptions);
+    logger.debug('[RedisQueueAdapter] Job enqueued', { jobType, jobId: job.id });
+    return String(job.id);
+  }
+
+  async process(jobType, handler) {
+    const queue = this._getQueue(jobType);
+    queue.process(async (job) => {
+      logger.debug('[RedisQueueAdapter] Processing job', { jobType, jobId: job.id });
+      return await handler(job.data);
+    });
+  }
+
+  _mapState(state) {
+    const map = { waiting: 'pending', delayed: 'pending', paused: 'pending', active: 'running', completed: 'completed', failed: 'failed' };
+    return map[state] || 'pending';
+  }
+
+  async getJobStatus(jobId) {
+    for (const queue of this.queues.values()) {
+      const job = await queue.getJob(jobId);
+      if (job) {
+        const state = await job.getState();
+        return { status: this._mapState(state), result: job.returnvalue, error: job.failedReason };
+      }
+    }
+    return { status: 'not_found' };
+  }
+
+  async cancelJob(jobId) {
+    for (const queue of this.queues.values()) {
+      const job = await queue.getJob(jobId);
+      if (job) {
+        const state = await job.getState();
+        if (state === 'waiting' || state === 'delayed') {
+          await job.remove();
+          return true;
+        }
+        return false;
+      }
+    }
+    return false;
+  }
+
+  async waitForResult(jobId, timeout = 60000) {
+    for (const queue of this.queues.values()) {
+      const job = await queue.getJob(jobId);
+      if (job) {
+        let timer;
+        return await Promise.race([
+          job.finished().finally(() => clearTimeout(timer)),
+          new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`Job timed out after ${timeout}ms`)), timeout); })
+        ]);
+      }
+    }
+    throw new Error(`Job not found: ${jobId}`);
+  }
+
+  async shutdown() {
+    const closePromises = [];
+    for (const queue of this.queues.values()) {
+      closePromises.push(queue.close());
+    }
+    await Promise.all(closePromises);
+    this.queues.clear();
+    logger.info('[RedisQueueAdapter] Shutdown complete');
+  }
+}
+
+module.exports = { RedisQueueAdapter };

package/lib/queue/index.js

@@ -0,0 +1,28 @@
+const { QueueAdapter } = require('./QueueAdapter');
+const { LocalQueueAdapter } = require('./LocalQueueAdapter');
+const { RedisQueueAdapter } = require('./RedisQueueAdapter');
+
+const adapters = {
+  local: LocalQueueAdapter,
+  redis: RedisQueueAdapter
+};
+
+function registerQueueAdapter(name, AdapterClass) {
+  adapters[name] = AdapterClass;
+}
+
+function createQueueAdapter(type = 'local', config = {}) {
+  const AdapterClass = adapters[type];
+  if (!AdapterClass) {
+    throw new Error(`Unknown queue adapter type: ${type}. Available: ${Object.keys(adapters).join(', ')}`);
+  }
+  return new AdapterClass(config);
+}
+
+module.exports = {
+  QueueAdapter,
+  LocalQueueAdapter,
+  RedisQueueAdapter,
+  registerQueueAdapter,
+  createQueueAdapter
+};

package/lib/utils/sanitizerUtils.js

@@ -52,11 +52,33 @@ function validateRequired(params, fields) {
   return missing.length ? missing : null;
 }
 
+function isAllowedUrl(url, allowedDomains) {
+  try {
+    const parsed = new URL(url);
+    return allowedDomains.some(domain => parsed.hostname === domain || parsed.hostname.endsWith(`.${domain}`));
+  } catch {
+    return false;
+  }
+}
+
+function redactUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const pathParts = parsed.pathname.split('/');
+    const id = pathParts.find(p => /^[A-Z]{2}[a-f0-9]{32}$/i.test(p)) || pathParts.pop();
+    return `${parsed.hostname}/.../${id}`;
+  } catch {
+    return '[invalid-url]';
+  }
+}
+
 module.exports = {
   sanitizeFilename,
   sanitizeMediaFilename,
   sanitizeLogMetadata,
   maskSensitiveValue,
   cleanObject,
-  validateRequired
+  validateRequired,
+  isAllowedUrl,
+  redactUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "3.3.10",
+  "version": "3.3.12",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",
@@ -90,10 +90,20 @@
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.32.0",
     "baileys": "^6.4.0",
+    "bull": "^4.12.0",
     "express": "^4.22.1",
+    "ioredis": "^5.3.0",
     "openai": "6.7.0",
     "twilio": "5.11.2"
   },
+  "peerDependenciesMeta": {
+    "bull": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=20.0.0"
   },