HealthLog/src/lib/analytics/bp-in-target.ts

/**
 * BP-in-target percentage helper.
 *
 * The "BD im Zielbereich" tile on the dashboard reports the share of
 * recent blood-pressure readings that are at or below the user's
 * age-band ceiling. Up to v1.4.14 this lived inline in
 * `src/app/api/analytics/route.ts` and had two latent bugs that made
 * the tile read 0 % even when the user clearly had readings inside the
 * target band:
 *
 * 1. **Wrong denominator (v1.4.14).** The legacy code divided
 *    `inTarget / sysData.length`, but readings are only countable when
 *    a matching diastolic exists within 5 minutes. v1.4.15 A4 fixed the
 *    denominator to count only paired readings.
 *
 * 2. **Wrong target semantics (v1.4.15 -> v1.4.16 A2 regression).** The
 *    v1.4.15 fix kept the original "within narrow goal band" semantics:
 *    `sys >= sysLow && sys <= sysHigh && dia >= diaLow && dia <= diaHigh`.
 *    With ESH 2023 narrow targets (Sys 120-129, Dia 70-79 for under-65)
 *    this collapses to 0 % for healthy normotensive users whose
 *    readings sit BELOW the goal band — Marc's actual data has many
 *    readings like 117/79 (textbook normotensive, well-controlled) that
 *    were marked OUT of target because sys < 120. Users intuitively
 *    consider those readings *in target* — and so does clinical
 *    practice ("BP is well-controlled" = "at goal or below the goal
 *    ceiling, not implausibly hypotensive"). The v1.4.16 fix changes
 *    semantics from a narrow band to a one-sided ceiling check with a
 *    clinical floor for true hypotension:
 *
 *      in-target := sys >= 90 AND sys <= sysHigh
 *                  AND dia >= 50 AND dia <= diaHigh
 *
 *    The 90/50 floors are well below any plausible "normal-low" and
 *    flag symptomatic hypotension as out-of-target instead of silently
 *    counting it as good control.
 *
 * 3. **No fallback when timestamps don't pair (v1.4.15 fix).** Withings
 *    imports and moodLog.app imports each write sys + dia as separate
 *    Measurement rows that ought to share a `measuredAt` to the second
 *    — but rounding through different timezones can drift them by
 *    minutes. The 5-minute window was tight; data imported with
 *    hour-level rounding (some legacy Withings ranges) had `timeDiff >
 *    5 min`. The fallback to same-Berlin-day pairing covers that.
 *
 * Pure & deterministic so the unit test suite can pin the exact %.
 */
import type { BpTargets } from "./bp-targets";

export interface BpReading {
  measuredAt: Date;
  value: number;
}

/**
 * Clinical floors below which a reading is symptomatic hypotension and
 * NOT a desirable "well-controlled BP" outcome. Roughly mid-band
 * shock-onset thresholds; well below any reasonable normotensive
 * resting reading.
 */
const SYS_HYPOTENSION_FLOOR = 90;
const DIA_HYPOTENSION_FLOOR = 50;

const BERLIN_DAY_FORMATTER = new Intl.DateTimeFormat("en-CA", {
  timeZone: "Europe/Berlin",
  year: "numeric",
  month: "2-digit",
  day: "2-digit",
});

function toBerlinDayKey(date: Date): string {
  // en-CA gives us the YYYY-MM-DD shape directly.
  return BERLIN_DAY_FORMATTER.format(date);
}

/**
 * Pair a systolic reading with its closest diastolic by absolute time
 * delta. Returns the time delta (ms) and the matched dia, or `null` if
 * the dia list is empty.
 */
function findClosestDia(
  sys: BpReading,
  diaSeries: BpReading[],
): { dia: BpReading; deltaMs: number } | null {
  if (diaSeries.length === 0) return null;
  let bestDia = diaSeries[0];
  let bestDelta = Math.abs(
    diaSeries[0].measuredAt.getTime() - sys.measuredAt.getTime(),
  );
  for (let i = 1; i < diaSeries.length; i++) {
    const candidate = diaSeries[i];
    const delta = Math.abs(
      candidate.measuredAt.getTime() - sys.measuredAt.getTime(),
    );
    if (delta < bestDelta) {
      bestDelta = delta;
      bestDia = candidate;
    }
  }
  return { dia: bestDia, deltaMs: bestDelta };
}

/**
 * `true` when a paired reading is at or below the upper bound for both
 * sys and dia, AND above the clinical hypotension floors. This is the
 * canonical "BP in target" definition shared across every call site
 * (dashboard tile, insight cards, AI snapshot, comprehensive endpoint,
 * targets endpoint). Exported so the other modules don't drift.
 */
export function isBpReadingInTarget(
  sys: number,
  dia: number,
  targets: BpTargets,
): boolean {
  return (
    sys >= SYS_HYPOTENSION_FLOOR &&
    sys <= targets.sysHigh &&
    dia >= DIA_HYPOTENSION_FLOOR &&
    dia <= targets.diaHigh
  );
}

/**
 * Compute the share (0-100, rounded to nearest integer) of paired BP
 * readings inside `targets` over the supplied series. Returns `null`
 * when no pairs can be formed (caller renders the tile as "no data"
 * instead of 0 %).
 *
 * Pairing strategy:
 *   1. For each sys reading, find the closest dia by absolute time
 *      delta.
 *   2. Accept the pair if `deltaMs <= 5 minutes` (legacy bound) — same
 *      session.
 *   3. Otherwise accept the pair if both share the same Berlin
 *      calendar day (handles imports rounded to the hour or to noon).
 *   4. Discard otherwise.
 *
 * Denominator is the number of accepted pairs, NOT `sysData.length` —
 * that was the v1.4.14 bug that made the tile read 0 % when imports
 * had drifted timestamps.
 *
 * In-target check is the one-sided ceiling defined by
 * `isBpReadingInTarget()` — see file-header comment for the rationale.
 */
export function computeBpInTargetPct(
  sysSeries: BpReading[],
  diaSeries: BpReading[],
  targets: BpTargets,
): { pct: number; pairs: number } | null {
  if (sysSeries.length === 0 || diaSeries.length === 0) return null;

  const SAME_SESSION_MS = 5 * 60 * 1000;
  let pairs = 0;
  let inTarget = 0;

  for (const sys of sysSeries) {
    const match = findClosestDia(sys, diaSeries);
    if (!match) continue;

    const sameSession = match.deltaMs <= SAME_SESSION_MS;
    const sameBerlinDay =
      !sameSession &&
      toBerlinDayKey(sys.measuredAt) === toBerlinDayKey(match.dia.measuredAt);

    if (!sameSession && !sameBerlinDay) continue;

    pairs += 1;
    if (isBpReadingInTarget(sys.value, match.dia.value, targets)) {
      inTarget += 1;
    }
  }

  if (pairs === 0) return null;

  return {
    pct: Math.round((inTarget / pairs) * 100),
    pairs,
  };
}