@peopl-health/nexus 5.10.0-dev.1114 → 5.10.1

package/lib/clinical/providers/BaseLLMProvider.js

@@ -62,8 +62,7 @@ class BaseLLMProvider {
 
     const resolvedSchemas = this._resolveToolSchemas({ assistant, toolIds, filtered, toolDescriptions });
     const { toolChoice: flooredToolChoice, toolSchemas, narrowed } = this._applyDeliveryFloor(
-      toolChoice, resolvedSchemas, prePromptResult?.toolChoice,
-      Boolean(additionalInstructions && assistant?.toolRuntimeContext));
+      toolChoice, resolvedSchemas, Boolean(assistant?.toolRuntimeContext));
     const effectiveToolIds = narrowed ? toolSchemas.map(s => s.function?.name).filter(Boolean) : toolIds;
     const devContent = this._buildInstructions({ resolvedPrompt, toolSchemas, prePromptResult });
     const auditedPrompt = additionalInstructions
@@ -94,7 +93,7 @@ class BaseLLMProvider {
       instructions: instructions || devContent || '',
       input,
       toolSchemas,
-      toolChoice: prePromptResult?.toolChoice || flooredToolChoice,
+      toolChoice: narrowed ? flooredToolChoice : prePromptResult?.toolChoice || flooredToolChoice,
       followUpToolChoice: flooredToolChoice,
       modelConfig,
       metadata,
@@ -372,11 +371,9 @@ class BaseLLMProvider {
     return toolNames.length > 0 && toolNames.every(name => TERMINAL_DELIVERY_TOOLS.has(name));
   }
 
-  _applyDeliveryFloor(toolChoice, toolSchemas, prePromptToolChoice = null, isClinicalDirective = false) {
-    if (prePromptToolChoice) return { toolChoice, toolSchemas, narrowed: false };
+  _applyDeliveryFloor(toolChoice, toolSchemas, hasToolRuntimeContext = false) {
     if (toolChoice !== 'none') return { toolChoice, toolSchemas, narrowed: false };
-    // A directive dictates the message, not the turn's capabilities, so a clinical turn keeps its toolset.
-    if (isClinicalDirective) return { toolChoice: 'auto', toolSchemas, narrowed: false };
+    if (!hasToolRuntimeContext) return { toolChoice, toolSchemas, narrowed: false };
     const deliveryOnly = toolSchemas.filter(s => TERMINAL_DELIVERY_TOOLS.has(s.function?.name));
     if (!deliveryOnly.length) return { toolChoice, toolSchemas, narrowed: false };
     return { toolChoice: 'auto', toolSchemas: deliveryOnly, narrowed: true };

package/lib/core/NexusMessaging.js

@@ -255,7 +255,7 @@ class NexusMessaging {
         },
         saveFn,
         async ({ body, _id }) => {
-          await triggerTemplateRecovery({ _id, body, numero: messageData.code }, { source: 'preemptive' });
+          await triggerTemplateRecovery({ _id, body, numero: messageData.code, media: messageData.media }, { source: 'preemptive' });
           return { success: true, messageId: String(_id), status: 'queued', preemptive: true, delivered: false, deferred: true };
         },
         { onSaved: messageData.onParentMessageId },

package/lib/helpers/messageStatusHelper.js

@@ -6,7 +6,7 @@ const { createEvent, safeEmit } = require('../utils/eventUtils');
 const { Message } = require('../models/messageModel');
 const { DeliveryAttempt, DELIVERY_ATTEMPT_TERMINAL_STATUSES } = require('../models/deliveryAttemptModel');
 
-const { handle24HourWindowError } = require('../helpers/templateRecoveryHelper');
+const { handle24HourWindowError, cleanupRecoveryTemplate } = require('../helpers/templateRecoveryHelper');
 const { updateDeliveryAttemptByTwilioSid } = require('../helpers/deliveryAttemptHelper');
 
 const { addLinkedRecord, updateRecordByFilter } = require('../services/airtableService');
@@ -105,11 +105,19 @@ async function handleStatusCallback(twilioStatusData, { eventBus } = {}) {
   }
 
   if ((ErrorCode === 63016 || ErrorCode === '63016') && updated) {
-    handle24HourWindowError(updated, MessageSid).catch(err => 
+    handle24HourWindowError(updated, MessageSid).catch(err =>
       logger.error('[MessageStatus] Recovery error', { messageSid: MessageSid, error: err.message })
     );
   }
 
+  const deliveryStatus = MessageStatus.toLowerCase();
+  if (updated?.statusInfo?.recoverySentAt && updated?.statusInfo?.recoveryTemplateSid &&
+      (deliveryStatus === 'sent' || deliveryStatus === 'delivered' || deliveryStatus === 'read')) {
+    cleanupRecoveryTemplate(updated).catch(err =>
+      logger.warn('[MessageStatus] Recovery template cleanup failed', { messageSid: MessageSid, error: err.message })
+    );
+  }
+
   return updated;
 }
 

package/lib/helpers/templateRecoveryHelper.js

@@ -1,3 +1,4 @@
+const { generatePresignedUrl } = require('../config/awsConfig');
 const { logger } = require('../utils/logger');
 const { Message } = require('../models/messageModel');
 const TemplateModel = require('../models/templateModel');
@@ -7,6 +8,17 @@ const { recordDeliveryAttempt } = require('./deliveryAttemptHelper');
 const getMessaging = () => require('../core/NexusMessaging');
 
 const TEMPLATE_BODY_LIMIT = 1024;
+const RECOVERY_MEDIA_URL_TTL_SECONDS = 7 * 24 * 60 * 60;
+
+async function resolveRecoveryMediaUrl(media) {
+  if (!media?.bucketName || !media?.key) return null;
+  try {
+    return await generatePresignedUrl(media.bucketName, media.key, RECOVERY_MEDIA_URL_TTL_SECONDS);
+  } catch (error) {
+    logger.warn('[TemplateRecovery] Could not presign media; sending text-only', { error: error.message });
+    return null;
+  }
+}
 
 async function triggerTemplateRecovery(messageDoc, { source = 'reactive', messageSid = null } = {}) {
   try {
@@ -45,6 +57,9 @@ async function triggerTemplateRecovery(messageDoc, { source = 'reactive', messag
     const template = new Template(templateName, 'UTILITY', 'es');
     template.setBody(messageDoc.body, []);
 
+    const mediaUrl = await resolveRecoveryMediaUrl(messageDoc.media);
+    if (mediaUrl) template.setMedia(mediaUrl);
+
     let twilioContent;
     let setupErr = null;
     if (messageDoc.body.length > TEMPLATE_BODY_LIMIT) {
@@ -96,7 +111,7 @@ async function triggerTemplateRecovery(messageDoc, { source = 'reactive', messag
       { $set: { 'statusInfo.recoveryTemplateSid': twilioContent.sid } }
     );
 
-    logger.info('[TemplateRecovery] Template created', { ...logCtx, templateSid: twilioContent.sid });
+    logger.info('[TemplateRecovery] Template created', { ...logCtx, templateSid: twilioContent.sid, hasMedia: !!mediaUrl });
 
     await scheduleTemplateApproval({
       templateSid: twilioContent.sid,
@@ -114,4 +129,23 @@ async function handle24HourWindowError(message, messageSid) {
   return triggerTemplateRecovery(message, { source: 'reactive', messageSid });
 }
 
-module.exports = { handle24HourWindowError, triggerTemplateRecovery };
+async function cleanupRecoveryTemplate(messageDoc) {
+  const templateSid = messageDoc?.statusInfo?.recoveryTemplateSid;
+  if (!templateSid || !messageDoc?._id) return;
+
+  const claim = await Message.updateOne(
+    { _id: messageDoc._id, 'statusInfo.recoveryTemplateSid': templateSid },
+    { $unset: { 'statusInfo.recoveryTemplateSid': '' } }
+  );
+  if (!claim.modifiedCount && !claim.nModified) return;
+
+  try {
+    const provider = getMessaging().requireProvider();
+    await provider.deleteTemplate(templateSid);
+    logger.info('[TemplateRecovery] Template deleted after delivery', { messageDocId: String(messageDoc._id), templateSid });
+  } catch (error) {
+    logger.warn('[TemplateRecovery] Failed to delete template after delivery', { templateSid, error: error.message });
+  }
+}
+
+module.exports = { handle24HourWindowError, triggerTemplateRecovery, cleanupRecoveryTemplate };

package/lib/jobs/TemplateApprovalJob.js

@@ -84,7 +84,7 @@ class TemplateApprovalJob extends BaseJob {
     logger.info('[TemplateApprovalJob] Approval status', { templateSid, approvalStatus, attempt, messageId, originalMessageSid });
 
     if (approvalStatus === 'APPROVED') {
-      return await this._handleApproved({ provider, message, templateSid, originalMessageSid });
+      return await this._handleApproved({ message, templateSid, originalMessageSid });
     }
     if (approvalStatus === 'REJECTED') {
       return await this._handleRejected({ provider, message, templateSid });
@@ -109,7 +109,7 @@ class TemplateApprovalJob extends BaseJob {
     return { success: false, reason, nextAttempt };
   }
 
-  async _handleApproved({ provider, message, templateSid, originalMessageSid }) {
+  async _handleApproved({ message, templateSid, originalMessageSid }) {
     const claim = await Message.updateOne(
       { _id: message._id, 'statusInfo.recoverySentAt': null },
       { $set: { 'statusInfo.recoverySentAt': new Date() } }
@@ -148,10 +148,6 @@ class TemplateApprovalJob extends BaseJob {
       { $set: { status: 'sent', completedAt: new Date() } }
     );
 
-    provider.deleteTemplate(templateSid).catch((deleteErr) =>
-      logger.warn('[TemplateApprovalJob] Failed to delete template after send', { templateSid, error: deleteErr.message })
-    );
-
     return { success: true, recoveryMessageId: sendResult.messageId };
   }
 

package/lib/templates/templateStructure.js

@@ -14,7 +14,8 @@ class Template {
       buttons: []
     };
     this.variables = [];
-        
+    this.media = null;
+
     const uniqueId = `${Date.now()}_${uuidv4().substring(0, 6)}`;
     this.friendlyName = `${name}_${uniqueId}`;
     this.templateName = this.friendlyName;
@@ -45,6 +46,11 @@ class Template {
     return this;
   }
 
+  setMedia(url) {
+    this.media = url;
+    return this;
+  }
+
   addQuickReply(text) {
     if (this.components.buttons.length >= 3) {
       throw new Error('Maximum of 3 buttons allowed');
@@ -116,7 +122,14 @@ class Template {
     if (this.category) {
       template.categories = [this.category];
     }
-        
+
+    if (this.media) {
+      template.types['twilio/media'] = {
+        body: this.components.body[0].text,
+        media: [this.media]
+      };
+    }
+
     if (this.components.buttons && this.components.buttons.length > 0) {
       const actions = this.components.buttons.map((button, index) => {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "5.10.0-dev.1114",
+  "version": "5.10.1",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",