@peopl-health/nexus 1.5.4 → 1.5.6

package/lib/adapters/BaileysProvider.js

@@ -148,17 +148,36 @@ class BaileysProvider extends MessageProvider {
   }
 
   async sendScheduledMessage(scheduledMessage) {
-    const { sendTime, timeZone } = scheduledMessage;
+    const { sendTime, timeZone, __nexusSend } = scheduledMessage;
     const delay = this.calculateDelay(sendTime, timeZone);
-    
+
+    const sender = typeof __nexusSend === 'function'
+      ? __nexusSend
+      : async (payload) => await this.sendMessage(payload);
+
+    console.log('[BaileysProvider] Scheduled message created', {
+      to: scheduledMessage.to || scheduledMessage.code,
+      delay,
+      hasMedia: Boolean(scheduledMessage.fileUrl)
+    });
+
     setTimeout(async () => {
       try {
-        await this.sendMessage(scheduledMessage);
+        const payload = { ...scheduledMessage };
+        delete payload.__nexusSend;
+        console.log('[BaileysProvider] Timer fired', {
+          to: payload.to || payload.code,
+          hasMessage: Boolean(payload.message || payload.body),
+          hasMedia: Boolean(payload.fileUrl)
+        });
+        await sender(payload);
         console.log('Scheduled message sent successfully');
       } catch (error) {
         console.error(`Scheduled message failed: ${error.message}`);
       }
     }, delay);
+
+    return { scheduled: true, delay };
   }
 
   calculateDelay(sendTime) {

package/lib/adapters/TwilioProvider.js

@@ -1,5 +1,10 @@
 const { MessageProvider } = require('../core/MessageProvider');
 const axios = require('axios');
+const runtimeConfig = require('../config/runtimeConfig');
+const { uploadMediaToS3, sanitizeFileName, getFileExtension } = require('../helpers/mediaHelper');
+const { generatePresignedUrl } = require('../config/awsConfig');
+const { validateMedia, getMediaType } = require('../utils/mediaValidator');
+const { v4: uuidv4 } = require('uuid');
 
 /**
  * Twilio WhatsApp messaging provider
@@ -40,7 +45,7 @@ class TwilioProvider extends MessageProvider {
     }
 
     const { to, message, fileUrl, fileType, variables, contentSid } = messageData;
-    
+
     const formattedFrom = this.ensureWhatsAppFormat(this.whatsappNumber);
     const formattedTo = this.ensureWhatsAppFormat(to);
 
@@ -71,10 +76,19 @@ class TwilioProvider extends MessageProvider {
 
     // Handle media messages
     if (fileUrl && fileType !== 'text') {
-      messageParams.mediaUrl = [fileUrl];
+      const mediaPrep = await this.prepareOutboundMedia(messageData, formattedTo);
+      const outboundMediaUrl = mediaPrep.mediaUrl || fileUrl;
+      messageParams.mediaUrl = [outboundMediaUrl];
       if (!messageParams.body || messageParams.body.trim() === '') {
         delete messageParams.body;
       }
+      if (mediaPrep.uploaded) {
+        console.log('[TwilioProvider] Outbound media uploaded to S3', {
+          to: formattedTo,
+          bucket: mediaPrep.bucketName,
+          key: mediaPrep.key
+        });
+      }
     }
 
     // Validate message has content
@@ -84,6 +98,28 @@ class TwilioProvider extends MessageProvider {
 
     try {
       const result = await this.twilioClient.messages.create(messageParams);
+      if (this.messageStorage && typeof this.messageStorage.saveMessage === 'function') {
+        try {
+          console.log('[TwilioProvider] Persisting outbound message', {
+            to: formattedTo,
+            from: formattedFrom,
+            hasMedia: Boolean(messageParams.mediaUrl && messageParams.mediaUrl.length),
+            hasTemplate: Boolean(messageParams.contentSid)
+          });
+          await this.messageStorage.saveMessage({
+            ...messageData,
+            to: formattedTo,
+            from: formattedFrom,
+            messageId: result.sid,
+            provider: 'twilio',
+            timestamp: new Date(),
+            fromMe: true
+          });
+          console.log('[TwilioProvider] Message persisted successfully', { messageId: result.sid });
+        } catch (storageError) {
+          console.error('TwilioProvider storage failed:', storageError);
+        }
+      }
       return {
         success: true,
         messageId: result.sid,
@@ -96,17 +132,142 @@ class TwilioProvider extends MessageProvider {
   }
 
   async sendScheduledMessage(scheduledMessage) {
-    const { sendTime, timeZone } = scheduledMessage;
+    const { sendTime, timeZone, __nexusSend } = scheduledMessage;
     const delay = this.calculateDelay(sendTime, timeZone);
-    
+
+    const sender = typeof __nexusSend === 'function'
+      ? __nexusSend
+      : async (payload) => await this.sendMessage(payload);
+
+    console.log('[TwilioProvider] Scheduled message created', {
+      to: scheduledMessage.to || scheduledMessage.code,
+      delay,
+      hasContentSid: Boolean(scheduledMessage.contentSid)
+    });
+
     setTimeout(async () => {
       try {
-        await this.sendMessage(scheduledMessage);
+        const payload = { ...scheduledMessage };
+        delete payload.__nexusSend;
+        console.log('[TwilioProvider] Timer fired', {
+          to: payload.to || payload.code,
+          hasMessage: Boolean(payload.message || payload.body),
+          hasMedia: Boolean(payload.fileUrl)
+        });
+        await sender(payload);
         console.log('Scheduled message sent successfully');
       } catch (error) {
         console.error(`Scheduled message failed: ${error.message}`);
       }
     }, delay);
+
+    return { scheduled: true, delay };
+  }
+
+  supportsMessageStorage() {
+    return true;
+  }
+
+  async prepareOutboundMedia(messageData, formattedTo) {
+    const bucketName = runtimeConfig.get('AWS_S3_BUCKET_NAME') || process.env.AWS_S3_BUCKET_NAME;
+    const fileUrl = messageData.fileUrl;
+
+    if (!fileUrl) {
+      return { mediaUrl: null, uploaded: false };
+    }
+
+    if (!bucketName) {
+      console.warn('[TwilioProvider] AWS_S3_BUCKET_NAME not configured. Skipping media upload for outbound message.');
+      return { mediaUrl: fileUrl, uploaded: false };
+    }
+
+    // Reuse existing uploaded media if present
+    if (messageData.media?.bucketName && messageData.media?.key) {
+      const presigned = await generatePresignedUrl(messageData.media.bucketName, messageData.media.key, 3600);
+      return {
+        mediaUrl: presigned,
+        uploaded: false,
+        bucketName: messageData.media.bucketName,
+        key: messageData.media.key
+      };
+    }
+
+    try {
+      const response = await axios.get(fileUrl, { responseType: 'arraybuffer' });
+      const buffer = Buffer.from(response.data);
+      let contentType = messageData.contentType || response.headers['content-type'];
+      const declaredType = typeof messageData.fileType === 'string' ? messageData.fileType : null;
+
+      if (!contentType) {
+        const fallbackType = declaredType ? {
+          image: 'image/jpeg',
+          video: 'video/mp4',
+          audio: 'audio/mpeg',
+          document: 'application/pdf'
+        }[declaredType] : null;
+        contentType = fallbackType || 'application/octet-stream';
+      }
+
+      const validation = validateMedia(buffer, contentType);
+      const mediaType = validation.valid ? validation.mediaType : (declaredType || getMediaType(contentType));
+
+      if (!validation.valid) {
+        console.warn('[TwilioProvider] Outbound media validation warning', {
+          to: formattedTo,
+          message: validation.message
+        });
+      }
+
+      const existingFileName = messageData.fileName || (() => {
+        try {
+          const parsed = new URL(fileUrl);
+          const segments = parsed.pathname.split('/').filter(Boolean);
+          return segments.length ? segments[segments.length - 1] : null;
+        } catch (err) {
+          return null;
+        }
+      })();
+
+      const baseName = existingFileName ? existingFileName.split('.').slice(0, -1).join('.') : `${mediaType}_${Date.now()}`;
+      const sanitizedBase = sanitizeFileName(baseName) || `${mediaType}_${Date.now()}`;
+      const extension = getFileExtension(contentType) || 'bin';
+      const uploadId = uuidv4();
+      const key = await uploadMediaToS3(buffer, uploadId, sanitizedBase, bucketName, contentType, mediaType);
+      const presignedUrl = await generatePresignedUrl(bucketName, key, 3600);
+      const s3Url = `https://${bucketName}.s3.amazonaws.com/${key}`;
+
+      messageData.media = {
+        contentType,
+        bucketName,
+        key,
+        mediaType,
+        fileName: existingFileName || `${sanitizedBase}.${extension}`,
+        fileSize: buffer.length,
+        caption: messageData.message || '',
+        metadata: {
+          originalUrl: fileUrl,
+          uploadedAt: new Date().toISOString()
+        }
+      };
+
+      messageData.fileUrl = s3Url;
+      messageData.fileType = mediaType;
+      messageData.contentType = contentType;
+
+      return {
+        mediaUrl: presignedUrl,
+        uploaded: true,
+        bucketName,
+        key
+      };
+    } catch (error) {
+      console.error('[TwilioProvider] Failed to upload outbound media to S3. Using original URL.', {
+        to: formattedTo,
+        error: error?.message || error
+      });
+
+      return { mediaUrl: fileUrl, uploaded: false };
+    }
   }
 
   calculateDelay(sendTime) {

package/lib/core/MessageProvider.js

@@ -5,6 +5,7 @@ class MessageProvider {
   constructor(config = {}) {
     this.config = config;
     this.isConnected = false;
+    this.messageStorage = null;
   }
 
   /**
@@ -66,6 +67,22 @@ class MessageProvider {
   async disconnect() {
     throw new Error('disconnect() must be implemented by provider');
   }
+
+  /**
+   * Inject message storage so providers can persist messages themselves
+   * @param {Object|null} storage
+   */
+  setMessageStorage(storage) {
+    this.messageStorage = storage;
+  }
+
+  /**
+   * Whether the provider performs its own message storage
+   * @returns {boolean}
+   */
+  supportsMessageStorage() {
+    return false;
+  }
 }
 
 module.exports = { MessageProvider };

package/lib/core/NexusMessaging.js

@@ -1,6 +1,7 @@
 const { airtable, getBase } = require('../config/airtableConfig');
 const { replyAssistant } = require('../services/assistantService');
 const { createProvider } = require('../adapters/registry');
+const runtimeConfig = require('../config/runtimeConfig');
 
 const mongoose = require('mongoose');
 const OpenAI = require('openai');
@@ -187,6 +188,9 @@ class NexusMessaging {
    */
   async initializeProvider(providerType, providerConfig) {
     this.provider = createProvider(providerType, providerConfig);
+    if (this.messageStorage && typeof this.provider?.setMessageStorage === 'function') {
+      this.provider.setMessageStorage(this.messageStorage);
+    }
     await this.provider.initialize();
   }
 
@@ -196,6 +200,9 @@ class NexusMessaging {
    */
   setMessageStorage(storage) {
     this.messageStorage = storage;
+    if (this.provider && typeof this.provider.setMessageStorage === 'function') {
+      this.provider.setMessageStorage(storage);
+    }
   }
 
   /**
@@ -270,9 +277,13 @@ class NexusMessaging {
     }
 
     const result = await this.provider.sendMessage(normalized);
-    
-    // Store message if storage is configured
-    if (this.messageStorage) {
+
+    // Store message only if provider does not handle persistence itself
+    const providerStoresMessage = typeof this.provider.supportsMessageStorage === 'function'
+      ? this.provider.supportsMessageStorage()
+      : false;
+
+    if (this.messageStorage && !providerStoresMessage) {
       await this.messageStorage.saveMessage({
         ...normalized,
         messageId: result.messageId,
@@ -364,7 +375,12 @@ class NexusMessaging {
       typeof messageData.message?.conversation === 'string' ? messageData.message.conversation : null,
       typeof messageData.Body === 'string' ? messageData.Body : null,
       typeof messageData.raw?.message?.conversation === 'string' ? messageData.raw.message.conversation : null,
-      typeof messageData.raw?.Body === 'string' ? messageData.raw.Body : null
+      typeof messageData.raw?.Body === 'string' ? messageData.raw.Body : null,
+      typeof messageData.caption === 'string' ? messageData.caption : null,
+      typeof messageData.media?.caption === 'string' ? messageData.media.caption : null,
+      Array.isArray(messageData.media) && typeof messageData.media[0]?.caption === 'string'
+        ? messageData.media[0].caption
+        : null
     ].find((value) => typeof value === 'string' && value.trim().length > 0) || null;
 
     return { from, message };
@@ -406,7 +422,109 @@ class NexusMessaging {
   }
 
   async handleMedia(messageData) {
-    return await this._handleWithPipeline('media', 'onMedia', messageData);
+    await this._ensureMediaPersistence(messageData);
+
+    return await this._handleWithPipeline('media', 'onMedia', messageData, async (ctx) => {
+      return await this.handleMediaWithAssistant(ctx);
+    });
+  }
+
+  async handleMediaWithAssistant(messageData) {
+    try {
+      const { from, message } = this._extractAssistantInputs(messageData);
+
+      if (!from) {
+        console.warn('Unable to resolve sender for media message, skipping automatic reply.');
+        return;
+      }
+
+      const mediaDescriptor = (() => {
+        const media = Array.isArray(messageData.media) ? messageData.media[0] : messageData.media;
+        if (!media) return null;
+        if (typeof media.mediaType === 'string') return media.mediaType;
+        if (typeof media.type === 'string') return media.type;
+        if (typeof media.contentType === 'string') return media.contentType;
+        return null;
+      })();
+
+      const fallbackMessage = message && message.trim().length > 0
+        ? message
+        : `Media received (${mediaDescriptor || 'attachment'})`;
+
+      const response = await replyAssistant(from, fallbackMessage);
+
+      if (response) {
+        await this.sendMessage({
+          to: from,
+          message: response
+        });
+      }
+    } catch (error) {
+      console.error('Error in handleMediaWithAssistant:', error);
+    }
+  }
+
+  async _ensureMediaPersistence(messageData) {
+    try {
+      const raw = messageData?.raw;
+      if (!raw || raw.__nexusMediaProcessed) return;
+
+      const numMedia = parseInt(raw.NumMedia || '0', 10);
+      if (!numMedia || numMedia <= 0 || !raw.MediaUrl0) return;
+
+      const bucketName = runtimeConfig.get('AWS_S3_BUCKET_NAME') || process.env.AWS_S3_BUCKET_NAME;
+      if (!bucketName) {
+        console.warn('[NexusMessaging] AWS_S3_BUCKET_NAME not configured. Skipping media persistence.');
+        return;
+      }
+
+      const { processTwilioMediaMessage } = require('../helpers/twilioMediaProcessor');
+      const { logger } = require('../utils/logger');
+      const mediaItems = await processTwilioMediaMessage(raw, logger, bucketName);
+
+      if (!mediaItems || mediaItems.length === 0) {
+        console.warn('[NexusMessaging] Media processing returned no items for incoming message.');
+        return;
+      }
+
+      raw.__nexusMediaProcessed = true;
+
+      const [primary, ...rest] = mediaItems;
+      const mediaPayload = rest.length > 0
+        ? { ...primary, metadata: { ...(primary.metadata || {}), attachments: rest } }
+        : primary;
+
+      messageData.media = messageData.media || mediaPayload;
+      messageData.fileUrl = messageData.fileUrl || mediaPayload.metadata?.presignedUrl || null;
+      messageData.fileType = messageData.fileType || mediaPayload.mediaType;
+      messageData.caption = messageData.caption || primary.caption;
+      if (!messageData.message && messageData.caption) {
+        messageData.message = messageData.caption;
+      }
+      messageData.isMedia = true;
+
+      if (!this.messageStorage) {
+        const { convertTwilioToInternalFormat } = require('../helpers/twilioHelper');
+        const { getMessageValues, insertMessage } = require('../models/messageModel');
+
+        const messageObj = convertTwilioToInternalFormat(raw);
+        const values = getMessageValues(
+          messageObj,
+          messageData.message || messageData.caption || '',
+          null,
+          true
+        );
+        values.media = mediaPayload;
+
+        await insertMessage(values);
+        console.log('[NexusMessaging] Media message stored via legacy inserter', {
+          messageId: values.message_id,
+          numero: values.numero
+        });
+      }
+    } catch (error) {
+      console.error('[NexusMessaging] Failed to ensure media persistence:', error);
+    }
   }
 
   async handleCommand(messageData) {

package/lib/helpers/twilioMediaProcessor.js

@@ -0,0 +1,149 @@
+const { uploadMediaToS3 } = require('./mediaHelper');
+const {
+  convertTwilioToInternalFormat,
+  downloadMediaFromTwilio,
+  getMediaTypeFromContentType,
+  extractTitle
+} = require('./twilioHelper');
+const { validateMedia } = require('../utils/mediaValidator');
+const { generatePresignedUrl } = require('../config/awsConfig');
+const { addRecord, getRecordByFilter } = require('../services/airtableService');
+const { Monitoreo_ID } = require('../config/airtableConfig');
+
+const ensureLogger = (logger) => {
+  if (!logger) return console;
+  const fallback = {};
+  for (const level of ['info', 'warn', 'error', 'debug']) {
+    fallback[level] = typeof logger[level] === 'function' ? logger[level].bind(logger) : console[level].bind(console);
+  }
+  return fallback;
+};
+
+const normalizeMediaType = (type) => {
+  if (!type || typeof type !== 'string') return 'document';
+  return type.replace(/Message$/i, '').replace(/WithCaption$/i, '').toLowerCase();
+};
+
+async function processTwilioMediaMessage(twilioMessage, logger, bucketName) {
+  if (!twilioMessage) return [];
+
+  const log = ensureLogger(logger);
+  const numMedia = parseInt(twilioMessage.NumMedia || '0', 10);
+  if (!numMedia || numMedia <= 0) {
+    log.debug && log.debug('[TwilioMedia] No media detected in message');
+    return [];
+  }
+
+  if (!bucketName) {
+    log.warn && log.warn('[TwilioMedia] AWS bucket not configured; skipping media processing');
+    return [];
+  }
+
+  const mediaItems = [];
+  const code = twilioMessage.From;
+  const caption = twilioMessage.Body || '';
+  const messageObj = convertTwilioToInternalFormat(twilioMessage);
+  const messageId = messageObj?.key?.id || twilioMessage.MessageSid;
+
+  for (let i = 0; i < numMedia; i++) {
+    const mediaUrl = twilioMessage[`MediaUrl${i}`];
+    const contentType = twilioMessage[`MediaContentType${i}`];
+
+    if (!mediaUrl || !contentType) {
+      log.warn && log.warn('[TwilioMedia] Missing media URL or content type', { index: i });
+      continue;
+    }
+
+    log.info && log.info('[TwilioMedia] Processing media item', { index: i, contentType, mediaUrl });
+
+    let mediaBuffer;
+    try {
+      mediaBuffer = await downloadMediaFromTwilio(mediaUrl, log);
+    } catch (error) {
+      log.error && log.error('[TwilioMedia] Failed to download media', { index: i, error: error?.message || error });
+      continue;
+    }
+
+    const validationResult = validateMedia(mediaBuffer, contentType);
+    if (!validationResult.valid) {
+      log.warn && log.warn('[TwilioMedia] Media validation warning', { index: i, message: validationResult.message });
+    } else {
+      log.debug && log.debug('[TwilioMedia] Media validation passed', { index: i, message: validationResult.message });
+    }
+
+    const helperMediaType = getMediaTypeFromContentType(contentType);
+    const derivedMediaType = validationResult.valid
+      ? validationResult.mediaType
+      : normalizeMediaType(helperMediaType);
+    const titleFile = (extractTitle(twilioMessage, helperMediaType) || '').trim();
+    const sanitizedTitle = titleFile.replace(/\s+/g, '');
+    const fallbackName = `${derivedMediaType}_${Date.now()}`;
+    const fileName = sanitizedTitle || fallbackName;
+
+    let key;
+    try {
+      key = await uploadMediaToS3(
+        mediaBuffer,
+        messageId,
+        fileName,
+        bucketName,
+        contentType,
+        derivedMediaType
+      );
+    } catch (error) {
+      log.error && log.error('[TwilioMedia] Failed to upload media to S3', { index: i, error: error?.message || error });
+      continue;
+    }
+
+    const baseMetadata = {
+      originalUrl: mediaUrl,
+      receivedAt: new Date().toISOString(),
+      validation: validationResult.message
+    };
+
+    const item = {
+      contentType,
+      bucketName,
+      key,
+      mediaType: derivedMediaType,
+      fileName: titleFile || fallbackName,
+      fileSize: mediaBuffer.length,
+      caption,
+      thumbnail: null,
+      metadata: baseMetadata
+    };
+
+    try {
+      const url = await generatePresignedUrl(bucketName, key);
+      item.metadata.presignedUrl = url;
+
+      if (Monitoreo_ID) {
+        const patient = await getRecordByFilter(Monitoreo_ID, 'estado_general', `whatsapp_id = "${code}"`);
+        const patientId = Array.isArray(patient) && patient.length > 0 ? [patient[0].recordID || patient[0].recordId || patient[0].record_id] : [];
+        await addRecord(Monitoreo_ID, 'estudios', [{
+          fields: {
+            estudios: [{ url }],
+            combined_estudios: [{ url }],
+            patient_id: patientId
+          }
+        }]);
+      }
+    } catch (error) {
+      log.warn && log.warn('[TwilioMedia] Failed to update Airtable with media reference', { index: i, error: error?.message || error });
+    }
+
+    mediaItems.push(item);
+  }
+
+  console.log('[TwilioMedia] Completed processing', {
+    from: code,
+    itemsStored: mediaItems.length,
+    bucket: bucketName
+  });
+
+  return mediaItems;
+}
+
+module.exports = {
+  processTwilioMediaMessage
+};

package/lib/storage/MongoStorage.js

@@ -61,9 +61,23 @@ class MongoStorage {
 
   async saveMessage(messageData) {
     try {
-      const values = this.buildLegacyMessageValues(messageData);
+      console.log('[MongoStorage] saveMessage called', {
+        to: messageData?.to || messageData?.code || messageData?.numero,
+        from: messageData?.from,
+        provider: messageData?.provider || 'unknown',
+        hasRaw: Boolean(messageData?.raw),
+        hasMedia: Boolean(messageData?.media || messageData?.fileUrl)
+      });
+      const enrichedMessage = await this._enrichTwilioMedia(messageData);
+      const values = this.buildLegacyMessageValues(enrichedMessage);
       const { insertMessage } = require('../models/messageModel');
       await insertMessage(values);
+      console.log('[MongoStorage] Message stored', {
+        messageId: values.message_id,
+        numero: values.numero,
+        isMedia: values.is_media,
+        hasMediaPayload: Boolean(values.media)
+      });
       return values;
     } catch (error) {
       console.error('Error saving message:', error);
@@ -71,6 +85,64 @@ class MongoStorage {
     }
   }
 
+  async _enrichTwilioMedia(messageData = {}) {
+    try {
+      const rawMessage = messageData?.raw;
+      if (!rawMessage || !rawMessage.From) return messageData;
+
+      const numMedia = parseInt(rawMessage.NumMedia || '0', 10);
+      if (!numMedia || numMedia <= 0 || !rawMessage.MediaUrl0) {
+        return messageData;
+      }
+
+      console.log('[MongoStorage] Detected Twilio media message', {
+        from: rawMessage.From,
+        numMedia
+      });
+
+      const bucketName = runtimeConfig.get('AWS_S3_BUCKET_NAME') || process.env.AWS_S3_BUCKET_NAME;
+      if (!bucketName) {
+        console.warn('[MongoStorage] AWS_S3_BUCKET_NAME not configured. Skipping media upload.');
+        return messageData;
+      }
+
+      const { processTwilioMediaMessage } = require('../helpers/twilioMediaProcessor');
+      const { logger } = require('../utils/logger');
+
+      const mediaItems = await processTwilioMediaMessage(rawMessage, logger, bucketName);
+      if (!mediaItems || mediaItems.length === 0) {
+        console.warn('[MongoStorage] Media processing returned no items');
+        return messageData;
+      }
+
+      const [primary, ...rest] = mediaItems;
+      const mediaPayload = rest.length > 0
+        ? { ...primary, metadata: { ...(primary.metadata || {}), attachments: rest } }
+        : primary;
+
+      rawMessage.__nexusMediaProcessed = true;
+
+      console.log('[MongoStorage] Media processed successfully', {
+        primaryType: mediaPayload.mediaType,
+        mediaCount: mediaItems.length,
+        s3Key: mediaPayload.key
+      });
+
+      return {
+        ...messageData,
+        media: mediaPayload,
+        fileUrl: undefined,
+        fileType: mediaPayload.mediaType || messageData.fileType,
+        isMedia: true,
+        message: messageData.message || rawMessage.Body || primary.caption || '',
+        caption: primary.caption || messageData.caption
+      };
+    } catch (error) {
+      console.error('[MongoStorage] Failed to enrich Twilio media message:', error);
+      return messageData;
+    }
+  }
+
   normalizeNumero(numero) {
     if (!numero || typeof numero !== 'string') return numero;
 

package/lib/utils/mediaValidator.js

@@ -0,0 +1,94 @@
+const MEDIA_LIMITS = {
+  image: 5 * 1024 * 1024, // 5MB
+  video: 16 * 1024 * 1024, // 16MB
+  audio: 16 * 1024 * 1024, // 16MB
+  document: 100 * 1024 * 1024, // 100MB (PDFs, etc.)
+  sticker: 500 * 1024 // 500KB
+};
+
+const ALLOWED_FORMATS = {
+  image: ['image/jpeg', 'image/png', 'image/webp'],
+  video: ['video/mp4', 'video/3gpp'],
+  audio: ['audio/mp4', 'audio/mpeg', 'audio/ogg', 'audio/amr'],
+  document: [
+    'application/pdf',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    'text/plain',
+    'application/zip'
+  ],
+  sticker: ['image/webp']
+};
+
+function validateMediaSize(media, mediaType) {
+  const fileSize = Buffer.isBuffer(media) ? media.length : media;
+  const maxSize = MEDIA_LIMITS[mediaType] || MEDIA_LIMITS.document;
+
+  if (fileSize > maxSize) {
+    const maxSizeMB = maxSize / (1024 * 1024);
+    return {
+      valid: false,
+      message: `${mediaType} exceeds WhatsApp limit of ${maxSizeMB}MB`
+    };
+  }
+
+  return {
+    valid: true,
+    message: `${mediaType} size is valid (${(fileSize / (1024 * 1024)).toFixed(2)}MB)`
+  };
+}
+
+function validateMediaFormat(contentType, mediaType) {
+  const allowedTypes = ALLOWED_FORMATS[mediaType] || [];
+
+  if (allowedTypes.length === 0 || !allowedTypes.includes(contentType)) {
+    return {
+      valid: false,
+      message: `Content type ${contentType} is not supported for ${mediaType}`
+    };
+  }
+
+  return {
+    valid: true,
+    message: `${contentType} is a valid format for ${mediaType}`
+  };
+}
+
+function getMediaType(contentType) {
+  for (const [type, formats] of Object.entries(ALLOWED_FORMATS)) {
+    if (formats.includes(contentType)) {
+      return type;
+    }
+  }
+  return 'document';
+}
+
+function validateMedia(media, contentType) {
+  const mediaType = getMediaType(contentType);
+  const formatValidation = validateMediaFormat(contentType, mediaType);
+
+  if (!formatValidation.valid) {
+    return formatValidation;
+  }
+
+  const sizeValidation = validateMediaSize(media, mediaType);
+  if (!sizeValidation.valid) {
+    return sizeValidation;
+  }
+
+  return {
+    valid: true,
+    mediaType,
+    message: `Media validated successfully as ${mediaType}`
+  };
+}
+
+module.exports = {
+  validateMedia,
+  validateMediaSize,
+  validateMediaFormat,
+  getMediaType,
+  MEDIA_LIMITS,
+  ALLOWED_FORMATS
+};

package/package.json

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