@peopl-health/nexus 1.2.0 → 1.3.1

package/lib/core/NexusMessaging.js

@@ -1,8 +1,11 @@
-const { TwilioProvider } = require('../adapters/TwilioProvider');
-const { BaileysProvider } = require('../adapters/BaileysProvider');
-const mongoose = require('mongoose');
 const { airtable, getBase } = require('../config/airtableConfig');
+const { convertTwilioToInternalFormat } = require('../helpers/twilioHelper');
+const { replyAssistant } = require('../services/assistantService');
+const { createProvider } = require('../adapters/registry');
+
+const mongoose = require('mongoose');
 const OpenAI = require('openai');
+const EventEmitter = require('events');
 
 /**
  * Core messaging class that manages providers and message handling
@@ -23,6 +26,8 @@ class NexusMessaging {
       onKeyword: null,
       onFlow: null
     };
+    this.events = new EventEmitter();
+    this.middleware = { any: [], message: [], interactive: [], media: [], command: [], keyword: [], flow: [] };
   }
 
   /**
@@ -79,6 +84,54 @@ class NexusMessaging {
     return this.llmProvider;
   }
 
+  /**
+   * Get the underlying messaging provider instance
+   */
+  getProvider() {
+    return this.provider;
+  }
+
+  /**
+   * Access the internal event bus (EventEmitter)
+   */
+  getEventBus() {
+    return this.events;
+  }
+
+  /**
+   * Register middleware. Usage: use(type, fn) or use(fn) for global.
+   * Middleware signature: async (messageData, nexus, next) => {}
+   */
+  use(typeOrFn, maybeFn) {
+    if (typeof typeOrFn === 'function') {
+      this.middleware.any.push(typeOrFn);
+      return this;
+    }
+    const type = String(typeOrFn || '').toLowerCase();
+    const fn = maybeFn;
+    if (!this.middleware[type]) this.middleware[type] = [];
+    this.middleware[type].push(fn);
+    return this;
+  }
+
+  /**
+   * Internal helper to run middleware pipeline and the final handler
+   */
+  async _runPipeline(type, messageData, finalHandler) {
+    const chain = [...(this.middleware.any || []), ...(this.middleware[type] || []), async (ctx) => { return finalHandler(ctx); }];
+    let idx = -1;
+    const runner = async (i) => {
+      if (i <= idx) throw new Error('next() called multiple times');
+      idx = i;
+      const fn = chain[i];
+      if (!fn) return;
+      return await fn(messageData, this, () => runner(i+1));
+    };
+    return await runner(0);
+  }
+
+
+
   /**
    * Initialize Nexus with all services
    * @param {Object} options - Configuration options
@@ -122,17 +175,7 @@ class NexusMessaging {
    * @param {Object} providerConfig - Provider-specific configuration
    */
   async initializeProvider(providerType, providerConfig) {
-    switch (providerType.toLowerCase()) {
-    case 'twilio':
-      this.provider = new TwilioProvider(providerConfig);
-      break;
-    case 'baileys':
-      this.provider = new BaileysProvider(providerConfig);
-      break;
-    default:
-      throw new Error(`Unsupported provider: ${providerType}`);
-    }
-
+    this.provider = createProvider(providerType, providerConfig);
     await this.provider.initialize();
   }
 
@@ -209,12 +252,18 @@ class NexusMessaging {
       throw new Error('No provider initialized');
     }
 
-    const result = await this.provider.sendMessage(messageData);
+    // Backward compatibility: accept `code` as destination
+    const normalized = { ...messageData };
+    if (!normalized.to && normalized.code) {
+      normalized.to = normalized.code;
+    }
+
+    const result = await this.provider.sendMessage(normalized);
     
     // Store message if storage is configured
     if (this.messageStorage) {
       await this.messageStorage.saveMessage({
-        ...messageData,
+        ...normalized,
         messageId: result.messageId,
         provider: result.provider,
         timestamp: new Date(),
@@ -268,44 +317,111 @@ class NexusMessaging {
   }
 
   async handleMessage(messageData) {
-    if (this.handlers.onMessage) {
-      return await this.handlers.onMessage(messageData, this);
+    this.events.emit && this.events.emit('message:received', messageData);
+    const final = async (ctx) => {
+      if (this.handlers.onMessage) {
+        return await this.handlers.onMessage(ctx, this);
+      } else {
+        return await this.handleMessageWithAssistant(ctx);
+      }
+    };
+    const result = await this._runPipeline('message', messageData, final);
+    this.events.emit && this.events.emit('message:handled', messageData);
+    return result;
+  }
+
+  async handleMessageWithAssistant(messageData) {
+    try {
+      // Convert Twilio format to internal format if needed
+      const internalMessage = this.provider.constructor.name === 'TwilioProvider' 
+        ? convertTwilioToInternalFormat(messageData)
+        : messageData;
+
+      // Extract standardized data
+      const extractedData = {
+        from: internalMessage.key?.remoteJid || '',
+        message: internalMessage.message?.conversation || '',
+        messageId: internalMessage.key?.id || '',
+        fromMe: internalMessage.key?.fromMe || false
+      };
+
+      const response = await replyAssistant(
+        extractedData.from, 
+        extractedData.message
+      );
+
+      if (response) {
+        await this.sendMessage({
+          to: extractedData.from,
+          message: response
+        });
+      }
+    } catch (error) {
+      console.error('Error in handleMessageWithAssistant:', error);
     }
   }
 
   async handleInteractive(messageData) {
-    // Store interactive message
     if (this.messageStorage) {
       await this.messageStorage.saveInteractive(messageData);
     }
-
-    if (this.handlers.onInteractive) {
-      return await this.handlers.onInteractive(messageData, this);
-    }
+    this.events.emit && this.events.emit('interactive:received', messageData);
+    const final = async (ctx) => {
+      if (this.handlers.onInteractive) {
+        return await this.handlers.onInteractive(ctx, this);
+      }
+    };
+    const result = await this._runPipeline('interactive', messageData, final);
+    this.events.emit && this.events.emit('interactive:handled', messageData);
+    return result;
   }
 
   async handleMedia(messageData) {
-    if (this.handlers.onMedia) {
-      return await this.handlers.onMedia(messageData, this);
-    }
+    this.events.emit && this.events.emit('media:received', messageData);
+    const final = async (ctx) => {
+      if (this.handlers.onMedia) {
+        return await this.handlers.onMedia(ctx, this);
+      }
+    };
+    const result = await this._runPipeline('media', messageData, final);
+    this.events.emit && this.events.emit('media:handled', messageData);
+    return result;
   }
 
   async handleCommand(messageData) {
-    if (this.handlers.onCommand) {
-      return await this.handlers.onCommand(messageData, this);
-    }
+    this.events.emit && this.events.emit('command:received', messageData);
+    const final = async (ctx) => {
+      if (this.handlers.onCommand) {
+        return await this.handlers.onCommand(ctx, this);
+      }
+    };
+    const result = await this._runPipeline('command', messageData, final);
+    this.events.emit && this.events.emit('command:handled', messageData);
+    return result;
   }
 
   async handleKeyword(messageData) {
-    if (this.handlers.onKeyword) {
-      return await this.handlers.onKeyword(messageData, this);
-    }
+    this.events.emit && this.events.emit('keyword:received', messageData);
+    const final = async (ctx) => {
+      if (this.handlers.onKeyword) {
+        return await this.handlers.onKeyword(ctx, this);
+      }
+    };
+    const result = await this._runPipeline('keyword', messageData, final);
+    this.events.emit && this.events.emit('keyword:handled', messageData);
+    return result;
   }
 
   async handleFlow(messageData) {
-    if (this.handlers.onFlow) {
-      return await this.handlers.onFlow(messageData, this);
-    }
+    this.events.emit && this.events.emit('flow:received', messageData);
+    const final = async (ctx) => {
+      if (this.handlers.onFlow) {
+        return await this.handlers.onFlow(ctx, this);
+      }
+    };
+    const result = await this._runPipeline('flow', messageData, final);
+    this.events.emit && this.events.emit('flow:handled', messageData);
+    return result;
   }
 
   /**

package/lib/helpers/assistantHelper.js

@@ -1,7 +1,7 @@
 const { downloadFileFromS3, generatePresignedUrl } = require('../config/awsConfig.js');
 const { openaiClient } = require('../config/llmConfig.js');
 
-const { LegacyMessage } = require('../models/messageModel.js');
+const { Message } = require('../models/messageModel.js');
 
 const { convertPdfToImages } = require('./filesHelper.js');
 const { analyzeImage } = require('../helpers/llmsHelper.js');
@@ -78,7 +78,7 @@ async function getLastMessages(code) {
       query.is_group = false;
     }
 
-    const lastMessages = await LegacyMessage.find(query).sort({ timestamp: -1 });
+    const lastMessages = await Message.find(query).sort({ timestamp: -1 });
     console.log('[getLastMessages] lastMessages', lastMessages.map(msg => msg.body).join('\n\n'));
 
     if (lastMessages.length === 0) return [];
@@ -86,7 +86,7 @@ async function getLastMessages(code) {
     let patientReply = [];
     for (const message of lastMessages) {
       patientReply.push(message);
-      await LegacyMessage.updateOne(
+      await Message.updateOne(
         { message_id: message.message_id, timestamp: message.timestamp },
         { $set: { processed: true } }
       );
@@ -101,7 +101,7 @@ async function getLastMessages(code) {
 
 async function getLastNMessages(code, n) {
   try {
-    const lastMessages = await LegacyMessage.find({ numero: code })
+    const lastMessages = await Message.find({ numero: code })
       .sort({ timestamp: -1 })
       .limit(n);
 
@@ -149,7 +149,7 @@ function formatMessage(reply) {
 }
 
 async function downloadMediaAndCreateFile(code, reply) {
-  const resultMedia = await LegacyMessage.findOne({
+  const resultMedia = await Message.findOne({
     message_id: reply.message_id,
     timestamp: reply.timestamp,
     media: { $ne: null }
@@ -259,7 +259,7 @@ async function processMessage(code, reply, thread) {
 
     console.log('Formatted message:', formattedMessage);
 
-    await LegacyMessage.updateOne(
+    await Message.updateOne(
       { message_id: reply.message_id, timestamp: reply.timestamp },
       { $set: { assistant_id: thread.assistant_id, thread_id: thread.thread_id } }
     );

package/lib/helpers/baileysHelper.js

@@ -1,4 +1,4 @@
-const { LegacyMessage, insertMessage, getMessageValues } = require('../models/messageModel.js');
+const { Message, insertMessage, getMessageValues } = require('../models/messageModel.js');
 const { uploadMediaToS3 } = require('./mediaHelper.js');
 const { downloadMediaMessage } = require('baileys');
 
@@ -103,7 +103,7 @@ function extractContentTypeAndReply(message, messageType) {
 async function isRecentMessage(chatId) {
   const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000);
 
-  const recentMessage = await LegacyMessage.find({
+  const recentMessage = await Message.find({
     $or: [{ group_id: chatId }, { numero: chatId }],
     timestamp: { $gte: fiveMinutesAgo.toISOString() }
   }).sort({ timestamp: -1 }).limit(1);
@@ -112,7 +112,7 @@ async function isRecentMessage(chatId) {
 }
 
 async function getLastMessages(chatId, n) {
-  const messages = await LegacyMessage.find({ group_id: chatId })
+  const messages = await Message.find({ group_id: chatId })
     .sort({ timestamp: -1 })
     .limit(n)
     .select('timestamp numero nombre_whatsapp body');

package/lib/helpers/twilioHelper.js

@@ -1,4 +1,4 @@
-const { LegacyMessage } = require('../models/messageModel');
+const { Message } = require('../models/messageModel');
 
 const axios = require('axios');
 const { v4: uuidv4 } = require('uuid');
@@ -68,7 +68,7 @@ function extractTitle(message, mediaType) {
 async function isRecentMessage(chatId) {
   const fiveMinutesAgo = new Date(Date.now() - 5 * 60 * 1000);
 
-  const recentMessage = await LegacyMessage.find({
+  const recentMessage = await Message.find({
     $or: [{ group_id: chatId }, { numero: chatId }],
     timestamp: { $gte: fiveMinutesAgo.toISOString() }
   }).sort({ timestamp: -1 }).limit(1);
@@ -78,7 +78,7 @@ async function isRecentMessage(chatId) {
 
 
 async function getLastMessages(chatId, n) {
-  const messages = await LegacyMessage.find({ numero: chatId })
+  const messages = await Message.find({ numero: chatId })
     .sort({ timestamp: -1 })
     .limit(n)
     .select('timestamp numero nombre_whatsapp body');

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-declare module '@peopl/nexus' {
+declare module '@peopl-health/nexus' {
   import { EventEmitter } from 'events';
   import mongoose from 'mongoose';
 

package/lib/index.js

@@ -1,9 +1,19 @@
 const { NexusMessaging } = require('./core/NexusMessaging');
-const { TwilioProvider } = require('./adapters/TwilioProvider');
-const { BaileysProvider } = require('./adapters/BaileysProvider');
 const { MongoStorage } = require('./storage/MongoStorage');
 const { MessageParser } = require('./utils/messageParser');
 const { DefaultLLMProvider } = require('./utils/defaultLLMProvider');
+const { loadNexusConfig } = require('./config/configLoader');
+const templateController = require('./controllers/templateController');
+const templateFlowController = require('./controllers/templateFlowController');
+const interactive = require('./interactive');
+const {
+  configureLLMProvider: configureAssistantsLLM,
+  registerAssistant,
+  overrideGetAssistantById,
+  configureAssistants: setAssistantsConfig
+} = require('./services/assistantService');
+const { TwilioProvider } = require('./adapters/TwilioProvider');
+const { BaileysProvider } = require('./adapters/BaileysProvider');
 
 /**
  * Main Nexus class that orchestrates all components
@@ -40,17 +50,50 @@ class Nexus {
       parser = 'MessageParser',
       parserConfig = {},
       llm = 'openai',
-      llmConfig = {}
+      llmConfig = {},
+      assistants: assistantsOpt = undefined,
+      assistant: assistantOpt = undefined
     } = options;
 
     // Initialize messaging provider
     await this.messaging.initializeProvider(provider, providerConfig);
 
+    // Auto-configure template controllers with active provider when Twilio is used
+    try {
+      const activeProvider = typeof this.messaging.getProvider === 'function' 
+        ? this.messaging.getProvider() 
+        : null;
+      if (activeProvider && activeProvider.constructor && activeProvider.constructor.name === 'TwilioProvider') {
+        if (typeof templateController.configureNexusProvider === 'function') {
+          templateController.configureNexusProvider(activeProvider);
+        }
+        if (typeof templateFlowController.configureNexusProvider === 'function') {
+          templateFlowController.configureNexusProvider(activeProvider);
+        }
+      }
+    } catch (e) {
+      console.warn('Warning: failed to auto-configure template providers:', e?.message || e);
+    }
+
     // Initialize storage if provided
-    if (storage === 'mongo') {
-      this.storage = new MongoStorage(storageConfig);
-      await this.storage.connect();
-      this.messaging.setMessageStorage(this.storage);
+    if (storage) {
+      try {
+        const { createStorage } = require('./storage/registry');
+        if (typeof storage === 'string') {
+          this.storage = createStorage(storage, storageConfig || {});
+        } else if (typeof storage === 'object' && (storage.saveMessage || storage.saveInteractive)) {
+          this.storage = storage; // external adapter instance
+        } else {
+          // default to mongo if truthy but not recognized
+          this.storage = createStorage('mongo', storageConfig || {});
+        }
+        if (this.storage && typeof this.storage.connect === 'function') {
+          await this.storage.connect();
+        }
+        this.messaging.setMessageStorage(this.storage);
+      } catch (e) {
+        console.warn('Warning: storage initialization failed:', e?.message || e);
+      }
     }
 
     // Initialize message parser if provided
@@ -63,6 +106,31 @@ class Nexus {
       this.llmProvider = new DefaultLLMProvider(llmConfig);
     }
 
+
+    // Configure Assistants (registry + overrides)
+    const assistantsConfig = assistantsOpt || assistantOpt;
+    try {
+      if (this.llmProvider && typeof configureAssistantsLLM === 'function') {
+        // Provide the raw OpenAI client to the assistant service
+        configureAssistantsLLM(this.llmProvider.getClient());
+      }
+      if (assistantsConfig) {
+        if (assistantsConfig.registry && typeof assistantsConfig.registry === 'object') {
+          for (const [id, AssistantClass] of Object.entries(assistantsConfig.registry)) {
+            registerAssistant(id, AssistantClass);
+          }
+        }
+        if (typeof assistantsConfig.getAssistantById === 'function') {
+          overrideGetAssistantById(assistantsConfig.getAssistantById);
+        }
+        if (typeof setAssistantsConfig === 'function') {
+          setAssistantsConfig(assistantsConfig);
+        }
+      }
+    } catch (e) {
+      console.warn('Warning: failed to configure assistants:', e?.message || e);
+    }
+
     this.isInitialized = true;
   }
 
@@ -193,7 +261,14 @@ module.exports = {
   MessageParser,
   DefaultLLMProvider,
   routes,
-  // Direct access to route utilities for convenience
   setupDefaultRoutes: routes.setupDefaultRoutes,
-  createRouter: routes.createRouter
+  createRouter: routes.createRouter,
+  loadNexusConfig,
+  interactive,
+  registerFlow: interactive.registerFlow,
+  getFlow: interactive.getFlow,
+  listFlows: interactive.listFlows,
+  sendInteractive: interactive.sendInteractive,
+  registerInteractiveHandler: interactive.registerInteractiveHandler,
+  attachInteractiveRouter: interactive.attachInteractiveRouter
 };

package/lib/interactive/index.js

@@ -0,0 +1,86 @@
+
+const { toTwilioContent } = require('./twilioMapper');
+const { registerFlow, getFlow, listFlows, registerInteractiveHandler, listInteractiveHandlers } = require('./registry');
+
+async function sendInteractive(nexusOrMessaging, params) {
+  const { to, spec, id, variables } = params || {};
+  if (!nexusOrMessaging) throw new Error('sendInteractive requires a Nexus or NexusMessaging instance');
+  const messaging = typeof nexusOrMessaging.getMessaging === 'function' ? nexusOrMessaging.getMessaging() : nexusOrMessaging;
+  const provider = typeof messaging.getProvider === 'function' ? messaging.getProvider() : null;
+  if (!provider) throw new Error('No active provider');
+
+  const useSpec = spec || (id ? getFlow(id) : null);
+  if (!useSpec) throw new Error('Interactive spec not found');
+
+  // If user supplied a contentSid directly in spec, just send it
+  if (useSpec.contentSid) {
+    return await provider.sendMessage({ to, contentSid: useSpec.contentSid, variables });
+  }
+
+  // Twilio mapping
+  if (provider.constructor && provider.constructor.name === 'TwilioProvider') {
+    const content = toTwilioContent(useSpec);
+    const created = await provider.createTemplate(content);
+    return await provider.sendMessage({ to, contentSid: created.sid, variables });
+  }
+
+  // Baileys or others: not supported yet
+  throw new Error('Interactive/flows not supported for this provider');
+}
+
+module.exports = {
+  registerFlow,
+  getFlow,
+  listFlows,
+  sendInteractive,
+  registerInteractiveHandler,
+  attachInteractiveRouter
+};
+
+
+function _matchInteractive(match, interactive) {
+  if (!match) return true;
+  if (!interactive) return false;
+  // Type match (button, list, flow)
+  if (match.type && String(match.type).toLowerCase() !== String(interactive.type || '').toLowerCase()) return false;
+  // ID match (e.g., ListId)
+  if (match.id) {
+    const targetId = interactive.id || interactive.payload || interactive.title || '';
+    if (match.id instanceof RegExp) {
+      if (!match.id.test(String(targetId))) return false;
+    } else if (String(match.id) != String(targetId)) {
+      return false;
+    }
+  }
+  // Payload includes
+  if (match.payloadIncludes) {
+    const blob = JSON.stringify(interactive);
+    if (!blob.includes(match.payloadIncludes)) return false;
+  }
+  // Custom predicate
+  if (typeof match.predicate === 'function' && !match.predicate(interactive)) return false;
+  return true;
+}
+
+function attachInteractiveRouter(nexusOrMessaging) {
+  const messaging = typeof nexusOrMessaging.getMessaging === 'function' ? nexusOrMessaging.getMessaging() : nexusOrMessaging;
+  const bus = typeof messaging.getEventBus === 'function' ? messaging.getEventBus() : null;
+  if (!bus) throw new Error('Interactive router requires event bus support');
+
+  const handler = async (messageData) => {
+    const interactive = messageData && messageData.interactive ? messageData.interactive : null;
+    const items = listInteractiveHandlers();
+    for (const { match, handler } of items) {
+      try {
+        if (_matchInteractive(match, interactive)) {
+          await handler(messageData, messaging);
+        }
+      } catch (e) {
+        console.warn('Interactive handler error:', e && e.message || e);
+      }
+    }
+  };
+
+  bus.on('interactive:received', handler);
+  return () => bus.off && bus.off('interactive:received', handler);
+}

package/lib/interactive/registry.js

@@ -0,0 +1,31 @@
+
+// Simple in-memory registry for interactive specs (flows, quick replies)
+const _flows = new Map();
+const _handlers = [];
+
+function registerFlow(id, spec) {
+  if (!id || typeof id !== 'string') throw new Error('registerFlow requires id');
+  if (!spec || typeof spec !== 'object') throw new Error('registerFlow requires spec object');
+  _flows.set(id, spec);
+}
+
+function getFlow(id) {
+  return _flows.get(id) || null;
+}
+
+function listFlows() {
+  return Array.from(_flows.entries()).map(([id, spec]) => ({ id, spec }));
+}
+
+module.exports = { registerFlow, getFlow, listFlows, registerInteractiveHandler, listInteractiveHandlers };
+
+
+function registerInteractiveHandler(match, handler) {
+  if (typeof handler !== 'function') throw new Error('Handler must be a function');
+  const m = match || {};
+  _handlers.push({ match: m, handler });
+}
+
+function listInteractiveHandlers() {
+  return _handlers.slice();
+}

package/lib/interactive/twilioMapper.js

@@ -0,0 +1,60 @@
+
+// Map a provider-agnostic interactive spec to Twilio Content API payload
+
+function toTwilioContent(spec) {
+  if (!spec || typeof spec !== 'object') throw new Error('Interactive spec must be an object');
+  const { type = 'text', language = 'es', body = '', footer, variables, buttons, flow } = spec;
+
+  const content = {
+    friendly_name: spec.friendlyName || (spec.name || ('interactive_' + Date.now())),
+    language,
+    variables: {},
+    types: {}
+  };
+
+  // Build variables map from array/object
+  if (Array.isArray(variables)) {
+    variables.forEach((v, idx) => {
+      content.variables[String(idx + 1)] = typeof v === 'string' ? v : (v.example || '');
+    });
+  } else if (variables && typeof variables === 'object') {
+    Object.keys(variables).forEach(k => {
+      content.variables[k] = variables[k];
+    });
+  }
+
+  if (type === 'flow') {
+    content.types['twilio/flows'] = {
+      body: flow?.body || body || '',
+      button_text: flow?.buttonText || spec.buttonText || undefined,
+      subtitle: flow?.subtitle || spec.subtitle || undefined,
+      pages: flow?.pages || spec.pages || []
+    };
+  } else if (type === 'quick-reply') {
+    const actions = (buttons || []).slice(0, 3).map((b, i) => ({
+      title: b.text || b.title || ('Button ' + (i + 1)),
+      id: b.id || ('button_' + (i + 1))
+    }));
+    content.types['twilio/quick-reply'] = {
+      body: body || '',
+      actions
+    };
+    // Also include base text body type
+    content.types['twilio/text'] = { body: body || '' };
+  } else {
+    // Plain text
+    content.types['twilio/text'] = { body: body || '' };
+  }
+
+  if (footer) {
+    ['twilio/text', 'twilio/quick-reply'].forEach(t => {
+      if (content.types[t]) {
+        content.types[t].footer = footer;
+      }
+    });
+  }
+
+  return content;
+}
+
+module.exports = { toTwilioContent };