@peopl-health/nexus 4.4.4 → 4.5.21

package/README.md

@@ -1,6 +1,6 @@
 # @peopl-health/nexus
 
-A concise, configurable messaging and assistant toolkit for WhatsApp. It supports Twilio (production‑ready) and Baileys (limited), optional Mongo storage, OpenAI assistants, templates/flows via Twilio Content API, and an event/middleware model so apps can customize behavior.
+A concise, configurable messaging and assistant toolkit for WhatsApp. It supports Twilio (production‑ready) and Baileys (limited), optional Mongo storage, OpenAI assistants, and templates/flows via Twilio Content API.
 
 ## Install
 
@@ -108,17 +108,12 @@ await nexus.initialize({ storage: 'src', storageConfig: { /* ... */ } });
 await nexus.initialize({ storage: new MyStorageClass(/* ... */) });
 ```
 
-## Middleware & Events
+## Events
 
-Add middleware per type or global; subscribe to events.
+Subscribe to internal events via the event bus.
 ```js
 const bus = nexus.getMessaging().getEventBus();
 bus.on('message:received', (m) => console.log('rx', m.id));
-
-nexus.getMessaging().use('message', async (msg, nx, next) => {
-  // sanitize/annotate
-  return next();
-});
 ```
 
 ## Assistants (Optional)
@@ -190,4 +185,4 @@ await nexus.getStorage().setConfig('media.bucketName', process.env.AWS_S3_BUCKET
 Tips
 - Connect Mongo before `app.listen()` to avoid Mongoose buffering timeouts.
 - If you initialize OpenAI, pass `llm: 'openai'` and `llmConfig: { apiKey }` to `nexus.initialize`.
-- Use the event bus + middleware for custom routing and transformations without forking the default handlers.
+- Use the event bus for observability and custom reactions without forking the default handlers.

package/lib/adapters/BaileysProvider.js

@@ -135,7 +135,9 @@ class BaileysProvider extends MessageProvider {
         success: true,
         messageId: result?.key?.id,
         provider: 'baileys',
-        result
+        result,
+        delivered: true,
+        deferred: false
       };
     } catch (error) {
       throw new Error(`Baileys send failed: ${error.message}`);
@@ -172,7 +174,7 @@ class BaileysProvider extends MessageProvider {
       }
     }, delay);
 
-    return { scheduled: true, delay };
+    return { scheduled: true, delay, delivered: false, deferred: true };
   }
 
   getConnectionStatus() {

package/lib/adapters/MessageProvider.js

@@ -38,7 +38,7 @@ class MessageProvider {
    * @param {string} messageData.fileType - File type (text, image, document, audio)
    * @param {Object} messageData.variables - Template variables
    * @param {string} messageData.contentSid - Template content SID
-   * @returns {Promise<Object>} Message result
+   * @returns {Promise<Object>} Result with `delivered` and `deferred` boolean flags.
    */
   async sendMessage(messageData) {
     // eslint-disable-next-line no-unused-vars
@@ -49,7 +49,7 @@ class MessageProvider {
   /**
    * Send a scheduled message
    * @param {Object} scheduledMessage - Scheduled message data
-   * @returns {Promise<void>}
+   * @returns {Promise<Object>} Result with `delivered: false, deferred: true`.
    */
   async sendScheduledMessage(scheduledMessage) {
     // eslint-disable-next-line no-unused-vars

package/lib/adapters/TwilioProvider.js

@@ -64,7 +64,9 @@ class TwilioProvider extends MessageProvider {
         provider: 'twilio',
         status: 'bench_suppressed',
         result: { sid: benchSid, status: 'bench_suppressed' },
-        finalize: { sid: benchSid, status: 'bench_suppressed' }
+        finalize: { sid: benchSid, status: 'bench_suppressed' },
+        delivered: false,
+        deferred: false
       };
     }
 
@@ -158,7 +160,9 @@ class TwilioProvider extends MessageProvider {
       provider: 'twilio',
       status: result.status,
       result,
-      finalize: { sid: chunks ? null : result.sid, status: result.status?.toLowerCase() || null }
+      finalize: { sid: chunks ? null : result.sid, status: result.status?.toLowerCase() || null },
+      delivered: true,
+      deferred: false
     };
   }
 
@@ -263,7 +267,7 @@ class TwilioProvider extends MessageProvider {
       }
     }, delay);
 
-    return { scheduled: true, delay };
+    return { scheduled: true, delay, delivered: false, deferred: true };
   }
 
   supportsMessageStorage() {

package/lib/controllers/assistantController.js

@@ -6,7 +6,7 @@ const { logger } = require('../utils/logger');
 const { getThreadInfo, switchThreadStoppedStatus } = require('../helpers/threadHelper');
 
 const { getRecordByFilter } = require('../services/airtableService');
-const { createAssistant, addMsgAssistant, switchAssistant } = require('../services/assistantService');
+const { createAssistant, switchAssistant } = require('../services/assistantService');
 
 const { sendMessage, processInstruction, processSystemMessage } = require('../core/NexusMessaging');
 
@@ -42,11 +42,7 @@ const addMsgAssistantController = async (req, res) => {
   if (!code) return res.status(400).json({ success: false, error: 'Code is required' });
 
   try {
-    if (reply) {
-      await processSystemMessage(code, messages, role, { triggeredBy });
-    } else {
-      await addMsgAssistant(code, messages, role);
-    }
+    await processSystemMessage(code, messages, role, { reply, triggeredBy });
     return res.status(200).json({ success: true, message: 'Message added to assistant' });
   } catch (error) {
     logger.error('[AssistantController] Add message error', { error: error.message, code, role });

package/lib/controllers/bugReportController.js

@@ -3,10 +3,10 @@ const runtimeConfig = require('../config/runtimeConfig');
 
 const { logger } = require('../utils/logger');
 
-const { Message } = require('../models/messageModel');
 const { getBug, VALID_SEVERITIES, UPDATABLE_FIELDS } = require('../models/bugModel');
 
 const { addRecord, getRecordByFilter } = require('../services/airtableService');
+const { getMessages } = require('../services/messageService');
 
 async function logBugReportToAirtable(reportedBug) {
   const {
@@ -16,7 +16,7 @@ async function logBugReportToAirtable(reportedBug) {
   try {
     let conversation = null;
     if (messages?.length) {
-      const msgs = await Message.find({ _id: { $in: messages } }).sort({ createdAt: 1 });
+      const msgs = await getMessages({ _id: { $in: messages } }, { sort: { createdAt: 1 } });
       conversation = msgs.map(msg => {
         const timestamp = msg.createdAt.toISOString().slice(0, 16).replace('T', ' ');
         const role = msg.from_me ? 'Assistant' : 'Patient';

package/lib/controllers/conversationController.js

@@ -13,6 +13,7 @@ const { ensureWhatsAppFormat } = require('../helpers/twilioHelper');
 
 const { getRecordByFilter, updateRecordByFilter } = require('../services/airtableService');
 const { fetchConversationData, processConversations, startConversation } = require('../services/conversationService');
+const { getMessages, countMessages, aggregateMessages } = require('../services/messageService');
 
 const { sendMessage } = require('../core/NexusMessaging');
 
@@ -25,7 +26,7 @@ const getConversationController = async (req, res) => {
     const skip = (page - 1) * limit;
     const filter = req.query.filter || 'all';
 
-    if (!Message || await Message.countDocuments({}) === 0) {
+    if (!Message || await countMessages({}) === 0) {
       return res.status(200).json({
         success: true,
         conversations: [],
@@ -88,8 +89,8 @@ const getConversationMessagesController = async (req, res) => {
       query.createdAt = { $lt: new Date(before) };
     }
 
-    const total = await Message.countDocuments(query);
-    const messages = await Message.find(query).sort({ createdAt: -1 }).skip(skip).limit(limit).lean();
+    const total = await countMessages(query);
+    const messages = await getMessages(query, { sort: { createdAt: -1 }, skip, limit });
     const totalPages = Math.ceil(total / limit);
 
     res.status(200).json({
@@ -190,7 +191,7 @@ const searchConversationsController = async (req, res) => {
 
     const escapedQuery = query.replace(/\+/g, '\\+');
 
-    const matches = await Message.aggregate([
+    const matches = await aggregateMessages([
       {
         $facet: {
           primary: [
@@ -329,7 +330,7 @@ const getConversationsByNameController = async (req, res) => {
       }
     ];
 
-    const [facetResult] = await Message.aggregate(pipeline, { allowDiskUse: true });
+    const [facetResult] = await aggregateMessages(pipeline, { allowDiskUse: true });
 
     const conversations = facetResult?.data ?? [];
     const total = facetResult?.totalCount[0]?.total ?? 0;
@@ -365,7 +366,7 @@ const getConversationsByNameController = async (req, res) => {
 const getNewMessagesController = async (req, res) => {
   try {
     const { phoneNumber } = req.params;
-    const { after, limit = 20 } = req.query;
+    const { after } = req.query;
         
     if (!phoneNumber) {
       return res.status(400).json({
@@ -381,7 +382,7 @@ const getNewMessagesController = async (req, res) => {
       });
     }
         
-    const lastMessage = await Message.findById(after).lean();
+    const [lastMessage] = await getMessages({ _id: after }, { limit: 1 });
         
     if (!lastMessage) {
       return res.status(404).json({
@@ -396,10 +397,9 @@ const getNewMessagesController = async (req, res) => {
       createdAt: { $gt: lastMessage.createdAt }
     };
         
-    const messages = await Message.find(query)
-      .sort({ createdAt: 1 })
-      .limit(parseInt(limit))
-      .lean();
+    const raw = parseInt(req.query.limit, 10);
+    const clampedLimit = Number.isFinite(raw) ? Math.min(Math.max(raw, 1), 100) : 20;
+    const messages = await getMessages(query, { sort: { createdAt: 1 }, limit: clampedLimit });
         
     res.status(200).json({
       success: true,
@@ -559,8 +559,8 @@ const searchMessagesByNumberController = async (req, res) => {
     
     const mongoSort = { createdAt: -1 };
 
-    const total = await Message.countDocuments(mongoQuery);
-    const messages = await Message.find(mongoQuery).sort(mongoSort).skip(skip).limit(limit).lean();
+    const total = await countMessages(mongoQuery);
+    const messages = await getMessages(mongoQuery, { sort: mongoSort, skip, limit });
     const totalPages = Math.ceil(total / limit);
 
     res.status(200).json({

package/lib/controllers/interactionController.js

@@ -4,13 +4,13 @@ const { Logging_ID } = require('../config/airtableConfig');
 const { logger } = require('../utils/logger');
 
 const { getInteraction } = require('../models/interactionModel');
-const { Message } = require('../models/messageModel');
 
 const { addRecord, getRecordByFilter } = require('../services/airtableService');
+const { getMessages } = require('../services/messageService');
 
 async function logInteractionToAirtable(messageIds, whatsapp_id, reporter, quality, description, type, medical_note) {
   try {
-    const messageObjects = await Message.find({ _id: { $in: messageIds } }).sort({ createdAt: -1 });
+    const messageObjects = await getMessages({ _id: { $in: messageIds } }, { sort: { createdAt: -1 } });
     
     const conversation = messageObjects.map(msg => {
       const timestamp = msg.createdAt.toISOString().slice(0, 16).replace('T', ' ');

package/lib/controllers/messageController.js

@@ -3,7 +3,6 @@ const mongoose = require('mongoose');
 
 const { logger } = require('../utils/logger');
 
-const { Message } = require('../models/messageModel.js');
 const { ScheduledMessage } = require('../models/agendaMessageModel.js');
 const { DeliveryAttempt } = require('../models/deliveryAttemptModel.js');
 const FlowRouting = require('../models/flowRoutingModel.js');
@@ -12,6 +11,7 @@ const { ensureWhatsAppFormat } = require('../helpers/twilioHelper');
 const { ensureFlowTokenInVariables } = require('../helpers/templateFlowControllerHelper');
 
 const { getRecordByFilter } = require('../services/airtableService');
+const { getMessages } = require('../services/messageService');
 
 const { sendMessage, sendScheduledMessage, getDefaultInstance } = require('../core/NexusMessaging');
 
@@ -215,9 +215,10 @@ const getLastInteractionController = async (req, res) => {
 
   try {
     const normalizedCode = ensureWhatsAppFormat(code);
-    const lastMessage = await Message.findOne({
-      $or: [{ numero: normalizedCode }, { group_id: normalizedCode }]
-    }).sort({ createdAt: -1 });
+    const [lastMessage] = await getMessages(
+      { $or: [{ numero: normalizedCode }, { group_id: normalizedCode }] },
+      { sort: { createdAt: -1 }, limit: 1 }
+    );
 
     if (!lastMessage) {
       return res.status(404).json({ success: false, error: 'No messages found' });
@@ -259,7 +260,7 @@ const checkMessageStatusController = async (req, res) => {
   }
 
   try {
-    const msg = await Message.findOne({ content_sid: contentSid, numero: ensureWhatsAppFormat(code) });
+    const [msg] = await getMessages({ content_sid: contentSid, numero: ensureWhatsAppFormat(code) }, { limit: 1 });
     if (!msg) {
       return res.status(404).json({ success: false, error: 'Message not found' });
     }

package/lib/controllers/qualityMessageController.js

@@ -1,7 +1,8 @@
 const { logger } = require('../utils/logger');
 
 const { getQualityMessage } = require('../models/qualityMessageModel');
-const { Message } = require('../models/messageModel');
+
+const { getMessages } = require('../services/messageService');
 
 const VALID_QUALITIES = ['low', 'medium', 'high'];
 
@@ -15,7 +16,7 @@ const addQualityVoteController = async (req, res) => {
       return res.status(400).json({ success: false, error: 'Quality must be low, medium, or high' });
     }
 
-    const message = await Message.findById(message_id);
+    const [message] = await getMessages({ _id: message_id }, { limit: 1 });
     if (!message) return res.status(404).json({ success: false, error: 'Message not found' });
 
     const qualityVote = await getQualityMessage().findOneAndUpdate(

package/lib/core/AssistantProcessor.js

@@ -4,8 +4,8 @@ const { runAssistantWithRetries } = require('../helpers/assistantHelper');
 const { getAssistantById } = require('../services/assistantResolver');
 
 class AssistantProcessor {
-  constructor({ mode = 'local', queueAdapter = null, sendMessage = null, storeRunMetrics = null }) {
-    Object.assign(this, { mode, queueAdapter, sendMessage, storeRunMetrics });
+  constructor({ mode = 'local', queueAdapter = null, sendMessage = null, phiProcessor = null, storeRunMetrics = null }) {
+    Object.assign(this, { mode, queueAdapter, sendMessage, phiProcessor, storeRunMetrics });
     if (mode === 'queue' && queueAdapter) {
       queueAdapter.process('assistant.process', (payload) => this._executeLocal(payload));
     }
@@ -22,7 +22,7 @@ class AssistantProcessor {
 
   async executeLLM(thread, assistant, runOptions = {}, messages = null) {
     const startTime = Date.now();
-    const runResult = await runAssistantWithRetries(thread, assistant, runOptions, messages);
+    const runResult = await runAssistantWithRetries(thread, assistant, { ...runOptions, phiProcessor: this.phiProcessor }, messages);
     const predictionTimeMs = Date.now() - startTime;
 
     const output = sanitizeOutput(runResult?.output);

package/lib/core/BatchingManager.js

@@ -1,5 +1,6 @@
 const { logger } = require('../utils/logger');
-const { Message } = require('../models/messageModel');
+
+const { getMessages } = require('../services/messageService');
 
 class BatchingManager {
   constructor({ provider = null, config = {} }) {
@@ -115,10 +116,10 @@ class BatchingManager {
   async _startTypingRefresh(chatId, runId) {
     if (!this.config.typingIndicator || !this.provider?.sendTypingIndicator) return;
 
-    const lastMessage = await Message.findOne({
-      numero: chatId, from_me: false, processed: false,
-      message_id: { $exists: true, $ne: null, $not: /^pending-/ }
-    }).sort({ createdAt: -1 });
+    const [lastMessage] = await getMessages(
+      { numero: chatId, from_me: false, processed: false, message_id: { $exists: true, $ne: null, $not: /^pending-/ } },
+      { sort: { createdAt: -1 }, limit: 1 }
+    );
 
     if (!lastMessage?.message_id || this.activeRequests.get(chatId) !== runId) return;