Merge remote-tracking branch 'origin/fix/unwired-columns' into integration/post-1385

# Conflicts:
#	CHANGELOG.md
This commit is contained in:
Marc-André Bombeck committed 2026-09-03 06:35:35 +02:00
commit 7c5f49c18e
36 files changed
+1613 -45

No files matched your search

+9 -1
View File
@@ -9,7 +9,15 @@
export type GlucoseUnit = "mg/dL" | "mmol/L";
const MGDL_PER_MMOL = 18.0182;
/**
* mg/dL per mmol/L, per the DGIM / DDG S3 guideline. Exported because it is
* the one factor for this conversion in the tree: the inbound alias resolver
* normalises a mmol/L cell with it, the glucose insight page scales its chart
* by its reciprocal, and the helpers below round with it. Two nearly-equal
* copies of a health conversion is how the same reading comes out as two
* different numbers on two screens.
*/
export const MGDL_PER_MMOL = 18.0182;
export function mgdlToMmol(mgdl: number): number {
return Math.round((mgdl / MGDL_PER_MMOL) * 10) / 10;
@@ -1,4 +1,5 @@
import { describe, it, expect } from "vitest";
import { MGDL_PER_MMOL, mgdlToMmol } from "@/lib/glucose";
import {
parseCsvMeasurements,
@@ -98,7 +99,12 @@ describe("parseCsvMeasurements — unit conversion", () => {
]);
expect(out.rows[0].status).toBe("ok");
expect(out.rows[0].row?.unit).toBe("mg/dL");
expect(out.rows[0].row?.value).toBeCloseTo(5.3 * 18.016, 3);
// The one factor the app converts glucose by, both directions. The
// literal that used to sit here was 18.016 while every display path
// divided by 18.0182, so a reading imported in mmol/L did not read back
// as the number it went in as.
expect(out.rows[0].row?.value).toBeCloseTo(5.3 * MGDL_PER_MMOL, 3);
expect(mgdlToMmol(out.rows[0].row?.value ?? 0)).toBe(5.3);
});
it("converts weight lb to canonical kg", () => {
@@ -176,7 +182,7 @@ describe("parseCsvMeasurements — glucose context", () => {
for (const result of out.rows) {
expect(result.row).not.toHaveProperty("glucoseContext");
expect(result.row?.unit).toBe("mg/dL");
expect(result.row?.value).toBeCloseTo(95.4848, 3);
expect(result.row?.value).toBeCloseTo(5.3 * MGDL_PER_MMOL, 3);
}
expect(out.rows[0].row?.measuredAt.toISOString()).toBe(
"2024-04-03T02:15:00.000Z",
@@ -0,0 +1,69 @@
/**
* `ImportJob.exportedAt` — the worker end of the wiring.
*
* The parse side is proved behaviourally in
* `src/lib/measurements/__tests__/import-apple-health-export.test.ts`:
* the parser hands the archive's own stamp to `onExportDate`. What that
* cannot show is whether anything persists it. The column, the status
* endpoint that returns it and the published contract that requires it
* all existed for a year while the one line that would produce the value
* was a `return`, so the half of the pipe worth pinning is this one.
*
* Source-shaped rather than run-shaped: driving the worker needs a real
* `export.zip`, a queue and a database, which the ECG contract test
* beside this one already declines to do for the same reason.
*/
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
const workerSource = readFileSync(
join(process.cwd(), "src/lib/jobs/apple-health-import-worker.ts"),
"utf8",
);
const parserSource = readFileSync(
join(process.cwd(), "src/lib/measurements/import-apple-health-export.ts"),
"utf8",
);
const statusRouteSource = readFileSync(
join(
process.cwd(),
"src/app/api/import/apple-health-export/[jobId]/status/route.ts",
),
"utf8",
);
describe("Apple Health import — the archive's export stamp reaches the column", () => {
it("subscribes to the parser's export-date hook", () => {
expect(workerSource).toMatch(/onExportDate:\s*async\s*\(exportedAt\)/);
});
it("writes the stamp onto the job row it is running", () => {
expect(workerSource).toMatch(
/onExportDate:[\s\S]{0,400}?prisma\s*\.?\s*importJob[\s\S]{0,200}?\.update\([\s\S]{0,200}?exportedAt/,
);
});
it("keeps the write best-effort so provenance cannot fail an import", () => {
expect(workerSource).toMatch(
/onExportDate:[\s\S]{0,400}?exportedAt[\s\S]{0,120}?\.catch\(/,
);
});
it("no longer discards the element that carries the stamp", () => {
// The ignore list is where `ExportDate` spent its first year.
const ignoreBlock = /Known elements we intentionally ignore/.exec(
parserSource,
);
expect(ignoreBlock).not.toBeNull();
const before = parserSource.slice(
Math.max(0, (ignoreBlock?.index ?? 0) - 400),
ignoreBlock?.index ?? 0,
);
expect(before).not.toMatch(/name === "ExportDate" \|\|/);
});
it("still surfaces the column the contract promises", () => {
expect(statusRouteSource).toMatch(/exportedAt:\s*row\.exportedAt/);
});
});
@@ -417,6 +417,16 @@ export async function handleAppleHealthImport(
},
});
},
// The instant the Health app stamped on the archive. Persisted as
// soon as the parser reads it, so the status endpoint answers with
// it for the rest of the run and a job that later fails still
// records which export it was working from. Best-effort: the
// stamp is provenance, and losing it must not fail an import.
onExportDate: async (exportedAt) => {
await prisma.importJob
.update({ where: { id: importJobId }, data: { exportedAt } })
.catch(() => {});
},
})),
ecg: {
discovered: 0,
@@ -1226,3 +1226,55 @@ describe("streamParseExportXml — cycle module off", () => {
expect(result.totals.recordsRead).toBe(2);
});
});
/**
* `ImportJob.exportedAt` — the instant the Health app stamped on the
* archive. The status endpoint and the published contract have both
* promised it since v1.4.34, but `<ExportDate>` sat on the parser's
* ignore list, so the column could only ever answer null. These pin the
* capture: remove the `onExportDate` call from the parser and the first
* case goes red; drop the NaN guard and the third does.
*/
describe("streamParseExportXml — the archive's own export stamp", () => {
async function parseFor(xml: string) {
const tmp = mkdtempSync(join(tmpdir(), "healthlog-parser-export-date-"));
const xmlPath = join(tmp, "export.xml");
writeFileSync(xmlPath, xml);
const stamps: Date[] = [];
await streamParseExportXml({
xmlPath,
userId: "user-1",
userTimezone: "Europe/Berlin",
// eslint-disable-next-line @typescript-eslint/no-explicit-any
prisma: makeFakePrisma() as any,
onExportDate: (exportedAt) => {
stamps.push(exportedAt);
},
});
return stamps;
}
it("hands the caller the instant Apple wrote on the export", async () => {
const stamps = await parseFor(tinyExportXml());
expect(stamps).toHaveLength(1);
// "2026-05-15 14:32:01 +0200" — the fixture's own stamp.
expect(stamps[0]?.toISOString()).toBe("2026-05-15T12:32:01.000Z");
});
it("stays silent for an archive that carries no stamp", async () => {
const stamps = await parseFor(
`<?xml version="1.0" encoding="UTF-8"?>\n<HealthData locale="en_US"></HealthData>`,
);
expect(stamps).toEqual([]);
});
it("stays silent rather than guessing at an unreadable stamp", async () => {
const stamps = await parseFor(
`<?xml version="1.0" encoding="UTF-8"?>\n<HealthData locale="en_US">\n <ExportDate value="not a date"/>\n</HealthData>`,
);
expect(stamps).toEqual([]);
});
});
@@ -1,6 +1,7 @@
import { describe, it, expect } from "vitest";
import { resolveToCanonicalUnit } from "../unit-aliases";
import { MGDL_PER_MMOL, mgdlToMmol } from "@/lib/glucose";
describe("resolveToCanonicalUnit", () => {
it("passes the canonical unit through case-insensitively", () => {
@@ -53,10 +54,17 @@ describe("resolveToCanonicalUnit", () => {
});
});
it("converts glucose mmol/L to canonical mg/dL", () => {
it("converts glucose mmol/L to canonical mg/dL on the app's one factor", () => {
// This used to assert 18.016 while every display path divided by
// 18.0182, so a reading imported as mmol/L and read back as mmol/L did
// not return the number it went in as. Both ends take the same factor
// now, and the assertion names it rather than repeating a literal —
// pinning the constant twice is how the two drifted apart.
const out = resolveToCanonicalUnit("BLOOD_GLUCOSE", 5.3, "mmol/L");
expect(out?.unit).toBe("mg/dL");
expect(out?.value).toBeCloseTo(5.3 * 18.016, 3);
expect(out?.value).toBeCloseTo(5.3 * MGDL_PER_MMOL, 3);
// The round trip a mmol/L reader actually experiences.
expect(mgdlToMmol(out?.value ?? 0)).toBe(5.3);
});
it("refuses an unrecognised or type-mismatched unit (never mis-stores)", () => {
@@ -307,6 +307,13 @@ export interface StreamParseInput {
* continues even if the hook throws.
*/
onProgress?: (snapshot: ImportJobProgress) => Promise<void> | void;
/**
* Called once, mid-run, with the instant Apple stamped on the archive
* (`<ExportDate value="..."/>`, the first child of `<HealthData>`).
* Never called for an archive that omits the element or writes an
* unreadable value. Best-effort, like `onProgress`.
*/
onExportDate?: (exportedAt: Date) => Promise<void> | void;
/**
* Optional override of the spot-row flush batch size. Defaults to
* `SPOT_FLUSH_BATCH`. Lower values make the upsert path more
@@ -339,6 +346,7 @@ export async function streamParseExportXml(
userTimezone,
prisma,
onProgress,
onExportDate,
spotBatchSize = SPOT_FLUSH_BATCH,
workoutBatchSize = WORKOUT_FLUSH_BATCH,
} = input;
@@ -775,6 +783,21 @@ export async function streamParseExportXml(
let pendingError: Error | null = null;
let currentWorkout: PreparedWorkout | null = null;
// Apple stamps the archive with its own export instant as the first
// child of `<HealthData>`. The element used to be on the ignore list,
// so `ImportJob.exportedAt` — a column the status endpoint and the
// published contract both promise — could only ever answer null. The
// value is captured in the synchronous tag handler and handed to
// `onExportDate` from the async drain, so the worker can persist it
// while the run is still going rather than only on the terminal write.
let pendingExportDate: Date | null = null;
const flushExportDate = async (): Promise<void> => {
const stamped = pendingExportDate;
if (!stamped) return;
pendingExportDate = null;
if (onExportDate) await onExportDate(stamped);
};
parser.onerror = (err) => {
pendingError = err instanceof Error ? err : new Error(String(err));
};
@@ -983,8 +1006,17 @@ export async function streamParseExportXml(
return;
}
if (name === "ExportDate") {
// `value` carries Apple's own format ("2026-05-15 14:32:01 +0200"),
// the same shape every `Record` start/end date uses. An archive
// without the element, or with a value the runtime cannot read,
// leaves the column null rather than guessing at an instant.
const stamped = new Date(attrs.value ?? "");
if (!Number.isNaN(stamped.getTime())) pendingExportDate = stamped;
return;
}
if (
name === "ExportDate" ||
name === "Me" ||
name === "Correlation" ||
name === "ActivitySummary" ||
@@ -1049,9 +1081,11 @@ export async function streamParseExportXml(
}
// Drain any batches the parser filled to keep memory bounded.
const shouldFlush =
pendingExportDate !== null ||
spotBatch.length >= spotBatchSize ||
workoutBatch.length >= workoutBatchSize;
const drain = async (): Promise<void> => {
await flushExportDate();
if (spotBatch.length >= spotBatchSize) await flushSpotBatch();
if (workoutBatch.length >= workoutBatchSize)
await flushWorkoutBatch();
@@ -1090,6 +1124,10 @@ export async function streamParseExportXml(
await pipeline(readable, sink);
if (pendingError) throw pendingError;
// An archive small enough to arrive in a single chunk can finish
// before any drain ran; the stamp still has to reach the caller.
await flushExportDate();
await emitProgress("upserting");
// Drain any partial spot/workout batches that did not hit the flush
// threshold during the parse.
+2 -4
View File
@@ -17,9 +17,7 @@
* Pure + side-effect-free; safe to import from an API route or a script.
*/
import { getUnitForType } from "@/lib/validations/measurement";
/** Glucose mmol/L → mg/dL. */
const GLUCOSE_MMOL_TO_MGDL = 18.016;
import { MGDL_PER_MMOL } from "@/lib/glucose";
/** Exact pound → kilogram (1 lb = 0.45359237 kg). */
const LB_TO_KG = 0.45359237;
/** Exact inch → centimetre (1 in = 2.54 cm). */
@@ -87,7 +85,7 @@ export function resolveToCanonicalUnit(
// Glucose: mmol/L → mg/dL.
if (type === "BLOOD_GLUCOSE" && MMOL_ALIASES.has(lower)) {
return { value: value * GLUCOSE_MMOL_TO_MGDL, unit: canonical };
return { value: value * MGDL_PER_MMOL, unit: canonical };
}
// Body mass: lb → kg.
+65
View File
@@ -26,6 +26,7 @@ import {
injectionSitePrefsPatchSchema,
labsLocalOcrPatchSchema,
unitPreferencePatchSchema,
glucoseUnitPatchSchema,
useCentralCodexPatchSchema,
} from "@/lib/validations/user-prefs";
import {
@@ -555,6 +556,16 @@ const unitPreferenceResponse = z
.object({ unitPreference: z.enum(["metric", "imperial"]) })
.meta({ id: "UnitPreferenceResponse" });
const glucoseUnitPatchRequest = glucoseUnitPatchSchema.meta({
id: "GlucoseUnitPatchRequest",
description:
"Which unit blood-glucose readings are rendered in. Presentation only — every stored reading is mg/dL either way.",
});
const glucoseUnitResponse = z
.object({ glucoseUnit: z.enum(["mg/dL", "mmol/L"]) })
.meta({ id: "GlucoseUnitResponse" });
const documentsAutoAiReadPatchRequest = documentsAutoAiReadPatchSchema.meta({
id: "DocumentsAutoAiReadPatchRequest",
description:
@@ -1577,6 +1588,60 @@ export const profilePaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
},
"/api/auth/me/glucose-unit": {
get: {
tags: ["Auth"],
summary: "Read the blood-glucose display unit",
description:
"Which unit blood-glucose readings are rendered in — `mg/dL` or `mmol/L`. A separate choice from the metric/imperial preference, because metric countries are split on which one they read glucose in. Canonical storage is mg/dL on every reading and every ingest path; this changes presentation only. Any stored value other than `mmol/L` resolves to `mg/dL`, including a null on an account that never set it.",
responses: {
"200": {
description: "The resolved unit.",
content: {
"application/json": {
schema: dataEnvelope(
glucoseUnitResponse,
"GetGlucoseUnitEnvelope",
),
},
},
},
...stdResponses,
},
},
patch: {
tags: ["Auth"],
summary: "Set the blood-glucose display unit",
description:
"Hard-set, idempotent, audit-logged. Rate-limited 60 / min per user.\n\n" +
"Nothing already stored is converted or reinterpreted: readings stay mg/dL, and a value typed into the entry form in mmol/L is inverted to mg/dL before it is written.\n\n" +
"The body is capped at 1 KB and must carry `Content-Type: application/json`. Anything larger is 413, a wrong content type is 415, and a body that is not JSON at all is 400 — the same three the other scalars in this group answer.",
requestBody: {
required: true,
content: {
"application/json": { schema: glucoseUnitPatchRequest },
},
},
responses: {
"200": {
description: "The resolved next unit.",
content: {
"application/json": {
schema: dataEnvelope(
glucoseUnitResponse,
"PatchGlucoseUnitEnvelope",
),
},
},
},
"413": {
description: "Request body exceeds 1024 bytes. Nothing was written.",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
},
"/api/auth/me/documents-auto-ai-read": {
get: {
tags: ["Auth"],
+9
View File
@@ -31,6 +31,15 @@ export const authKeys = {
* without a manual reload.
*/
userUnitPreference: () => ["user", "unit-preference"] as const,
/**
* The mg/dL vs mmol/L glucose display control behind
* `GET /api/auth/me/glucose-unit`. A separate axis from the
* metric/imperial preference above — metric countries are split on
* which one they read glucose in — so it carries its own key. The
* PATCH also invalidates `authMe()`, since every glucose surface
* resolves the unit from the account payload rather than from here.
*/
userGlucoseUnit: () => ["user", "glucose-unit"] as const,
passkeys: () => ["passkeys"] as const,
+11
View File
@@ -20,6 +20,17 @@ export const unitPreferencePatchSchema = z.object({
unitPreference: z.enum(["metric", "imperial"]),
});
/**
* `PATCH /api/auth/me/glucose-unit` — mg/dL vs mmol/L display branch.
*
* Not the metric/imperial preference: the two split along different lines.
* Germany is metric and reads glucose in mg/dL; the UK and the Nordics read
* it in mmol/L. Canonical storage stays mg/dL either way.
*/
export const glucoseUnitPatchSchema = z.object({
glucoseUnit: z.enum(["mg/dL", "mmol/L"]),
});
/** `PATCH /api/auth/me/documents-auto-ai-read` — the auto-read opt-in. */
export const documentsAutoAiReadPatchSchema = z.object({
documentsAutoAiRead: z.boolean(),