@peopl-health/nexus 3.3.7 → 3.3.9

package/examples/basic-usage.js

@@ -1,6 +1,7 @@
 const express = require('express');
 require('dotenv').config();
 const { Nexus, setupDefaultRoutes, BaseAssistant } = require('@peopl-health/nexus');
+const { setMetaConfig } = require('../lib/config/metaConfig');
 
 const app = express();
 app.use(express.json());
@@ -66,6 +67,13 @@ class GeneralAssistant extends BaseAssistant {
 }
 
 async function startServer() {
+  // Configure Meta Flow API (consumer-owned)
+  setMetaConfig({
+    accessToken: process.env.META_ACCESS_TOKEN,
+    wabaId: process.env.META_WABA_ID,
+    apiVersion: process.env.META_API_VERSION || 'v21.0'
+  });
+
   // Initialize Nexus with check-after processing (immediate response, checks for new messages after)
   const nexus = new Nexus({
     messaging: {

package/lib/adapters/BaileysProvider.js

@@ -1,10 +1,8 @@
-const { MessageProvider } = require('../core/MessageProvider');
 const { logger } = require('../utils/logger');
 const { calculateDelay } = require('../utils/scheduleUtils');
 
-/**
- * Baileys WhatsApp messaging provider
- */
+const { MessageProvider } = require('../core/MessageProvider');
+
 class BaileysProvider extends MessageProvider {
   constructor(config) {
     super(config);
@@ -17,7 +15,6 @@ class BaileysProvider extends MessageProvider {
   async initialize() {
     try {
       const baileys = require('baileys');
-      // Support both CJS and ESM shapes
       const makeWASocket = baileys.default || baileys.makeWASocket || baileys;
       const useMultiFileAuthState = baileys.useMultiFileAuthState || baileys.useMultiFileAuthState;
       const { useMongoDBAuthState } = require('../config/mongoAuthConfig');
@@ -58,7 +55,6 @@ class BaileysProvider extends MessageProvider {
     const { connection, lastDisconnect, qr } = update || {};
 
     if (qr) {
-      // Emit QR code event for consumer to handle
       this.emit?.('qr', qr);
     }
 
@@ -100,7 +96,6 @@ class BaileysProvider extends MessageProvider {
     let sendOptions = {};
     let formattedMessage = this.formatMessage(body || '');
 
-    // Handle mentions
     const regex = /@\d+/g;
     const matches = formattedMessage.match(regex);
     if (matches) {
@@ -110,13 +105,11 @@ class BaileysProvider extends MessageProvider {
       sendOptions.mentions = processedNumbers;
     }
 
-    // Handle link preview
     const keywords = ['meet.google.com', 'airtable', 'zoom'];
     if (keywords.some(keyword => formattedMessage.includes(keyword)) || hidePreview) {
       sendOptions.linkPreview = false;
     }
 
-    // Set message content based on type
     if (!fileUrl || fileType === 'text') {
       sendOptions.text = formattedMessage;
     } else {
@@ -182,7 +175,6 @@ class BaileysProvider extends MessageProvider {
     return { scheduled: true, delay };
   }
 
-
   getConnectionStatus() {
     return this.waSocket?.user ? true : false;
   }
@@ -195,7 +187,6 @@ class BaileysProvider extends MessageProvider {
     this.isConnected = false;
   }
 
-  // Content/Template operations are not supported for Baileys
   async listTemplates() {
     throw new Error('Template operations are only supported with Twilio provider');
   }

package/lib/adapters/TwilioProvider.js

@@ -1,18 +1,19 @@
-const { MessageProvider } = require('../core/MessageProvider');
 const axios = require('axios');
+const { v4: uuidv4 } = require('uuid');
+
 const runtimeConfig = require('../config/runtimeConfig');
-const { uploadMediaToS3, getFileExtension } = require('../helpers/mediaHelper');
-const { ensureWhatsAppFormat } = require('../helpers/twilioHelper');
-const { sanitizeMediaFilename } = require('../utils/inputSanitizer');
 const { generatePresignedUrl } = require('../config/awsConfig');
+
+const { sanitizeMediaFilename } = require('../utils/inputSanitizer');
 const { validateMedia, getMediaType } = require('../utils/mediaValidator');
 const { logger } = require('../utils/logger');
 const { calculateDelay } = require('../utils/scheduleUtils');
-const { v4: uuidv4 } = require('uuid');
 
-/**
- * Twilio WhatsApp messaging provider
- */
+const { ensureWhatsAppFormat } = require('../helpers/twilioHelper');
+const { uploadMediaToS3, getFileExtension } = require('../helpers/mediaHelper');
+
+const { MessageProvider } = require('../core/MessageProvider');
+
 class TwilioProvider extends MessageProvider {
   constructor(config) {
     super(config);
@@ -47,7 +48,6 @@ class TwilioProvider extends MessageProvider {
     const formattedFrom = ensureWhatsAppFormat(this.whatsappNumber);
     const formattedCode = ensureWhatsAppFormat(code);
 
-
     if (!formattedFrom || !formattedCode) {
       throw new Error('Invalid sender or recipient number');
     }
@@ -68,7 +68,6 @@ class TwilioProvider extends MessageProvider {
       logger.debug('[TwilioProvider] No status callback URL configured');
     }
 
-    // Handle template messages
     if (contentSid) {
       const renderedMessage = await this.renderTemplate(contentSid, variables);
       if (renderedMessage) {
@@ -89,7 +88,6 @@ class TwilioProvider extends MessageProvider {
       messageParams.body = body;
     }
 
-    // Handle media messages
     if (fileUrl && fileType !== 'text') {
       const mediaPrep = await this.prepareOutboundMedia(messageData, formattedCode);
       const outboundMediaUrl = mediaPrep.mediaUrl || fileUrl;
@@ -294,7 +292,6 @@ class TwilioProvider extends MessageProvider {
 
     setTimeout(async () => {
       try {
-        // Convert Mongoose document to plain object if needed
         const payload = scheduledMessage.toObject ? scheduledMessage.toObject() : { ...scheduledMessage };
         delete payload.__nexusSend;
         
@@ -335,7 +332,6 @@ class TwilioProvider extends MessageProvider {
       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 {
@@ -424,13 +420,6 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
-
-  /**
-   * Split a message into chunks at sentence boundaries, respecting Twilio's character limit
-   * @param {string} text - The message text to split
-   * @param {number} maxLength - Maximum length per chunk (default: 1600)
-   * @returns {Array<string>} Array of message chunks
-   */
   splitMessageAtWordBoundaries(text, maxLength = 1600) {
     if (!text || text.length <= maxLength) return [text];
     const chunks = [];
@@ -465,11 +454,6 @@ class TwilioProvider extends MessageProvider {
     return chunks;
   }
 
-  /**
-   * List templates from Twilio Content API
-   * @param {Object} options - Query options
-   * @returns {Promise<Array>} Array of templates
-   */
   async listTemplates(options = {}) {
     if (!this.isConnected || !this.twilioClient) {
       throw new Error('Twilio provider not initialized');
@@ -484,9 +468,6 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
-  /**
-   * Fetch a specific template/content by SID
-   */
   async getTemplate(sid) {
     if (!this.isConnected || !this.twilioClient) {
       throw new Error('Twilio provider not initialized');
@@ -500,12 +481,6 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
-  /**
-   * Render template content with variables
-   * @param {string} contentSid - The Twilio content SID
-   * @param {Object} variables - The variables object with keys like "1", "2"
-   * @returns {Promise<string|null>} The rendered message content or null if not found
-   */
   async renderTemplate(contentSid, variables) {
     try {
       if (!contentSid) return null;
@@ -517,7 +492,6 @@ class TwilioProvider extends MessageProvider {
         return null;
       }
 
-      // Extract text content from different template types
       let textContent = this.extractTextFromTemplate(template);
 
       if (!textContent) {
@@ -525,7 +499,6 @@ class TwilioProvider extends MessageProvider {
         return null;
       }
 
-      // Render variables if provided
       if (variables && typeof variables === 'object' && Object.keys(variables).length > 0) {
         return this.renderTemplateWithVariables(textContent, variables);
       }
@@ -537,25 +510,17 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
-  /**
-   * Extract text content from different template types
-   * @param {Object} template - The Twilio template object
-   * @returns {string} The extracted text content
-   */
   extractTextFromTemplate(template) {
     const types = template.types || {};
     
-    // Handle plain text templates
     if (types['twilio/text']) {
       return types['twilio/text'].body || '';
     }
     
-    // Handle quick reply templates
     if (types['twilio/quick-reply']) {
       const quickReply = types['twilio/quick-reply'];
       let text = quickReply.body || '';
       
-      // Add quick reply options
       if (quickReply.actions && Array.isArray(quickReply.actions)) {
         const options = quickReply.actions
           .filter(action => action.title)
@@ -569,12 +534,10 @@ class TwilioProvider extends MessageProvider {
       return text;
     }
     
-    // Handle list templates
     if (types['twilio/list']) {
       const list = types['twilio/list'];
       let text = list.body || '';
       
-      // Add list items
       if (list.items && Array.isArray(list.items)) {
         const items = list.items
           .filter(item => item.title)
@@ -588,12 +551,10 @@ class TwilioProvider extends MessageProvider {
       return text;
     }
     
-    // Handle button templates
     if (types['twilio/button']) {
       const button = types['twilio/button'];
       let text = button.body || '';
       
-      // Add button options
       if (button.actions && Array.isArray(button.actions)) {
         const buttons = button.actions
           .filter(action => action.title)
@@ -607,17 +568,14 @@ class TwilioProvider extends MessageProvider {
       return text;
     }
     
-    // Handle flow templates (fallback to body)
     if (types['twilio/flows']) {
       return types['twilio/flows'].body || '';
     }
     
-    // Handle media templates (extract caption)
     if (types['twilio/media']) {
       return types['twilio/media'].caption || '';
     }
     
-    // Fallback: try to find any body content
     for (const typeKey of Object.keys(types)) {
       const type = types[typeKey];
       if (type && typeof type === 'object' && type.body) {
@@ -628,12 +586,6 @@ class TwilioProvider extends MessageProvider {
     return '';
   }
 
-  /**
-   * Render template content with variables
-   * @param {string} templateBody - The template body with placeholders like {{1}}, {{2}}
-   * @param {Object} variables - The variables object with keys like "1", "2"
-   * @returns {string} The rendered message content
-   */
   renderTemplateWithVariables(templateBody, variables) {
     if (!templateBody || typeof templateBody !== 'string') {
       return '';
@@ -646,12 +598,10 @@ class TwilioProvider extends MessageProvider {
     try {
       let rendered = templateBody;
       
-      // Replace placeholders like {{1}}, {{2}}, etc. with variable values
       Object.keys(variables).forEach(key => {
         const placeholder = `{{${key}}}`;
         const value = variables[key] || '';
         
-        // Simple string replacement - more reliable than regex for this use case
         if (rendered.includes(placeholder)) {
           rendered = rendered.replace(new RegExp(placeholder.replace(/[{}]/g, '\\$&'), 'g'), value);
         }
@@ -664,9 +614,6 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
-  /**
-   * Check template approval status using Twilio Content API helpers
-   */
   async checkApprovalStatus(sid) {
     if (!this.isConnected || !this.twilioClient) {
       throw new Error('Twilio provider not initialized');
@@ -729,9 +676,6 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
-  /**
-   * Submit template for approval (best-effort placeholder)
-   */
   async submitForApproval(contentSid, name, category) {
     if (!contentSid) throw new Error('Content SID is required');
     const content = await this.getTemplate(contentSid);
@@ -763,9 +707,6 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
-  /**
-   * Delete a template/content by SID
-   */
   async deleteTemplate(sid) {
     if (!this.isConnected || !this.twilioClient) {
       throw new Error('Twilio provider not initialized');
@@ -779,10 +720,6 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
-  /**
-   * Create a template/content using Twilio Content API
-   * @param {Object} templateData - Must follow Twilio Content API schema
-   */
   async createTemplate(templateData) {
     if (!this.isConnected || !this.twilioClient) {
       throw new Error('Twilio provider not initialized');
@@ -798,9 +735,6 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
-  /**
-   * Check the status of a sent message using its SID
-   */
   async getMessageStatus(messageSid) {
     if (!this.isConnected || !this.twilioClient) {
       throw new Error('Twilio provider not initialized');
@@ -811,8 +745,6 @@ class TwilioProvider extends MessageProvider {
 
     try {
       const message = await this.twilioClient.messages(messageSid).fetch();
-      // Returns the complete Twilio message object with all status information
-      // Status-related fields: status, errorCode, errorMessage, dateCreated, dateSent, dateUpdated
       return message;
     } catch (error) {
       if (error.status === 404) {

package/lib/adapters/registry.js

@@ -12,18 +12,17 @@ function getProvider(name) {
   return _providers.get(String(name || '').toLowerCase());
 }
 
-function createProvider(name, config) {
+function createMessagingProvider(name, config) {
   const ProviderClass = getProvider(name);
   if (!ProviderClass) throw new Error(`Unsupported provider: ${name}`);
   return new ProviderClass(config || {});
 }
 
-// Register built-ins
 registerProvider('twilio', TwilioProvider);
 registerProvider('baileys', BaileysProvider);
 
 module.exports = {
   registerProvider,
   getProvider,
-  createProvider
-};
+  createMessagingProvider
+};

package/lib/assistants/BaseAssistant.js

@@ -1,16 +1,16 @@
 const llmConfig = require('../config/llmConfig');
+
+const { logger } = require('../utils/logger');
+
 const { Thread } = require('../models/threadModel');
 const { Message } = require('../models/messageModel');
+
 const { formatMessage } = require('../helpers/messageHelper');
-const { createProvider } = require('../providers/createProvider');
-const { logger } = require('../utils/logger');
+
+const { createLLMProvider } = require('../providers/createLLMProvider');
 
 const DEFAULT_MAX_HISTORICAL_MESSAGES = parseInt(process.env.MAX_HISTORICAL_MESSAGES || '50', 10);
 
-/**
- * Flexible base assistant implementation that integrates with OpenAI Threads
- * and supports dynamic tool registration.
- */
 class BaseAssistant {
   constructor(options = {}) {
     this.assistantId = options.assistantId || null;
@@ -29,7 +29,7 @@ class BaseAssistant {
 
     if (!this.provider && this.client) {
       try {
-        const provider = createProvider({
+        const provider = createLLMProvider({
           client: this.client,
           variant: process.env.VARIANT || 'assistants'
         });
@@ -70,7 +70,7 @@ class BaseAssistant {
     if (!this.provider) {
       try {
         const variant = process.env.VARIANT || 'assistants';
-        const provider = createProvider({ client: this.client, variant });
+        const provider = createLLMProvider({ client: this.client, variant });
         this.provider = provider;
         if (typeof llmConfig.setOpenAIProvider === 'function') {
           llmConfig.setOpenAIProvider(provider);
@@ -167,7 +167,7 @@ class BaseAssistant {
     return await this.create(code, context);
   }
 
-  async create(code, context = {}) {
+  async create(code, _context = {}) {
     this._ensureClient();
     this.status = 'active';
     this.thread = { code };
@@ -195,7 +195,6 @@ class BaseAssistant {
 
       const messagesInOrder = lastMessages.reverse();
 
-      // Messages with from_me: true are assistant messages, from_me: false are user messages
       const formattedMessages = messagesInOrder
         .filter(message => message && message.timestamp && message.body && message.body.trim() !== '')
         .flatMap(message => {

package/lib/config/airtableConfig.js

@@ -1,11 +1,11 @@
 const Airtable = require('airtable');
+
 const runtimeConfig = require('./runtimeConfig');
 
 const airtableConfig = {
   apiKey: runtimeConfig.get('AIRTABLE_API_KEY'),
 };
 
-// Configurable base IDs - users can override via environment variables
 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';
@@ -17,7 +17,6 @@ const Follow_Up_ID = require('./runtimeConfig').get('AIRTABLE_FOLLOW_UP_ID') ||
 const Webinars_Leads_ID = require('./runtimeConfig').get('AIRTABLE_WEBINARS_LEADS_ID') || 'appzjpVXTI0TgqGPq';
 const Product_ID = require('./runtimeConfig').get('AIRTABLE_PRODUCT_ID') || 'appu2YDW2pKDYLL5H';
 
-// Initialize Airtable only if API key is provided
 let airtable = null;
 if (airtableConfig.apiKey) {
   airtable = new Airtable({ apiKey: airtableConfig.apiKey });
@@ -49,7 +48,6 @@ module.exports = {
   Follow_Up_ID,
   Webinars_Leads_ID,
   Product_ID,
-  // Helper function to get base by ID
   getBase: (baseKeyOrId = require('./runtimeConfig').get('AIRTABLE_BASE_ID')) => {
     if (!airtable) {
       throw new Error('Airtable not configured. Please set AIRTABLE_API_KEY environment variable.');

package/lib/config/awsConfig.js

@@ -1,9 +1,10 @@
-const { logger } = require('../utils/logger');
-
-const AWS = require('aws-sdk');
 const fs = require('fs');
 const path = require('path');
 
+const AWS = require('aws-sdk');
+
+const { logger } = require('../utils/logger');
+
 AWS.config.update({
   accessKeyId: process.env.AWS_ACCESS_KEY_ID,
   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
@@ -13,7 +14,6 @@ AWS.config.update({
 
 const s3 = new AWS.S3();
 
-
 async function uploadBufferToS3(buffer, bucketName, key, contentType, isWhatsAppMedia = false) {
   const params = {
     Bucket: bucketName,

package/lib/config/configLoader.js

@@ -35,4 +35,4 @@ function loadNexusConfig(userConfig) {
   }
 }
 
-module.exports = { loadNexusConfig, defaults };
+module.exports = { loadNexusConfig, defaults };

package/lib/config/llmConfig.js

@@ -1,6 +1,8 @@
-const runtimeConfig = require('./runtimeConfig');
+const runtimeConfig = require('../config/runtimeConfig');
+
 const { logger } = require('../utils/logger');
-const { createProvider } = require('../providers/createProvider');
+
+const { createLLMProvider } = require('../providers/createLLMProvider');
 
 let anthropicClient = null;
 let openaiClient = null;
@@ -40,7 +42,7 @@ const getOpenAIProvider = ({ instantiate = true, variant = providerVariant } = {
   if (providerInstance) return providerInstance;
   if (!instantiate) return null;
   if (!openaiClient) return null;
-  const provider = createProvider({ client: openaiClient, variant });
+  const provider = createLLMProvider({ client: openaiClient, variant });
   setOpenAIProvider(provider);
   return provider;
 };
@@ -54,7 +56,7 @@ const requireOpenAIProvider = (options) => {
 };
 
 const configureOpenAIProvider = (config = {}) => {
-  const provider = createProvider(config);
+  const provider = createLLMProvider(config);
   setOpenAIProvider(provider);
   return provider;
 };

package/lib/config/metaConfig.js

@@ -0,0 +1,31 @@
+const { logger } = require('../utils/logger');
+
+let metaConfig = {
+  accessToken: null,
+  wabaId: null,
+  apiVersion: 'v21.0'
+};
+
+const setMetaConfig = ({ accessToken, wabaId, apiVersion }) => {
+  if (!accessToken || !wabaId) {
+    throw new Error('Meta API config requires accessToken and wabaId');
+  }
+  metaConfig = {
+    ...metaConfig,
+    accessToken,
+    wabaId,
+    apiVersion: apiVersion || metaConfig.apiVersion
+  };
+  logger.info('[MetaFlowAPI] Configuration updated', {
+    wabaId: metaConfig.wabaId,
+    apiVersion: metaConfig.apiVersion,
+    hasAccessToken: !!metaConfig.accessToken
+  });
+};
+
+const getMetaConfig = () => metaConfig;
+
+module.exports = {
+  setMetaConfig,
+  getMetaConfig
+};

package/lib/config/mongoAuthConfig.js

@@ -1,6 +1,8 @@
+const { randomBytes } = require('crypto');
+
 const { MongoClient } = require('mongodb');
 const { proto, Curve, signedKeyPair, generateRegistrationId } = require('baileys');
-const { randomBytes } = require('crypto');
+
 const { logger } = require('../utils/logger');
 
 async function connectToMongo(mongoClient) {

package/lib/config/mongoConfig.js

@@ -1,4 +1,5 @@
 const mongoose = require('mongoose');
+
 const { logger } = require('../utils/logger');
 
 let connection = null;

package/lib/controllers/assistantController.js

@@ -1,13 +1,15 @@
 const { Config_ID } = require('../config/airtableConfig');
 
+const { logger } = require('../utils/logger');
+
 const { Thread } = require('../models/threadModel');
 
+const { getThreadInfo } = require('../helpers/threadHelper');
+
 const { getRecordByFilter } = require('../services/airtableService');
 const { createAssistant, addMsgAssistant, addInsAssistant, switchAssistant } = require('../services/assistantService');
-const { getThreadInfo } = require('../helpers/threadHelper');
-const { sendMessage } = require('../core/NexusMessaging');
-const { logger } = require('../utils/logger');
 
+const { sendMessage } = require('../core/NexusMessaging');
 
 const activeAssistantController = async (req, res) => {
   const { code, active } = req.body;
@@ -123,7 +125,6 @@ const stopAssistantController = async (req, res) => {
   }
 };
 
-
 module.exports = {
   activeAssistantController,
   addInsAssistantController,

package/lib/controllers/bugReportController.js

@@ -1,8 +1,11 @@
-const { Message } = require('../models/messageModel');
-const { addRecord, getRecordByFilter } = require('../services/airtableService');
 const { Logging_ID } = require('../config/airtableConfig');
+
 const { logger } = require('../utils/logger');
 
+const { Message } = require('../models/messageModel');
+
+const { addRecord, getRecordByFilter } = require('../services/airtableService');
+
 async function logBugReportToAirtable(reporter, whatsapp_id, description, severity, messageIds = []) {
   try {
     let conversation = null;

package/lib/controllers/caseDocumentationController.js

@@ -1,7 +1,9 @@
-const { addRecord, getRecordByFilter } = require('../services/airtableService');
 const { Product_ID } = require('../config/airtableConfig');
+
 const { logger } = require('../utils/logger');
 
+const { addRecord, getRecordByFilter } = require('../services/airtableService');
+
 async function logCaseDocumentationToAirtable(reporter, whatsapp_id, tableName, dynamicFields = {}) {
   try {
     let patientId = null;