/** * `POST /api/nutrients/batch` — micronutrient day-total ingest (v1.28). * * iOS posts daily totals for the closed 26-code catalog (vitamins, * minerals, water, caffeine) computed via `HKStatisticsCollectionQuery` * day-anchored cumulative sums; `day` arrives as YYYY-MM-DD in the * user's IANA timezone (the `stats:` day-key contract — the server * trusts the string after regex + calendar sanity, no re-derivation). * * Upsert key = the composite PK (userId, day, nutrient, source), and this * route always owns the APPLE_HEALTH row. Re-post * replaces amount / unit / externalSourceVersion — last-writer-wins, * the day-total contract; per-entry status is `updated` then, never * `duplicate`. Validation failures (`unit_mismatch` | `value_out_of_range` * | `day_invalid`) are always isolated per entry. The DB write itself runs * as two batched groups — a single indexed existence read splits valid * entries into a bulk `createMany` (new pairs) and a `$transaction` of * per-row updates (existing pairs), the measurements-batch shape. A write * failure marks its WHOLE group `skipped upsert_failed` rather than * isolating the one entry that would have caused it (unavoidable once the * write is batched) — the request itself never fails. That reason is * transient, unlike the validation skips: the client sends those entries * again, and the response is marked `no-store` so an idempotent retry is not * answered from the cache. * * Module gate FIRST: the opt-in `nutrients` module (default off) * refuses ingest with the 403 `module.disabled` envelope, so a phone * whose user never opted in cannot land rows server-side * (refuse-ingest posture, mirroring mental health — not surface-only). */ import { NextRequest } from "next/server"; import { prisma } from "@/lib/db"; import { apiHandler, requireAuth } from "@/lib/api-handler"; import { annotate } from "@/lib/logging/context"; import { auditLog } from "@/lib/auth/audit"; import { apiError, apiSuccess, getClientIp, returnAllZodIssues, safeJson, } from "@/lib/api-response"; import { withIdempotency } from "@/lib/idempotency"; import { checkRateLimit } from "@/lib/rate-limit"; import { requireModuleEnabled } from "@/lib/modules/gate"; import { invalidateUserDashboardSnapshot } from "@/lib/cache/invalidate"; import { NUTRIENT_CATALOG } from "@/lib/nutrients/catalog"; import { maxAcceptableNutrientDay } from "@/lib/nutrients/day-bounds"; import { MAX_NUTRIENT_ENTRIES_PER_BATCH, nutrientBatchSchema, } from "@/lib/validations/nutrients"; const BATCH_RATE_LIMIT_MAX = 60; const BATCH_RATE_LIMIT_WINDOW_MS = 60 * 1000; /** * Calendar sanity for an already regex-shaped YYYY-MM-DD key: reject * impossible dates (2026-02-31) via a UTC round-trip. */ function isRealCalendarDay(day: string): boolean { const [y, m, d] = day.split("-").map(Number); const dt = new Date(Date.UTC(y, m - 1, d)); return ( dt.getUTCFullYear() === y && dt.getUTCMonth() === m - 1 && dt.getUTCDate() === d ); } type EntryStatus = "inserted" | "updated" | "skipped"; interface EntryResult { index: number; status: EntryStatus; reason?: string; } export const POST = apiHandler(withIdempotency<[NextRequest]>(postBatch)); async function postBatch(request: NextRequest): Promise { const { user } = await requireAuth(); // Module gate first: a disabled module must refuse before any body // work, so iOS can branch on the 403 `module.disabled` errorCode and // stop syncing rather than retry. const gate = await requireModuleEnabled(user.id, "nutrients"); if (!gate.enabled) return gate.response; const rl = await checkRateLimit( `nutrients:batch:${user.id}`, BATCH_RATE_LIMIT_MAX, BATCH_RATE_LIMIT_WINDOW_MS, ); if (!rl.allowed) { return apiError("Too many batch submissions, try again later", 429); } const { data: rawBody, error: jsonError } = await safeJson(request, { maxBytes: 1024 * 1024, }); if (jsonError) return jsonError; if ( typeof rawBody === "object" && rawBody !== null && "entries" in rawBody && Array.isArray((rawBody as { entries: unknown }).entries) && (rawBody as { entries: unknown[] }).entries.length > MAX_NUTRIENT_ENTRIES_PER_BATCH ) { return apiError( `Batch exceeds the ${MAX_NUTRIENT_ENTRIES_PER_BATCH}-entry limit`, 422, { errorCode: "nutrient.batch.too_large" }, ); } const parsed = nutrientBatchSchema.safeParse(rawBody); if (!parsed.success) { annotate({ action: { name: "nutrient.batch.validation-failed" }, meta: { issue_count: parsed.error.issues.length }, }); return returnAllZodIssues(parsed.error, 422, { errorCode: "nutrient.batch.invalid", }); } const { entries } = parsed.data; const dayCeiling = maxAcceptableNutrientDay(new Date()); const results: EntryResult[] = new Array(entries.length); const skipped: Array<{ index: number; reason: string }> = []; let inserted = 0; let updated = 0; interface ValidEntry { index: number; day: string; nutrient: (typeof entries)[number]["nutrient"]; amount: number; unit: string; externalSourceVersion: string | null; } const validEntries: ValidEntry[] = []; for (let i = 0; i < entries.length; i++) { const entry = entries[i]; const definition = NUTRIENT_CATALOG[entry.nutrient]; // The wire carries the unit deliberately: a µg/mg confusion is a // silent 1000× corruption; anything but the catalog's canonical // unit skips the entry rather than converting. if (entry.unit !== definition.unit) { skipped.push({ index: i, reason: "unit_mismatch" }); results[i] = { index: i, status: "skipped", reason: "unit_mismatch" }; continue; } if (entry.amount > definition.plausibleDailyMax) { skipped.push({ index: i, reason: "value_out_of_range" }); results[i] = { index: i, status: "skipped", reason: "value_out_of_range", }; continue; } if (!isRealCalendarDay(entry.day) || entry.day > dayCeiling) { skipped.push({ index: i, reason: "day_invalid" }); results[i] = { index: i, status: "skipped", reason: "day_invalid" }; continue; } validEntries.push({ index: i, day: entry.day, nutrient: entry.nutrient, amount: entry.amount, unit: definition.unit, externalSourceVersion: entry.externalSourceVersion ?? null, }); } // v1.29 — `source` joined the composite PK (migration 0249) so a manual // water entry (source=MANUAL, written by `POST /api/nutrients/water`) // coexists with the Apple-synced day total instead of one clobbering the // other on the next sync. The batch route always owns the APPLE_HEALTH // row. // // Perf (measurements/batch shape): ONE indexed existence read replaces the // per-entry probe-then-upsert (up to 1000 sequential round trips pre-fix). // Genuinely new (day, nutrient) pairs land via a single chunked // `createMany`; pairs that already exist update via a batched // `$transaction` of per-row `update` calls (values differ per row, so a // single bulk statement isn't available without raw SQL — this still // collapses the per-entry PROBE, and pipelines the writes through one // transaction instead of N standalone round trips). if (validEntries.length > 0) { const existing = await prisma.nutrientIntakeDay.findMany({ where: { userId: user.id, source: "APPLE_HEALTH", OR: validEntries.map((e) => ({ day: e.day, nutrient: e.nutrient })), }, select: { day: true, nutrient: true }, }); const existingKeys = new Set( existing.map((r) => `${r.day}::${r.nutrient}`), ); const toInsert: ValidEntry[] = []; const toUpdate: ValidEntry[] = []; for (const e of validEntries) { (existingKeys.has(`${e.day}::${e.nutrient}`) ? toUpdate : toInsert).push( e, ); } if (toInsert.length > 0) { try { const result = await prisma.nutrientIntakeDay.createMany({ data: toInsert.map((e) => ({ userId: user.id, day: e.day, nutrient: e.nutrient, amount: e.amount, unit: e.unit, source: "APPLE_HEALTH" as const, externalSourceVersion: e.externalSourceVersion, })), skipDuplicates: true, }); inserted += result.count; for (const e of toInsert) { results[e.index] = { index: e.index, status: "inserted" }; } // Rare race: a concurrent request claimed one of these keys between // our existence probe and this createMany, so skipDuplicates // silently dropped that row's write here — measurements/batch // accepts the same count-only trade-off for its own createMany race. // The DB itself stays consistent (the racing writer's row is // stored); only this response's per-row label may be stale for // that one entry. if (result.count < toInsert.length) { annotate({ action: { name: "nutrient.batch.insert_race" }, meta: { attempted: toInsert.length, stored: result.count }, }); } } catch (err: unknown) { console.error("[nutrient-batch] bulk insert failed", err); for (const e of toInsert) { skipped.push({ index: e.index, reason: "upsert_failed" }); results[e.index] = { index: e.index, status: "skipped", reason: "upsert_failed", }; } } } if (toUpdate.length > 0) { try { await prisma.$transaction( toUpdate.map((e) => prisma.nutrientIntakeDay.update({ where: { userId_day_nutrient_source: { userId: user.id, day: e.day, nutrient: e.nutrient, source: "APPLE_HEALTH", }, }, data: { // Last-writer-wins on the day total: iOS re-posts the // current and previous local day on every sync as the // totals grow. amount: e.amount, unit: e.unit, externalSourceVersion: e.externalSourceVersion, }, }), ), ); updated += toUpdate.length; for (const e of toUpdate) { results[e.index] = { index: e.index, status: "updated" }; } } catch (err: unknown) { // The client-facing `reason` is a closed set (see the file header) — // never echo raw exception text into it. Log the real error // server-side only (SWC keeps `console.error` in prod) and return // the fixed `upsert_failed` member. console.error("[nutrient-batch] bulk update failed", err); for (const e of toUpdate) { skipped.push({ index: e.index, reason: "upsert_failed" }); results[e.index] = { index: e.index, status: "skipped", reason: "upsert_failed", }; } } } } // v1.34.3 — per-reason skip breakdown, durable AND ephemeral. Computed // once from the closed `reason` set (never raw exception text — see the // upsert `catch` blocks above), so this carries only counts and reason // codes, never a per-entry health value or anything user-typed. const skippedByReason: Record = {}; for (const s of skipped) { skippedByReason[s.reason] = (skippedByReason[s.reason] ?? 0) + 1; } // v1.34.3 — audit UNCONDITIONALLY. This used to fire only when // `inserted + updated > 0`, which made it the ONLY durable trace of the // call — so a batch where every entry was skipped (say, a systemic unit // mismatch) left the exact same empty AuditLog record as a phone that // never posted at all. An operator investigating an empty // `nutrient_intake_days` table could not tell "the client never called" // from "the client called and every entry was rejected" without that // record. Mirrors `measurement.batch.ingest` / `workout.batch.ingest` // (unconditional, counts-only, no per-entry health values) plus the // aggregate skip-reason breakdown so "did it post, and why did nothing // land" is answerable from the durable row alone, without a Wide-Event // trail that (unlike this table) isn't guaranteed to still exist. await auditLog("nutrient.batch.ingest", { userId: user.id, ipAddress: getClientIp(request), details: { processed: entries.length, inserted, updated, skipped: skipped.length, skippedByReason, }, }); if (inserted + updated > 0) { // v1.30.3 (QA F9) — a landed row changes the dashboard's water/nutrient // tile; without this the snapshot kept serving the pre-sync figure // until the analytics fresh TTL lapsed (~3 min). Mirrors the manual // water POST's own hard-evict (`nutrients/water/route.ts`) so an // Apple-Health-synced total reflects on the very next dashboard read, // same as a manually logged one. invalidateUserDashboardSnapshot(user.id); } annotate({ action: { name: "nutrient.batch.ingest" }, meta: { processed: entries.length, inserted, updated, skipped: skipped.length, skipped_by_reason: skippedByReason, }, }); const response = apiSuccess({ processed: entries.length, inserted, updated, skipped, entries: results, }); // `upsert_failed` is transient: nothing was stored for those entries and the // client sends them again. `no-store` keeps the idempotency layer from // caching this answer, so a retry under the same key writes instead of // replaying the failure. The measurement batch does the same for `failed`. if (skippedByReason.upsert_failed) { response.headers.set("Cache-Control", "private, no-store"); } return response; }