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

package/lib/clinical/helpers/doctorPlanHelper.js

@@ -1,8 +1,12 @@
 const { oneLineOf } = require('../../utils/coercionUtils');
+const { normalizeForAnchor: drugKey } = require('../../utils/textMatchUtils');
+const { DURATION_SOURCE, durationDays, isRouteOnly } = require('./planTextHelper');
 
 const DEFAULT_FOLLOW_UP_HOURS = Object.freeze({ check_in: 24, vigilancia: 48 });
-// A route is not a dose: the doctor still says how many tablets.
-const ROUTE_ONLY = /^(vo|v[ií]a oral|oral)$/i;
+// «1 tableta» «cada 8 horas | c/8h» «por 5 días», then «, …» what else the formulary says.
+const DOSING = new RegExp(`^(.*?)\\s+((?:cada|c\\/)\\s*[^,;]+?)(?:\\s+(${DURATION_SOURCE}))?(?:\\s*[,;]\\s*(.*))?$`, 'i');
+// Only a clause of its own: «…, y tragar, por 7 días» gives the days, «…, no manejar durante 2 días» does not.
+const LATE_DURATION = new RegExp(`(?:^|[,;]\\s*)(${DURATION_SOURCE})\\s*$`, 'i');
 
 const needsPrescriber = (plan) => plan.items.length > 0 || plan.studies.length > 0;
 
@@ -16,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) {
@@ -34,11 +37,10 @@ function planInstructions(plan) {
 
 // An edit can drop the receta line; the PDF goes out anyway, so the assistant is still told.
 function assistantInstructionsOf(plan) {
-  if (!needsPrescriber(plan) || plan.instructions.includes(PRESCRIPTION_LINE)) return plan.instructions;
+  if (!needsPrescriber(plan) || oneLineOf(plan.instructions).includes(PRESCRIPTION_LINE)) return plan.instructions;
   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('; ')}.`);
@@ -46,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(/^(.*?)\s+(cada [^,;]+?)(?:\s+por\s+(\d+)\s+d[ií]as?)?(?:\s*[,;]\s*(.*))?$/i);
+  const match = text.match(DOSING);
   if (!match) return { dose: text || null, frequency: null, days: null, rest: null };
-  const [, dose, frequency, days, rest] = match;
-  // A duration said after other directions («…, y tragar, por 7 días») is still the days.
-  const lateDays = !days && rest?.match(/(?:^|[,;]\s*|\s)por\s+(\d+)\s+d[ií]as?\s*$/i);
-  return {
-    dose: ROUTE_ONLY.test(dose) ? null : dose,
-    frequency,
-    days: Number(days ?? lateDays?.[1]) || null,
-    rest: (lateDays ? rest.slice(0, lateDays.index).replace(/[,;\s]+$/, '') : rest) || null,
-  };
+  const [, dose, frequency, duration, , , , rest] = match;
+  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 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();
@@ -77,7 +75,7 @@ function proposedPlanOf(draft) {
   const items = (draft?.symptoms ?? [])
     .filter((entry) => entry?.proposal?.confirmed)
     .flatMap((entry) => (entry.proposal.items ?? []).map((item) => ({ item, formularyKey: entry.proposal.formularyKey })))
-    .filter(({ item }) => !seen.has(oneLineOf(item.drug).toLowerCase()) && seen.add(oneLineOf(item.drug).toLowerCase()))
+    .filter(({ item }) => !seen.has(drugKey(item.drug)) && seen.add(drugKey(item.drug)))
     .map(({ item, formularyKey }) => {
       const { rest, ...dosing } = dosingOf(item.instructions);
       if (rest) rests.push(`${item.drug}: ${rest}`);
@@ -86,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

@@ -0,0 +1,98 @@
+const { foldAccents } = require('../../utils/formatUtils');
+const { normalizeForAnchor } = require('../../utils/textMatchUtils');
+
+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,
+  treinta: 30, 'treinta y seis': 36, cuarenta: 40, 'cuarenta y ocho': 48, 'setenta y dos': 72,
+});
+const WORDS = Object.keys(NUMBER_WORDS).sort((a, b) => b.length - a.length).join('|');
+const COUNT = `(?:\\d+|${WORDS})`;
+// «y» is left out: «treinta y cinco» is one number, not a range.
+const TO = '\\s*(?:a|-|o|u)\\s*';
+const DAYS_PER = Object.freeze({ d: 1, dia: 1, dias: 1, semana: 7, semanas: 7, mes: 30, meses: 30 });
+const DAY_UNITS = 'd[ií]as?|semanas?|mes(?:es)?|d\\b';
+
+// «por 5 días», «durante una semana», «x 7 días», «por unos 5 días», «por 3 a 5 días»
+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');
+
+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;
+// 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();
+
+const countOf = (word) => (/^\d+$/.test(word) ? Number(word) : NUMBER_WORDS[folded(word).replace(/\s+/g, ' ')] ?? null);
+const daysPer = (unit) => DAYS_PER[folded(unit)];
+
+const isRouteOnly = (text) => ROUTES.has(folded(text).replace(/\./g, '').replace(/^(?:por\s+)?(?:via\s+)?/, '').trim());
+
+const drugNameOf = (text) => normalizeForAnchor(text).split(' ').filter((word) => word && !NOT_A_NAME.test(word)).join(' ');
+
+// 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;
+  const count = countOf(match[1]);
+  return count ? count * daysPer(match[3]) : null;
+}
+
+const NUMBER_WORD = new RegExp(`\\b(${WORDS})\\b`, 'g');
+const IN_DAYS = new RegExp(`\\b(\\d+)(?:${TO}(\\d+))?\\s*(semanas?|mes(?:es)?|d)\\b`, 'g');
+const DAYS_IN_UNIT = (_, from, to, unit) => [from, to].filter(Boolean).map((value) => value * daysPer(unit)).join(' a ').concat(' dias');
+const TIMES_A_DAY = (written, ...counts) => {
+  const times = counts.slice(0, 2).filter(Boolean).map(Number);
+  return times.every((count) => count > 0 && 24 % count === 0) ? times.map((count) => `cada ${24 / count} horas`).join(' o ') : written;
+};
+
+// 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, ''))
+    .replace(/(\d),(\d)/g, '$1.$2')
+    .replace(NUMBER_WORD, (word) => String(countOf(word)))
+    .replace(/\bc\/\s*(\d+)\s*(?:h|hs|hrs?|horas?)\b/g, 'cada $1 horas')
+    .replace(new RegExp(`\\b(\\d+)(?:${TO}(\\d+))?\\s+ve(?:z|ces)\\s+(?:al|por|cada)\\s+dia\\b`, 'g'), TIMES_A_DAY)
+    .replace(/\bcada\s+hora\b/g, 'cada 1 horas')
+    .replace(/\bcada\s+dia\b/g, 'cada 24 horas')
+    .replace(/\b(?:por|durante|x)\s+(?:(?:unos|unas|los|las|proximos|otros)\s+)*(?=\d)/g, 'por ')
+    .replace(IN_DAYS, DAYS_IN_UNIT)
+    .replace(/\s+/g, ' ');
+}
+
+const RANGE = `(\\d+)(?:${TO}(\\d+))?`;
+const HOURS = new RegExp(`cada\\s+${RANGE}\\s*h(?:s|rs?|oras?)?\\b`, 'g');
+const DAYS = new RegExp(`por\\s+${RANGE}\\s+dias?\\b`, 'g');
+const AMOUNTS = /\b(\d+(?:\.\d+)?)\s*(microgramos?|miligramos?|gramos?|mcg|µg|ug|mg|gr?|ml|ui)(?![a-z])/g;
+const UNIT_SCALE = Object.freeze({
+  microgramo: ['mg', 0.001], microgramos: ['mg', 0.001], mcg: ['mg', 0.001], µg: ['mg', 0.001], ug: ['mg', 0.001],
+  miligramo: ['mg', 1], miligramos: ['mg', 1], mg: ['mg', 1],
+  gramo: ['mg', 1000], gramos: ['mg', 1000], g: ['mg', 1000], gr: ['mg', 1000],
+  ml: ['ml', 1], ui: ['ui', 1],
+});
+
+const valuesIn = (text, pattern) => new Set([...text.matchAll(pattern)].flatMap((match) => [match[1], match[2]]).filter(Boolean).map(Number));
+
+// 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]) => {
+    const [base, scale] = UNIT_SCALE[unit];
+    return [`${Math.round(Number(value) * scale * 1000) / 1000} ${base}`, written];
+  }));
+  return { hours: valuesIn(dosing, HOURS), days: valuesIn(dosing, DAYS), amounts };
+}
+
+function urgencyWordsIn(text) {
+  const plain = folded(text);
+  return new Set([...plain.matchAll(URGENCY_WORDS)]
+    .filter((match) => !CALMING_BEFORE.test(plain.slice(0, match.index)))
+    .map((match) => match[1]));
+}
+
+module.exports = { DURATION_SOURCE, dosingFactsOf, drugNameOf, durationDays, isRouteOnly, urgencyWordsIn };

package/lib/clinical/services/doctorPlanService.js

@@ -1,8 +1,9 @@
 const { DEFAULT_FOLLOW_UP_HOURS, planInstructions, plannedTextOf } = require('../helpers/doctorPlanHelper');
+const { dosingFactsOf, urgencyWordsIn } = require('../helpers/planTextHelper');
 const { httpError } = require('../../utils/httpErrorUtils');
 const { oneLineOf } = require('../../utils/coercionUtils');
 const { PLAN_FOLLOW_UPS } = require('../../models/escalationReviewModel');
-const { unplannedDrugsIn } = require('./treatmentProposalService');
+const { isDrugNamed, unplannedDrugsIn } = require('./treatmentProposalService');
 
 const FIRST_LINE = '1L';
 const MAX_ENTRIES = 10;
@@ -43,9 +44,8 @@ const listOf = (value, name) => {
 
 function itemOf(item, index) {
   const name = `plan.items[${index}]`;
-  const position = textOf(item?.position, `${name}.position`);
+  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`),
@@ -67,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 = {
@@ -89,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 };
@@ -98,33 +96,21 @@ function approvedInstructions(plan, edited) {
   return { instructions, instructionsEdited: instructions !== planInstructions(plan) };
 }
 
-const plain = (text) => String(text ?? '').normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase();
-const URGENCY_WORDS = /\b(urgencias?|urgente|de inmediato|inmediatamente|emergencias?|911|lo antes posible|cuanto antes|no esperes)\b/g;
-const numbersIn = (text, pattern) => new Set([...plain(text).matchAll(pattern)].map((match) => match[1].replace(',', '.')));
-const HOURS = /cada\s+(\d+)\s*h(?:rs?|oras?)?\b/g;
-const DAYS = /por\s+(\d+)\s+dias?/g;
-const MG = /(\d+(?:[.,]\d+)?)\s*mg\b/g;
+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) {
-  const text = plain(reply);
-  if (!text) return ['no se pudo leer el mensaje enviado'];
+  if (!oneLineOf(reply)) return ['no se pudo leer el mensaje enviado'];
   const planned = plannedTextOf(plan);
-  const unplannedDrugs = unplannedDrugsIn(reply, planned);
-  const issues = [];
-  for (const item of plan.items) {
-    const name = plain(item.drug).split(/[\s/]/)[0];
-    if (name && !text.includes(name)) issues.push(`no menciona ${item.drug}`);
-  }
-  const strays = (pattern) => [...numbersIn(reply, pattern)].filter((value) => !numbersIn(planned, pattern).has(value));
-  for (const value of strays(HOURS)) issues.push(`dice «cada ${value} horas», que no está en el plan`);
-  for (const value of strays(DAYS)) issues.push(`dice «por ${value} días», que no está en el plan`);
-  for (const value of strays(MG)) issues.push(`dice «${value} mg», que no está en el plan`);
-  for (const name of unplannedDrugs) issues.push(`menciona ${name}, que el médico no indicó`);
-  const plannedWords = new Set([...plain(planned).matchAll(URGENCY_WORDS)].map((match) => match[1]));
-  for (const word of new Set([...text.matchAll(URGENCY_WORDS)].map((match) => match[1]))) {
-    if (!plannedWords.has(word)) issues.push(`usa «${word}», que el médico no indicó`);
+  const said = dosingFactsOf(reply);
+  const allowed = dosingFactsOf(planned);
+  const issues = plan.items.filter((item) => !isDrugNamed(reply, item.drug)).map((item) => `no menciona ${item.drug}`);
+  for (const hours of strays(said.hours, allowed.hours)) issues.push(`dice «cada ${hours} horas», que no está en el plan`);
+  for (const days of strays(said.days, allowed.days)) issues.push(`dice «por ${days} días», que no está en el plan`);
+  for (const [amount, written] of said.amounts) {
+    if (!allowed.amounts.has(amount)) issues.push(`dice «${written}», que no está en el plan`);
   }
+  for (const name of unplannedDrugsIn(reply, planned)) issues.push(`menciona ${name}, que el médico no indicó`);
+  for (const word of strays(urgencyWordsIn(reply), urgencyWordsIn(planned))) issues.push(`usa «${word}», que el médico no indicó`);
   return issues;
 }
 

package/lib/clinical/services/treatmentProposalService.js

@@ -1,3 +1,4 @@
+const { drugNameOf } = require('../helpers/planTextHelper');
 const { TREATMENT_FORMULARY, findDrug, formularyFor } = require('../protocols/treatmentFormulary');
 
 const { normalizeForAnchor: key } = require('../../utils/textMatchUtils');
@@ -90,7 +91,8 @@ function validateProposal(proposal, context = {}) {
 
 const namesOf = (drug) => [drug.drug, ...drug.drug.split('/'), ...String(drug.brand ?? '').split('/')].map(key).filter((name) => name.length >= 4);
 
-const FORMULARY_DRUGS = TREATMENT_FORMULARY.flatMap((entry) => entry.drugs).filter((drug) => drug.isPharmacological !== false);
+const ALL_FORMULARY_DRUGS = TREATMENT_FORMULARY.flatMap((entry) => entry.drugs);
+const FORMULARY_DRUGS = ALL_FORMULARY_DRUGS.filter((drug) => drug.isPharmacological !== false);
 const DRUG_NAMES = [...new Set(FORMULARY_DRUGS.flatMap(namesOf))];
 
 function resolvedDrugs(proposals) {
@@ -105,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);
@@ -134,8 +136,21 @@ function crossSymptomIssues(proposals) {
   return issues;
 }
 
+// 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} `);
+  const name = String(drugName ?? '');
+  const outside = name.replace(/\(.*?\)/g, ' ');
+  const inside = [...name.matchAll(/\((.*?)\)/g)].map((match) => drugNameOf(match[1]));
+  const brands = ALL_FORMULARY_DRUGS.filter((drug) => drugNameOf(drug.drug) === drugNameOf(outside)).flatMap((drug) => String(drug.brand ?? '').split('/').map(key));
+  const parts = outside.split(/\s*[/+]\s*/).map(drugNameOf).filter(Boolean);
+  return (parts.length > 0 && parts.every(says)) || [...inside, ...brands].some(says);
+}
+
 module.exports = {
   JUSTIFICATION_KINDS,
+  isDrugNamed,
   validateProposal,
   unproposedDrugsIn,
   unplannedDrugsIn,

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.18778",
+  "version": "6.4.0-dev.18830",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",