@peopl-health/nexus 6.3.1 → 6.4.0-dev.18675

package/lib/clinical/helpers/doctorPlanHelper.js

@@ -0,0 +1,165 @@
+const { httpError } = require('../../utils/httpErrorUtils');
+const { oneLineOf } = require('../../utils/coercionUtils');
+const { PLAN_FOLLOW_UPS } = require('../../models/escalationReviewModel');
+
+const DEFAULT_FOLLOW_UP_HOURS = { check_in: 24, vigilancia: 48 };
+const FIRST_LINE = '1L';
+const MAX_ENTRIES = 10;
+const MAX_FIELD_LENGTH = 300;
+const MAX_NOTE_LENGTH = 1000;
+const MAX_INSTRUCTIONS_LENGTH = 4000;
+const MAX_DAYS = 90;
+const MAX_FOLLOW_UP_HOURS = 168;
+// A route is not a dose: the doctor still says how many tablets.
+const ROUTE_ONLY = /^(vo|v[ií]a oral|oral)$/i;
+
+const textOf = (value, name, max = MAX_FIELD_LENGTH) => {
+  if (value != null && typeof value !== 'string') throw httpError(400, `${name} must be text`);
+  const text = oneLineOf(value);
+  if (text.length > max) throw httpError(400, `${name} exceeds ${max} characters`);
+  return text || null;
+};
+
+const neededText = (value, name) => {
+  const text = textOf(value, name);
+  if (!text) throw httpError(400, `${name} is required`);
+  return text;
+};
+
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+// Only a number or a string of digits: `true`, `[5]` and `'1e1'` are not days.
+const wholeNumber = (value, name, max) => {
+  const number = typeof value === 'number' || (typeof value === 'string' && /^\d+$/.test(value.trim())) ? Number(value) : NaN;
+  if (!Number.isInteger(number) || number < 1 || number > max) throw httpError(400, `${name} must be a whole number from 1 to ${max}`);
+  return number;
+};
+
+const listOf = (value, name) => {
+  if (value == null) return [];
+  if (!Array.isArray(value)) throw httpError(400, `${name} must be a list`);
+  if (value.length > MAX_ENTRIES) throw httpError(400, `${name} allows at most ${MAX_ENTRIES} entries`);
+  return value;
+};
+
+function itemOf(item, index) {
+  const name = `plan.items[${index}]`;
+  const position = textOf(item?.position, `${name}.position`);
+  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`),
+    strength: textOf(item?.strength, `${name}.strength`),
+    dose: neededText(item?.dose, `${name}.dose`),
+    frequency: neededText(item?.frequency, `${name}.frequency`),
+    days: wholeNumber(item?.days, `${name}.days`, MAX_DAYS),
+    position,
+    reason,
+    formularyKey: textOf(item?.formularyKey, `${name}.formularyKey`),
+  };
+}
+
+function followUpOf(value) {
+  if (value != null && !isPlainObject(value)) throw httpError(400, 'plan.followUp must be an object with a kind');
+  const kind = value?.kind ?? 'none';
+  if (!PLAN_FOLLOW_UPS.includes(kind)) throw httpError(400, `plan.followUp.kind must be one of: ${PLAN_FOLLOW_UPS.join(', ')}`);
+  if (kind === 'none') return { kind, hours: null };
+  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 = {
+    items: listOf(input.items, 'plan.items').map((item, index) => {
+      if (!isPlainObject(item)) throw httpError(400, `plan.items[${index}] must be an object`);
+      return itemOf(item, index);
+    }),
+    studies: listOf(input.studies, 'plan.studies').map((study, index) => ({
+      name: neededText(study?.name, `plan.studies[${index}].name`),
+      instructions: textOf(study?.instructions, `plan.studies[${index}].instructions`),
+    })),
+    homeCare: listOf(input.homeCare, 'plan.homeCare').map((entry, index) => neededText(entry, `plan.homeCare[${index}]`)),
+    note: textOf(input.note, 'plan.note', MAX_NOTE_LENGTH),
+    followUp: followUpOf(input.followUp),
+  };
+  if (!plan.items.length && !plan.studies.length && !plan.homeCare.length && !plan.note) {
+    throw httpError(400, 'plan needs a drug, a study, a home care measure or a note');
+  }
+  return plan;
+}
+
+const needsPrescriber = (plan) => plan.items.length > 0 || plan.studies.length > 0;
+
+const daysText = (days) => (days === 1 ? '1 día' : `${days} días`);
+
+const FOLLOW_UP_LINES = {
+  check_in: (hours) => `Seguimiento: le escribiremos en unas ${hours} horas para ver cómo va.`,
+  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) {
+    lines.push('Medicamentos:', ...plan.items.map((item) => `- ${[item.drug, item.strength].filter(Boolean).join(' ')}: ${item.dose} ${item.frequency} por ${daysText(item.days)}.`));
+  }
+  if (plan.studies.length) {
+    lines.push('Estudios:', ...plan.studies.map((study) => `- ${study.name}${study.instructions ? `: ${study.instructions}` : ''}.`));
+  }
+  if (plan.homeCare.length) lines.push('Cuidados en casa:', ...plan.homeCare.map((entry) => `- ${entry}`));
+  if (plan.note) lines.push(`Nota del médico: «${plan.note}».`);
+  if (plan.followUp.kind !== 'none') lines.push(FOLLOW_UP_LINES[plan.followUp.kind](plan.followUp.hours));
+  return lines.join('\n');
+}
+
+// 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 };
+  const instructions = edited.trim();
+  if (instructions.length > MAX_INSTRUCTIONS_LENGTH) throw httpError(400, `instructions exceed ${MAX_INSTRUCTIONS_LENGTH} characters`);
+  return { instructions, instructionsEdited: instructions !== planInstructions(plan) };
+}
+
+// «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);
+  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,
+  };
+}
+
+// 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();
+  const rests = [];
+  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()))
+    .map(({ item, formularyKey }) => {
+      const { rest, ...dosing } = dosingOf(item.instructions);
+      if (rest) rests.push(`${item.drug}: ${rest}`);
+      return { drug: item.drug, strength: item.strength ?? null, ...dosing, position: item.position ?? null, reason: null, formularyKey };
+    });
+  return { items, studies: [], homeCare: [], note: rests.join('. ') || null, followUp: { kind: 'check_in', hours: DEFAULT_FOLLOW_UP_HOURS.check_in } };
+}
+
+module.exports = {
+  approvedInstructions,
+  needsPrescriber,
+  planInstructions,
+  planOf,
+  proposedPlanOf,
+};

package/lib/controllers/escalationReviewController.js

@@ -11,6 +11,7 @@ const {
   handOffToDoctor,
   listEscalationReviews,
   openEscalationReview,
+  previewPlanInstructions,
   reclassifyUrgency,
   recordDoctorDecision,
   requestBotDraft,
@@ -53,13 +54,22 @@ const openEscalationReviewController = async (req, res) => {
 
 const getEscalationReviewController = async (req, res) => {
   try {
-    const { review, isApprover, responseDeadline } = await getEscalationReviewById({ id: req.params.id, requestedBy: req.query.requestedBy });
-    res.status(200).json({ success: true, review: withCaseStatus(review), isApprover, responseDeadline });
+    const { review, isApprover, responseDeadline, proposedPlan } = await getEscalationReviewById({ id: req.params.id, requestedBy: req.query.requestedBy });
+    res.status(200).json({ success: true, review: withCaseStatus(review), isApprover, responseDeadline, proposedPlan });
   } catch (error) {
     respondWithError(res, error, 'reading escalation review', { reviewId: req.params?.id });
   }
 };
 
+const previewEscalationReviewPlanController = async (req, res) => {
+  try {
+    const instructions = previewPlanInstructions({ id: req.params.id, plan: req.body?.plan });
+    res.status(200).json({ success: true, instructions });
+  } catch (error) {
+    respondWithError(res, error, 'previewing the plan instructions', { reviewId: req.params?.id });
+  }
+};
+
 const getReviewTimelineController = async (req, res) => {
   try {
     const timeline = await getReviewTimeline({ id: req.params.id });
@@ -175,6 +185,8 @@ const recordEscalationReviewDecisionController = async (req, res) => {
       source,
       decision,
       finalText = null,
+      plan = null,
+      instructions = null,
       comment = null,
       doctorName = null,
       doctorReply = null,
@@ -188,6 +200,8 @@ const recordEscalationReviewDecisionController = async (req, res) => {
       source,
       decision,
       finalText,
+      plan,
+      instructions,
       comment,
       doctorName,
       doctorReply,
@@ -284,6 +298,7 @@ module.exports = {
   closeEscalationReviewController,
   getEscalationReviewController,
   getReviewTimelineController,
+  previewEscalationReviewPlanController,
   requestEscalationReviewDraftController,
   handOffEscalationReviewController,
   listEscalationReviewsController,

package/lib/models/escalationReviewModel.js

@@ -12,7 +12,8 @@ const HANDOFF_MODES = ['sent_whatsapp', 'copied'];
 const INTERRUPTED_STATUSES = ['handing_off', 'sending'];
 const CANCELLABLE_AFTER_HANDOFF_STATUSES = ['awaiting_doctor', 'approved', 'returned', 'indications_queued'];
 const CANCELLABLE_STATUSES = ['open', 'documenting', 'draft_ready', ...CANCELLABLE_AFTER_HANDOFF_STATUSES];
-const DOCTOR_DECISIONS = ['approved', 'edited_approved', 'needs_intervention', 'returned', 'monitor', 'direct_chat'];
+const DOCTOR_DECISIONS = ['approved', 'edited_approved', 'plan_approved', 'needs_intervention', 'returned', 'monitor', 'direct_chat'];
+const PLAN_FOLLOW_UPS = ['none', 'check_in', 'vigilancia'];
 const DECISION_SOURCES = ['platform', 'registered_by_navigator', 'chat'];
 const RETURN_REASONS = ['llamar', 'falta_dato', 'no_requiere'];
 
@@ -193,11 +194,39 @@ const doctorHandoffSchema = new mongoose.Schema({
   sentBy: { type: String, required: true },
 }, { timestamps: { createdAt: true, updatedAt: false } });
 
+const planItemSchema = new mongoose.Schema({
+  drug: { type: String, required: true },
+  strength: { type: String, default: null },
+  dose: { type: String, required: true },
+  frequency: { type: String, required: true },
+  days: { type: Number, required: true },
+  position: { type: String, default: null },
+  reason: { type: String, default: null },
+  formularyKey: { type: String, default: null },
+}, { _id: false });
+
+const planSchema = new mongoose.Schema({
+  items: { type: [planItemSchema], default: [] },
+  studies: {
+    type: [new mongoose.Schema({ name: { type: String, required: true }, instructions: { type: String, default: null } }, { _id: false })],
+    default: [],
+  },
+  homeCare: { type: [String], default: [] },
+  note: { type: String, default: null },
+  followUp: {
+    type: new mongoose.Schema({ kind: { type: String, enum: PLAN_FOLLOW_UPS, required: true }, hours: { type: Number, default: null } }, { _id: false }),
+    required: true,
+  },
+  instructions: { type: String, required: true },
+  instructionsEdited: { type: Boolean, default: false },
+}, { _id: false });
+
 const decisionSchema = new mongoose.Schema({
   decision: { type: String, enum: DOCTOR_DECISIONS, required: true },
   source: { type: String, enum: DECISION_SOURCES, required: true },
   draftNumber: { type: Number, required: true },
   finalText: { type: String, default: null },
+  plan: { type: planSchema, default: undefined },
   comment: { type: String, default: null },
   doctorReply: { type: String, default: null },
   returnReason: { type: String, enum: [...RETURN_REASONS, null], default: null },
@@ -381,6 +410,7 @@ module.exports = {
   DOCTOR_DECISIONS,
   HANDOFF_MODES,
   INTERRUPTED_STATUSES,
+  PLAN_FOLLOW_UPS,
   FOLLOWUP_STATUSES,
   RETURN_REASONS,
   URGENCY_LEVELS,

package/lib/routes/index.js

@@ -138,6 +138,7 @@ const escalationReviewRouteDefinitions = {
   'POST /:id/note-facts': 'confirmEscalationReviewNoteFactsController',
   'POST /:id/drafts': 'addEscalationReviewDraftController',
   'POST /:id/doctor-handoffs': 'handOffEscalationReviewController',
+  'POST /:id/plan-instructions': 'previewEscalationReviewPlanController',
   'POST /:id/decisions': 'recordEscalationReviewDecisionController',
   'POST /:id/patient-deliveries': 'sendEscalationReviewIndicationsController',
   'POST /:id/close': 'closeEscalationReviewController',
@@ -314,6 +315,7 @@ const builtInControllers = {
   listReviewBoardController: escalationReviewController.listReviewBoardController,
   getEscalationReviewController: escalationReviewController.getEscalationReviewController,
   getReviewTimelineController: escalationReviewController.getReviewTimelineController,
+  previewEscalationReviewPlanController: escalationReviewController.previewEscalationReviewPlanController,
   requestEscalationReviewDraftController: escalationReviewController.requestEscalationReviewDraftController,
   setEscalationReviewCasesController: escalationReviewController.setEscalationReviewCasesController,
   addEscalationReviewCallLogController: escalationReviewController.addEscalationReviewCallLogController,

package/lib/services/escalationReviewService.js

@@ -33,6 +33,7 @@ const { doctorAlertHeadline, doctorAlertOpener, renderDoctorMessage, templateSum
 const { generateKeyQuestions } = require('../clinical/services/escalationQuestionsService');
 const { drugsNamedIn } = require('../clinical/services/treatmentProposalService');
 const { characterizationSeedOf } = require('../clinical/helpers/reviewUpdateHelper');
+const { approvedInstructions, needsPrescriber, planInstructions, planOf, proposedPlanOf } = require('../clinical/helpers/doctorPlanHelper');
 const { readNoteFacts, assertionOf } = require('../clinical/services/escalationNoteFactsService');
 const { humanReplyFilter } = require('../clinical/config/safetyNetConfig');
 const {
@@ -104,7 +105,8 @@ const RECLASSIFIABLE_STATUSES = [...DOCUMENTING_STATUSES, 'awaiting_doctor'];
 const SAME_URGENCY = 'The review is already at that urgency';
 const RECLASSIFY_CHANGED = 'The review changed while you were reclassifying it; read it again before changing the urgency';
 const DIRECT_CHAT_STATUSES = ['open', 'documenting', 'draft_ready', 'returned', 'awaiting_doctor', 'approved', 'needs_intervention'];
-const APPROVALS = ['approved', 'edited_approved'];
+const APPROVALS = ['approved', 'edited_approved', 'plan_approved'];
+const PRESCRIBER_ONLY = 'Only an approving doctor can indicate drugs or studies, or edit the instructions to the assistant';
 const STALE_DRAFT = 'New information reached the review after this draft; wait for the updated draft before approving';
 const STALE_HANDOFF = 'New information reached the review after the draft the doctor received; it went back to documenting for a new draft';
 const DRAFT_CHANGED = 'A newer draft was written after the one you saw; read it before deciding';
@@ -145,7 +147,7 @@ const configured = (key) => {
   return value;
 };
 
-const STATUS_AFTER = { edited_approved: 'approved', monitor: 'monitoring' };
+const STATUS_AFTER = { edited_approved: 'approved', plan_approved: 'approved', monitor: 'monitoring' };
 const statusAfter = (decision) => STATUS_AFTER[decision] ?? decision;
 
 const redactedError = (error) => redactDirectIdentifiers(String(error?.message || ''));
@@ -728,6 +730,18 @@ async function isEscalationApprover(operator) {
   }
 }
 
+// Unlike a read, a failed lookup refuses the decision instead of treating the doctor as not approving.
+async function requireApprover(operator) {
+  let approver;
+  try {
+    approver = await getEscalationApprover(operator);
+  } catch (error) {
+    logger.error('[EscalationReview] Approver lookup failed; the plan was not recorded', { error: redactedError(error) });
+    throw httpError(503, 'The approving doctors could not be read; try again');
+  }
+  if (!approver) throw httpError(403, PRESCRIBER_ONLY);
+}
+
 async function getEscalationReviewById({ id, requestedBy } = {}) {
   const reviewId = reviewIdOf(id);
   const operator = requiredText(requestedBy, 'requestedBy');
@@ -748,7 +762,19 @@ async function getEscalationReviewById({ id, requestedBy } = {}) {
       .updateOne({ _id: review._id }, { $max: { approverViewedAt: readAt } }, { timestamps: false })
       .catch(warnUnmarked);
   }
-  return { review, isApprover, responseDeadline: responseDeadlineOf(review, responseDeadlinePolicy()) };
+  const draft = DECIDABLE_STATUSES.includes(review.status) ? review.drafts?.at(-1) : null;
+  return {
+    review,
+    isApprover,
+    responseDeadline: responseDeadlineOf(review, responseDeadlinePolicy()),
+    proposedPlan: draft ? { draftNumber: review.drafts.length, ...proposedPlanOf(draft) } : null,
+  };
+}
+
+// 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));
 }
 
 async function getReviewTimeline({ id } = {}) {
@@ -1787,6 +1813,8 @@ async function recordDoctorDecision({
   source,
   decision,
   finalText = null,
+  plan: requestedPlan = null,
+  instructions = null,
   comment = null,
   doctorName = null,
   doctorReply = null,
@@ -1815,6 +1843,17 @@ async function recordDoctorDecision({
     if (!RETURN_REASONS.includes(reason)) throw httpError(400, `reason must be one of: ${RETURN_REASONS.join(', ')}`);
     returnReason = reason;
   }
+  let plan = null;
+  if (decision === 'plan_approved') {
+    if (source !== 'platform') throw httpError(400, 'A plan is approved by the doctor on the platform');
+    // The plan names the draft it started from, so a newer draft is refused instead of decided unseen.
+    if (seenDraftNumber === null) throw httpError(400, 'draftNumber is required for a plan');
+    plan = planOf(requestedPlan);
+    plan = { ...plan, ...approvedInstructions(plan, instructions) };
+    // The team may send home care alone; a note, an edit or a named drug goes out on a doctor's word.
+    const namesDrug = drugsNamedIn(plan.homeCare.join(' ')).length > 0;
+    if (needsPrescriber(plan) || plan.note || plan.instructionsEdited || namesDrug) await requireApprover(operator);
+  }
 
   const review = await loadReview(reviewId);
   const isDraftless = DRAFTLESS_DECISIONS.includes(decision);
@@ -1858,6 +1897,7 @@ async function recordDoctorDecision({
         source,
         draftNumber,
         finalText: approvedText,
+        ...(plan && { plan }),
         comment: optionalText(comment),
         doctorReply: reply,
         ...(returnReason && { returnReason }),
@@ -2076,6 +2116,7 @@ const EPISODE_SOURCE = 'doctor';
 const DECISION_WORDS = {
   approved: 'el médico aprobó las indicaciones',
   edited_approved: 'el médico aprobó las indicaciones con cambios',
+  plan_approved: 'el médico dio las indicaciones',
   needs_intervention: 'el médico pidió valoración presencial',
   returned: 'el médico devolvió el caso a navegación',
 };
@@ -2259,6 +2300,7 @@ module.exports = {
   generateBotDraft,
   getEscalationReviewById,
   getReviewTimeline,
+  previewPlanInstructions,
   handOffToDoctor,
   listEscalationReviews,
   openEscalationReview,

package/package.json

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