@peopl-health/nexus 6.4.0-dev.18779 → 6.4.0-dev.18830

package/lib/clinical/helpers/doctorPlanHelper.js

@@ -20,7 +20,6 @@ const FOLLOW_UP_LINES = {
   vigilancia: (hours) => `Seguimiento: queda en vigilancia las próximas ${hours} horas; le escribiremos para ver cómo va.`,
 };
 
-// What the assistant is told to pass on; it writes the patient message itself.
 function planInstructions(plan) {
   const lines = ['Transmítele al paciente lo que indicó el médico, con tus palabras: no cambies dosis, frecuencia ni días, y no agregues otros medicamentos ni estudios.'];
   if (plan.items.length) {
@@ -42,7 +41,6 @@ function assistantInstructionsOf(plan) {
   return `${plan.instructions}\n${PRESCRIPTION_LINE}`;
 }
 
-// What the team's case shows as the indication, in the doctor's terms rather than the assistant's.
 function planSummary(plan) {
   const lines = [...plan.items.map(itemLine), ...plan.studies.map((study) => `Estudio: ${studyLine(study)}`)];
   if (plan.homeCare.length) lines.push(`Cuidados en casa: ${plan.homeCare.join('; ')}.`);
@@ -50,30 +48,26 @@ function planSummary(plan) {
   return lines.join('\n');
 }
 
-// The receta the Airtable automations turn into the doctor's PDF.
 function prescriptionText(plan) {
   const lines = plan.items.map(itemLine);
   if (plan.studies.length) lines.push('Estudios:', ...plan.studies.map(studyLine));
   return lines.join('\n');
 }
 
-// «1 tableta cada 24 horas por 5 días; además, …» → dose, frequency, days and the rest; what does not match is left for the doctor.
 function dosingOf(instructions) {
   const text = oneLineOf(instructions);
   const match = text.match(DOSING);
   if (!match) return { dose: text || null, frequency: null, days: null, rest: null };
   const [, dose, frequency, duration, , , , rest] = match;
-  // A duration said after other directions («…, y tragar, por 7 días») is still the days.
   const late = !duration ? rest?.match(LATE_DURATION) : null;
   const said = duration ?? late?.[1];
   const days = durationDays(said);
   const others = late ? rest.slice(0, late.index).replace(/[,;\s]+$/, '') : rest;
-  // A range («por 3 a 5 días») is the doctor's to settle, so it stays in view with the rest.
+  // A range («por 3 a 5 días») is the doctor's to settle, so it stays in the note.
   const left = [others, said && !days ? said : null].filter(Boolean).join(', ');
   return { dose: isRouteOnly(dose) ? null : dose, frequency, days, rest: left || null };
 }
 
-// The doctor's starting point: the drugs the bot proposed and confirmed, once each, and a 24 h check-in.
 // What the formulary adds after the dosing («además, valoración por oftalmología») goes to the note.
 function proposedPlanOf(draft) {
   const seen = new Set();
@@ -90,7 +84,7 @@ function proposedPlanOf(draft) {
   return { items, studies: [], homeCare: [], note: rests.join('. ') || null, followUp: { kind: 'check_in', hours: DEFAULT_FOLLOW_UP_HOURS.check_in } };
 }
 
-// The plan's own words, so what the doctor wrote anywhere in it is never flagged.
+// The note and home care count, so what the doctor wrote anywhere in the plan is never flagged.
 const plannedTextOf = (plan) => [
   ...plan.items.flatMap((item) => [item.drug, item.strength, item.dose, item.frequency, `por ${item.days} dias`]),
   ...plan.studies.flatMap((study) => [study.name, study.instructions]),

package/lib/clinical/helpers/planTextHelper.js

@@ -1,8 +1,6 @@
 const { foldAccents } = require('../../utils/formatUtils');
 const { normalizeForAnchor } = require('../../utils/textMatchUtils');
 
-// Reading the Spanish of a doctor's plan and of the assistant's reply about it.
-
 const NUMBER_WORDS = Object.freeze({
   un: 1, uno: 1, una: 1, dos: 2, tres: 3, cuatro: 4, cinco: 5, seis: 6, siete: 7, ocho: 8, nueve: 9, diez: 10,
   once: 11, doce: 12, trece: 13, catorce: 14, quince: 15, dieciseis: 16, dieciocho: 18, veinte: 20, veinticuatro: 24,
@@ -19,14 +17,12 @@ const DAY_UNITS = 'd[ií]as?|semanas?|mes(?:es)?|d\\b';
 const DURATION_SOURCE = `(?:por|durante|x)\\s+(?:(?:unos|unas|los|las|pr[oó]ximos|otros)\\s+)*(${COUNT})(?:${TO}(${COUNT}))?\\s*(${DAY_UNITS})`;
 const DURATION = new RegExp(`^${DURATION_SOURCE}$`, 'i');
 
-// «VO», «v.o.», «vía oral», «por vía oral», «IV», «SL»…
 const ROUTES = new Set(['vo', 'po', 'oral', 'iv', 'ev', 'intravenosa', 'im', 'intramuscular', 'sc', 'subcutanea', 'sl', 'sublingual', 'topica', 'rectal']);
 // What a drug's name may carry that does not name it: «Ondansetrón 8 mg», «Metoclopramida gotas».
 const NOT_A_NAME = /^(?:\d+(?:mg|ml|mcg|g|ui)?|mg|ml|mcg|g|ui|vo|iv|im|sc|sl|oral|tabletas?|capsulas?|comprimidos?|gotas|jarabe|crema|gel|unguento|solucion|suspension|sobres?|ampolletas?|ampulas?|parches?|spray|colirio)$/;
 
 const URGENCY_WORDS = /\b(urgencias?|urgente|de inmediato|inmediatamente|emergencias?|911|lo antes posible|cuanto antes|no esperes)\b/g;
-// «no es urgente», «no hay urgencia», «no necesitas ir a urgencias»: the word calms instead of sending the patient.
-// Only filler words may sit between the negation and the word, so «no es normal, ve a urgencias» still counts.
+// Only filler may sit between: «no necesitas ir a urgencias» calms, «no es normal, ve a urgencias» does not.
 const CALMING_BEFORE = /\b(?:no\s+(?:es|son|parece|hay|hace\s+falta|necesitas?|requiere|requieres|tienes\s+(?:que|por\s+que))|sin\s+necesidad\s+de)(?:\s+(?:ir|acudir|a|al|una|un|de|la|que))*\s*$/;
 
 const folded = (text) => foldAccents(text).toLowerCase();
@@ -36,10 +32,9 @@ const daysPer = (unit) => DAYS_PER[folded(unit)];
 
 const isRouteOnly = (text) => ROUTES.has(folded(text).replace(/\./g, '').replace(/^(?:por\s+)?(?:via\s+)?/, '').trim());
 
-// The name in a drug line, without the dose or the form beside it.
 const drugNameOf = (text) => normalizeForAnchor(text).split(' ').filter((word) => word && !NOT_A_NAME.test(word)).join(' ');
 
-// The days a duration phrase says; null for a range or an unknown count, which the doctor settles.
+// Null for a range or an unknown count: the doctor settles those.
 function durationDays(phrase) {
   const match = String(phrase ?? '').trim().match(DURATION);
   if (!match || match[2]) return null;
@@ -55,8 +50,7 @@ const TIMES_A_DAY = (written, ...counts) => {
   return times.every((count) => count > 0 && 24 % count === 0) ? times.map((count) => `cada ${24 / count} horas`).join(' o ') : written;
 };
 
-// One spelling to compare dosing in: no accents, digits for number words, «c/8hs» as «cada 8 horas»,
-// «3 veces al día» as «cada 8 horas», weeks and months as days. A dot stays decimal, as written in Mexico.
+// A dot stays decimal, as written in Mexico.
 function dosingTextOf(text) {
   return folded(text)
     .replace(/\b[1-9]\d{0,2}(?:,\d{3})+\b/g, (thousands) => thousands.replace(/,/g, ''))
@@ -84,7 +78,7 @@ const UNIT_SCALE = Object.freeze({
 
 const valuesIn = (text, pattern) => new Set([...text.matchAll(pattern)].flatMap((match) => [match[1], match[2]]).filter(Boolean).map(Number));
 
-// The hours, days and amounts a text gives; amounts are keyed in mg, ml or UI, so «1 g» and «1000 mg» meet.
+// Amounts are keyed in mg, ml or UI, so «1 g» and «1000 mg» meet.
 function dosingFactsOf(text) {
   const dosing = dosingTextOf(text);
   const amounts = new Map([...dosing.matchAll(AMOUNTS)].map(([written, value, unit]) => {

package/lib/clinical/services/doctorPlanService.js

@@ -46,7 +46,6 @@ function itemOf(item, index) {
   const name = `plan.items[${index}]`;
   const position = textOf(item?.position, `${name}.position`)?.toUpperCase() ?? null;
   const reason = textOf(item?.reason, `${name}.reason`);
-  // An alternative to the first line has to say why the first line does not fit.
   if (position && position !== FIRST_LINE && !reason) throw httpError(400, `${name}.reason is required for a drug that is not first line`);
   return {
     drug: neededText(item?.drug, `${name}.drug`),
@@ -68,7 +67,6 @@ function followUpOf(value) {
   return { kind, hours: wholeNumber(value?.hours ?? DEFAULT_FOLLOW_UP_HOURS[kind], 'plan.followUp.hours', MAX_FOLLOW_UP_HOURS) };
 }
 
-// The plan as the doctor approved it, refused whole when any line is incomplete.
 function planOf(input) {
   if (!isPlainObject(input)) throw httpError(400, 'plan is required');
   const plan = {
@@ -90,7 +88,6 @@ function planOf(input) {
   return plan;
 }
 
-// The doctor's edit wins; with none, the instructions follow the plan.
 function approvedInstructions(plan, edited) {
   if (edited != null && typeof edited !== 'string') throw httpError(400, 'instructions must be text');
   if (!edited?.trim()) return { instructions: planInstructions(plan), instructionsEdited: false };
@@ -101,7 +98,6 @@ function approvedInstructions(plan, edited) {
 
 const strays = (said, planned) => [...said].filter((value) => !planned.has(value));
 
-// What in the assistant's reply strays from the plan, for the team to check.
 function replyIssues(plan, reply) {
   if (!oneLineOf(reply)) return ['no se pudo leer el mensaje enviado'];
   const planned = plannedTextOf(plan);

package/lib/clinical/services/treatmentProposalService.js

@@ -107,7 +107,7 @@ function drugsNamedIn(text) {
   return DRUG_NAMES.filter((name) => padded.includes(` ${name} `));
 }
 
-// Drugs the text names that the planned text does not; a brand of a planned drug counts as planned, a combination only when named whole.
+// A brand of a planned drug counts as planned; a combination only when named whole.
 function unplannedDrugsIn(text, plannedText) {
   const planned = new Set(drugsNamedIn(plannedText));
   const ownNames = (drug) => [drug.drug, ...String(drug.brand ?? '').split('/')].map(key).filter(Boolean);
@@ -136,8 +136,7 @@ function crossSymptomIssues(proposals) {
   return issues;
 }
 
-// The text names the drug: every part of it («Paracetamol/Codeína»), a name in parentheses, or a formulary brand of it.
-// The dose or the form beside the name («Ondansetrón 8 mg», «(400 mg)») does not have to be said.
+// A combination needs every part; the dose or form beside a name («Ondansetrón 8 mg») need not be said.
 function isDrugNamed(text, drugName) {
   const padded = ` ${key(text)} `;
   const says = (name) => Boolean(name) && padded.includes(` ${name} `);

package/lib/config/recoveryTemplateConfig.js

@@ -0,0 +1,31 @@
+const { logger } = require('../utils/logger');
+const { MapCache } = require('../utils/MapCache');
+const { getRecordByFilter } = require('../services/airtableService');
+const { Config_ID } = require('./airtableConfig');
+const { programConfigSource } = require('./programConfig');
+
+const RECOVERY_TEMPLATES_TABLE = 'recovery_templates';
+const CACHE_TTL = 5 * 60 * 1000;
+const CACHE_KEY = 'recoveryTemplates';
+
+const cache = new MapCache({ maxSize: 1, ttl: CACHE_TTL });
+
+// An unreadable table reads as empty, which keeps messages on their one-off templates.
+async function getRecoveryTemplateConfig() {
+  const cached = cache.get(CACHE_KEY);
+  if (cached) return cached;
+  try {
+    const records = await getRecordByFilter(Config_ID, RECOVERY_TEMPLATES_TABLE, 'TRUE()');
+    const rows = (records || []).filter((row) => row.is_active && row.source === programConfigSource());
+    const config = Object.fromEntries(rows.map((row) => [row.config, row.value]));
+    cache.set(CACHE_KEY, config);
+    return config;
+  } catch (error) {
+    logger.warn('[recoveryTemplateConfig] Could not read the fixed templates', { error: error.message });
+    return {};
+  }
+}
+
+function _resetRecoveryTemplateConfig() { cache.clear(); }
+
+module.exports = { getRecoveryTemplateConfig, _resetRecoveryTemplateConfig };

package/lib/core/NexusMessaging.js

@@ -402,14 +402,14 @@ class NexusMessaging {
 
     let gate = null;
     try {
-      gate = await reserveSend(messageData);
+      gate = messageData.skipContactGate ? null : await reserveSend(messageData);
       if (gate?.blocked) {
         await releaseSendClaim(claim.claimId);
         return { success: false, messageId: null, status: 'contact_capped', reason: gate.reason, category: gate.category, delivered: false, deferred: false };
       }
       const result = await this._sendMessage(gate ? { ...messageData, contactGateDecisionId: gate.decisionId } : messageData);
-      // A deferred send is recorded when it actually leaves, so its reservation must not also count.
-      if (result?.success !== true || result?.deferred === true) await releaseSend(gate?.decisionId);
+      // A deferred send is recorded when it actually leaves, and a nested send records itself, so the reservation must not also count.
+      if (result?.success !== true || result?.deferred === true || result?.sentByNestedSend) await releaseSend(gate?.decisionId);
       if (result?.success === true && result?.deferred !== true && !await completeSendClaim(claim.claimId)) {
         logger.error('[NexusMessaging] send claim completion failed; a retry after the claim expires may send again', {
           code: messageData.code,
@@ -430,7 +430,7 @@ class NexusMessaging {
     if (messageData.body) messageData.body = decodeUnicodeEscapes(messageData.body);
     if (messageData.variables) messageData.variables = decodeUnicodeEscapesDeep(messageData.variables);
 
-    if (messageData.fileUrl && this._providerStores) await prepareMessageMedia(messageData);
+    if (messageData.fileUrl && !messageData.media?.key && this._providerStores) await prepareMessageMedia(messageData);
 
     const storesTemplateMedia = Boolean(messageData.contentSid && !messageData.fileUrl && !messageData.parentMessageId && this.provider.renderTemplateContent);
     if (messageData.contentSid && (!messageData.body || storesTemplateMedia)) {
@@ -484,6 +484,7 @@ class NexusMessaging {
       if (!found) return { success: false, delivered: false, deferred: true };
       const queued = await triggerTemplateRecovery(found, { source: 'preemptive' });
       if (queued?.expired) return { ...NOT_SENT_EXPIRED, messageId: String(found._id) };
+      if (queued?.sentOnFixedTemplate) return { success: true, messageId: String(found._id), status: 'sent', delivered: false, deferred: false, sentByNestedSend: true };
       return { success: true, messageId: String(found._id), status: 'queued', preemptive: true, delivered: false, deferred: true };
     }
     const saveFn = this.messageStorage.savePendingMessage.bind(this.messageStorage);
@@ -499,10 +500,13 @@ class NexusMessaging {
         // triggerTemplateRecovery swallows its own errors and returns undefined. Reporting "queued"
         // regardless is how a template that was never created still counts as an outreach, and the
         // weekly guard then stops us ever trying again.
-        const queued = await triggerTemplateRecovery({ _id, body, numero: messageData.code, media: messageData.media, expiresAt: messageData.expiresAt }, { source: 'preemptive' });
+        const queued = await triggerTemplateRecovery({ _id, body, numero: messageData.code, media: messageData.media, expiresAt: messageData.expiresAt, contact_code: messageData.contactCode, contact_role: messageData.contactRole, triggeredBy: messageData.triggeredBy }, { source: 'preemptive' });
         if (queued?.expired) {
           return { ...NOT_SENT_EXPIRED, messageId: String(_id) };
         }
+        if (queued?.sentOnFixedTemplate) {
+          return { success: true, messageId: String(_id), status: 'sent', delivered: false, deferred: false, sentByNestedSend: true };
+        }
         if (!queued?.deferred) {
           logger.error('[NexusMessaging] template recovery setup failed; message not queued', { code: messageData.code, messageId: String(_id) });
           return { success: false, messageId: String(_id), status: 'failed', preemptive: true, delivered: false, deferred: false };

package/lib/helpers/templateRecoveryHelper.js

@@ -1,10 +1,13 @@
+const { getRecoveryTemplateConfig } = require('../config/recoveryTemplateConfig');
 const { generatePresignedUrl } = require('../config/awsConfig');
 const { logger } = require('../utils/logger');
 const { isAtOrBefore } = require('../utils/dateUtils');
 const { createEvent, safeEmit } = require('../utils/eventUtils');
 const { Message } = require('../models/messageModel');
+const { DeliveryAttempt } = require('../models/deliveryAttemptModel');
 const { Template: TemplateModel } = require('../models/templateModel');
 const { Template } = require('../templates/templateStructure');
+const { contactOf } = require('./caregiverHelper');
 const { recordDeliveryAttempt } = require('./deliveryAttemptHelper');
 
 const getMessaging = () => require('../core/NexusMessaging');
@@ -12,6 +15,16 @@ const getMessaging = () => require('../core/NexusMessaging');
 const TEMPLATE_BODY_LIMIT = 1024;
 const RECOVERY_MEDIA_URL_TTL_SECONDS = 7 * 24 * 60 * 60;
 
+const FIXED_TEXT_TEMPLATE_KEY = 'RECOVERY_TEXT_TEMPLATE_SID';
+const FIXED_FILE_TEMPLATE_KEYS = {
+  'application/pdf': 'RECOVERY_DOCUMENT_TEMPLATE_SID',
+  'image/jpeg': 'RECOVERY_IMAGE_TEMPLATE_SID',
+  'image/png': 'RECOVERY_IMAGE_TEMPLATE_SID'
+};
+const FIXED_TEMPLATE_TEXT_LIMIT = 800;
+const FIXED_TEMPLATE_DEFAULT_TEXT = 'Te compartimos un archivo.';
+const FIXED_TEMPLATE_MEDIA_PREFIX_KEY = 'RECOVERY_TEMPLATE_MEDIA_PREFIX';
+
 async function resolveRecoveryMediaUrl(media) {
   if (!media?.bucketName || !media?.key) return null;
   try {
@@ -36,6 +49,75 @@ async function resolveRecoveryBody(messageDoc) {
 
 const EXPIRED_ERROR_MESSAGE = 'Expired before it could be delivered';
 
+// Approved UTILITY, so Meta cannot reclassify it per message; null keeps the one-off template.
+async function fixedRecoveryTemplate(media, body) {
+  const text = String(body ?? '').replace(/\s+/g, ' ').trim();
+  if (text.length > FIXED_TEMPLATE_TEXT_LIMIT) return null;
+  const config = await getRecoveryTemplateConfig();
+
+  if (!media?.key) {
+    const contentSid = config[FIXED_TEXT_TEMPLATE_KEY];
+    return contentSid && text ? { contentSid, variables: { 1: text } } : null;
+  }
+
+  const contentSid = config[FIXED_FILE_TEMPLATE_KEYS[media.contentType]];
+  const mediaPrefix = config[FIXED_TEMPLATE_MEDIA_PREFIX_KEY];
+  if (!contentSid || !mediaPrefix) return null;
+  const mediaUrl = await resolveRecoveryMediaUrl(media);
+  if (!mediaUrl?.startsWith(mediaPrefix)) {
+    logger.warn('[TemplateRecovery] Signed URL does not match the fixed template, using a one-off template', { contentSid });
+    return null;
+  }
+  return { contentSid, variables: { 1: text || FIXED_TEMPLATE_DEFAULT_TEXT, 2: mediaUrl.slice(mediaPrefix.length) } };
+}
+
+// Returns the provider SID if the fixed send got through after all; otherwise the row goes back to queued.
+async function settleFailedFixedSend(messageDoc, contentSid) {
+  const accepted = await DeliveryAttempt.findOne(
+    { messageId: messageDoc._id, contentSid, twilioSid: { $ne: null } }, 'twilioSid'
+  ).lean();
+  if (accepted) return accepted.twilioSid;
+  await Message.updateOne(
+    { _id: messageDoc._id },
+    { $set: { 'statusInfo.status': 'queued' }, $unset: { 'statusInfo.errorCode': '', 'statusInfo.errorMessage': '' } }
+  );
+  return null;
+}
+
+async function sendFixedRecovery(messageDoc, template, logCtx, { skipContactGate }) {
+  const claim = await Message.updateOne(
+    { _id: messageDoc._id, 'statusInfo.recoverySentAt': null, 'statusInfo.recoveryReleasedAt': null },
+    { $set: { 'statusInfo.recoverySentAt': new Date() } }
+  );
+  if (!claim.modifiedCount && !claim.nModified) return 'skipped';
+
+  try {
+    const result = await getMessaging().sendMessage({
+      code: messageDoc.numero,
+      ...contactOf(messageDoc),
+      ...template,
+      parentMessageId: messageDoc._id,
+      kind: 'recovery_template',
+      body: messageDoc.body,
+      triggeredBy: messageDoc.triggeredBy,
+      idempotencyKey: `recovery-fixed:${messageDoc._id}`,
+      skipContactGate
+    });
+    if (result?.duplicate || result?.status === 'outbound_blocked') return 'skipped';
+    if (!result?.messageId) throw new Error('Provider did not return a messageId for the fixed template send');
+    logger.info('[TemplateRecovery] Sent on the fixed template', { ...logCtx, contentSid: template.contentSid });
+    return 'sent';
+  } catch (error) {
+    if (await settleFailedFixedSend(messageDoc, template.contentSid)) {
+      logger.error('[TemplateRecovery] Fixed template reached the provider but bookkeeping failed', { ...logCtx, error: error.message });
+      return 'sent';
+    }
+    await Message.updateOne({ _id: messageDoc._id }, { $unset: { 'statusInfo.recoverySentAt': '' } });
+    logger.warn('[TemplateRecovery] Fixed template send failed, using a one-off template', { ...logCtx, error: error.message });
+    return null;
+  }
+}
+
 async function closeExpiredRecovery(messageDoc) {
   const claim = await Message.updateOne(
     { _id: messageDoc._id, 'statusInfo.recoveryReleasedAt': null, 'statusInfo.recoverySentAt': null },
@@ -110,6 +192,17 @@ async function triggerTemplateRecovery(messageDoc, { source = 'reactive', messag
     }
 
     const recoveryBody = await resolveRecoveryBody(messageDoc);
+
+    let fixedSendFailed = false;
+    if (messageDoc.media?.key && !hasUnresolvedPhi(recoveryBody)) {
+      const fixedTemplate = await fixedRecoveryTemplate(messageDoc.media, recoveryBody);
+      // The preemptive caller's own reservation would count against this send; a reactive one has none.
+      const outcome = fixedTemplate && await sendFixedRecovery(messageDoc, fixedTemplate, logCtx, { skipContactGate: source === 'preemptive' });
+      if (outcome === 'sent') return { delivered: false, deferred: false, sentOnFixedTemplate: true };
+      if (outcome) return { delivered: false, deferred: true };
+      fixedSendFailed = outcome === null;
+    }
+
     const templateName = `auto_${Date.now()}_${Math.floor(Math.random() * 1000)}`;
     const template = new Template(templateName, 'UTILITY', 'es');
     template.setBody(recoveryBody, []);
@@ -178,6 +271,13 @@ async function triggerTemplateRecovery(messageDoc, { source = 'reactive', messag
       originalMessageSid: messageSid
     });
 
+    if (fixedSendFailed) {
+      safeEmit(getMessaging().getEventBus(), 'message:status', createEvent('message:status', {
+        messageId: String(messageDocId),
+        to: messageDoc.numero,
+        status: 'queued'
+      }));
+    }
     return { delivered: false, deferred: true };
   } catch (error) {
     logger.error('[TemplateRecovery] Error', { source, messageSid, error: error.message });
@@ -207,4 +307,4 @@ async function cleanupRecoveryTemplate(messageDoc) {
   }
 }
 
-module.exports = { handle24HourWindowError, triggerTemplateRecovery, cleanupRecoveryTemplate, resolveRecoveryBody, hasUnresolvedPhi, closeExpiredRecovery };
+module.exports = { settleFailedFixedSend, handle24HourWindowError, triggerTemplateRecovery, cleanupRecoveryTemplate, resolveRecoveryBody, fixedRecoveryTemplate, hasUnresolvedPhi, closeExpiredRecovery };

package/lib/jobs/TemplateApprovalJob.js

@@ -10,7 +10,7 @@ const { DeliveryAttempt } = require('../models/deliveryAttemptModel');
 const { alertUndeliverable } = require('../helpers/channelRetryHelper');
 
 const { contactOf } = require('../helpers/caregiverHelper');
-const { closeExpiredRecovery } = require('../helpers/templateRecoveryHelper');
+const { closeExpiredRecovery, fixedRecoveryTemplate, hasUnresolvedPhi, resolveRecoveryBody, settleFailedFixedSend } = require('../helpers/templateRecoveryHelper');
 const { getMessages } = require('../services/messageService');
 const { recordUndeliverable } = require('../services/undeliverableService');
 
@@ -104,6 +104,7 @@ class TemplateApprovalJob extends BaseJob {
 
     let provider;
     let approvalStatus;
+    let approvalCategory;
     let checkError = null;
     try {
       provider = this.requireProvider();
@@ -113,6 +114,7 @@ class TemplateApprovalJob extends BaseJob {
         'checkApprovalStatus'
       );
       approvalStatus = status?.approvalRequest?.status?.toUpperCase();
+      approvalCategory = status?.approvalRequest?.category?.toUpperCase();
     } catch (err) {
       checkError = err;
     }
@@ -131,7 +133,7 @@ class TemplateApprovalJob extends BaseJob {
     logger.info('[TemplateApprovalJob] Approval status', { templateSid, approvalStatus, attempt, messageId, originalMessageSid });
 
     if (approvalStatus === 'APPROVED') {
-      return await this._handleApproved({ message, templateSid, originalMessageSid });
+      return await this._handleApproved({ message, templateSid, originalMessageSid, category: approvalCategory });
     }
     if (approvalStatus === 'REJECTED') {
       return await this._handleRejected({ provider, message, templateSid });
@@ -288,7 +290,21 @@ class TemplateApprovalJob extends BaseJob {
     return { sent: Boolean(result?.messageId), nudgeMessageId: result?.messageId || null };
   }
 
-  async _handleApproved({ message, templateSid, originalMessageSid }) {
+  // Meta can approve a one-off template as MARKETING, which some patients never receive.
+  async _replacementFor(message, category) {
+    if (!category || category === 'UTILITY') return null;
+    try {
+      const body = await resolveRecoveryBody(message);
+      return hasUnresolvedPhi(body) ? null : await fixedRecoveryTemplate(message.media, body);
+    } catch (err) {
+      logger.warn('[TemplateApprovalJob] Could not build the fixed template, sending as approved', {
+        messageId: String(message._id), error: err.message
+      });
+      return null;
+    }
+  }
+
+  async _handleApproved({ message, templateSid, originalMessageSid, category }) {
     const claim = await Message.updateOne(
       { _id: message._id, 'statusInfo.recoverySentAt': null, 'statusInfo.recoveryReleasedAt': null },
       { $set: { 'statusInfo.recoverySentAt': new Date() } }
@@ -298,17 +314,27 @@ class TemplateApprovalJob extends BaseJob {
       return { success: false, reason: 'already_claimed' };
     }
 
+    const replacement = await this._replacementFor(message, category);
+
+    const send = (template) => this.sendMessage({
+      code: message.numero,
+      ...contactOf(message),
+      contentSid: template?.contentSid ?? templateSid,
+      variables: template?.variables ?? {},
+      parentMessageId: message._id,
+      kind: 'recovery_template',
+      body: message.body,
+      idempotencyKey: `recovery:${message._id}`
+    });
+
     let sendResult;
     try {
-      sendResult = await this.sendMessage({
-        code: message.numero,
-        ...contactOf(message),
-        contentSid: templateSid,
-        variables: {},
-        parentMessageId: message._id,
-        kind: 'recovery_template',
-        body: message.body,
-        idempotencyKey: `recovery:${message._id}`
+      sendResult = await send(replacement).catch(async (err) => {
+        if (!replacement) throw err;
+        const acceptedSid = await settleFailedFixedSend(message, replacement.contentSid);
+        if (acceptedSid) return { messageId: acceptedSid };
+        logger.warn('[TemplateApprovalJob] Fixed template failed, sending as approved', { messageId: String(message._id), error: err.message });
+        return send(null);
       });
       if (sendResult?.duplicate) {
         logger.info('[TemplateApprovalJob] Recovery send already claimed elsewhere', { templateSid, messageId: message._id });
@@ -335,7 +361,7 @@ class TemplateApprovalJob extends BaseJob {
 
     await DeliveryAttempt.updateOne(
       { messageId: message._id, kind: 'recovery_template_setup', twilioSid: templateSid },
-      { $set: { status: 'sent', completedAt: new Date() } }
+      { $set: { status: 'sent', ...(category && { templateCategory: category }), completedAt: new Date() } }
     );
 
     return { success: true, recoveryMessageId: sendResult.messageId };

package/lib/models/deliveryAttemptModel.js

@@ -26,6 +26,7 @@ const deliveryAttemptSchema = new mongoose.Schema({
     enum: STATUS_VALUES,
     default: null
   },
+  templateCategory: { type: String, default: null },
   errorCode: { type: String, default: null },
   errorMessage: { type: String, default: null },
   errorSource: {

package/lib/services/assistantMessageService.js

@@ -140,7 +140,7 @@ async function processAssistantSystemMessage(code, messages, role = 'system', op
     // The cause stays internal: callers tell a drain that refused the turn from one that may have answered.
     throw new AssistantMessageError('MESSAGE_REPLY_FAILED', acceptedCount, error);
   }
-  // What the reply's send returned, or null when the turn produced or sent nothing; a send that threw may still have reached the patient.
+  // A send that threw may still have reached the patient.
   return { delivery: turn?.delivery ?? null, sendThrew: settled === 'threw', reply: turn?.output ?? null };
 }
 

package/lib/services/escalationReviewService.js

@@ -731,7 +731,7 @@ async function isEscalationApprover(operator) {
   }
 }
 
-// The doctor whose word the plan is, from the approving doctors; unpicked, the one recording it if they approve, or the only one there is.
+// Unpicked, the doctor is the one recording if they approve, or the only approver there is.
 async function prescriberOf(email, operator) {
   if (email != null && typeof email !== 'string') throw httpError(400, 'prescriberEmail must be text');
   let approvers;
@@ -748,7 +748,7 @@ async function prescriberOf(email, operator) {
   return { name: chosen.name, email: chosen.email };
 }
 
-// Who can sign a receta, for whoever records the plan to pick; null when the list could not be read, which the read survives.
+// Null when the list could not be read; the review is still returned.
 async function prescribersForRead() {
   try {
     return (await listEscalationApprovers()).map(({ name, email }) => ({ name, email }));
@@ -788,7 +788,6 @@ async function getEscalationReviewById({ id, requestedBy } = {}) {
   };
 }
 
-// The instructions a plan would give the assistant, for the doctor to read before approving.
 function previewPlanInstructions({ id, plan } = {}) {
   reviewIdOf(id);
   return planInstructions(planOf(plan));
@@ -1868,7 +1867,7 @@ async function recordDoctorDecision({
     if (seenDraftNumber === null) throw httpError(400, 'draftNumber is required for a plan');
     plan = planOf(requestedPlan);
     plan = { ...plan, ...approvedInstructions(plan, instructions) };
-    // Anyone may record it, often beside the doctor; a drug, a study, a note, an edit or a named drug names the doctor who gave it.
+    // Anyone may record a plan, often beside the doctor; one with a drug, study, note or edit names the doctor who gave it.
     const namesDrug = drugsNamedIn(plan.homeCare.join(' ')).length > 0;
     if (needsPrescriber(plan) || plan.note || plan.instructionsEdited || namesDrug) {
       plan = { ...plan, prescriber: await prescriberOf(prescriberEmail, operator) };
@@ -2145,7 +2144,6 @@ async function issuePrescription(review, plan, prescriberEmail) {
   }
 }
 
-// How the assistant's reply left: sent, queued for the patient's reply window, not sent, or unknown.
 function replyOutcome(delivery, sendThrew) {
   if (sendThrew) return 'unknown';
   if (!delivery) return 'not_sent';
@@ -2155,7 +2153,7 @@ function replyOutcome(delivery, sendThrew) {
   return 'unknown';
 }
 
-// A reply in the case's alarm thread; a notice that fails is logged and never undoes the send.
+// A notice that fails is logged and never undoes the send.
 async function notifyPlanIssues(review, issues) {
   try {
     const { patient, doctor, link } = await teamAlertIdentity(review);
@@ -2172,7 +2170,6 @@ async function notifyPlanIssues(review, issues) {
   }
 }
 
-// The assistant writes the patient message from the doctor's instructions; the review closes unless a follow-up was chosen or the reply needs a look.
 async function sendPlanThroughAssistant({ claimed, claim, decisionNumber, plan, operator, requestId }) {
   const reviewId = claimed._id;
   const release = () => releaseReview(reviewId, 'sending', 'approved', claim).catch((releaseError) => {

package/lib/services/heldMessageService.js

@@ -53,6 +53,7 @@ async function releaseOne(message, now) {
     return false;
   }
 
+  const { media } = message;
   const body = await resolveRecoveryBody(message);
   if (hasUnresolvedPhi(body)) {
     logger.error('[HeldMessage] Body still carries a PHI placeholder, refusing to release', logCtx);
@@ -72,6 +73,7 @@ async function releaseOne(message, now) {
       code: message.numero,
       ...contactOf(message),
       body,
+      ...(media?.key && { media, fileUrl: `https://${media.bucketName}.s3.amazonaws.com/${media.key}`, fileType: media.mediaType }),
       parentMessageId: message._id,
       kind: 'freeform',
       idempotencyKey: `window-release:${message._id}`

package/package.json

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