@peopl-health/nexus 1.1.8 → 1.3.0

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 };

package/lib/models/messageModel.js

@@ -51,6 +51,12 @@ messageSchema.pre('save', function (next) {
 
 const Message = mongoose.model('Message', messageSchema);
 
+async function insertMessage(values) {
+  const msg = new Message(values);
+  await msg.save();
+  return msg;
+}
+
 function formatTimestamp(unixTimestamp) {
   const date = new Date(unixTimestamp * 1000);
   return date.toLocaleString('sv-MX', {
@@ -86,6 +92,8 @@ function getMessageValues(message, content, reply, is_media) {
 
 module.exports = {
   Message,
+  // Backward-compatible helper used by helpers
+  insertMessage,
   getMessageValues,
   formatTimestamp
 };

package/lib/routes/index.js

@@ -31,7 +31,8 @@ const mediaRouteDefinitions = {
 const messageRouteDefinitions = {
   'POST /send': 'sendMessageController',
   'POST /send-bulk': 'sendBulkMessageController',
-  'POST /send-bulk-airtable': 'sendBulkMessageAirtableController'
+  'POST /send-bulk-airtable': 'sendBulkMessageAirtableController',
+  'POST /get-last': 'getLastInteractionController'
 };
 
 const templateRouteDefinitions = {
@@ -103,6 +104,7 @@ const builtInControllers = {
   sendMessageController: messageController.sendMessageController,
   sendBulkMessageController: messageController.sendBulkMessageController,
   sendBulkMessageAirtableController: messageController.sendBulkMessageAirtableController,
+  getLastInteractionController: messageController.getLastInteractionController,
   
   // Template controllers
   createTemplate: templateController.createTemplate,

package/lib/services/airtableService.js

@@ -3,6 +3,7 @@ const { airtable } = require('../config/airtableConfig');
 
 async function addRecord(baseID, tableName, fields) {
   try {
+    if (!airtable) throw new Error('Airtable not configured. Set AIRTABLE_API_KEY');
     const base = airtable.base(baseID);
     const record = await base(tableName).create(fields);
     console.log('Record added at', tableName);
@@ -17,6 +18,7 @@ async function addRecord(baseID, tableName, fields) {
 async function getRecords(baseID, tableName) {
   try {
     const records = [];
+    if (!airtable) throw new Error('Airtable not configured. Set AIRTABLE_API_KEY');
     const base = airtable.base(baseID);
     await base(tableName).select({
       maxRecords: 3
@@ -36,6 +38,7 @@ async function getRecords(baseID, tableName) {
 async function getRecordByFilter(baseID, tableName, filter, view = 'Grid view') {
   try {
     const records = [];
+    if (!airtable) throw new Error('Airtable not configured. Set AIRTABLE_API_KEY');
     const base = airtable.base(baseID);
     await base(tableName).select({
       filterByFormula: `${filter}`,
@@ -55,6 +58,7 @@ async function getRecordByFilter(baseID, tableName, filter, view = 'Grid view')
 
 async function updateRecordByFilter(baseID, tableName, filter, updateFields) {
   try {
+    if (!airtable) throw new Error('Airtable not configured. Set AIRTABLE_API_KEY');
     const base = airtable.base(baseID);
     const updatedRecords = [];
         

package/lib/services/assistantService.js

@@ -7,6 +7,7 @@ const configureLLMProvider = (provider) => {
 
 let assistantConfig = null;
 let assistantRegistry = {};
+let customGetAssistantById = null;
 
 const { Message, formatTimestamp } = require('../models/messageModel.js');
 const { Thread } = require('../models/threadModel.js');
@@ -26,9 +27,21 @@ const registerAssistant = (assistantId, AssistantClass) => {
   assistantRegistry[assistantId] = AssistantClass;
 };
 
+const overrideGetAssistantById = (resolverFn) => {
+  if (typeof resolverFn === 'function') {
+    customGetAssistantById = resolverFn;
+  }
+};
+
 const getAssistantById = (assistant_id, thread) => {
+  if (customGetAssistantById) {
+    const inst = customGetAssistantById(assistant_id, thread);
+    if (inst) return inst;
+  }
+
   if (!assistantConfig) {
-    throw new Error('Assistants not configured. Call configureAssistants() first.');
+    // Provide a more permissive default: allow registry usage without full config
+    assistantConfig = {};
   }
   
   const AssistantClass = assistantRegistry[assistant_id];
@@ -288,5 +301,6 @@ module.exports = {
   switchAssistant,
   configureAssistants,
   registerAssistant,
-  configureLLMProvider
+  configureLLMProvider,
+  overrideGetAssistantById
 };

package/lib/storage/NoopStorage.js

@@ -0,0 +1,19 @@
+
+/**
+ * Noop storage adapter - implements the storage interface but does nothing.
+ */
+class NoopStorage {
+  constructor(config = {}) {
+    this.config = config;
+  }
+  async connect() {}
+  async saveMessage() { return null; }
+  async saveInteractive() { return null; }
+  async getMessages() { return []; }
+  async getThread() { return null; }
+  async createThread() { return null; }
+  async updateThread() { return null; }
+  async disconnect() {}
+}
+
+module.exports = { NoopStorage };

package/lib/storage/registry.js

@@ -0,0 +1,31 @@
+
+const { MongoStorage } = require('./MongoStorage');
+const { NoopStorage } = require('./NoopStorage');
+
+const _storages = new Map();
+
+function registerStorage(name, StorageClassOrFactory) {
+  if (!name || !StorageClassOrFactory) throw new Error('registerStorage requires a name and class/factory');
+  _storages.set(String(name).toLowerCase(), StorageClassOrFactory);
+}
+
+function getStorage(name) {
+  return _storages.get(String(name || '').toLowerCase());
+}
+
+function createStorage(name, config) {
+  const Entry = getStorage(name);
+  if (!Entry) throw new Error(`Unsupported storage: ${name}`);
+  if (typeof Entry === 'function' && /^class\s/.test(Function.prototype.toString.call(Entry))) {
+    return new Entry(config || {});
+  }
+  // factory function
+  if (typeof Entry === 'function') return Entry(config || {});
+  throw new Error('Invalid storage registry entry');
+}
+
+// Register built-ins
+registerStorage('mongo', MongoStorage);
+registerStorage('noop', NoopStorage);
+
+module.exports = { registerStorage, getStorage, createStorage };

package/lib/templates/predefinedTemplates.js

@@ -76,6 +76,4 @@ const predefinedTemplates = {
   }
 };
 
-module.exports = {
-  predefinedTemplates
-};
+module.exports = predefinedTemplates;

package/lib/utils/defaultLLMProvider.js

@@ -1,4 +1,4 @@
-const { OpenAI } = require('openai');
+const OpenAI = require('openai');
 
 /**
  * Default LLM Provider using OpenAI

package/lib/utils/index.js

@@ -1,10 +1,8 @@
-const AssistantManager = require('./AssistantManager');
-const DefaultLLMProvider = require('./DefaultLLMProvider');
-const MessageParser = require('./MessageParser');
-const logger = require('./logger');
+const { DefaultLLMProvider } = require('./defaultLLMProvider');
+const { MessageParser } = require('./messageParser');
+const { logger } = require('./logger');
 
 module.exports = {
-  AssistantManager,
   DefaultLLMProvider,
   MessageParser,
   logger

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "1.1.8",
+  "version": "1.3.0",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "publishConfig": {
     "access": "public"
@@ -34,6 +34,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "test": "jest",
+    "test:inband": "jest --runInBand",
     "lint": "eslint lib/**/*.js",
     "prepublishOnly": "npm test && npm run lint",
     "version": "npm run prepublishOnly && git add -A lib",