Files
HealthLog/src/app/api/integrations/healthkit/route.ts
T
Marc-André Bombeck 59434cd463 feat(healthkit): list the accepted sample types on the integration read
GET /api/integrations/healthkit carries acceptedTypes, the quantity and
category identifiers the batch route maps today. The list is derived from
APPLE_HEALTH_TYPE_MAP alone, so a deferred type is never in it and the
client no longer needs a release to follow a mapping change.

Refs #1340
2026-11-04 21:18:30 +01:00

336 lines
12 KiB
TypeScript

/**
* HealthKit (iOS) integration config.
*
* Persisted on `User.healthKitConfigJson` as `{ entries: [...] }`.
* Each entry: `{ id, kind, direction, enabled }` where `direction` is one
* of `bidirectional | readOnly | writeOnly`.
*
* GET → resolved config (with default entries when nothing is stored).
* PATCH → merge by `id`; unknown ids are silently ignored.
*/
import { NextRequest } from "next/server";
import { z } from "zod/v4";
import { apiHandler, requireAuth } from "@/lib/api-handler";
import {
apiSuccess,
returnAllZodIssues,
safeJson,
sanitiseZodIssues,
} from "@/lib/api-response";
import { annotate } from "@/lib/logging/context";
import { prisma, toJson } from "@/lib/db";
import { auditLog } from "@/lib/auth/audit";
import { getAppleHealthSyncProgress } from "@/lib/integrations/apple-health-progress";
import { acceptedHealthKitTypes } from "@/lib/measurements/healthkit-accepted-types";
import {
getHealthKitTypeArrivals,
healthKitWriteBackTypes,
newestAppleHealthDataAt,
withHealthKitArrivals,
} from "@/lib/integrations/healthkit-type-sync";
import {
getAppleHealthDoseFreshness,
getEnteredHereAt,
getSourceFreshness,
} from "@/lib/integrations/metric-freshness";
import { loadOneConnectionHealth } from "@/lib/integrations/connection-health-load";
import {
classifyMetricFreshness,
PUSH_CADENCE,
resolveSyncVerdict,
} from "@/lib/integrations/sync-verdict";
export const directionEnum = z.enum([
"bidirectional",
"readOnly",
"writeOnly",
"disabled",
]);
const entrySchema = z.object({
id: z.string().min(1).max(64),
kind: z.string().min(1).max(64).optional(),
direction: directionEnum,
enabled: z.boolean().optional(),
});
const patchSchema = z.object({
entries: z.array(entrySchema).max(50),
});
export interface HealthKitEntry {
id: string;
kind: string;
direction: z.infer<typeof directionEnum>;
enabled: boolean;
}
export const DEFAULT_HEALTHKIT_ENTRIES: HealthKitEntry[] = [
{
id: "bodyMass",
kind: "bodyMass",
direction: "bidirectional",
enabled: true,
},
{
id: "bp",
kind: "bloodPressure",
direction: "bidirectional",
enabled: true,
},
{
id: "glucose",
kind: "bloodGlucose",
direction: "bidirectional",
enabled: true,
},
{ id: "heartRate", kind: "heartRate", direction: "readOnly", enabled: true },
{ id: "stepCount", kind: "stepCount", direction: "readOnly", enabled: true },
{ id: "sleep", kind: "sleepAnalysis", direction: "readOnly", enabled: true },
];
interface StoredConfig {
entries: HealthKitEntry[];
}
function parseStored(json: unknown): StoredConfig | null {
if (!json || typeof json !== "object") return null;
const obj = json as Record<string, unknown>;
const entries = obj.entries;
if (!Array.isArray(entries)) return null;
const out: HealthKitEntry[] = [];
for (const raw of entries) {
if (!raw || typeof raw !== "object") continue;
const e = raw as Record<string, unknown>;
const id = typeof e.id === "string" ? e.id : null;
const kind = typeof e.kind === "string" ? e.kind : id;
const directionRaw = typeof e.direction === "string" ? e.direction : null;
if (!id || !kind || !directionRaw) continue;
const dir = directionEnum.safeParse(directionRaw);
if (!dir.success) continue;
out.push({
id,
kind,
direction: dir.data,
enabled: typeof e.enabled === "boolean" ? e.enabled : true,
});
}
return { entries: out };
}
function mergeWithDefaults(stored: StoredConfig | null): HealthKitEntry[] {
const map = new Map<string, HealthKitEntry>();
for (const def of DEFAULT_HEALTHKIT_ENTRIES) {
map.set(def.id, { ...def });
}
if (stored) {
for (const entry of stored.entries) {
const existing = map.get(entry.id);
if (existing) {
map.set(entry.id, { ...existing, ...entry });
} else {
// Surface custom keys the user has added.
map.set(entry.id, { ...entry, enabled: entry.enabled ?? true });
}
}
}
return [...map.values()];
}
export const GET = apiHandler(async () => {
const { user } = await requireAuth();
annotate({ action: { name: "integrations.healthkit.get" } });
const row = await prisma.user.findUnique({
where: { id: user.id },
select: {
healthKitConfigJson: true,
healthKitLastSyncedAt: true,
healthKitLastSyncTrigger: true,
healthKitLastBackgroundSyncAt: true,
},
});
const stored = parseStored(row?.healthKitConfigJson ?? null);
const entries = mergeWithDefaults(stored);
const lastSyncedAt = row?.healthKitLastSyncedAt?.toISOString() ?? null;
// What triggered the most recent accepted batch, and when data last arrived
// without the app being opened. `lastSyncedAt` alone cannot separate those
// two cases, which is the whole diagnostic: a card that only ever says "last
// sync 10 minutes ago" reads the same whether the phone is delivering by
// itself or whether every arrival was the user opening the app. Null in
// either field is honest absence — an older client that declares no trigger,
// or a pipe that has never delivered in the background.
const lastSyncTrigger = row?.healthKitLastSyncTrigger ?? null;
const lastBackgroundSyncAt =
row?.healthKitLastBackgroundSyncAt?.toISOString() ?? null;
// Apple Health is push-based: the iOS app delivers and nothing here polls, so
// liveness is a data question, not an attempt question. Without a threshold a
// three-week-dead pipe rendered the same green as one that delivered an hour
// ago. Fail-soft on the per-metric read — an honesty signal is never worth
// 500-ing the config the iOS client needs.
// #1173 — when each type last ARRIVED and under which trigger, beside when
// its newest sample was taken. Fail-soft to null, which leaves the entries
// without arrival fields rather than reporting every type as never received.
// Issue #778 — a first-run backfill used to be invisible from the web: the
// card said "last sync 2 minutes ago" while giving no sense of how much had
// arrived or how far back it reached. These two figures (row count + oldest
// instant) are everything the server actually knows about backfill
// progress; the phone's queue and throttle state stay on the phone and are
// not guessed at. Fail-soft for the same reason the freshness read is —
// a progress line is never worth 500-ing the config the iOS client needs.
// `health` is the unified connection state; fail-soft to null for the same
// reason as the reads beside it, so the config the phone needs never 500s
// over a diagnostic.
// v1.42.4 — Apple Health doses join the list as `MEDICATION_DOSE`, so the
// phone can read when doses last arrived from the same entries as every
// other type. Fail-soft on its own: a failed dose read drops that one entry.
// #1247 — the types the app writes back to the phone: what is entered here
// goes to Apple Health and never arrives back, so each of them also carries
// the newest reading entered here, and is quiet only when both are. Fail-
// soft to undefined, which leaves the list as it was before.
const [
measurementSamples,
doseSample,
arrivals,
syncProgress,
health,
enteredHere,
] = await Promise.all([
getSourceFreshness(user.id, "APPLE_HEALTH").catch(() => []),
getAppleHealthDoseFreshness(user.id).catch(() => null),
getHealthKitTypeArrivals(user.id).catch(() => null),
getAppleHealthSyncProgress(user.id).catch(() => null),
loadOneConnectionHealth(user.id, "apple-health").catch(() => null),
getEnteredHereAt(user.id, healthKitWriteBackTypes(entries)).catch(
() => undefined,
),
]);
const samples = doseSample
? [...measurementSamples, doseSample].sort((a, b) =>
a.type.localeCompare(b.type),
)
: measurementSamples;
// No `connected` hint: Apple Health has nothing to connect or disconnect, so
// "never delivered" resolves to `pending_first_sync`, not `disconnected`.
// "Delivered" is read off the data, not only off the user column: that
// column moves on a live batch alone, so rows from the export.zip import
// left it null and the card said "waiting for first data" beside a
// four-digit record count.
const syncHealth = resolveSyncVerdict({
configured: true,
lastDataAt: newestAppleHealthDataAt(lastSyncedAt, arrivals, samples),
legacyLastSyncedAt: lastSyncedAt,
cadence: PUSH_CADENCE,
});
return apiSuccess({
entries,
lastSyncedAt,
lastSyncTrigger,
lastBackgroundSyncAt,
syncHealth,
metricFreshness: withHealthKitArrivals(
classifyMetricFreshness(
samples,
syncHealth.verdict,
Date.now(),
enteredHere,
),
arrivals,
),
syncProgress,
health,
// #1340 — what the batch route maps, so the app asks only for those.
acceptedTypes: acceptedHealthKitTypes(),
});
});
export const PATCH = apiHandler(async (request: NextRequest) => {
const { user } = await requireAuth();
const { data: body, error } = await safeJson(request, {
maxBytes: 64 * 1024,
});
if (error) return error;
const parsed = patchSchema.safeParse(body);
if (!parsed.success) {
// v1.4.43 — iOS HealthKit ingest is a hot path. Multi-issue
// 422 + audit breadcrumb so the iOS Sync engine sees the full
// diff and stops iterating one field at a time.
const issues = sanitiseZodIssues(parsed.error.issues);
annotate({
action: { name: "integrations.healthkit.validation-failed" },
meta: { issue_count: issues.length },
});
// v1.4.49 — strip `message` from the audit-ledger row; the
// HealthKit patch payload carries caller-provided `id` + `kind`
// strings that Zod can echo.
const auditIssues = sanitiseZodIssues(parsed.error.issues, {
stripValuesFromMessage: true,
});
auditLog("integrations.healthkit.validation-failed", {
userId: user.id,
details: { issues: auditIssues },
}).catch(() => {
/* swallow — 422 response is the contract */
});
return returnAllZodIssues(parsed.error, 422);
}
const row = await prisma.user.findUnique({
where: { id: user.id },
select: { healthKitConfigJson: true },
});
const stored = parseStored(row?.healthKitConfigJson ?? null);
// Resolve known ids set: default ids + already-stored ids.
const knownIds = new Set<string>(DEFAULT_HEALTHKIT_ENTRIES.map((e) => e.id));
if (stored) for (const e of stored.entries) knownIds.add(e.id);
// Merge by id; unknown ids are silently ignored per spec.
const map = new Map<string, HealthKitEntry>();
if (stored) for (const e of stored.entries) map.set(e.id, e);
for (const update of parsed.data.entries) {
if (!knownIds.has(update.id)) continue;
const existing =
map.get(update.id) ??
DEFAULT_HEALTHKIT_ENTRIES.find((d) => d.id === update.id);
map.set(update.id, {
id: update.id,
kind: update.kind ?? existing?.kind ?? update.id,
direction: update.direction,
enabled: update.enabled ?? existing?.enabled ?? true,
});
}
const updatedConfig: StoredConfig = { entries: [...map.values()] };
await prisma.user.update({
where: { id: user.id },
data: {
healthKitConfigJson: toJson(updatedConfig),
},
});
await auditLog("integrations.healthkit.update", {
userId: user.id,
details: { count: updatedConfig.entries.length },
});
annotate({
action: { name: "integrations.healthkit.update" },
meta: { count: updatedConfig.entries.length },
});
// Return resolved config (defaults merged) so the client always sees a
// complete entries list.
const merged = mergeWithDefaults(updatedConfig);
return apiSuccess({
entries: merged,
lastSyncedAt: null,
});
});