@peopl-health/nexus 4.4.4 → 4.5.21

package/lib/core/NexusMessaging.js

@@ -3,10 +3,11 @@ const EventEmitter = require('events');
 const { airtable } = require('../config/airtableConfig');
 const llmConfigModule = require('../config/llmConfig');
 const { connect } = require('../config/mongoConfig');
+const { setMetaConfig } = require('../config/metaConfig');
 
 const { logger } = require('../utils/logger');
 
-const { Message, insertMessage } = require('../models/messageModel');
+const { Message } = require('../models/messageModel');
 const { Thread } = require('../models/threadModel');
 
 const { ensureThreadExists } = require('../helpers/threadHelper');
@@ -18,6 +19,7 @@ const { createMessagingProvider } = require('../adapters/registry');
 
 const { preProcessMessages } = require('../services/assistantService');
 const { hasPreprocessingHandler, invokePreprocessingHandler } = require('../services/preprocessingService');
+const { getMessages, updateMessage } = require('../services/messageService');
 
 const { BatchingManager } = require('../core/BatchingManager');
 const { ProcessingPipeline } = require('../core/ProcessingPipeline');
@@ -27,6 +29,8 @@ const { createQueueAdapter } = require('../queue');
 const { ScheduledMessageJob } = require('../jobs/ScheduledMessageJob');
 const { TemplateApprovalJob } = require('../jobs/TemplateApprovalJob');
 
+const { PhiProcessor } = require('./PhiProcessor');
+
 /**
  * Core messaging orchestrator for providers, storage, and assistant processing.
  */
@@ -47,15 +51,6 @@ class NexusMessaging {
       onFlow: null
     };
     this.events = new EventEmitter();
-    this.middleware = {
-      any: [],
-      message: [],
-      interactive: [],
-      media: [],
-      command: [],
-      keyword: [],
-      flow: []
-    };
 
     this.batchingConfig = {
       enabled: config.messageBatching?.enabled ?? true,
@@ -75,17 +70,23 @@ class NexusMessaging {
     const queueConfig = config.queue?.config || {};
     this.queueAdapter = createQueueAdapter(queueType, queueConfig);
 
+    this.phiProcessor = new PhiProcessor({
+      encode: config.phi?.encode || false,
+      ner: config.phi?.ner || null,
+      hashSecret: config.phi?.hashSecret || null,
+    });
+
     this.assistantProcessor = new AssistantProcessor({
       mode: config.assistant?.mode || 'local',
       queueAdapter: this.queueAdapter,
-      sendMessage: this.sendMessage.bind(this),
+      sendMessage: this.sendAssistantReply.bind(this),
+      phiProcessor: this.phiProcessor,
       storeRunMetrics,
     });
 
     this.scheduledMessageJob = new ScheduledMessageJob({
       queueAdapter: this.queueAdapter,
       sendMessage: this.sendMessage.bind(this),
-      requireMessageStorage: () => this.messageStorage,
       requireProvider: () => this.getProvider()
     });
 
@@ -98,10 +99,45 @@ class NexusMessaging {
         return provider;
       }
     });
+
+    this._providerStores = false;
+    this._saveFn = null;
+    this._saveMessageFn = async () => null;
+  }
+
+  _selectSaveFn(providerStores) {
+    if (!this.messageStorage) return null;
+    if (providerStores && this.messageStorage.savePendingMessage) {
+      return this.messageStorage.savePendingMessage.bind(this.messageStorage);
+    }
+    if (!providerStores && this.messageStorage.saveMessage) {
+      return this.messageStorage.saveMessage.bind(this.messageStorage);
+    }
+    return null;
+  }
+
+  async _transport(messageData) {
+    if (messageData.contentSid && !messageData.body && this.provider.renderTemplate) {
+      const rendered = await this.provider.renderTemplate(messageData.contentSid, messageData.variables);
+      if (rendered) messageData = { ...messageData, body: rendered };
+    }
+
+    const result = await this.provider.sendMessage(messageData);
+
+    if (messageData.parentMessageId && result?.finalize && this.messageStorage?.finalizePendingMessage) {
+      await this.messageStorage.finalizePendingMessage(messageData.parentMessageId, result.finalize.sid, {
+        status: result.finalize.status,
+        updatedAt: new Date()
+      });
+    }
+
+    if (messageData.code) ensureThreadExists(messageData.code);
+
+    return result;
   }
 
   async initialize(options = {}) {
-    const { provider, providerConfig, mongoUri, messageStorage, llm, llmConfig } = options;
+    const { provider, providerConfig, mongoUri, messageStorage, llm, llmConfig, meta } = options;
 
     if (mongoUri || process.env.MONGODB_URI) {
       await this.initializeMongoDB(mongoUri);
@@ -112,6 +148,9 @@ class NexusMessaging {
     if (llm && llmConfig) {
       this.initializeLLM(llm, llmConfig);
     }
+    if (meta) {
+      setMetaConfig(meta);
+    }
     if (messageStorage) {
       this.setMessageStorage(messageStorage);
     }
@@ -157,6 +196,9 @@ class NexusMessaging {
     if (this.provider && typeof this.provider.setMessageStorage === 'function') {
       this.provider.setMessageStorage(storage);
     }
+    this._providerStores = this.provider?.supportsMessageStorage?.() ?? false;
+    this._saveFn = this._selectSaveFn(this._providerStores);
+    this._saveMessageFn = this.messageStorage ? (msg) => this.messageStorage.saveMessage(msg) : async () => null;
   }
 
   setHandlers(handlers) {
@@ -181,54 +223,10 @@ class NexusMessaging {
   getPipeline() { return this.pipeline; }
   getAssistantProcessor() { return this.assistantProcessor; }
   getQueueAdapter() { return this.queueAdapter; }
+  getPhiProcessor() { return this.phiProcessor; }
   isConnected() { return this.provider?.getConnectionStatus() ?? false; }
   isProcessing(chatId) { return this.batchingManager.isProcessing(chatId); }
 
-  /*
-   * MIDDLEWARE
-   */
-
-  use(typeOrFn, maybeFn) {
-    if (typeof typeOrFn === 'function') {
-      this.middleware.any.push(typeOrFn);
-      return this;
-    }
-    const type = String(typeOrFn || '').toLowerCase();
-    if (!this.middleware[type]) this.middleware[type] = [];
-    this.middleware[type].push(maybeFn);
-    return this;
-  }
-
-  async _runPipeline(type, messageData, finalHandler) {
-    const chain = [
-      ...(this.middleware.any || []),
-      ...(this.middleware[type] || []),
-      async (ctx) => await 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);
-  }
-
-  async _handleWithPipeline(type, handlerKey, messageData, fallback) {
-    const result = await this._runPipeline(type, messageData, async (ctx) => {
-      const handler = this.handlers[handlerKey];
-      if (handler) {
-        return await handler(ctx, this);
-      }
-      if (fallback) {
-        return await fallback(ctx);
-      }
-    });
-    return result;
-  }
-
   /*
    * OUTBOUND MESSAGING
    */
@@ -238,62 +236,96 @@ class NexusMessaging {
 
     if (messageData._fromConversationReply) messageData.processed = true;
 
-    if (messageData.contentSid && !messageData.body && this.provider.renderTemplate) {
-      const rendered = await this.provider.renderTemplate(messageData.contentSid, messageData.variables);
-      if (rendered) messageData.body = rendered;
-    }
-
     if (this._needsTemplateRoute(messageData) && !(await isWithin24HourWindow(messageData.code))) {
-      const parent = messageData.parentMessageId
-        ? await Message.findById(messageData.parentMessageId)
-        : await this.messageStorage.savePendingMessage({
+      if (messageData.parentMessageId) {
+        const [found] = await getMessages({ _id: messageData.parentMessageId }, { limit: 1 });
+        if (!found) return { success: false, delivered: false, deferred: true };
+        await triggerTemplateRecovery(found, { source: 'preemptive' });
+        return { success: true, messageId: String(found._id), status: 'queued', preemptive: true, delivered: false, deferred: true };
+      }
+      const saveFn = this.messageStorage.savePendingMessage.bind(this.messageStorage);
+      return this.phiProcessor.outDataFromPlain(
+        {
           ...messageData,
-          provider: 'twilio', fromMe: true,
-          processed: messageData.processed ?? false
+          provider: 'twilio',
+          fromMe: true,
+          processed: messageData.processed ?? false,
+        },
+        saveFn,
+        async ({ body, _id }) => {
+          await triggerTemplateRecovery({ _id, body, numero: messageData.code }, { source: 'preemptive' });
+          return { success: true, messageId: String(_id), status: 'queued', preemptive: true, delivered: false, deferred: true };
+        },
+        { onSaved: messageData.onParentMessageId },
+      );
+    }
+
+    if (messageData.parentMessageId) {
+      return this._transport(messageData);
+    }
+
+    if (!this._providerStores) {
+      const encodedBody = await this.phiProcessor.encodeBody(messageData.body, messageData.code);
+      const result = await this._transport(messageData);
+      if (this.messageStorage?.saveMessage) {
+        await this.messageStorage.saveMessage({
+          ...messageData, body: encodedBody,
+          messageId: result?.messageId, provider: result?.provider,
+          fromMe: true, processed: true,
         });
-      await triggerTemplateRecovery(parent, { source: 'preemptive' });
-      return { success: true, messageId: String(parent._id), status: 'queued', preemptive: true };
+      }
+      return result;
     }
 
-    const providerStores = this.provider.supportsMessageStorage?.() ?? false;
-    let parentId = messageData.parentMessageId || null;
-    if (!parentId && providerStores && this.messageStorage?.savePendingMessage) {
-      const pending = await this.messageStorage.savePendingMessage({
-        ...messageData,
-        provider: 'twilio',
-        fromMe: true,
-        processed: messageData.processed ?? false
-      });
-      parentId = pending?._id || null;
+    const saveFn = this._saveFn;
+
+    if (!saveFn) {
+      return this._transport(messageData);
     }
 
-    const result = await this.provider.sendMessage({ ...messageData, parentMessageId: parentId });
+    return this.phiProcessor.outDataFromPlain(
+      { ...messageData, provider: 'twilio', fromMe: true, processed: messageData.processed ?? false },
+      saveFn,
+      ({ body, _id }) => this._transport({ ...messageData, body, parentMessageId: _id }),
+      { onSaved: messageData.onParentMessageId },
+    );
+  }
 
-    if (parentId && result?.finalize && this.messageStorage?.finalizePendingMessage) {
-      await this.messageStorage.finalizePendingMessage(parentId, result.finalize.sid, {
-        status: result.finalize.status,
-        updatedAt: new Date()
-      });
+  async sendAssistantReply(messageData) {
+    if (!this.provider) throw new Error('No provider initialized');
+
+    if (messageData.parentMessageId) {
+      return this._transport(messageData);
     }
 
-    if (this.messageStorage && !providerStores) {
-      await this.messageStorage.saveMessage({
-        ...messageData,
-        messageId: result.messageId,
-        provider: result.provider,
-        fromMe: true,
-        processed: true
-      });
+    if (!this._providerStores) {
+      const decodedBody = await this.phiProcessor.decodeBody(messageData.body, messageData.code);
+      const result = await this._transport({ ...messageData, body: decodedBody });
+      if (this.messageStorage?.saveMessage) {
+        await this.messageStorage.saveMessage({
+          ...messageData,
+          messageId: result?.messageId, provider: result?.provider,
+          fromMe: true, processed: true, origin: messageData.origin || 'assistant',
+        });
+      }
+      return result;
     }
 
-    const chatId = messageData.code;
-    if (chatId) ensureThreadExists(chatId);
+    const saveFn = this._saveFn;
 
-    return result;
+    if (!saveFn) {
+      return this._transport(messageData);
+    }
+
+    return this.phiProcessor.outDataFromEncoded(
+      { ...messageData, fromMe: true, processed: true, origin: messageData.origin || 'assistant' },
+      saveFn,
+      ({ body, _id }) => this._transport({ ...messageData, body, parentMessageId: _id }),
+    );
   }
 
   _needsTemplateRoute(messageData) {
-    if (this.provider?.supportsMessageStorage?.() !== true) return false;
+    if (!this._providerStores) return false;
     if (messageData.contentSid) return false;
     if (!messageData.code) return false;
     return true;
@@ -306,10 +338,11 @@ class NexusMessaging {
     if (!scheduledMessage?.sendTime) {
       throw new Error('sendScheduledMessage requires sendTime');
     }
-    return await this.scheduledMessageJob.schedule({
+    const job = await this.scheduledMessageJob.schedule({
       scheduledMessageId: scheduledMessage._id,
       sendTime: scheduledMessage.sendTime
     });
+    return { ...(job || {}), delivered: false, deferred: true };
   }
 
   async scheduleTemplateApproval({ templateSid, messageId, originalMessageSid = null, attempt = 0 }) {
@@ -326,8 +359,6 @@ class NexusMessaging {
    */
 
   async processIncomingMessage(messageData) {
-    if (this.messageStorage) await this.messageStorage.saveMessage(messageData);
-
     const chatId = messageData.code;
 
     if (chatId) {
@@ -339,41 +370,52 @@ class NexusMessaging {
       }
     }
 
-    if (chatId && hasPreprocessingHandler()) {
-      const stop = await invokePreprocessingHandler({ code: chatId, context: 'incomingMessage', message: messageData });
-      if (stop) return;
-    }
-
-    if (messageData.interactive) return this.handleInteractive(messageData);
-    if (messageData.command) return this.handleCommand(messageData);
-    if (messageData.keyword) return this.handleKeyword(messageData);
-    if (messageData.flow) return this.handleFlow(messageData);
-
-    if (this.batchingConfig.enabled && chatId) {
-      return this._handleWithCheckAfter(chatId);
-    }
-    return messageData.media ? this.handleMedia(messageData) : this.handleMessage(messageData);
+    return this.phiProcessor.inData(
+      messageData,
+      this._saveMessageFn,
+      async ({ body }) => {
+        messageData = { ...messageData, body };
+        if (chatId && hasPreprocessingHandler()) {
+          const stop = await invokePreprocessingHandler({ code: chatId, context: 'incomingMessage', message: messageData });
+          if (stop) return;
+        }
+
+        if (messageData.interactive) return this.handleInteractive(messageData);
+        if (messageData.command) return this.handleCommand(messageData);
+        if (messageData.keyword) return this.handleKeyword(messageData);
+        if (messageData.flow) return this.handleFlow(messageData);
+
+        if (this.batchingConfig.enabled && chatId) return this._handleWithCheckAfter(chatId);
+        return messageData.media ? this.handleMedia(messageData) : this.handleMessage(messageData);
+      },
+    );
   }
 
   async handleMessage(messageData) {
-    return await this._handleWithPipeline('message', 'onMessage', messageData, async (ctx) => {
-      return await this.handleMessageWithAssistant(ctx);
-    });
+    if (this.handlers.onMessage) return await this.handlers.onMessage(messageData, this);
+    return await this.handleMessageWithAssistant(messageData);
   }
 
   async handleInteractive(messageData) {
-    return this._handleWithPipeline('interactive', 'onInteractive', messageData);
+    if (this.handlers.onInteractive) return await this.handlers.onInteractive(messageData, this);
   }
 
   async handleMedia(messageData) {
-    return await this._handleWithPipeline('media', 'onMedia', messageData, async (ctx) => {
-      return await this.handleMediaWithAssistant(ctx);
-    });
+    if (this.handlers.onMedia) return await this.handlers.onMedia(messageData, this);
+    return await this.handleMediaWithAssistant(messageData);
   }
 
-  async handleCommand(messageData) { return this._handleWithPipeline('command', 'onCommand', messageData); }
-  async handleKeyword(messageData) { return this._handleWithPipeline('keyword', 'onKeyword', messageData); }
-  async handleFlow(messageData) { return this._handleWithPipeline('flow', 'onFlow', messageData); }
+  async handleCommand(messageData) {
+    if (this.handlers.onCommand) return await this.handlers.onCommand(messageData, this);
+  }
+
+  async handleKeyword(messageData) {
+    if (this.handlers.onKeyword) return await this.handlers.onKeyword(messageData, this);
+  }
+
+  async handleFlow(messageData) {
+    if (this.handlers.onFlow) return await this.handlers.onFlow(messageData, this);
+  }
 
   /*
    * ASSISTANT INTEGRATION
@@ -444,6 +486,22 @@ class NexusMessaging {
           if (!resolved) return null;
 
           const preProcessed = await preProcessMessages(chatId, null, resolved.thread);
+
+          await Promise.all((preProcessed.pendingMediaUpdates ?? []).map(u =>
+            this.phiProcessor.inData(
+              { body: u.processedContent, code: chatId },
+              ({ body: encoded }) => updateMessage(
+                { message_id: u.message_id },
+                { $set: {
+                  assistant_id: u.assistantId,
+                  thread_id: u.threadId,
+                  'media.metadata.processedContent': encoded,
+                }}
+              ),
+              () => null,
+            )
+          ));
+
           if (!preProcessed.shouldProcess) return null;
 
           const result = await this.assistantProcessor.executeLLM(
@@ -461,55 +519,69 @@ class NexusMessaging {
 
   async processInstruction(code, instruction, role = 'developer', { triggeredBy } = {}) {
     const assistantId = await this._getThreadAssistantId(code);
-    await insertMessage({
-      nombre_whatsapp: 'Instruction',
-      numero: code,
+    const messageData = {
+      pushName: 'Instruction',
+      code,
       body: instruction,
-      message_id: `instruction_${Date.now()}_${Math.random().toString(36).substring(7)}`,
-      from_me: true,
+      messageId: `instruction_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+      fromMe: true,
       processed: true,
       origin: 'instruction',
-      assistant_id: assistantId,
+      assistantId,
       raw: { role },
-      triggeredBy: triggeredBy || null
-    });
+      triggeredBy: triggeredBy || null,
+      silent: true,
+    };
 
-    const result = await this._executeWithPipeline(code, 'instruction', 'queue',
-      async (preProcessResult) => {
-        return await this.assistantProcessor.process({
+    const result = await this.phiProcessor.inData(
+      messageData,
+      this._saveMessageFn,
+      ({ body }) => this._executeWithPipeline(code, 'instruction', 'queue',
+        async (preProcessResult) => this.assistantProcessor.process({
           code,
           runOptions: {
             prePromptResult: preProcessResult,
-            additionalInstructions: instruction,
-            additionalMessages: [{ role, content: instruction }],
+            additionalInstructions: body,
+            additionalMessages: [{ role, content: body }],
             toolChoice: 'none',
           }
-        });
-      }
+        }),
+      ),
     );
 
     return result?.output || null;
   }
 
-  async processSystemMessage(code, messages, role = 'system', { triggeredBy } = {}) {
-    const normalizedMessages = Array.isArray(messages) ? messages : [messages];
+  async processSystemMessage(code, messages, role = 'system', { triggeredBy, reply = true } = {}) {
+    const thread = await Thread.findOne({ code }).lean();
+    if (!thread) return null;
+
     const assistantId = await this._getThreadAssistantId(code);
+    const normalizedMessages = Array.isArray(messages) ? messages : [messages];
 
     for (let i = 0; i < normalizedMessages.length; i++) {
-      await insertMessage({
-        nombre_whatsapp: 'System',
-        numero: code,
-        body: normalizedMessages[i],
-        message_id: `system_${Date.now()}_${i}_${Math.random().toString(36).substring(7)}`,
-        from_me: true,
-        processed: true,
-        origin: 'system',
-        assistant_id: assistantId,
-        raw: { role },
-        triggeredBy: triggeredBy || null
-      });
+      try {
+        const messageData = {
+          pushName: 'System',
+          code,
+          body: normalizedMessages[i],
+          messageId: `system_${Date.now()}_${i}_${Math.random().toString(36).substring(7)}`,
+          fromMe: true,
+          processed: true,
+          origin: 'system',
+          assistantId,
+          raw: { role },
+          triggeredBy: triggeredBy || null,
+          silent: true,
+        };
+        await this.phiProcessor.inData(messageData, this._saveMessageFn, () => {});
+      } catch (err) {
+        logger.error('[processSystemMessage] Error saving system message', { error: err.message, code, index: i });
+      }
     }
 
+    if (!reply) return null;
+
     const result = await this._executeWithPipeline(code, 'system', 'queue',
       async (preProcessResult) => {
         return await this.assistantProcessor.process({
@@ -532,7 +604,7 @@ class NexusMessaging {
 
   async _processMessages(chatId, processingFn, shouldFinalize = () => true) {
     const query = { numero: chatId, from_me: false, processed: false };
-    const unprocessed = await Message.find(query).select('_id');
+    const unprocessed = await getMessages(query, { select: '_id' });
 
     try {
       const result = await processingFn();
@@ -618,6 +690,8 @@ const processSystemMessage = async (code, messages, role, options) => {
 
 const getEventBus = () => getDefaultInstance()?.getEventBus();
 
+const getPhiProcessor = () => getDefaultInstance()?.getPhiProcessor();
+
 const _resetDefaultInstance = () => { defaultInstance = null; };
 
 module.exports = {
@@ -631,6 +705,7 @@ module.exports = {
   getDefaultInstance,
   requireDefaultInstance,
   getProvider,
+  getPhiProcessor,
   requireProvider,
   getEventBus,
   _resetDefaultInstance

package/lib/core/PhiProcessor.js

@@ -0,0 +1,113 @@
+const { createHmac } = require('crypto');
+
+const { logger } = require('../utils/logger');
+
+const { PHI_CATEGORIES } = require('../models/tokenMapModel');
+
+const { NerClient } = require('../providers/NerClient');
+
+const tokenMapService = require('../services/tokenMapService');
+
+const { lookupGlobal, lookupGlobalToken } = require('../services/globalEntityService');
+
+const TOKEN_REGEX = /<<[A-Z_]+_\d+>>/g;
+
+class PhiProcessor {
+  constructor({ encode = false, ner, hashSecret } = {}) {
+    this._nerClient = null;
+    this._hashSecret = hashSecret || null;
+    this._phiEnabled = !!encode;
+    if (!encode) return;
+    if (!ner) {
+      logger.error('[PhiProcessor] PHI encoding enabled but no NER config provided — body will be stored as plain text');
+      return;
+    }
+    this._setNerClient(ner);
+  }
+
+  _setNerClient(nerConfig) {
+    if (!nerConfig) { this._nerClient = null; return; }
+    this._nerClient = typeof nerConfig.detectEntities === 'function' ? nerConfig : new NerClient(nerConfig);
+  }
+
+  hashCode(code) {
+    if (!code) return null;
+    if (!this._phiEnabled) return code;
+    if (!this._hashSecret) {
+      logger.warn('[PhiProcessor] PHI hash secret not configured — numero omitted from metadata');
+      return null;
+    }
+    return createHmac('sha256', this._hashSecret).update(code).digest('hex');
+  }
+
+  async encodeBody(body, numero) {
+    if (!body || !numero || !this._nerClient) return body;
+
+    const entities = await this._nerClient.detectEntities(body);
+    if (!entities?.length) return body;
+
+    const sorted = [...entities].sort((a, b) => b.start - a.start);
+
+    let encoded = body;
+    for (const entity of sorted) {
+      if (!PHI_CATEGORIES.includes(entity.label)) {
+        logger.debug('[PhiProcessor] Unknown label, skipping', { label: entity.label });
+        continue;
+      }
+
+      const plaintext = entity.plaintext || encoded.slice(entity.start, entity.end);
+      const global = await lookupGlobal(plaintext);
+      const token = global
+        ? global.token
+        : await tokenMapService.encode(numero, plaintext, entity.label);
+
+      encoded = encoded.slice(0, entity.start) + token + encoded.slice(entity.end);
+    }
+
+    logger.debug('[PhiProcessor] Body encoded', { numero, entityCount: entities.length });
+    return encoded;
+  }
+
+  async inData(messageData, saveFn, handler) {
+    const encoded = await this.encodeBody(messageData.body, messageData.code);
+    const saved = await saveFn({ ...messageData, body: encoded });
+    return handler({ body: encoded, _id: saved?._id });
+  }
+
+  async outDataFromPlain(messageData, saveFn, handler, { onSaved } = {}) {
+    const encoded = await this.encodeBody(messageData.body, messageData.code);
+    const saved = await saveFn({ ...messageData, body: encoded });
+    await onSaved?.(saved?._id);
+    return handler({ body: messageData.body, _id: saved?._id });
+  }
+
+  async decodeBody(body, numero) {
+    if (!body || !numero) return body;
+    const tokens = body.match(TOKEN_REGEX);
+    if (!tokens) return body;
+    let decoded = body;
+    try {
+      for (const token of new Set(tokens)) {
+        const globalPlain = await lookupGlobalToken(token);
+        const plaintext = globalPlain ?? await tokenMapService.decode(numero, token);
+        if (plaintext && plaintext !== token) decoded = decoded.replaceAll(token, plaintext);
+      }
+    } catch (e) {
+      logger.error('[PhiProcessor] decodeBody failed, returning encoded body', { numero, error: e.message });
+      return body;
+    }
+    return decoded;
+  }
+
+  async outDataFromEncoded(messageData, saveFn, handler) {
+    const saved = await saveFn(messageData);
+    const decodedBody = this._phiEnabled
+      ? await this.decodeBody(messageData.body, messageData.code)
+      : messageData.body;
+    return handler({ body: decodedBody, _id: saved?._id });
+  }
+}
+
+module.exports = {
+  PhiProcessor,
+};