Merge branch 'feat/v146-server-meds' into feat/v146-server

This commit is contained in:
Marc-André Bombeck committed 2026-10-23 12:41:47 +02:00
commit f942389a4b
53 files changed
+26036 -902

No files matched your search

+86 -16
View File
@@ -421,6 +421,51 @@ function callsSymbol(rel: string, symbol: string): boolean {
return callSites(rel).some((c) => c.name === symbol);
}
/**
* Route modules whose handler bodies live in service modules under `lib/`.
*
* The route keeps the resolver call, so the verb and membership legs read the
* route alone. The legs about what a handler writes (the audit trail, the
* tombstone, the overwrite and destruction details, the provenance a moved
* dose keeps) ask the route AND the modules it hands the body to, because
* that is where the rows are written now. A leg reading only the route would
* go on passing for a reason that has nothing to do with the rule. Each
* listed module has to be imported by its route (leg below), so an entry
* cannot outlive the delegation it describes.
*/
const HANDLER_BODY_MODULES: Record<string, readonly string[]> = {
"app/api/medications/route.ts": ["lib/medications/create-medication.ts"],
"app/api/medications/[id]/intake/[eventId]/route.ts": [
"lib/medications/update-intake-event.ts",
"lib/medications/delete-intake-event.ts",
],
};
/** The route and the service modules carrying its handler bodies. */
function handlerModules(rel: string): string[] {
return [rel, ...(HANDLER_BODY_MODULES[rel] ?? [])];
}
function handlerCallsSymbol(rel: string, symbol: string): boolean {
return handlerModules(rel).some((m) => callsSymbol(m, symbol));
}
function handlerIdentifiers(rel: string): Set<string> {
return new Set(handlerModules(rel).flatMap((m) => [...identifiers(m)]));
}
function handlerAuditDetailKeys(rel: string): string[][] {
return handlerModules(rel).flatMap((m) => auditDetailKeysIn(m));
}
function handlerDirectAuditWrites(rel: string): string[] {
return handlerModules(rel).flatMap((m) => directAuditWritesIn(read(m), m));
}
function handlerText(rel: string): string {
return handlerModules(rel).map(read).join("\n");
}
/**
* v1.37.0 — the exported HTTP verbs whose bodies reach the record resolver at
* a given level.
@@ -2876,9 +2921,10 @@ describe("(e) the delegable write set is frozen", () => {
expect(modules.length).toBeGreaterThan(0);
for (const rel of modules) {
expect(callsSymbol(rel, "auditLog"), `${rel} never calls auditLog`).toBe(
true,
);
expect(
handlerCallsSymbol(rel, "auditLog"),
`${rel} never calls auditLog`,
).toBe(true);
}
});
@@ -2898,7 +2944,7 @@ describe("(e) the delegable write set is frozen", () => {
for (const rel of modules) {
expect(
directAuditWritesIn(read(rel), rel),
handlerDirectAuditWrites(rel),
`${rel} writes an audit row without the helper`,
).toEqual([]);
}
@@ -3015,6 +3061,28 @@ describe("(g) the MANAGE route set is frozen", () => {
expect(discovered).toEqual(expected);
});
it("reads each moved handler body where its route imports it from", () => {
// The map above widens what the audit and tombstone legs read. An entry
// naming a module the route no longer imports would widen it to code the
// handler does not run, so every entry is held to the route's imports,
// and every listed module has to carry an audit call of its own.
const entries = Object.entries(HANDLER_BODY_MODULES);
expect(entries.length).toBeGreaterThan(0);
for (const [route, modules] of entries) {
expect(DELEGABLE_ROUTES, route).toHaveProperty([route]);
for (const body of modules) {
const specifier = `@/${body.replace(/\.ts$/, "")}`;
expect(read(route), `${route} does not import ${specifier}`).toContain(
`"${specifier}"`,
);
expect(
callsSymbol(body, "auditLog"),
`${body} writes no audit row`,
).toBe(true);
}
}
});
it("is a subset of the delegable set", () => {
// A module cannot manage a record it may not read. The read list is where
// each file's argument lives, so a manage entry with no read entry would
@@ -3043,16 +3111,17 @@ describe("(g) the MANAGE route set is frozen", () => {
expect(mutating.length).toBeGreaterThan(30);
for (const rel of mutating) {
expect(callsSymbol(rel, "auditLog"), `${rel} never calls auditLog`).toBe(
true,
);
expect(
handlerCallsSymbol(rel, "auditLog"),
`${rel} never calls auditLog`,
).toBe(true);
}
});
it("no manage module reaches the audit table without the helper", () => {
for (const rel of Object.keys(DELEGABLE_MANAGE_ROUTES)) {
expect(
directAuditWritesIn(read(rel), rel),
handlerDirectAuditWrites(rel),
`${rel} writes an audit row without the helper`,
).toEqual([]);
}
@@ -3071,7 +3140,7 @@ describe("(g) the MANAGE route set is frozen", () => {
for (const rel of destructive) {
const entry = DELEGABLE_MANAGE_ROUTES[rel];
const tombstones = identifiers(rel).has("deletedAt");
const tombstones = handlerIdentifiers(rel).has("deletedAt");
expect(
tombstones ||
entry.conditions.includes("C3") ||
@@ -3092,7 +3161,7 @@ describe("(g) the MANAGE route set is frozen", () => {
for (const [rel, { keys, why }] of members) {
expect(why.trim().length, `${rel} has no reason`).toBeGreaterThan(0);
expect(DELEGABLE_MANAGE_ROUTES, rel).toHaveProperty([rel]);
const carried = auditDetailKeysIn(rel);
const carried = handlerAuditDetailKeys(rel);
expect(carried.length, `${rel} files no audit details`).toBeGreaterThan(
0,
);
@@ -3115,10 +3184,10 @@ describe("(g) the MANAGE route set is frozen", () => {
for (const rel of members) {
if (rel in MANAGE_RECONSTRUCTION_BY_HAND) continue;
expect(
callsSymbol(rel, "destroyedDetails"),
handlerCallsSymbol(rel, "destroyedDetails"),
`${rel} carries C3 and never calls destroyedDetails`,
).toBe(true);
const named = auditDetailKeysIn(rel).some((keys) =>
const named = handlerAuditDetailKeys(rel).some((keys) =>
keys.some((key) => /(^id$|Id$)/.test(key)),
);
expect(named, `${rel} files no id on any audit details literal`).toBe(
@@ -3133,7 +3202,7 @@ describe("(g) the MANAGE route set is frozen", () => {
for (const rel of members) {
expect(
callsSymbol(rel, "overwriteDetails"),
handlerCallsSymbol(rel, "overwriteDetails"),
`${rel} carries C4 and never calls overwriteDetails`,
).toBe(true);
}
@@ -3314,7 +3383,7 @@ describe("(g) the MANAGE route set is frozen", () => {
const medication = "app/api/medications/[id]/route.ts";
expect(manageModulesWith("C7")).toEqual([medication]);
const cadence = auditDetailKeysIn(medication).some(
const cadence = handlerAuditDetailKeys(medication).some(
(keys) =>
keys.includes("replacedCadence") &&
keys.includes("tombstonedSlotCount"),
@@ -3325,14 +3394,15 @@ describe("(g) the MANAGE route set is frozen", () => {
expect(manageModulesWith("C8")).toEqual([dose]);
// The hardcoded provenance this condition removed. A re-created row that
// stamps `WEB` says a human typed a dose that arrived from a device.
expect(read(dose)).not.toContain('createSource: "WEB"');
expect(handlerText(dose)).not.toContain('createSource: "WEB"');
expect(handlerText(dose)).toContain("createSource: event.source");
expect(manageModulesWith("C9")).toEqual([
"app/api/medications/[id]/intake/import/route.ts",
"app/api/medications/intake/dose-history-import/route.ts",
]);
for (const rel of manageModulesWith("C9")) {
const joined = auditDetailKeysIn(rel).some((keys) =>
const joined = handlerAuditDetailKeys(rel).some((keys) =>
keys.includes("jobId"),
);
expect(joined, `${rel} enqueues work no audit row names`).toBe(true);
@@ -1,8 +1,6 @@
import { prisma } from "@/lib/db";
import { apiHandler, requireRecordAuth } from "@/lib/api-handler";
import { annotate } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import { overwriteDetails } from "@/lib/sharing/audit-details";
import {
apiSuccess,
apiError,
@@ -13,22 +11,14 @@ import {
} from "@/lib/api-response";
import { updateIntakeEventSchema } from "@/lib/validations/medication";
import {
consumeForIntake,
restoreForIntake,
} from "@/lib/medications/inventory/consumption";
import { reconcileOneShotState } from "@/lib/medications/lifecycle";
import { invalidateUserMedications } from "@/lib/cache/invalidate";
import { queueMedicationIntakeSync } from "@/lib/notifications/medication-intake-sync";
import { refreshDoseSlot } from "@/lib/medications/dose-day-refresh";
import { dayKeyForUserTz } from "@/lib/measurements/consolidation-tz";
findEditableIntakeEvent,
updateIntakeEvent,
} from "@/lib/medications/update-intake-event";
import {
applyCanonicalSlotWrite,
findPinConflict,
resolveForcedSlotForWrite,
resolveSlotForWriteByBand,
} from "@/lib/medications/scheduling/slot-upsert";
deleteIntakeEvent,
findDeletableIntakeEvent,
} from "@/lib/medications/delete-intake-event";
import { NextRequest } from "next/server";
import { dateOnlyKey } from "@/lib/tz/date-only";
type RouteParams = { params: Promise<{ id: string; eventId: string }> };
@@ -41,13 +31,12 @@ export const PUT = apiHandler(
const { id, eventId } = await params;
// v1.7.0 sync — a tombstoned event 404s on PUT; the `deletedAt: null`
// filter refuses to resurrect-edit a soft-deleted intake.
const event = await prisma.medicationIntakeEvent.findFirst({
where: { id: eventId, deletedAt: null },
const event = await findEditableIntakeEvent({
userId: user.id,
medicationId: id,
eventId,
});
if (!event || event.userId !== user.id || event.medicationId !== id) {
if (!event) {
return apiError("Intake not found", 404);
}
@@ -87,341 +76,20 @@ export const PUT = apiHandler(
return returnAllZodIssues(parsed.error, 422);
}
const data = parsed.data;
// v1.15.19 — start-date guard on an edited `takenAt` (audit P0-4). The
// schema bounds the instant to a plausible absolute range; this check
// adds the per-medication floor: a take cannot predate the day the
// medication starts (calendar-day comparison in the user's timezone, so
// a take in the early hours of the start day never false-rejects).
if (data.takenAt instanceof Date) {
const medication = await prisma.medication.findFirst({
where: { id, userId: user.id },
select: { startsOn: true },
});
if (medication?.startsOn) {
const takenDay = dayKeyForUserTz(data.takenAt, user.timezone);
const startsOnDay = dateOnlyKey(medication.startsOn);
if (takenDay < startsOnDay) {
annotate({
action: {
name: "medications.intake.event.update.before-start-date",
},
meta: { medication_id: id, event_id: eventId },
});
return apiError(
"takenAt is before the medication's start date",
422,
{ errorCode: "medications.intake.taken_at.before_start" },
);
}
}
}
// The post-edit state of the row (current values where the body omits a
// field) — drives the re-attribution decision.
const nextTakenAt =
data.takenAt !== undefined ? data.takenAt : event.takenAt;
const nextSkipped =
data.skipped !== undefined ? data.skipped : event.skipped;
const takenOrSkippedChanged =
(data.takenAt !== undefined &&
data.takenAt?.getTime() !== event.takenAt?.getTime()) ||
(data.skipped !== undefined && data.skipped !== event.skipped);
// v1.15.18 — re-run window-band attribution when the edit moves `takenAt`
// or `skipped`, so an edited time re-binds to the correct slot instead of
// leaving `scheduledFor` stale (audit HIGH-4). Precedence:
// 1. an explicit `scheduledFor` in the body wins (deliberate override);
// 2. else `forceSlotInstant` pins onto a named real slot (422 if it is
// not a slot of this med) — v1.15.20: standalone too, no takenAt /
// skipped change required ("Slot zuordnen" from the ledger kebab),
// and the row is stamped USER_PIN so the read ledger binds it by
// anchor instead of degrading the off-window take back to ad-hoc;
// 3. else an explicit `forceSlotInstant: null` UNPINS (v1.15.20,
// "Zuordnung lösen"): re-attribute the take by band on its takenAt
// (ad-hoc when no band matches). v1.16.0 — the release is itself a
// deliberate binding decision, so the row KEEPS `USER_PIN`
// provenance ("attribution user-fixed": onto a slot OR deliberately
// ad-hoc). The persisted marker is what keeps the nightly slot
// dedup from snapping the released row back into the cluster the
// user just detached it from;
// 4. else a taken edit attributes by band (slot anchor on match, the
// take's own time on a miss → ad-hoc), provenance AUTO;
// 5. a skip / pending edit keeps the existing `scheduledFor` anchor.
let resolvedScheduledFor: Date | undefined = data.scheduledFor;
let attributionSource: "AUTO" | "USER_PIN" | undefined;
if (resolvedScheduledFor === undefined) {
if (
data.forceSlotInstant !== undefined &&
data.forceSlotInstant !== null
) {
const forced = await resolveForcedSlotForWrite({
userId: user.id,
medicationId: id,
userTz: user.timezone,
slotInstant: data.forceSlotInstant,
});
if (forced === null) {
annotate({
action: { name: "medication.intake.force_slot.invalid" },
meta: { medication_id: id, event_id: eventId },
});
return apiError(
"forceSlotInstant is not a scheduled slot of this medication",
422,
{ errorCode: "medications.intake.force_slot.invalid" },
);
}
// v1.16.0 — refuse to pin onto a slot another recorded action
// already serves (excluding the row being edited): the explicit-
// write last-write-wins rule would silently overwrite that dose
// record. The ledger UI only offers the pin for unserved slots,
// so this only fires for stale clients / raw API calls.
if (
await findPinConflict({
userId: user.id,
medicationId: id,
canonicalSlot: forced,
incomingTakenAt: nextSkipped ? null : nextTakenAt,
excludeEventId: eventId,
})
) {
annotate({
action: { name: "medication.intake.force_slot.occupied" },
meta: { medication_id: id, event_id: eventId },
});
return apiError(
"forceSlotInstant already carries a recorded dose action",
422,
{ errorCode: "medications.intake.force_slot.occupied" },
);
}
resolvedScheduledFor = forced;
attributionSource = "USER_PIN";
} else if (
(data.forceSlotInstant === null || takenOrSkippedChanged) &&
nextTakenAt !== null &&
!nextSkipped
) {
const attribution = await resolveSlotForWriteByBand({
userId: user.id,
medicationId: id,
userTz: user.timezone,
takenAt: nextTakenAt,
});
// band.at on match; the take's own time on a miss (ad-hoc).
resolvedScheduledFor = attribution.slotInstant ?? nextTakenAt;
// v1.16.0 — an explicit unpin stays user-fixed (USER_PIN) even on
// the released row; a plain taken/skipped edit re-attributes AUTO.
attributionSource =
data.forceSlotInstant === null ? "USER_PIN" : "AUTO";
} else if (data.forceSlotInstant === null) {
// Unpin on a row that is not a confirmed take (skip / pending):
// nothing to re-attribute, but the provenance still resets — a
// skip / pending row anchors on its slot by construction, so there
// is no user-fixed ad-hoc decision to persist.
attributionSource = "AUTO";
}
// skip / pending edits leave `scheduledFor` on the existing anchor.
}
const targetScheduledFor = resolvedScheduledFor ?? event.scheduledFor;
const slotMoved =
targetScheduledFor.getTime() !== event.scheduledFor.getTime();
// v1.16.10 — transition gate for the inventory hooks below. Only an
// edit moving the row INTO taken may consume; a row that was
// already taken keeps its stamp frozen (a stamped row would no-op
// anyway, and a pre-v1.16.10 taken row — NULL stamp, stock already
// moved by the legacy hook at take time — must never retro-consume
// on a time correction).
const wasTaken = event.takenAt !== null && !event.skipped;
let updated;
if (!slotMoved) {
// The slot is unchanged — a bare in-place update can never collide with
// a sibling row (it is its own slot).
updated = await prisma.medicationIntakeEvent.update({
where: { id: eventId },
data: {
...(data.takenAt !== undefined && { takenAt: data.takenAt }),
...(data.skipped !== undefined && { skipped: data.skipped }),
// v1.15.20 — binding provenance: pin / unpin / band re-attribution
// stamps it even when the anchor itself did not move (e.g. a pin
// onto the slot the row already sits on, or an unpin whose band
// re-attribution lands on the same anchor).
...(attributionSource !== undefined && { attributionSource }),
// v1.42.2 — an edit of the outcome is the person's own record.
...((data.takenAt !== undefined || data.skipped !== undefined) && {
autoRecorded: false,
}),
// v1.7.0 sync — bump the reconciliation counter on every
// server-side mutation so the `/api/sync/changes` feed echoes a
// monotonic value to paired clients.
syncVersion: { increment: 1 },
},
});
// v1.16.10 — inventory follows the post-edit state: an edit that
// moves the row INTO taken consumes; a row that stays taken keeps
// its stamp untouched (the stamp freezes what the original take
// pulled, even when `unitsPerDose` changed since, and a pre-stamp
// legacy row must not retro-consume); a row edited out of taken
// (skip flip, takenAt cleared) refunds its stamp.
if (nextTakenAt !== null && !nextSkipped) {
if (!wasTaken) {
await consumeForIntake({
client: prisma,
userId: user.id,
medicationId: id,
eventId,
intakeAt: nextTakenAt,
});
}
} else {
await restoreForIntake({
client: prisma,
userId: user.id,
eventId,
});
}
} else {
// The edit moved the dose to a different slot. Tombstone the original
// row (the iOS "a correction is a tombstone + re-insert" model the
// DELETE handler documents) and route the corrected dose through the
// shared canonical-slot upsert, which converges onto any row already at
// the target slot (a pending REMINDER row) rather than bare-updating
// into an occupied slot and risking a P2002 (audit HIGH-4).
//
// v1.16.10 — refund the source row's consumption stamp BEFORE the
// tombstone; the consume on the converged row below nets the move
// to exactly one consumption.
await restoreForIntake({
client: prisma,
userId: user.id,
eventId,
});
await prisma.medicationIntakeEvent.update({
where: { id: eventId },
data: { deletedAt: new Date(), syncVersion: { increment: 1 } },
});
const applied = await applyCanonicalSlotWrite({
client: prisma,
userId: user.id,
medicationId: id,
canonicalSlot: targetScheduledFor,
takenAt: nextSkipped ? null : nextTakenAt,
skipped: nextSkipped,
isExplicitTaken: !nextSkipped && nextTakenAt !== null,
isExplicitSkip: nextSkipped,
idempotencyKey: null,
// The converged row keeps the ORIGINAL's provenance. This used
// to be a hardcoded `"WEB"`, which said "somebody typed this in the
// browser" about an Apple Health dose whose time was corrected. Under
// MANAGE the sentence would be wrong about a second person as well.
createSource: event.source,
attributionSource,
// v1.16.9 — a slot move is a re-binding, not a new dose: the
// original row's recorded injection site and dose override ride
// along onto the converged row instead of being tombstoned away.
injectionSite: event.injectionSite,
doseTaken: event.doseTaken,
});
updated = applied.row;
// A taken source WITHOUT a stamp is a pre-v1.16.10 row whose
// stock moved through the legacy hook: the refund above was a
// no-op, so consuming on the converged row would double-charge —
// skip it. Every other taken outcome nets the move to exactly one
// consumption.
if (
nextTakenAt !== null &&
!nextSkipped &&
(!wasTaken || event.inventoryConsumption !== null)
) {
await consumeForIntake({
client: prisma,
userId: user.id,
medicationId: id,
eventId: applied.row.id,
intakeAt: nextTakenAt,
});
}
}
await auditLog("medication.intake.update", {
userId: user.id,
ipAddress: getClientIp(request),
// What the correction moved. A dose edit changes when a dose is
// recorded as taken, which is exactly what a clinician reads back.
details: {
eventId,
medicationId: id,
...overwriteDetails({
before: {
scheduledFor: event.scheduledFor,
takenAt: event.takenAt,
skipped: event.skipped,
},
// The slot-write result carries the canonical four. The injection
// site and the dose override are not compared here because the move
// path copies them onto the converged row by construction — there is
// no edit of them to report.
after: {
scheduledFor: updated.scheduledFor,
takenAt: updated.takenAt,
skipped: updated.skipped,
},
}),
},
});
annotate({
action: {
name: "medication.intake.update",
entity_type: "intake_event",
entity_id: eventId,
},
meta: { medication_id: id },
});
// v1.4.34 — bust per-user medications + compliance + achievement
// caches so the next read reflects the edited event.
invalidateUserMedications(user.id, { evict: true });
// v1.4.39 — refresh the rollup row for both the old + new
// scheduledFor day-keys when the dose moved across a day boundary
// (band re-attribution can move it as well as an explicit edit); if the
// slot is unchanged the second call collapses to a no-op upsert.
await refreshDoseSlot({
userId: user.id,
const outcome = await updateIntakeEvent({
user,
medicationId: id,
scheduledFor: event.scheduledFor,
tz: user.timezone,
});
if (slotMoved) {
await refreshDoseSlot({
userId: user.id,
medicationId: id,
scheduledFor: targetScheduledFor,
tz: user.timezone,
});
}
// v1.5.0 — re-evaluate the one-shot active flag. A skip-flip on the
// single live intake of a one-shot medication should reactivate it
// (the dose is no longer logged), and the reverse case should
// deactivate again. No-op for non-one-shot medications.
await reconcileOneShotState(prisma, id, user.id);
// (#22) — silent cross-device intake sync: an edited dose must
// reconcile on the user's other iOS devices too. Coalesced per user,
// best-effort — never affects the response.
queueMedicationIntakeSync({
userId: user.id,
eventId,
event,
data: parsed.data,
ipAddress: getClientIp(request),
originDeviceToken: request.headers.get("x-device-id"),
});
if (!outcome.ok) {
return apiError(outcome.message, 422, { errorCode: outcome.errorCode });
}
return apiSuccess(updated);
return apiSuccess(outcome.row);
},
);
@@ -433,80 +101,21 @@ export const DELETE = apiHandler(
const { id, eventId } = await params;
const event = await prisma.medicationIntakeEvent.findUnique({
where: { id: eventId },
const event = await findDeletableIntakeEvent({
userId: user.id,
medicationId: id,
eventId,
});
if (!event || event.userId !== user.id || event.medicationId !== id) {
if (!event) {
return apiError("Intake not found", 404);
}
// v1.16.10 — a deleted dose record refunds its consumption stamp
// (no-op for a never-consumed row; a re-delete finds it cleared).
await restoreForIntake({
client: prisma,
userId: user.id,
eventId,
});
// v1.7.0 sync — soft-delete instead of a hard `delete`. An intake is
// an immutable fact, so a "correction" is a tombstone + re-insert
// (never an in-place edit). Setting `deletedAt` (+ bumping
// `syncVersion`) leaves the row in place so the `/api/sync/changes`
// feed surfaces the deletion as a tombstone keyed on the server `id`
// to paired clients offline at delete time. Every today / compliance
// / list read filters `deletedAt: null`, so the row is invisible to
// normal reads from here on. A re-delete re-bumps harmlessly.
await prisma.medicationIntakeEvent.update({
where: { id: eventId },
data: {
deletedAt: new Date(),
syncVersion: { increment: 1 },
},
});
const ip = getClientIp(request) ?? "unknown";
await auditLog("medication.intake.delete", {
userId: user.id,
ipAddress: ip,
details: { eventId, medicationId: id },
});
annotate({
action: {
name: "medication.intake.delete",
entity_type: "intake_event",
entity_id: eventId,
},
meta: { medication_id: id },
});
// v1.4.34 — bust per-user medications + compliance + achievement
// caches so the next read reflects the deletion.
invalidateUserMedications(user.id, { evict: true });
// v1.4.39 — refresh the rollup row for the day the deleted
// event sat on. When that day now holds zero events the helper
// drops the rollup row entirely.
await refreshDoseSlot({
userId: user.id,
await deleteIntakeEvent({
user,
medicationId: id,
scheduledFor: event.scheduledFor,
tz: user.timezone,
});
// v1.5.0 — re-evaluate the one-shot active flag. Deleting the
// single live intake of a one-shot medication reactivates it so
// the dashboard / lists / worker pick it back up. No-op for
// non-one-shot medications.
await reconcileOneShotState(prisma, id, user.id);
// (#22) — silent cross-device intake sync: an undone dose must
// reconcile on the user's other iOS devices (the widget count and a
// pending Live Activity both change). Coalesced per user,
// best-effort — never affects the response.
queueMedicationIntakeSync({
userId: user.id,
eventId,
event,
ipAddress: getClientIp(request) ?? "unknown",
originDeviceToken: request.headers.get("x-device-id"),
});
+17 -464
View File
@@ -1,8 +1,5 @@
import { prisma } from "@/lib/db";
import { Prisma } from "@/generated/prisma/client";
import { apiHandler, requireRecordAuth } from "@/lib/api-handler";
import { annotate, getEvent } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import { annotate } from "@/lib/logging/context";
import {
apiError,
apiSuccess,
@@ -10,45 +7,15 @@ import {
returnAllZodIssues,
safeJson,
} from "@/lib/api-response";
import {
courseRefusalResponse,
resolveCourseFields,
} from "@/lib/medications/courses";
import {
dateOfDayKey,
dayKeyOfDate,
validateCourses,
} from "@/lib/medications/course-window";
import { DEFAULT_TIMEZONE, userDayKey } from "@/lib/tz/format";
import {
createMedicationSchema,
isCustomMedicationCategoryKey,
} from "@/lib/validations/medication";
import { createMedicationSchema } from "@/lib/validations/medication";
import {
unstableExternalIdMeta,
unstableExternalIdShape,
} from "@/lib/validations/external-id";
import {
isAssignableCategory,
resolveMedicationCategories,
setMedicationCategory,
} from "@/lib/medication-category";
import { serializeScheduleRecurrence } from "@/lib/medication-schedule";
import { invalidateUserMedications } from "@/lib/cache/invalidate";
import { readMedicationsListCached } from "@/lib/medications/list-read";
import { serializeScheduleUnitsPerDose } from "@/lib/medications/schedule-units-dto";
import { createMedication } from "@/lib/medications/create-medication";
import { withIdempotency } from "@/lib/idempotency";
import { NextRequest } from "next/server";
import { scheduleWireFields } from "@/lib/medications/intake-tracking";
// v1.32.25 — blast-radius cap on externally-mirrored medications per user.
// A client that mints a fresh `externalId` for the same source concept on
// every sync sweep (a known iOS unstable-key bug class) never matches the
// idempotency triple, so each sweep would otherwise create a new mirror
// row unbounded. Apple's own medication list makes >30 genuinely distinct
// meds implausible, so this caps the damage a buggy client can do without
// breaking any legitimate use.
const APPLE_HEALTH_MIRROR_CAP = 30;
export const GET = apiHandler(async () => {
const { user } = await requireRecordAuth("read", "medications");
@@ -73,66 +40,12 @@ export const GET = apiHandler(async () => {
return apiSuccess(result);
});
/**
* v1.28 — idempotent response for a re-mirrored medication. The create
* route returns the EXISTING row (status 200, vs 201 for a fresh create)
* when the caller re-posts a `(externalSource, externalId)` pair this
* user already mirrors — the iOS re-sync replays its full HealthKit
* medication list, and a replay must neither duplicate nor 500. Response
* shape mirrors the fresh-create envelope (schedules included, category
* joined, Decimal unwrapped); no audit row and no cache eviction because
* nothing was written.
*/
async function respondWithExistingMirror(
medication: Record<string, unknown> & {
id: string;
unitsPerDose: unknown;
trackIntake: boolean;
schedules: Array<{ unitsPerDose: Prisma.Decimal | null }>;
},
): Promise<Response> {
let category = "OTHER";
let categoryLabel: string | null = null;
try {
const categories = await resolveMedicationCategories([medication.id]);
category = categories[medication.id]?.category ?? "OTHER";
categoryLabel = categories[medication.id]?.categoryLabel ?? null;
} catch {
getEvent()?.addWarning("Medication categories could not be loaded");
}
annotate({
action: {
name: "medication.create",
entity_type: "medication",
entity_id: medication.id,
},
meta: { idempotent_replay: true },
});
return apiSuccess({
...medication,
unitsPerDose: Number(medication.unitsPerDose),
// #219 — Decimal → number for the per-schedule column too.
// v1.39.1 (#1033) — record-only medications ship `schedules: []`.
...scheduleWireFields(
medication.trackIntake,
serializeScheduleUnitsPerDose(
medication.schedules,
Number(medication.unitsPerDose),
),
),
category,
categoryLabel,
});
}
/**
* The create is wrapped in `withIdempotency` so a client replaying its offline
* outbox after a lost success response replays the first answer instead of
* minting a second medication. The `(externalSource, externalId)` dedupe below
* only ever covered a MIRRORED create; a manually entered medication carries
* neither field and had nothing to collapse a retry onto.
* minting a second medication. The `(externalSource, externalId)` dedupe in
* `createMedication` only ever covered a MIRRORED create; a manually entered
* medication carries neither field and had nothing to collapse a retry onto.
*/
export const POST = apiHandler(withIdempotency<[NextRequest]>(postMedication));
@@ -165,377 +78,17 @@ async function postMedication(request: NextRequest): Promise<Response> {
return returnAllZodIssues(parsed.error, 422);
}
const {
name,
dose,
category,
treatmentClass,
dosesPerUnit,
unitsPerDose,
reorderLeadDays,
deliveryForm,
trackInjectionSites,
allowedInjectionSites,
notificationsEnabled,
liveActivityEnabled,
criticalAlarmEnabled,
atcCode,
rxNormCode,
externalSource,
externalId,
schedules,
startsOn,
endsOn,
oneShot,
asNeeded,
trackIntake,
autoMarkTaken,
} = parsed.data;
// v1.40 (#1041) — a custom category must be one of this record's own.
if (
category !== undefined &&
!(await isAssignableCategory(user.id, category))
) {
return apiError("Unknown medication category", 422, {
errorCode: "medications.category.unknown",
});
}
// v1.28 — idempotent mirror create. A mirrored medication (Apple
// Health) is keyed by the `(userId, externalSource, externalId)`
// unique; a re-post of the same concept id (iOS re-sync, retry after a
// dropped response) returns the EXISTING medication with 200 instead
// of minting a duplicate or 500-ing on P2002. The pre-query covers the
// common replay; the P2002 catch around the create below covers the
// concurrent race.
if (externalSource !== undefined && externalId !== undefined) {
const existing = await prisma.medication.findFirst({
where: { userId: user.id, externalSource, externalId },
include: { schedules: true },
});
if (existing) {
return respondWithExistingMirror(existing);
}
// v1.32.25 — growth guard. This point is only reached when the
// idempotency lookup MISSED, i.e. this is a genuinely NEW mirror row,
// not a replay of one the user already holds (a replay returned 200
// above). An idempotent re-post of an existing mirror is therefore
// never blocked, even for a user already at the cap. Refuse only the
// minting of a fresh row once the user already holds the cap of
// Apple-Health-mirrored medications, so a client feeding a rotating
// key can no longer fill the list with duplicates. The count runs on
// the mirror-create-miss path only; native creates (no
// `externalSource`) never reach this branch and pay nothing.
const mirroredCount = await prisma.medication.count({
where: { userId: user.id, externalSource: "APPLE_HEALTH" },
});
if (mirroredCount >= APPLE_HEALTH_MIRROR_CAP) {
annotate({
action: { name: "medication.mirror.limit_exceeded" },
meta: { existing: mirroredCount },
});
return apiError(
"This account already mirrors the maximum number of medications from an external source",
422,
{ errorCode: "medications.mirror.limit_exceeded" },
);
}
}
// ── v1.5 route invariants for the new scheduling primitives ───────
//
// The Zod layer already enforces `rrule` xor `rollingIntervalDays`
// (scheduleSchema.refine). The route layer enforces the cross-field
// invariants that span medication + schedules:
//
// 1. **One-shot consistency** — when `oneShot === true`:
// a. The medication has at most ONE schedule.
// b. The single schedule carries neither `rrule` nor
// `rollingIntervalDays` (a one-shot dose IS the schedule).
// c. `endsOn` is normalised to equal `startsOn` on write so the
// worker's date-range cap matches the one-and-only slot.
//
// 2. **Recurring default** — when `oneShot !== true` AND the
// schedule has no `rrule`, no `rollingIntervalDays`, and no
// legacy `daysOfWeek`, the route stamps `rrule = "FREQ=DAILY"`
// so the canonical recurrence engine has a clean shape going
// forward instead of falling through to the legacy parser.
//
// 3. **iOS contract dual-write** — when `timesOfDay` is absent or
// empty, the route stamps `[windowStart]` so the new engine
// always sees a populated `timesOfDay` while legacy iOS clients
// (v0.6.x) keep encoding the `windowStart` / `windowEnd` /
// `daysOfWeek` shape. Both shapes coexist through v1.5.x.
// 4. **As-needed (v1.16.11, #316)** — when `asNeeded === true` the
// medication carries ZERO schedules (the Zod refine already
// rejects a populated array, mutual exclusion with `oneShot`
// included). Every "never due / never reminded / never scored"
// surface follows structurally from the empty schedule list.
const scheduleInputs = schedules ?? [];
if (oneShot === true) {
if (scheduleInputs.length > 1) {
return apiError(
"A one-shot medication can have at most one schedule",
422,
);
}
const s = scheduleInputs[0];
if (s && (s.rrule !== undefined || s.rollingIntervalDays !== undefined)) {
return apiError(
"A one-shot medication cannot have a recurrence (rrule or rollingIntervalDays)",
422,
);
}
}
// Normalise endsOn for one-shot. Zod gives us `Date | null | undefined`.
const normalisedEndsOn =
oneShot === true && startsOn ? startsOn : (endsOn ?? undefined);
// v1.40 (#1024) — a medication created with a window starts with one
// course; the row projects it. An end without a start has always meant
// "running since creation", so the course starts today (or on the end day,
// when that lies earlier). No window: no course, chronic since creation.
let initialCourse: { startsOn: Date; endsOn: Date | null } | null = null;
if (startsOn || normalisedEndsOn) {
const todayKey = userDayKey(new Date(), user.timezone || DEFAULT_TIMEZONE);
const endKey = normalisedEndsOn ? dayKeyOfDate(normalisedEndsOn) : null;
initialCourse = {
startsOn:
startsOn ??
dateOfDayKey(endKey && endKey < todayKey ? endKey : todayKey),
endsOn: normalisedEndsOn ?? null,
};
const refusal = validateCourses(
[initialCourse],
todayKey,
oneShot === true,
);
if (refusal) {
const r = courseRefusalResponse(refusal);
return apiError(r.message, r.status, { errorCode: r.errorCode });
}
}
const createMedication = () =>
prisma.medication.create({
data: {
userId: user.id,
name,
dose,
// v1.4.25 — treatmentClass + dosesPerUnit are optional in the
// wire schema; Prisma fills the default GENERIC when omitted.
...(treatmentClass !== undefined && { treatmentClass }),
...(dosesPerUnit !== undefined && { dosesPerUnit }),
// v1.16.10 — units consumed per dose; Prisma defaults to 1 when omitted.
...(unitsPerDose !== undefined && { unitsPerDose }),
// v1.17.0 — optional reorder lead override; null/omitted = inherit
// the user-level default in the low-stock alert.
...(reorderLeadDays !== undefined && { reorderLeadDays }),
// v1.6.0 — route of administration; Prisma defaults to ORAL when omitted.
...(deliveryForm !== undefined && { deliveryForm }),
// v1.8.5 — injection-site tracking opt-in + per-medication allowed
// sites; Prisma defaults to false / [] when omitted.
...(trackInjectionSites !== undefined && { trackInjectionSites }),
...(allowedInjectionSites !== undefined && { allowedInjectionSites }),
// v1.7.0 — iOS reminder flags; Prisma defaults both to false.
...(liveActivityEnabled !== undefined && { liveActivityEnabled }),
...(criticalAlarmEnabled !== undefined && { criticalAlarmEnabled }),
// v1.9.0 — optional drug-classification codes (ATC / RxNorm).
// Validated for format by Zod; stored verbatim when present.
...(atcCode !== undefined && { atcCode }),
...(rxNormCode !== undefined && { rxNormCode }),
// v1.28 — mirrored-medication provenance (Apple Health). Zod
// enforces the both-or-neither pairing; field-by-field like every
// other column.
...(externalSource !== undefined && { externalSource }),
...(externalId !== undefined && { externalId }),
// v1.5 — wizard's reminders toggle now ships through the create
// payload (was orphaned in the initial diff). Prisma defaults to
// true when omitted, matching the legacy form's behaviour.
...(notificationsEnabled !== undefined && { notificationsEnabled }),
// v1.5 scheduling primitives — pass-through when supplied.
...(startsOn !== undefined && { startsOn }),
...(normalisedEndsOn !== undefined && { endsOn: normalisedEndsOn }),
...(initialCourse && {
startsOn: initialCourse.startsOn,
endsOn: initialCourse.endsOn,
courses: {
create: {
userId: user.id,
startsOn: initialCourse.startsOn,
endsOn: initialCourse.endsOn,
},
},
}),
...(oneShot !== undefined && { oneShot }),
// v1.16.11 — as-needed flag, field-by-field. An asNeeded create
// carries an empty `scheduleInputs`, so the nested create below
// persists zero schedule rows.
...(asNeeded !== undefined && { asNeeded }),
// v1.39.1 (#1033) — intake tracking, field-by-field. Created off,
// the schedule is stored as a record from the start; the column
// default (true) covers every caller that does not send it.
...(trackIntake !== undefined && { trackIntake }),
// v1.42.2 — auto-mark-taken, field-by-field. Created on, the
// auto-take job fills slots from this moment only.
...(autoMarkTaken !== undefined && {
autoMarkTaken,
autoMarkTakenSince: autoMarkTaken ? new Date() : null,
}),
schedules: {
create: scheduleInputs.map((s) => {
// Invariant 2 — default to FREQ=DAILY when nothing else is set.
// v1.7.0 — PRN schedules carry no cadence, so never default
// them to FREQ=DAILY (they would otherwise project + remind).
const hasLegacyDays = (s.daysOfWeek?.length ?? 0) > 0;
const isPrn = s.scheduleType === "PRN";
const defaultedRrule =
!oneShot &&
!isPrn &&
s.rrule === undefined &&
s.rollingIntervalDays === undefined &&
!hasLegacyDays
? "FREQ=DAILY"
: s.rrule;
// Invariant 3 — dual-write `timesOfDay` from windowStart when
// the legacy-shape iOS client doesn't send the new field.
const effectiveTimesOfDay =
s.timesOfDay && s.timesOfDay.length > 0
? s.timesOfDay
: [s.windowStart];
return {
windowStart: s.windowStart,
windowEnd: s.windowEnd,
label: s.label ?? null,
dose: s.dose ?? null,
// #219 — per-schedule inventory units. Field-by-field (no mass
// assignment); absent leaves the column NULL so the consume
// hook inherits the medication-level units_per_dose.
...(s.unitsPerDose !== undefined && {
unitsPerDose: s.unitsPerDose,
}),
daysOfWeek: serializeScheduleRecurrence({
daysOfWeek: s.daysOfWeek ?? [],
intervalWeeks: s.intervalWeeks ?? 1,
}),
// v1.5 first-class times-of-day.
timesOfDay: effectiveTimesOfDay,
...(s.reminderGraceMinutes !== undefined && {
reminderGraceMinutes: s.reminderGraceMinutes,
}),
...(defaultedRrule !== undefined && { rrule: defaultedRrule }),
...(s.rollingIntervalDays !== undefined && {
rollingIntervalDays: s.rollingIntervalDays,
}),
// v1.7.0 — schedule type + cyclic weeks, field-by-field.
...(s.scheduleType !== undefined && {
scheduleType: s.scheduleType,
}),
...(s.cyclicOnWeeks !== undefined && {
cyclicOnWeeks: s.cyclicOnWeeks,
}),
...(s.cyclicOffWeeks !== undefined && {
cyclicOffWeeks: s.cyclicOffWeeks,
}),
// v1.15.18 — per-dose configurable on-time windows. Stored as the
// validated `{ timeOfDay, start, end }[]` JSON; absent leaves the
// column NULL (every slot on the default ±1h derivation).
...(s.doseWindows !== undefined && {
doseWindows: s.doseWindows,
}),
};
}),
},
},
include: { schedules: true },
});
let medication: Awaited<ReturnType<typeof createMedication>>;
try {
medication = await createMedication();
} catch (err: unknown) {
// v1.28 — P2002 on the mirror triple: a concurrent create of the
// same `(userId, externalSource, externalId)` won the race between
// the pre-query above and this insert. Resolve to the winning row
// and answer idempotently instead of 500-ing. Any other unique
// violation (there is none on this table today) rethrows.
const isP2002 =
typeof err === "object" &&
err !== null &&
"code" in err &&
(err as { code: string }).code === "P2002";
if (isP2002 && externalSource !== undefined && externalId !== undefined) {
const winner = await prisma.medication.findFirst({
where: { userId: user.id, externalSource, externalId },
include: { schedules: true },
});
if (winner) return respondWithExistingMirror(winner);
}
throw err;
}
const normalizedCategory = await setMedicationCategory(
medication.id,
category,
);
const categoryLabel = isCustomMedicationCategoryKey(normalizedCategory)
? ((await resolveMedicationCategories([medication.id]))[medication.id]
?.categoryLabel ?? null)
: null;
await auditLog("medication.create", {
userId: user.id,
const outcome = await createMedication({
user,
data: parsed.data,
ipAddress: getClientIp(request),
details: {
medicationId: medication.id,
name,
// v1.42.2 — a medication created with its doses recorded
// automatically says so in its audit row.
autoMarkTaken: medication.autoMarkTaken,
},
});
annotate({
action: {
name: "medication.create",
entity_type: "medication",
entity_id: medication.id,
},
});
// v1.4.34 — bust per-user medications + compliance + achievement
// caches so the next read reflects the new schedule.
invalidateUserMedications(user.id, { evict: true });
return apiSuccess(
{
...medication,
unitsPerDose: Number(medication.unitsPerDose),
// #219 — Decimal → number for the per-schedule column too.
// v1.39.1 (#1033) — record-only medications ship `schedules: []`.
...scheduleWireFields(
medication.trackIntake,
serializeScheduleUnitsPerDose(
medication.schedules,
medication.unitsPerDose,
),
),
category: normalizedCategory,
categoryLabel,
// v1.40 (#1024) — the courses, as every medication read carries them.
...(
await resolveCourseFields(
[medication],
new Date(),
user.timezone || DEFAULT_TIMEZONE,
)
).get(medication.id),
},
201,
);
switch (outcome.kind) {
case "refused":
return apiError(outcome.message, outcome.status, outcome.meta);
case "existing":
return apiSuccess(outcome.body);
case "created":
return apiSuccess(outcome.body, 201);
}
}
+583
View File
@@ -0,0 +1,583 @@
/**
* Create a medication with its nested schedule: `POST /api/medications`.
*
* The route authenticates (WRITE over the `medications` section), reads the
* body and answers the schema refusal; everything from the category check to
* the cache eviction runs here, in the order it always ran. The result says
* what the route answers: a refusal, the existing row of a mirrored concept
* the record already holds, or the new row.
*/
import type { z } from "zod/v4";
import { prisma } from "@/lib/db";
import type { Prisma } from "@/generated/prisma/client";
import { annotate, getEvent } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import type { SessionUser } from "@/lib/auth/session-user";
import {
courseRefusalResponse,
resolveCourseFields,
} from "@/lib/medications/courses";
import {
dateOfDayKey,
dayKeyOfDate,
validateCourses,
} from "@/lib/medications/course-window";
import { DEFAULT_TIMEZONE, userDayKey } from "@/lib/tz/format";
import {
isCustomMedicationCategoryKey,
type createMedicationSchema,
} from "@/lib/validations/medication";
import {
isAssignableCategory,
resolveMedicationCategories,
setMedicationCategory,
} from "@/lib/medication-category";
import { serializeScheduleRecurrence } from "@/lib/medication-schedule";
import { invalidateUserMedications } from "@/lib/cache/invalidate";
import { serializeScheduleUnitsPerDose } from "@/lib/medications/schedule-units-dto";
import { scheduleWireFields } from "@/lib/medications/intake-tracking";
export type CreateMedicationInput = z.output<typeof createMedicationSchema>;
type ScheduleInput = NonNullable<CreateMedicationInput["schedules"]>[number];
/**
* Blast-radius cap on externally-mirrored medications per user. A client
* that mints a fresh `externalId` for the same source concept on every sync
* sweep (a known iOS unstable-key bug class) never matches the idempotency
* triple, so each sweep would otherwise create a new mirror row unbounded.
* Apple's own medication list makes >30 genuinely distinct meds implausible,
* so this caps the damage a buggy client can do without breaking any
* legitimate use.
*/
const APPLE_HEALTH_MIRROR_CAP = 30;
export type CreateMedicationOutcome =
| {
kind: "refused";
message: string;
status: number;
meta?: { errorCode: string };
}
| { kind: "existing"; body: Record<string, unknown> }
| { kind: "created"; body: Record<string, unknown> };
/**
* Idempotent response for a re-mirrored medication. The create returns the
* EXISTING row (status 200, vs 201 for a fresh create) when the caller
* re-posts a `(externalSource, externalId)` pair this user already mirrors —
* the iOS re-sync replays its full HealthKit medication list, and a replay
* must neither duplicate nor 500. Response shape mirrors the fresh-create
* envelope (schedules included, category joined, Decimal unwrapped); no
* audit row and no cache eviction because nothing was written.
*/
async function existingMirrorBody(
medication: Record<string, unknown> & {
id: string;
unitsPerDose: unknown;
trackIntake: boolean;
schedules: Array<{ unitsPerDose: Prisma.Decimal | null }>;
},
): Promise<CreateMedicationOutcome> {
let category = "OTHER";
let categoryLabel: string | null = null;
try {
const categories = await resolveMedicationCategories([medication.id]);
category = categories[medication.id]?.category ?? "OTHER";
categoryLabel = categories[medication.id]?.categoryLabel ?? null;
} catch {
getEvent()?.addWarning("Medication categories could not be loaded");
}
annotate({
action: {
name: "medication.create",
entity_type: "medication",
entity_id: medication.id,
},
meta: { idempotent_replay: true },
});
return {
kind: "existing",
body: {
...medication,
unitsPerDose: Number(medication.unitsPerDose),
// #219 — Decimal → number for the per-schedule column too.
// (#1033) — record-only medications ship `schedules: []`.
...scheduleWireFields(
medication.trackIntake,
serializeScheduleUnitsPerDose(
medication.schedules,
Number(medication.unitsPerDose),
),
),
category,
categoryLabel,
},
};
}
/**
* Idempotent mirror create. A mirrored medication (Apple Health) is keyed by
* the `(userId, externalSource, externalId)` unique; a re-post of the same
* concept id (iOS re-sync, retry after a dropped response) returns the
* EXISTING medication with 200 instead of minting a duplicate or 500-ing on
* P2002. The pre-query covers the common replay; the P2002 catch around the
* create covers the concurrent race. Null when the create goes ahead.
*/
async function existingMirrorOrCap(
userId: string,
externalSource: NonNullable<CreateMedicationInput["externalSource"]>,
externalId: string,
): Promise<CreateMedicationOutcome | null> {
const existing = await prisma.medication.findFirst({
where: { userId, externalSource, externalId },
include: { schedules: true },
});
if (existing) {
return existingMirrorBody(existing);
}
// Growth guard. This point is only reached when the idempotency lookup
// MISSED, i.e. this is a genuinely NEW mirror row, not a replay of one the
// user already holds (a replay returned 200 above). An idempotent re-post
// of an existing mirror is therefore never blocked, even for a user already
// at the cap. Refuse only the minting of a fresh row once the user already
// holds the cap of Apple-Health-mirrored medications, so a client feeding a
// rotating key can no longer fill the list with duplicates. The count runs
// on the mirror-create-miss path only; native creates (no `externalSource`)
// never reach this branch and pay nothing.
const mirroredCount = await prisma.medication.count({
where: { userId, externalSource: "APPLE_HEALTH" },
});
if (mirroredCount >= APPLE_HEALTH_MIRROR_CAP) {
annotate({
action: { name: "medication.mirror.limit_exceeded" },
meta: { existing: mirroredCount },
});
return {
kind: "refused",
message:
"This account already mirrors the maximum number of medications from an external source",
status: 422,
meta: { errorCode: "medications.mirror.limit_exceeded" },
};
}
return null;
}
/**
* Route invariants for the scheduling primitives.
*
* The Zod layer already enforces `rrule` xor `rollingIntervalDays`
* (scheduleSchema.refine). This layer enforces the cross-field invariants
* that span medication + schedules:
*
* 1. **One-shot consistency** — when `oneShot === true`:
* a. The medication has at most ONE schedule.
* b. The single schedule carries neither `rrule` nor
* `rollingIntervalDays` (a one-shot dose IS the schedule).
* c. `endsOn` is normalised to equal `startsOn` on write so the
* worker's date-range cap matches the one-and-only slot.
*
* 2. **Recurring default** — when `oneShot !== true` AND the schedule has
* no `rrule`, no `rollingIntervalDays`, and no legacy `daysOfWeek`, the
* create stamps `rrule = "FREQ=DAILY"` so the canonical recurrence
* engine has a clean shape going forward instead of falling through to
* the legacy parser.
*
* 3. **iOS contract dual-write** — when `timesOfDay` is absent or empty,
* the create stamps `[windowStart]` so the new engine always sees a
* populated `timesOfDay` while legacy iOS clients (v0.6.x) keep encoding
* the `windowStart` / `windowEnd` / `daysOfWeek` shape. Both shapes
* coexist.
* 4. **As-needed (#316)** — when `asNeeded === true` the medication carries
* ZERO schedules (the Zod refine already rejects a populated array,
* mutual exclusion with `oneShot` included). Every "never due / never
* reminded / never scored" surface follows structurally from the empty
* schedule list.
*/
function refuseOneShotShape(
oneShot: boolean | undefined,
scheduleInputs: readonly ScheduleInput[],
): CreateMedicationOutcome | null {
if (oneShot === true) {
if (scheduleInputs.length > 1) {
return {
kind: "refused",
message: "A one-shot medication can have at most one schedule",
status: 422,
};
}
const s = scheduleInputs[0];
if (s && (s.rrule !== undefined || s.rollingIntervalDays !== undefined)) {
return {
kind: "refused",
message:
"A one-shot medication cannot have a recurrence (rrule or rollingIntervalDays)",
status: 422,
};
}
}
return null;
}
/**
* A medication created with a window starts with one course; the row
* projects it (#1024). An end without a start has always meant "running
* since creation", so the course starts today (or on the end day, when that
* lies earlier). No window: no course, chronic since creation.
*/
function resolveInitialCourse(
timezone: string,
startsOn: Date | null | undefined,
normalisedEndsOn: Date | undefined,
oneShot: boolean | undefined,
):
| { initialCourse: { startsOn: Date; endsOn: Date | null } | null }
| { refusal: CreateMedicationOutcome } {
let initialCourse: { startsOn: Date; endsOn: Date | null } | null = null;
if (startsOn || normalisedEndsOn) {
const todayKey = userDayKey(new Date(), timezone || DEFAULT_TIMEZONE);
const endKey = normalisedEndsOn ? dayKeyOfDate(normalisedEndsOn) : null;
initialCourse = {
startsOn:
startsOn ??
dateOfDayKey(endKey && endKey < todayKey ? endKey : todayKey),
endsOn: normalisedEndsOn ?? null,
};
const refusal = validateCourses(
[initialCourse],
todayKey,
oneShot === true,
);
if (refusal) {
const r = courseRefusalResponse(refusal);
return {
refusal: {
kind: "refused",
message: r.message,
status: r.status,
meta: { errorCode: r.errorCode },
},
};
}
}
return { initialCourse };
}
/** One nested schedule row, field-by-field from the parsed input. */
function scheduleCreateData(s: ScheduleInput, oneShot: boolean | undefined) {
// Invariant 2 — default to FREQ=DAILY when nothing else is set. PRN
// schedules carry no cadence, so never default them to FREQ=DAILY (they
// would otherwise project + remind).
const hasLegacyDays = (s.daysOfWeek?.length ?? 0) > 0;
const isPrn = s.scheduleType === "PRN";
const defaultedRrule =
!oneShot &&
!isPrn &&
s.rrule === undefined &&
s.rollingIntervalDays === undefined &&
!hasLegacyDays
? "FREQ=DAILY"
: s.rrule;
// Invariant 3 — dual-write `timesOfDay` from windowStart when the
// legacy-shape iOS client doesn't send the new field.
const effectiveTimesOfDay =
s.timesOfDay && s.timesOfDay.length > 0 ? s.timesOfDay : [s.windowStart];
return {
windowStart: s.windowStart,
windowEnd: s.windowEnd,
label: s.label ?? null,
dose: s.dose ?? null,
// #219 — per-schedule inventory units. Field-by-field (no mass
// assignment); absent leaves the column NULL so the consume hook
// inherits the medication-level units_per_dose.
...(s.unitsPerDose !== undefined && {
unitsPerDose: s.unitsPerDose,
}),
daysOfWeek: serializeScheduleRecurrence({
daysOfWeek: s.daysOfWeek ?? [],
intervalWeeks: s.intervalWeeks ?? 1,
}),
// First-class times-of-day.
timesOfDay: effectiveTimesOfDay,
...(s.reminderGraceMinutes !== undefined && {
reminderGraceMinutes: s.reminderGraceMinutes,
}),
...(defaultedRrule !== undefined && { rrule: defaultedRrule }),
...(s.rollingIntervalDays !== undefined && {
rollingIntervalDays: s.rollingIntervalDays,
}),
// Schedule type + cyclic weeks, field-by-field.
...(s.scheduleType !== undefined && {
scheduleType: s.scheduleType,
}),
...(s.cyclicOnWeeks !== undefined && {
cyclicOnWeeks: s.cyclicOnWeeks,
}),
...(s.cyclicOffWeeks !== undefined && {
cyclicOffWeeks: s.cyclicOffWeeks,
}),
// Per-dose configurable on-time windows. Stored as the validated
// `{ timeOfDay, start, end }[]` JSON; absent leaves the column NULL
// (every slot on the default ±1h derivation).
...(s.doseWindows !== undefined && {
doseWindows: s.doseWindows,
}),
};
}
/** The insert itself, field-by-field from the parsed input. */
function insertMedication(
userId: string,
data: CreateMedicationInput,
shape: {
scheduleInputs: readonly ScheduleInput[];
normalisedEndsOn: Date | undefined;
initialCourse: { startsOn: Date; endsOn: Date | null } | null;
},
) {
const {
name,
dose,
treatmentClass,
dosesPerUnit,
unitsPerDose,
reorderLeadDays,
deliveryForm,
trackInjectionSites,
allowedInjectionSites,
notificationsEnabled,
liveActivityEnabled,
criticalAlarmEnabled,
atcCode,
rxNormCode,
externalSource,
externalId,
startsOn,
oneShot,
asNeeded,
trackIntake,
autoMarkTaken,
} = data;
const { scheduleInputs, normalisedEndsOn, initialCourse } = shape;
return prisma.medication.create({
data: {
userId,
name,
dose,
// treatmentClass + dosesPerUnit are optional in the wire schema; Prisma
// fills the default GENERIC when omitted.
...(treatmentClass !== undefined && { treatmentClass }),
...(dosesPerUnit !== undefined && { dosesPerUnit }),
// Units consumed per dose; Prisma defaults to 1 when omitted.
...(unitsPerDose !== undefined && { unitsPerDose }),
// Optional reorder lead override; null/omitted = inherit the
// user-level default in the low-stock alert.
...(reorderLeadDays !== undefined && { reorderLeadDays }),
// Route of administration; Prisma defaults to ORAL when omitted.
...(deliveryForm !== undefined && { deliveryForm }),
// Injection-site tracking opt-in + per-medication allowed sites; Prisma
// defaults to false / [] when omitted.
...(trackInjectionSites !== undefined && { trackInjectionSites }),
...(allowedInjectionSites !== undefined && { allowedInjectionSites }),
// iOS reminder flags; Prisma defaults both to false.
...(liveActivityEnabled !== undefined && { liveActivityEnabled }),
...(criticalAlarmEnabled !== undefined && { criticalAlarmEnabled }),
// Optional drug-classification codes (ATC / RxNorm). Validated for
// format by Zod; stored verbatim when present.
...(atcCode !== undefined && { atcCode }),
...(rxNormCode !== undefined && { rxNormCode }),
// Mirrored-medication provenance (Apple Health). Zod enforces the
// both-or-neither pairing; field-by-field like every other column.
...(externalSource !== undefined && { externalSource }),
...(externalId !== undefined && { externalId }),
// The wizard's reminders toggle ships through the create payload.
// Prisma defaults to true when omitted, matching the legacy form's
// behaviour.
...(notificationsEnabled !== undefined && { notificationsEnabled }),
// Scheduling primitives — pass-through when supplied.
...(startsOn !== undefined && { startsOn }),
...(normalisedEndsOn !== undefined && { endsOn: normalisedEndsOn }),
...(initialCourse && {
startsOn: initialCourse.startsOn,
endsOn: initialCourse.endsOn,
courses: {
create: {
userId,
startsOn: initialCourse.startsOn,
endsOn: initialCourse.endsOn,
},
},
}),
...(oneShot !== undefined && { oneShot }),
// As-needed flag, field-by-field. An asNeeded create carries an empty
// `scheduleInputs`, so the nested create below persists zero schedule
// rows.
...(asNeeded !== undefined && { asNeeded }),
// (#1033) — intake tracking, field-by-field. Created off, the schedule
// is stored as a record from the start; the column default (true)
// covers every caller that does not send it.
...(trackIntake !== undefined && { trackIntake }),
// Auto-mark-taken, field-by-field. Created on, the auto-take job fills
// slots from this moment only.
...(autoMarkTaken !== undefined && {
autoMarkTaken,
autoMarkTakenSince: autoMarkTaken ? new Date() : null,
}),
schedules: {
create: scheduleInputs.map((s) => scheduleCreateData(s, oneShot)),
},
},
include: { schedules: true },
});
}
export async function createMedication(input: {
user: Pick<SessionUser, "id" | "timezone">;
data: CreateMedicationInput;
ipAddress: string | null;
}): Promise<CreateMedicationOutcome> {
const { user, data } = input;
const {
name,
category,
externalSource,
externalId,
schedules,
startsOn,
endsOn,
oneShot,
} = data;
// (#1041) — a custom category must be one of this record's own.
if (
category !== undefined &&
!(await isAssignableCategory(user.id, category))
) {
return {
kind: "refused",
message: "Unknown medication category",
status: 422,
meta: { errorCode: "medications.category.unknown" },
};
}
if (externalSource !== undefined && externalId !== undefined) {
const mirror = await existingMirrorOrCap(
user.id,
externalSource,
externalId,
);
if (mirror) return mirror;
}
const scheduleInputs = schedules ?? [];
const oneShotRefusal = refuseOneShotShape(oneShot, scheduleInputs);
if (oneShotRefusal) return oneShotRefusal;
// Normalise endsOn for one-shot. Zod gives us `Date | null | undefined`.
const normalisedEndsOn =
oneShot === true && startsOn ? startsOn : (endsOn ?? undefined);
const course = resolveInitialCourse(
user.timezone,
startsOn,
normalisedEndsOn,
oneShot,
);
if ("refusal" in course) return course.refusal;
const { initialCourse } = course;
let medication: Awaited<ReturnType<typeof insertMedication>>;
try {
medication = await insertMedication(user.id, data, {
scheduleInputs,
normalisedEndsOn,
initialCourse,
});
} catch (err: unknown) {
// P2002 on the mirror triple: a concurrent create of the same
// `(userId, externalSource, externalId)` won the race between the
// pre-query above and this insert. Resolve to the winning row and answer
// idempotently instead of 500-ing. Any other unique violation (there is
// none on this table today) rethrows.
const isP2002 =
typeof err === "object" &&
err !== null &&
"code" in err &&
(err as { code: string }).code === "P2002";
if (isP2002 && externalSource !== undefined && externalId !== undefined) {
const winner = await prisma.medication.findFirst({
where: { userId: user.id, externalSource, externalId },
include: { schedules: true },
});
if (winner) return existingMirrorBody(winner);
}
throw err;
}
const normalizedCategory = await setMedicationCategory(
medication.id,
category,
);
const categoryLabel = isCustomMedicationCategoryKey(normalizedCategory)
? ((await resolveMedicationCategories([medication.id]))[medication.id]
?.categoryLabel ?? null)
: null;
await auditLog("medication.create", {
userId: user.id,
ipAddress: input.ipAddress,
details: {
medicationId: medication.id,
name,
// A medication created with its doses recorded automatically says so
// in its audit row.
autoMarkTaken: medication.autoMarkTaken,
},
});
annotate({
action: {
name: "medication.create",
entity_type: "medication",
entity_id: medication.id,
},
});
// Bust per-user medications + compliance + achievement caches so the next
// read reflects the new schedule.
invalidateUserMedications(user.id, { evict: true });
return {
kind: "created",
body: {
...medication,
unitsPerDose: Number(medication.unitsPerDose),
// #219 — Decimal → number for the per-schedule column too.
// (#1033) — record-only medications ship `schedules: []`.
...scheduleWireFields(
medication.trackIntake,
serializeScheduleUnitsPerDose(
medication.schedules,
medication.unitsPerDose,
),
),
category: normalizedCategory,
categoryLabel,
// (#1024) — the courses, as every medication read carries them.
...(
await resolveCourseFields(
[medication],
new Date(),
user.timezone || DEFAULT_TIMEZONE,
)
).get(medication.id),
},
};
}
+115
View File
@@ -0,0 +1,115 @@
/**
* Undo one recorded dose: `DELETE /api/medications/{id}/intake/{eventId}`.
*
* A soft delete: the row stays, the sync feed carries the tombstone, and the
* inventory stamp is refunded. The route authenticates (MANAGE over the
* `medications` section) and answers the 404; the rest runs here.
*/
import type { MedicationIntakeEvent } from "@/generated/prisma/client";
import { prisma } from "@/lib/db";
import { annotate } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import type { SessionUser } from "@/lib/auth/session-user";
import { restoreForIntake } from "@/lib/medications/inventory/consumption";
import { reconcileOneShotState } from "@/lib/medications/lifecycle";
import { invalidateUserMedications } from "@/lib/cache/invalidate";
import { queueMedicationIntakeSync } from "@/lib/notifications/medication-intake-sync";
import { refreshDoseSlot } from "@/lib/medications/dose-day-refresh";
/**
* The event under this medication and record, tombstoned or not (a re-delete
* re-bumps harmlessly), or null for the route's 404.
*/
export async function findDeletableIntakeEvent(input: {
userId: string;
medicationId: string;
eventId: string;
}): Promise<MedicationIntakeEvent | null> {
const event = await prisma.medicationIntakeEvent.findUnique({
where: { id: input.eventId },
});
if (
!event ||
event.userId !== input.userId ||
event.medicationId !== input.medicationId
) {
return null;
}
return event;
}
export async function deleteIntakeEvent(input: {
user: Pick<SessionUser, "id" | "timezone">;
medicationId: string;
eventId: string;
event: MedicationIntakeEvent;
ipAddress: string;
originDeviceToken: string | null;
}): Promise<void> {
const { user, medicationId: id, eventId, event } = input;
// A deleted dose record refunds its consumption stamp (no-op for a
// never-consumed row; a re-delete finds it cleared).
await restoreForIntake({
client: prisma,
userId: user.id,
eventId,
});
// Sync — soft-delete instead of a hard `delete`. An intake is an immutable
// fact, so a "correction" is a tombstone + re-insert (never an in-place
// edit). Setting `deletedAt` (+ bumping `syncVersion`) leaves the row in
// place so the `/api/sync/changes` feed surfaces the deletion as a
// tombstone keyed on the server `id` to paired clients offline at delete
// time. Every today / compliance / list read filters `deletedAt: null`, so
// the row is invisible to normal reads from here on. A re-delete re-bumps
// harmlessly.
await prisma.medicationIntakeEvent.update({
where: { id: eventId },
data: {
deletedAt: new Date(),
syncVersion: { increment: 1 },
},
});
await auditLog("medication.intake.delete", {
userId: user.id,
ipAddress: input.ipAddress,
details: { eventId, medicationId: id },
});
annotate({
action: {
name: "medication.intake.delete",
entity_type: "intake_event",
entity_id: eventId,
},
meta: { medication_id: id },
});
// Bust per-user medications + compliance + achievement caches so the next
// read reflects the deletion.
invalidateUserMedications(user.id, { evict: true });
// Refresh the rows derived from the day the deleted event sat on.
await refreshDoseSlot({
userId: user.id,
medicationId: id,
scheduledFor: event.scheduledFor,
tz: user.timezone,
});
// Re-evaluate the one-shot active flag. Deleting the single live intake of
// a one-shot medication reactivates it so the dashboard / lists / worker
// pick it back up. No-op for non-one-shot medications.
await reconcileOneShotState(prisma, id, user.id);
// (#22) — silent cross-device intake sync: an undone dose must reconcile on
// the user's other iOS devices (the widget count and a pending Live
// Activity both change). Coalesced per user, best-effort — never affects
// the response.
queueMedicationIntakeSync({
userId: user.id,
originDeviceToken: input.originDeviceToken,
});
}
+503
View File
@@ -0,0 +1,503 @@
/**
* Correct one recorded dose: `PUT /api/medications/{id}/intake/{eventId}`.
*
* The route authenticates (MANAGE over the `medications` section), finds the
* live event, and parses the body; everything from the start-date floor to the
* cross-device sync tail runs here, in the order it always ran. A correction
* that keeps the dose on its slot edits the row in place; one that moves it
* tombstones the original and converges onto the target slot through the
* shared canonical-slot write.
*/
import type { MedicationIntakeEvent } from "@/generated/prisma/client";
import { prisma } from "@/lib/db";
import { annotate } from "@/lib/logging/context";
import { auditLog } from "@/lib/auth/audit";
import { overwriteDetails } from "@/lib/sharing/audit-details";
import type { SessionUser } from "@/lib/auth/session-user";
import type { updateIntakeEventSchema } from "@/lib/validations/medication";
import {
consumeForIntake,
restoreForIntake,
} from "@/lib/medications/inventory/consumption";
import { reconcileOneShotState } from "@/lib/medications/lifecycle";
import { invalidateUserMedications } from "@/lib/cache/invalidate";
import { queueMedicationIntakeSync } from "@/lib/notifications/medication-intake-sync";
import { refreshDoseSlot } from "@/lib/medications/dose-day-refresh";
import { dayKeyForUserTz } from "@/lib/measurements/consolidation-tz";
import {
applyCanonicalSlotWrite,
findPinConflict,
resolveForcedSlotForWrite,
resolveSlotForWriteByBand,
} from "@/lib/medications/scheduling/slot-upsert";
import { dateOnlyKey } from "@/lib/tz/date-only";
import type { z } from "zod/v4";
export type IntakeEventEdit = z.output<typeof updateIntakeEventSchema>;
/** A coded 422 refusal the route answers with `apiError`. */
export interface IntakeEditRefusal {
ok: false;
message: string;
errorCode: string;
}
type AttributionSource = "AUTO" | "USER_PIN";
interface EditContext {
user: Pick<SessionUser, "id" | "timezone">;
medicationId: string;
eventId: string;
event: MedicationIntakeEvent;
}
/**
* The live event a correction may edit, or null for the route's 404. A
* tombstoned event 404s on PUT; the `deletedAt: null` filter refuses to
* resurrect-edit a soft-deleted intake.
*/
export async function findEditableIntakeEvent(input: {
userId: string;
medicationId: string;
eventId: string;
}): Promise<MedicationIntakeEvent | null> {
const event = await prisma.medicationIntakeEvent.findFirst({
where: { id: input.eventId, deletedAt: null },
});
if (
!event ||
event.userId !== input.userId ||
event.medicationId !== input.medicationId
) {
return null;
}
return event;
}
/**
* Start-date guard on an edited `takenAt` (audit P0-4). The schema bounds the
* instant to a plausible absolute range; this check adds the per-medication
* floor: a take cannot predate the day the medication starts (calendar-day
* comparison in the user's timezone, so a take in the early hours of the
* start day never false-rejects).
*/
async function refuseTakeBeforeStart(
ctx: EditContext,
data: IntakeEventEdit,
): Promise<IntakeEditRefusal | null> {
const { user, medicationId: id, eventId } = ctx;
if (data.takenAt instanceof Date) {
const medication = await prisma.medication.findFirst({
where: { id, userId: user.id },
select: { startsOn: true },
});
if (medication?.startsOn) {
const takenDay = dayKeyForUserTz(data.takenAt, user.timezone);
const startsOnDay = dateOnlyKey(medication.startsOn);
if (takenDay < startsOnDay) {
annotate({
action: {
name: "medications.intake.event.update.before-start-date",
},
meta: { medication_id: id, event_id: eventId },
});
return {
ok: false,
message: "takenAt is before the medication's start date",
errorCode: "medications.intake.taken_at.before_start",
};
}
}
}
return null;
}
/**
* Re-run window-band attribution when the edit moves `takenAt` or `skipped`,
* so an edited time re-binds to the correct slot instead of leaving
* `scheduledFor` stale (audit HIGH-4). Precedence:
* 1. an explicit `scheduledFor` in the body wins (deliberate override);
* 2. else `forceSlotInstant` pins onto a named real slot (422 if it is
* not a slot of this med), standalone too, no takenAt / skipped change
* required ("Slot zuordnen" from the ledger kebab), and the row is
* stamped USER_PIN so the read ledger binds it by anchor instead of
* degrading the off-window take back to ad-hoc;
* 3. else an explicit `forceSlotInstant: null` UNPINS ("Zuordnung lösen"):
* re-attribute the take by band on its takenAt (ad-hoc when no band
* matches). The release is itself a deliberate binding decision, so the
* row KEEPS `USER_PIN` provenance ("attribution user-fixed": onto a slot
* OR deliberately ad-hoc). The persisted marker is what keeps the
* nightly slot dedup from snapping the released row back into the
* cluster the user just detached it from;
* 4. else a taken edit attributes by band (slot anchor on match, the
* take's own time on a miss → ad-hoc), provenance AUTO;
* 5. a skip / pending edit keeps the existing `scheduledFor` anchor.
*/
async function resolveEditAttribution(
ctx: EditContext,
data: IntakeEventEdit,
next: {
nextTakenAt: Date | null;
nextSkipped: boolean;
takenOrSkippedChanged: boolean;
},
): Promise<
| IntakeEditRefusal
| {
ok: true;
resolvedScheduledFor: Date | undefined;
attributionSource: AttributionSource | undefined;
}
> {
const { user, medicationId: id, eventId } = ctx;
const { nextTakenAt, nextSkipped, takenOrSkippedChanged } = next;
let resolvedScheduledFor: Date | undefined = data.scheduledFor;
let attributionSource: AttributionSource | undefined;
if (resolvedScheduledFor === undefined) {
if (data.forceSlotInstant !== undefined && data.forceSlotInstant !== null) {
const forced = await resolveForcedSlotForWrite({
userId: user.id,
medicationId: id,
userTz: user.timezone,
slotInstant: data.forceSlotInstant,
});
if (forced === null) {
annotate({
action: { name: "medication.intake.force_slot.invalid" },
meta: { medication_id: id, event_id: eventId },
});
return {
ok: false,
message:
"forceSlotInstant is not a scheduled slot of this medication",
errorCode: "medications.intake.force_slot.invalid",
};
}
// Refuse to pin onto a slot another recorded action already serves
// (excluding the row being edited): the explicit-write last-write-wins
// rule would silently overwrite that dose record. The ledger UI only
// offers the pin for unserved slots, so this only fires for stale
// clients / raw API calls.
if (
await findPinConflict({
userId: user.id,
medicationId: id,
canonicalSlot: forced,
incomingTakenAt: nextSkipped ? null : nextTakenAt,
excludeEventId: eventId,
})
) {
annotate({
action: { name: "medication.intake.force_slot.occupied" },
meta: { medication_id: id, event_id: eventId },
});
return {
ok: false,
message: "forceSlotInstant already carries a recorded dose action",
errorCode: "medications.intake.force_slot.occupied",
};
}
resolvedScheduledFor = forced;
attributionSource = "USER_PIN";
} else if (
(data.forceSlotInstant === null || takenOrSkippedChanged) &&
nextTakenAt !== null &&
!nextSkipped
) {
const attribution = await resolveSlotForWriteByBand({
userId: user.id,
medicationId: id,
userTz: user.timezone,
takenAt: nextTakenAt,
});
// band.at on match; the take's own time on a miss (ad-hoc).
resolvedScheduledFor = attribution.slotInstant ?? nextTakenAt;
// An explicit unpin stays user-fixed (USER_PIN) even on the released
// row; a plain taken/skipped edit re-attributes AUTO.
attributionSource = data.forceSlotInstant === null ? "USER_PIN" : "AUTO";
} else if (data.forceSlotInstant === null) {
// Unpin on a row that is not a confirmed take (skip / pending):
// nothing to re-attribute, but the provenance still resets — a
// skip / pending row anchors on its slot by construction, so there
// is no user-fixed ad-hoc decision to persist.
attributionSource = "AUTO";
}
// skip / pending edits leave `scheduledFor` on the existing anchor.
}
return { ok: true, resolvedScheduledFor, attributionSource };
}
/**
* The slot is unchanged — a bare in-place update can never collide with a
* sibling row (it is its own slot).
*/
async function editIntakeInPlace(
ctx: EditContext,
data: IntakeEventEdit,
edit: {
attributionSource: AttributionSource | undefined;
nextTakenAt: Date | null;
nextSkipped: boolean;
wasTaken: boolean;
},
) {
const { user, medicationId: id, eventId } = ctx;
const { attributionSource, nextTakenAt, nextSkipped, wasTaken } = edit;
const updated = await prisma.medicationIntakeEvent.update({
where: { id: eventId },
data: {
...(data.takenAt !== undefined && { takenAt: data.takenAt }),
...(data.skipped !== undefined && { skipped: data.skipped }),
// Binding provenance: pin / unpin / band re-attribution stamps it even
// when the anchor itself did not move (e.g. a pin onto the slot the row
// already sits on, or an unpin whose band re-attribution lands on the
// same anchor).
...(attributionSource !== undefined && { attributionSource }),
// An edit of the outcome is the person's own record.
...((data.takenAt !== undefined || data.skipped !== undefined) && {
autoRecorded: false,
}),
// Sync — bump the reconciliation counter on every server-side mutation
// so the `/api/sync/changes` feed echoes a monotonic value to paired
// clients.
syncVersion: { increment: 1 },
},
});
// Inventory follows the post-edit state: an edit that moves the row INTO
// taken consumes; a row that stays taken keeps its stamp untouched (the
// stamp freezes what the original take pulled, even when `unitsPerDose`
// changed since, and a pre-stamp legacy row must not retro-consume); a row
// edited out of taken (skip flip, takenAt cleared) refunds its stamp.
if (nextTakenAt !== null && !nextSkipped) {
if (!wasTaken) {
await consumeForIntake({
client: prisma,
userId: user.id,
medicationId: id,
eventId,
intakeAt: nextTakenAt,
});
}
} else {
await restoreForIntake({
client: prisma,
userId: user.id,
eventId,
});
}
return updated;
}
/**
* The edit moved the dose to a different slot. Tombstone the original row
* (the iOS "a correction is a tombstone + re-insert" model the DELETE handler
* documents) and route the corrected dose through the shared canonical-slot
* upsert, which converges onto any row already at the target slot (a pending
* REMINDER row) rather than bare-updating into an occupied slot and risking a
* P2002 (audit HIGH-4).
*
* The source row's consumption stamp is refunded BEFORE the tombstone; the
* consume on the converged row below nets the move to exactly one
* consumption.
*/
async function moveIntakeToSlot(
ctx: EditContext,
move: {
targetScheduledFor: Date;
attributionSource: AttributionSource | undefined;
nextTakenAt: Date | null;
nextSkipped: boolean;
wasTaken: boolean;
},
) {
const { user, medicationId: id, eventId, event } = ctx;
const {
targetScheduledFor,
attributionSource,
nextTakenAt,
nextSkipped,
wasTaken,
} = move;
await restoreForIntake({
client: prisma,
userId: user.id,
eventId,
});
await prisma.medicationIntakeEvent.update({
where: { id: eventId },
data: { deletedAt: new Date(), syncVersion: { increment: 1 } },
});
const applied = await applyCanonicalSlotWrite({
client: prisma,
userId: user.id,
medicationId: id,
canonicalSlot: targetScheduledFor,
takenAt: nextSkipped ? null : nextTakenAt,
skipped: nextSkipped,
isExplicitTaken: !nextSkipped && nextTakenAt !== null,
isExplicitSkip: nextSkipped,
idempotencyKey: null,
// The converged row keeps the ORIGINAL's provenance. This used to be a
// hardcoded `"WEB"`, which said "somebody typed this in the browser"
// about an Apple Health dose whose time was corrected. Under MANAGE the
// sentence would be wrong about a second person as well.
createSource: event.source,
attributionSource,
// A slot move is a re-binding, not a new dose: the original row's
// recorded injection site and dose override ride along onto the
// converged row instead of being tombstoned away.
injectionSite: event.injectionSite,
doseTaken: event.doseTaken,
});
// A taken source WITHOUT a stamp is a legacy row whose stock moved through
// the old take-time hook: the refund above was a no-op, so consuming on the
// converged row would double-charge — skip it. Every other taken outcome
// nets the move to exactly one consumption.
if (
nextTakenAt !== null &&
!nextSkipped &&
(!wasTaken || event.inventoryConsumption !== null)
) {
await consumeForIntake({
client: prisma,
userId: user.id,
medicationId: id,
eventId: applied.row.id,
intakeAt: nextTakenAt,
});
}
return applied.row;
}
/** Correct one dose; the event is the live row the route found. */
export async function updateIntakeEvent(
input: EditContext & {
data: IntakeEventEdit;
ipAddress: string | null;
originDeviceToken: string | null;
},
) {
const { user, medicationId: id, eventId, event, data } = input;
const ctx: EditContext = { user, medicationId: id, eventId, event };
const beforeStart = await refuseTakeBeforeStart(ctx, data);
if (beforeStart) return beforeStart;
// The post-edit state of the row (current values where the body omits a
// field) — drives the re-attribution decision.
const nextTakenAt = data.takenAt !== undefined ? data.takenAt : event.takenAt;
const nextSkipped = data.skipped !== undefined ? data.skipped : event.skipped;
const takenOrSkippedChanged =
(data.takenAt !== undefined &&
data.takenAt?.getTime() !== event.takenAt?.getTime()) ||
(data.skipped !== undefined && data.skipped !== event.skipped);
const attribution = await resolveEditAttribution(ctx, data, {
nextTakenAt,
nextSkipped,
takenOrSkippedChanged,
});
if (!attribution.ok) return attribution;
const { resolvedScheduledFor, attributionSource } = attribution;
const targetScheduledFor = resolvedScheduledFor ?? event.scheduledFor;
const slotMoved =
targetScheduledFor.getTime() !== event.scheduledFor.getTime();
// Transition gate for the inventory hooks. Only an edit moving the row INTO
// taken may consume; a row that was already taken keeps its stamp frozen (a
// stamped row would no-op anyway, and a legacy taken row — NULL stamp, stock
// already moved by the old hook at take time — must never retro-consume on
// a time correction).
const wasTaken = event.takenAt !== null && !event.skipped;
const updated = !slotMoved
? await editIntakeInPlace(ctx, data, {
attributionSource,
nextTakenAt,
nextSkipped,
wasTaken,
})
: await moveIntakeToSlot(ctx, {
targetScheduledFor,
attributionSource,
nextTakenAt,
nextSkipped,
wasTaken,
});
await auditLog("medication.intake.update", {
userId: user.id,
ipAddress: input.ipAddress,
// What the correction moved. A dose edit changes when a dose is
// recorded as taken, which is exactly what a clinician reads back.
details: {
eventId,
medicationId: id,
...overwriteDetails({
before: {
scheduledFor: event.scheduledFor,
takenAt: event.takenAt,
skipped: event.skipped,
},
// The slot-write result carries the canonical four. The injection
// site and the dose override are not compared here because the move
// path copies them onto the converged row by construction — there is
// no edit of them to report.
after: {
scheduledFor: updated.scheduledFor,
takenAt: updated.takenAt,
skipped: updated.skipped,
},
}),
},
});
annotate({
action: {
name: "medication.intake.update",
entity_type: "intake_event",
entity_id: eventId,
},
meta: { medication_id: id },
});
// Bust per-user medications + compliance + achievement caches so the next
// read reflects the edited event.
invalidateUserMedications(user.id, { evict: true });
// Refresh the rows derived from both the old + new scheduledFor day-keys
// when the dose moved across a day boundary (band re-attribution can move
// it as well as an explicit edit); if the slot is unchanged the second call
// collapses to a no-op upsert.
await refreshDoseSlot({
userId: user.id,
medicationId: id,
scheduledFor: event.scheduledFor,
tz: user.timezone,
});
if (slotMoved) {
await refreshDoseSlot({
userId: user.id,
medicationId: id,
scheduledFor: targetScheduledFor,
tz: user.timezone,
});
}
// Re-evaluate the one-shot active flag. A skip-flip on the single live
// intake of a one-shot medication should reactivate it (the dose is no
// longer logged), and the reverse case should deactivate again. No-op for
// non-one-shot medications.
await reconcileOneShotState(prisma, id, user.id);
// (#22) — silent cross-device intake sync: an edited dose must reconcile on
// the user's other iOS devices too. Coalesced per user, best-effort — never
// affects the response.
queueMedicationIntakeSync({
userId: user.id,
originDeviceToken: input.originDeviceToken,
});
return { ok: true as const, row: updated };
}