feat(apple-health): show when each type last arrived and how

The Apple Health card listed each type's newest sample. A type the phone
only hands over on "Sync all" can carry a reading from this morning and
never have arrived in the background, so the sample time could not answer
whether a type flows on its own.

The batch route's per-type ledger now records, in one upsert per batch,
when each Apple Health type last arrived, the trigger that carried it
(including the new `manual`), and when a batch last brought a new or
updated sample of it. Duplicate-only re-sends move the arrival but keep the
last new value; scoped credentials and MANUAL rows write nothing, the same
rule as the sync checkpoint. A ledger failure leaves a warn line and never
fails the ingest.

`GET /api/integrations/healthkit` lays `lastReceivedAt`, `lastTrigger` and
`lastNewSampleAt` over each `metricFreshness` entry (null for a type no live
sync has carried, absent on the workouts entry and when the ledger read
failed), and the card shows them as a second line per type.

The per-type newest-sample read walks live types through
`listLiveMeasurementTypes` and probes each type's newest row instead of
grouping every live row of the source.
This commit is contained in:
Marc-André Bombeck committed 2026-10-08 09:22:49 +02:00
1 parent c8470cc1e6
commit ba99551faa
15 files changed
+976 -114

No files matched your search

@@ -8,14 +8,35 @@
*/
import { beforeEach, describe, expect, it, vi } from "vitest";
const groupByMock = vi.hoisted(() => vi.fn());
/**
* The fixtures keep the grouped-row shape (`source`, `type`, `_max`) the read
* used to take. Since v1.42 the module asks `listLiveMeasurementTypes` per
* source and then probes each type's newest row in one raw query; the two
* mocks below answer both from the same fixture rows.
*/
type GroupedRow = {
source: string;
type: string;
_max: { measuredAt: Date | null };
};
let measurementRows: GroupedRow[] = [];
const groupByMock = {
mockResolvedValue(rows: GroupedRow[]) {
measurementRows = rows;
},
};
const liveTypesMock = vi.hoisted(() => vi.fn());
const queryRawMock = vi.hoisted(() => vi.fn());
const workoutGroupByMock = vi.hoisted(() => vi.fn());
vi.mock("@/lib/db", () => ({
prisma: {
measurement: { groupBy: groupByMock },
$queryRaw: queryRawMock,
workout: { groupBy: workoutGroupByMock },
},
}));
vi.mock("@/lib/measurements/live-types", () => ({
listLiveMeasurementTypes: liveTypesMock,
}));
import {
getSourceFreshness,
@@ -28,7 +49,32 @@ import {
} from "../sync-verdict";
beforeEach(() => {
groupByMock.mockReset();
measurementRows = [];
liveTypesMock.mockReset();
liveTypesMock.mockImplementation(
async (_userId: string, options: { source: string }) =>
measurementRows
.filter((row) => row.source === options.source)
.map((row) => row.type),
);
queryRawMock.mockReset();
queryRawMock.mockImplementation(
async (_strings: TemplateStringsArray, ...values: unknown[]) => {
const types = values.find(Array.isArray) as string[];
const source = values.find(
(value) =>
typeof value === "string" &&
measurementRows.some((row) => row.source === value),
);
return types.map((type) => ({
type,
last_seen:
measurementRows.find(
(row) => row.source === source && row.type === type,
)?._max.measuredAt ?? null,
}));
},
);
workoutGroupByMock.mockReset();
workoutGroupByMock.mockResolvedValue([]);
});
@@ -65,11 +111,10 @@ describe("getSourceMetricFreshness", () => {
expect(result.withings).toEqual([
{ type: "WEIGHT", lastSeenAt: "2026-07-06T00:00:00.000Z" },
]);
// Only the sync sources are queried.
expect(groupByMock.mock.calls[0][0].where.source.in).toEqual(
Object.values(INTEGRATION_MEASUREMENT_SOURCE),
);
expect(groupByMock.mock.calls[0][0].where.deletedAt).toBeNull();
// Only the sync sources are asked about, one live-type walk each.
expect(
liveTypesMock.mock.calls.map((call) => call[1].source).sort(),
).toEqual([...Object.values(INTEGRATION_MEASUREMENT_SOURCE)].sort());
});
it("skips rows with no reading and unmapped sources", async () => {
@@ -175,9 +220,30 @@ describe("getSourceFreshness — one source, for Apple Health", () => {
expect(await getSourceFreshness("u1", "APPLE_HEALTH")).toEqual([
{ type: "RESPIRATORY_RATE", lastSeenAt: "2026-07-01T00:00:00.000Z" },
]);
expect(groupByMock.mock.calls[0][0].where.source.in).toEqual([
"APPLE_HEALTH",
expect(liveTypesMock).toHaveBeenCalledTimes(1);
expect(liveTypesMock.mock.calls[0][1]).toEqual({ source: "APPLE_HEALTH" });
});
it("issues no per-type probe when the source has no live types", async () => {
expect(await getSourceFreshness("u1", "APPLE_HEALTH")).toEqual([]);
expect(queryRawMock).not.toHaveBeenCalled();
});
it("probes live rows of the one source only", async () => {
groupByMock.mockResolvedValue([
{
source: "APPLE_HEALTH",
type: "PULSE",
_max: { measuredAt: new Date("2026-07-01T00:00:00.000Z") },
},
]);
await getSourceFreshness("u1", "APPLE_HEALTH");
const sql = (queryRawMock.mock.calls[0][0] as TemplateStringsArray).join(
"?",
);
expect(sql).toContain('"deleted_at" IS NULL');
expect(sql).toContain('"source" = ?::"measurement_source"');
expect(sql).toContain("LIMIT 1");
});
});
+135 -3
View File
@@ -7,13 +7,30 @@
* it to show which types are actually flowing. A scoped ingest credential
* does not write it, the same rule as `lastSyncedAt`.
*
* Contract stub: the signature is final; the body records nothing yet.
* Sample time (`max(measuredAt)`, what the freshness list showed before) and
* arrival time are different questions. A type the phone only hands over
* when someone taps "Sync all" can carry a reading from this morning and
* still never have arrived in the background; only the arrival time and the
* trigger that carried it can show that.
*/
import type { MeasurementType, Prisma } from "@/generated/prisma/client";
import { prisma } from "@/lib/db";
import { logCaught } from "@/lib/logging/signal";
import {
WORKOUT_FRESHNESS_TYPE,
type MetricFreshnessEntry,
} from "./sync-verdict";
export type HealthKitSyncTrigger =
"foreground" | "background" | "push" | "manual";
const TRIGGERS: ReadonlySet<string> = new Set<HealthKitSyncTrigger>([
"foreground",
"background",
"push",
"manual",
]);
/** What one batch did for one type. */
export interface HealthKitTypeArrival {
/** Entries of this type the batch accepted (inserted, updated or duplicate). */
@@ -22,6 +39,16 @@ export interface HealthKitTypeArrival {
newSamples: number;
}
/**
* One statement for the whole batch (`unnest` over at most a few dozen
* types). `last_received_at` and `last_trigger` describe the latest batch
* that carried the type, so they are overwritten; `last_new_sample_at` only
* moves when this batch brought something new, so a duplicates-only re-send
* keeps the earlier date standing.
*
* Best effort: the ledger is a diagnostic beside rows that are already
* written, so a failure here leaves a `warn` line and never fails the ingest.
*/
export async function recordHealthKitTypeArrivals(
tx: Prisma.TransactionClient,
input: {
@@ -31,6 +58,111 @@ export async function recordHealthKitTypeArrivals(
at?: Date;
},
): Promise<void> {
void tx;
void input;
const types: string[] = [];
const brought: boolean[] = [];
for (const [type, arrival] of input.counts) {
if (arrival.accepted <= 0) continue;
types.push(type);
brought.push(arrival.newSamples > 0);
}
if (types.length === 0) return;
// An ISO string cast in SQL, not a JS `Date`: a Date parameter is
// serialised in the process's local zone and these are zone-less UTC
// columns (same reasoning as the access-token sunset in refresh-token.ts).
const at = (input.at ?? new Date()).toISOString();
try {
await tx.$executeRaw`
INSERT INTO "healthkit_type_syncs"
("user_id", "type", "last_received_at", "last_trigger", "last_new_sample_at")
SELECT ${input.userId}, u.t::"measurement_type",
${at}::timestamptz AT TIME ZONE 'UTC', ${input.trigger},
CASE WHEN u.n THEN ${at}::timestamptz AT TIME ZONE 'UTC' END
FROM unnest(${types}::text[], ${brought}::boolean[]) AS u(t, n)
ON CONFLICT ("user_id", "type") DO UPDATE SET
"last_received_at" = EXCLUDED."last_received_at",
"last_trigger" = EXCLUDED."last_trigger",
"last_new_sample_at" = COALESCE(
EXCLUDED."last_new_sample_at",
"healthkit_type_syncs"."last_new_sample_at"
)
`;
} catch (error) {
logCaught("healthkit.type_sync.record_failed", error, {
types: types.length,
});
}
}
/** One type's arrival facts, as the Apple Health status read serves them. */
export interface HealthKitTypeArrivalRecord {
lastReceivedAt: string;
lastTrigger: HealthKitSyncTrigger | null;
lastNewSampleAt: string | null;
}
/**
* Every recorded type for one account, keyed by `MeasurementType`. A stored
* trigger outside the known set (none is written, but the column is text)
* reads as null rather than reaching the client as an unknown label.
*/
export async function getHealthKitTypeArrivals(
userId: string,
): Promise<Map<string, HealthKitTypeArrivalRecord>> {
const rows = await prisma.healthKitTypeSync.findMany({
where: { userId },
select: {
type: true,
lastReceivedAt: true,
lastTrigger: true,
lastNewSampleAt: true,
},
});
const out = new Map<string, HealthKitTypeArrivalRecord>();
for (const row of rows) {
out.set(row.type, {
lastReceivedAt: row.lastReceivedAt.toISOString(),
lastTrigger:
row.lastTrigger && TRIGGERS.has(row.lastTrigger)
? (row.lastTrigger as HealthKitSyncTrigger)
: null,
lastNewSampleAt: row.lastNewSampleAt?.toISOString() ?? null,
});
}
return out;
}
/** A freshness entry with the arrival facts beside the newest sample. */
export interface HealthKitFreshnessEntry extends MetricFreshnessEntry {
/** When a live sync last carried this type; null when none has. */
lastReceivedAt?: string | null;
/** The trigger of that sync; null when absent or not reported. */
lastTrigger?: HealthKitSyncTrigger | null;
/** When a live sync last brought a new or updated sample of it. */
lastNewSampleAt?: string | null;
}
/**
* Lay the arrival ledger over the per-type freshness entries. Every
* measurement type gets the three fields, null when no live sync has carried
* it yet (a type that so far came only from the export import, or from before
* the ledger existed). The `WORKOUTS` entry is left without them: workouts
* arrive through their own batch route, which the ledger does not cover, and
* "not received yet" would be false. A null ledger (the read failed) leaves
* every entry as it was rather than claiming nothing arrived.
*/
export function withHealthKitArrivals(
entries: readonly MetricFreshnessEntry[],
arrivals: ReadonlyMap<string, HealthKitTypeArrivalRecord> | null,
): HealthKitFreshnessEntry[] {
if (!arrivals) return [...entries];
return entries.map((entry) => {
if (entry.type === WORKOUT_FRESHNESS_TYPE) return entry;
const arrival = arrivals.get(entry.type);
return {
...entry,
lastReceivedAt: arrival?.lastReceivedAt ?? null,
lastTrigger: arrival?.lastTrigger ?? null,
lastNewSampleAt: arrival?.lastNewSampleAt ?? null,
};
});
}
+58 -20
View File
@@ -10,7 +10,7 @@
* but idle".
*
* This computes the last-value timestamp per `(source, type)` straight from the
* `Measurement` table (no schema change, no migration) so a caller can surface
* `Measurement` table so a caller can surface
* per-metric liveness honestly: a metric whose newest reading is frozen weeks in
* the past is visibly distinct from one that is genuinely current. The
* classification of "quiet" vs "current" is a pure function next to the verdict
@@ -22,7 +22,11 @@
* pseudo-entry so those pipes are visible too.
*/
import { prisma } from "@/lib/db";
import type { MeasurementSource } from "@/generated/prisma/client";
import type {
MeasurementSource,
MeasurementType,
} from "@/generated/prisma/client";
import { listLiveMeasurementTypes } from "@/lib/measurements/live-types";
import type { IntegrationKey } from "./status";
import {
WORKOUT_FRESHNESS_TYPE,
@@ -70,34 +74,68 @@ export const INTEGRATION_WORKOUT_SOURCE: Partial<
};
/**
* Newest measurement per `(source, type)` for the given sources. One grouped
* query; a `(source, type)` pair with no rows simply has no entry, which is how
* honest absence stays structural — a metric a provider never delivered is
* never invented.
* Newest measurement per `(source, type)` for the given sources. A `(source,
* type)` pair with no rows simply has no entry, which is how honest absence
* stays structural — a metric a provider never delivered is never invented.
*
* v1.42: this used to be one `groupBy … _max(measuredAt)` over every live row
* of the sources, which on a multi-year Apple Health history reads six figures
* of rows for a two-digit answer on every settings visit. It now asks which
* types are live per source (`listLiveMeasurementTypes`, a loose index scan)
* and then probes each type's newest row through the same partial covering
* index, one `LIMIT 1` per type.
*/
export async function getMeasurementFreshnessBySource(
userId: string,
sources: readonly MeasurementSource[],
): Promise<Map<MeasurementSource, MetricFreshnessSample[]>> {
const out = new Map<MeasurementSource, MetricFreshnessSample[]>();
if (sources.length === 0) return out;
const grouped = await prisma.measurement.groupBy({
by: ["source", "type"],
where: { userId, deletedAt: null, source: { in: [...sources] } },
_max: { measuredAt: true },
});
for (const row of grouped) {
const lastSeen = row._max.measuredAt;
if (!lastSeen) continue;
const list = out.get(row.source) ?? [];
list.push({ type: row.type, lastSeenAt: lastSeen.toISOString() });
out.set(row.source, list);
const perSource = await Promise.all(
[...new Set(sources)].map(async (source) => {
const types = await listLiveMeasurementTypes(userId, { source });
return { source, samples: await newestPerType(userId, source, types) };
}),
);
for (const { source, samples } of perSource) {
if (samples.length > 0) out.set(source, samples);
}
return out;
}
async function newestPerType(
userId: string,
source: MeasurementSource,
types: readonly MeasurementType[],
): Promise<MetricFreshnessSample[]> {
if (types.length === 0) return [];
// Parameter-bound throughout; the enum casts are literal SQL.
const rows = await prisma.$queryRaw<
Array<{ type: string; last_seen: Date | null }>
>`
SELECT live."type"::text AS "type",
(
SELECT m."measured_at"
FROM "measurements" m
WHERE m."user_id" = ${userId}
AND m."type" = live."type"
AND m."deleted_at" IS NULL
AND m."source" = ${source}::"measurement_source"
ORDER BY m."measured_at" DESC
LIMIT 1
) AS "last_seen"
FROM unnest(${[...types]}::"measurement_type"[]) AS live("type")
`;
const samples: MetricFreshnessSample[] = [];
for (const row of rows) {
if (!row.last_seen) continue;
samples.push({
type: row.type,
lastSeenAt: new Date(row.last_seen).toISOString(),
});
}
return samples;
}
/**
* Newest workout per source. `Workout` rows are hard-deleted, so there is no
* tombstone predicate to apply.
+34 -2
View File
@@ -117,6 +117,38 @@ const metricFreshnessEntry = z
"Per-metric-type last-seen timestamp with the server-computed staleness flag. Only types that have actually delivered appear — absence is absence, never an invented row.",
});
// #1173 — the Apple Health read adds when each type last ARRIVED, under which
// trigger, and when a sync last brought something new for it. Mirrors
// `HealthKitFreshnessEntry` in `src/lib/integrations/healthkit-type-sync.ts`.
const appleHealthMetricFreshnessEntry = metricFreshnessEntry
.extend({
lastReceivedAt: z.iso
.datetime({ offset: true })
.nullable()
.optional()
.describe(
"When a live sync batch last carried this type (inserted, updated or duplicate entries all count). Null when no live sync has carried it yet: a type that so far came only from the export import, or from before v1.42. `lastSeenAt` is when the newest sample was TAKEN; this is when the server last RECEIVED the type. Omitted on the `WORKOUTS` entry, which the ledger does not cover, and on every entry when the ledger read failed.",
),
lastTrigger: healthKitSyncTriggerEnum
.nullable()
.optional()
.describe(
"The `syncTrigger` of that batch. Null when the client reported none. A type whose trigger is only ever `manual` reaches the server only through a user-started full sync. Same omission rules as `lastReceivedAt`.",
),
lastNewSampleAt: z.iso
.datetime({ offset: true })
.nullable()
.optional()
.describe(
"When a live sync batch last brought a new or updated sample of this type, as opposed to duplicates only. Null when none has. Same omission rules as `lastReceivedAt`.",
),
})
.meta({
id: "AppleHealthMetricFreshnessEntry",
description:
"Per-type Apple Health freshness: the newest sample's timestamp and staleness flag, plus the per-type arrival facts recorded by `POST /api/measurements/batch` (v1.42).",
});
// Issue #778 — the two backfill-progress figures the server genuinely holds.
// The iOS app drives the backfill; its queue, throttle state, and any ETA
// live on the device and are deliberately absent here.
@@ -167,10 +199,10 @@ const healthKitConfigResponse = z
.optional()
.describe("Present on the GET read; omitted from the PATCH echo."),
metricFreshness: z
.array(metricFreshnessEntry)
.array(appleHealthMetricFreshnessEntry)
.optional()
.describe(
"Per-metric-type freshness for the `APPLE_HEALTH` source. Present on the GET read; omitted from the PATCH echo.",
"Per-metric-type freshness for the `APPLE_HEALTH` source, with the per-type arrival facts. Present on the GET read; omitted from the PATCH echo.",
),
syncProgress: appleHealthSyncProgress
.nullable()
+1 -1
View File
@@ -130,7 +130,7 @@ const batchPayloadSchema = z
.enum(["foreground", "background", "push", "manual"])
.optional()
.describe(
'Diagnostic-only. Names what triggered this sync (foreground app open, background refresh, a push wake, or a user-initiated `manual` "Sync all" run, since v1.42). Recorded on the ingest wide event and kept on the account as `lastSyncTrigger` — plus `lastBackgroundSyncAt` for a `background` or `push` trigger — both readable from `GET /api/integrations/healthkit`. It does not affect dedup, attribution, or how any sample is stored. Optional and backward-compatible: pre-#66 clients omit it.',
'Diagnostic-only. Names what triggered this sync (foreground app open, background refresh, a push wake, or a user-initiated `manual` "Sync all" run, since v1.42). Recorded on the ingest wide event and kept on the account as `lastSyncTrigger` — plus `lastBackgroundSyncAt` for a `background` or `push` trigger — both readable from `GET /api/integrations/healthkit`. Since v1.42 it is also recorded per measurement type the batch carried (Apple Health rows only), served as `lastReceivedAt` / `lastTrigger` / `lastNewSampleAt` on each `metricFreshness` entry of that read. It does not affect dedup, attribution, or how any sample is stored. Optional and backward-compatible: pre-#66 clients omit it.',
),
})
.meta({