@peopl-health/nexus 5.69.0 → 5.70.0

package/lib/clinical/services/outreachSweepService.js

@@ -6,8 +6,10 @@ const { getMessages } = require('../../services/messageService');
 const { DEFAULT_TIMEZONE, isWithinHourWindow } = require('../../utils/scheduleUtils');
 const { logger } = require('../../utils/logger');
 const { botIsPaused } = require('../../helpers/pausedThreadHelper');
+const { Thread } = require('../../models/threadModel');
 const { PATIENT_CONTACT_WINDOW } = require('./contingencyDispatchService');
 const { hasPendingReminderForPatient } = require('./clinicalAirtableService');
+const { WriteClaimStore } = require('./writeClaimStore');
 
 const TABLE = 'weekly_questionnaires';
 const VIEW = 'seguimiento_72hrs_principal';
@@ -49,6 +51,11 @@ const AUDIT = {
   turnId: 'seguimiento_turn_id',
 };
 
+const WEEKLY_SOURCE = 'weekly';
+const SCOPE_SOURCE = 'patient_scope';
+
+const sweepClaims = new WriteClaimStore({ namespace: 'outreach_sweep', ttlMs: 8 * 24 * 60 * 60 * 1000 });
+
 const UNDELIVERED_STATUSES = ['failed', 'undelivered'];
 const CONTACT_SENT = {
   from_me: true,
@@ -203,6 +210,56 @@ function buildCandidates(rows, { now, cadence = 'daily', mode = 'continuity' })
   return { candidates, targetDays, weekday, cadence, mode };
 }
 
+function firstWord(value) {
+  return String(value || '').trim().split(/\s+/)[0];
+}
+
+function buildScopeCandidates({ threads, excludedCodes }) {
+  const threadsByCode = new Map();
+  for (const thread of threads) threadsByCode.set(thread.code, [...(threadsByCode.get(thread.code) || []), thread]);
+
+  const candidates = [];
+  for (const [code, docs] of threadsByCode) {
+    const [thread] = docs.sort((a, b) => String(a._id).localeCompare(String(b._id)));
+    const name = firstWord(thread.nombre);
+    const names = new Set(docs.map((doc) => firstWord(doc.nombre).toLowerCase()));
+    if (excludedCodes.has(code) || !name || names.size !== 1 || !thread.patient_id) continue;
+    candidates.push({
+      source: SCOPE_SOURCE,
+      patientId: thread.patient_id,
+      recordId: String(thread._id),
+      code,
+      name,
+      reason: 'no_triage_history',
+      rows: [],
+      brief: {
+        reason: 'no hay un triaje contestado que sirva como ancla clínica',
+        lastTriageAt: null,
+        maxGrade: null,
+        positiveSymptoms: [],
+      },
+    });
+  }
+  return candidates;
+}
+
+async function loadScopeCandidates({ now, viewRows, patientScope }) {
+  const weekStart = startOfLocalWeek(now).toISOString();
+  const [threads, weekRows] = await Promise.all([
+    Thread.find({ code: { $in: patientScope } }, { code: 1, nombre: 1, patient_id: 1 }).lean(),
+    airtableService.getRecordByFilter(
+      Symptoms_ID, TABLE, `NOT(IS_BEFORE({${F.createdAt}}, DATETIME_PARSE("${weekStart}")))`, null, [F.whatsapp],
+    ),
+  ]);
+  const excludedCodes = new Set([...viewRows, ...(weekRows || [])]
+    .map((row) => String(first(row[F.whatsapp]) || '').trim()));
+  return buildScopeCandidates({ threads: threads || [], excludedCodes });
+}
+
+function sweepClaimKey(candidate, now) {
+  return `${candidate.code}:${startOfLocalWeek(now).format('YYYY-MM-DD')}`;
+}
+
 function opsOptedOut(candidate, { now }) {
   const weekStart = startOfLocalWeek(now);
   for (const row of candidate.rows) {
@@ -238,9 +295,12 @@ async function rejectionReason(candidate, {
 } = {}) {
   const opsReason = opsOptedOut(candidate, { now });
   if (opsReason) return opsReason;
+  if (await Thread.exists({ code: candidate.code, outreachOptOut: true })) return 'outreach_opt_out';
   if (await botIsPaused(candidate.code, { label: '[outreachSweep]' })) return 'bot_paused';
   if (!includePreviouslySwept) {
-    const sweptReason = priorSweepReason(candidate);
+    const sweptReason = candidate.source === SCOPE_SOURCE
+      ? (await sweepClaims.has(sweepClaimKey(candidate, now)) ? 'already_swept_this_week' : null)
+      : priorSweepReason(candidate);
     if (sweptReason) return sweptReason;
 
     const since = mode === 'monday_triage_recovery'
@@ -359,8 +419,10 @@ async function enrichBrief(candidate) {
 // so a second overlapping sweep sees this one and stands down. A turn that then dies leaves the
 // patient uncontacted for the week, which is the safe direction: a free-text send carries no
 // contentSid and no idempotency key, so nothing downstream would catch a duplicate.
-async function claimCandidate({ candidate, weekdayLabel, dryRun }) {
+async function claimCandidate({ candidate, weekdayLabel, dryRun, now }) {
   if (dryRun) return true;
+  if ((await sweepClaims.acquire(sweepClaimKey(candidate, now))) !== 'acquired') return false;
+  if (candidate.source === SCOPE_SOURCE) return true;
   try {
     const claimed = await airtableService.updateRecordByFilter(
       Symptoms_ID,
@@ -383,7 +445,7 @@ async function claimCandidate({ candidate, weekdayLabel, dryRun }) {
 }
 
 async function recordOutcome({ candidate, outcome, weekdayLabel, dryRun }) {
-  if (dryRun) return;
+  if (dryRun || candidate.source === SCOPE_SOURCE) return;
   // Three outcomes, not two: a `write` whose delivery never happened is neither "escrito" nor a
   // deliberate hold, and collapsing it into either would hide the failure from the ops queue.
   let stamp;
@@ -422,6 +484,7 @@ async function runOutreachSweep({
   includePreviouslySwept = false,
   cadence = 'daily',
   mode = 'continuity',
+  source = WEEKLY_SOURCE,
   runOutreachTurn,
 } = {}) {
   if (typeof runOutreachTurn !== 'function') {
@@ -443,6 +506,12 @@ async function runOutreachSweep({
   if (!['continuity', 'monday_triage_recovery'].includes(mode)) {
     throw new Error('mode must be continuity or monday_triage_recovery');
   }
+  if (![WEEKLY_SOURCE, SCOPE_SOURCE].includes(source)) {
+    throw new Error('source must be weekly or patient_scope');
+  }
+  if (source === SCOPE_SOURCE && (mode !== 'continuity' || cadence !== 'daily' || !Array.isArray(patientScope))) {
+    throw new Error('the patient_scope source requires continuity mode, daily cadence and a patientScope');
+  }
 
   const localWeekday = moment.tz(now, DEFAULT_TIMEZONE).isoWeekday();
   if (mode === 'monday_triage_recovery' && localWeekday !== 1) {
@@ -460,7 +529,9 @@ async function runOutreachSweep({
   const rows = await airtableService.getRecordByFilter(
     Symptoms_ID, TABLE, 'TRUE()', mode === 'monday_triage_recovery' ? null : VIEW, Object.values(F), true,
   );
-  const { candidates, targetDays, weekday } = buildCandidates(rows || [], { now, cadence, mode });
+  const { candidates, targetDays, weekday } = source === SCOPE_SOURCE
+    ? { candidates: await loadScopeCandidates({ now, viewRows: rows || [], patientScope }), targetDays: [], weekday: localWeekday }
+    : buildCandidates(rows || [], { now, cadence, mode });
   if (cadence === 'legacy' && !targetDays.length) {
     logger.info('[outreachSweep] not a sweep day — nothing to do', { weekday });
     return { ran: false, weekday, reason: 'not_a_sweep_day', counts: {} };
@@ -498,7 +569,7 @@ async function runOutreachSweep({
   const weekdayLabel = moment.tz(now, DEFAULT_TIMEZONE).locale('es').format('dddd');
   const decisions = await mapWithConcurrency(admitted, concurrency, async (candidate) => {
     const brief = await enrichBrief(candidate);
-    if (!dryRun && !await claimCandidate({ candidate, weekdayLabel, dryRun })) {
+    if (!dryRun && !await claimCandidate({ candidate, weekdayLabel, dryRun, now })) {
       counts.rejected++;
       rejectedBy.claim_lost = (rejectedBy.claim_lost || 0) + 1;
       return { code: candidate.code, recordId: candidate.recordId, decision: 'skipped', holdReason: 'claim_lost' };
@@ -549,12 +620,13 @@ async function runOutreachSweep({
   });
 
   logger.info('[outreachSweep] complete', { dryRun, counts, rejectedBy });
-  return { ran: true, weekday, cadence, mode, targetDays, dryRun, counts, rejectedBy, decisions };
+  return { ran: true, weekday, cadence, mode, source, targetDays, dryRun, counts, rejectedBy, decisions };
 }
 
 module.exports = {
   runOutreachSweep,
   buildCandidates,
+  buildScopeCandidates,
   rejectionReason,
   priorSweepReason,
   TARGET_DAYS_BY_WEEKDAY,
@@ -566,4 +638,5 @@ module.exports = {
   VIEW,
   F,
   AUDIT,
+  sweepClaims,
 };

package/lib/index.d.ts

@@ -501,6 +501,7 @@ declare module '@peopl-health/nexus' {
     ran: boolean;
     weekday: number;
     mode?: 'continuity' | 'monday_triage_recovery';
+    source?: 'weekly' | 'patient_scope';
     targetDays?: string[];
     dryRun?: boolean;
     counts: Record<string, number>;
@@ -520,6 +521,8 @@ declare module '@peopl-health/nexus' {
     mode?: 'continuity' | 'monday_triage_recovery';
     /** daily: patients inactive for 7+ days. legacy: the Thursday/Saturday post-triage cohort (Mon/Tue and Wed/Thu triages). */
     cadence?: 'daily' | 'legacy';
+    /** weekly: the triage questionnaire view. patient_scope: the scoped patients outside that view; requires continuity, daily and a patientScope. */
+    source?: 'weekly' | 'patient_scope';
   }): Promise<OutreachSweepResult>;
 
   export const routes: any;

package/lib/models/threadModel.js

@@ -10,6 +10,7 @@ const threadSchema = new mongoose.Schema({
   run_id: { type: String, default: null },
   nombre: { type: String, default: null },
   stopped: { type: Boolean, default: false },
+  outreachOptOut: { type: Boolean, default: false },
   pausedAt: { type: Date, default: null },
   doNotAlertThrough: { type: Date, default: null },
   review: { type: Boolean, default: false },

package/package.json

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