Tell a first-run what Apple Health is actually doing

Refs #778. Two honesty gaps from the first-run report: the web onboarding
presented Apple Health like a web connector although the connection only
completes in the iPhone app, and the initial backfill gave no sign of
progress, so a working first sync looked broken.

The onboarding source step now says plainly that Apple Health is set up in
the iPhone app after onboarding, without dead-ending the flow. The
integration card gains a server-authoritative progress summary — rows
accepted, oldest reading reached, and an honest flowing/waiting line
derived from the last accepted batch. Nothing the server does not know is
shown: no percentage, no ETA, no invented throttle state; a quiet stretch
reads as waiting for the phone, not as an error.
This commit is contained in:
Marc-André Bombeck committed 2026-08-14 09:46:24 +02:00
1 parent b1be67bfa7
commit a3561b4600
10 files changed
+486 -4

No files matched your search

@@ -0,0 +1,93 @@
import { describe, it, expect, vi, beforeEach } from "vitest";
vi.mock("@/lib/db", () => ({
prisma: {
measurement: { aggregate: vi.fn() },
workout: { aggregate: vi.fn() },
},
}));
import { getAppleHealthSyncProgress } from "../apple-health-progress";
import { prisma } from "@/lib/db";
function mockAggregates(
measurement: { count: number; min: Date | null },
workout: { count: number; min: Date | null },
) {
vi.mocked(prisma.measurement.aggregate).mockResolvedValue({
_count: { _all: measurement.count },
_min: { measuredAt: measurement.min },
} as never);
vi.mocked(prisma.workout.aggregate).mockResolvedValue({
_count: { _all: workout.count },
_min: { startedAt: workout.min },
} as never);
}
describe("getAppleHealthSyncProgress", () => {
beforeEach(() => {
vi.resetAllMocks();
});
it("sums measurement and workout rows into one accepted count", async () => {
mockAggregates(
{ count: 1200, min: new Date("2019-03-01T08:00:00.000Z") },
{ count: 45, min: new Date("2021-06-01T06:30:00.000Z") },
);
const progress = await getAppleHealthSyncProgress("user-1");
expect(progress.recordsAccepted).toBe(1245);
});
it("reports the oldest instant across both tables", async () => {
mockAggregates(
{ count: 10, min: new Date("2020-01-05T00:00:00.000Z") },
{ count: 3, min: new Date("2018-11-20T07:15:00.000Z") },
);
const progress = await getAppleHealthSyncProgress("user-1");
expect(progress.oldestMeasuredAt).toBe("2018-11-20T07:15:00.000Z");
});
it("uses the measurement minimum when workouts have no rows", async () => {
mockAggregates(
{ count: 8, min: new Date("2022-02-02T12:00:00.000Z") },
{
count: 0,
min: null,
},
);
const progress = await getAppleHealthSyncProgress("user-1");
expect(progress.recordsAccepted).toBe(8);
expect(progress.oldestMeasuredAt).toBe("2022-02-02T12:00:00.000Z");
});
it("is honest about a source that has delivered nothing", async () => {
mockAggregates({ count: 0, min: null }, { count: 0, min: null });
const progress = await getAppleHealthSyncProgress("user-1");
expect(progress).toEqual({ recordsAccepted: 0, oldestMeasuredAt: null });
});
it("scopes both reads to the user and the APPLE_HEALTH source", async () => {
mockAggregates({ count: 0, min: null }, { count: 0, min: null });
await getAppleHealthSyncProgress("user-9");
expect(prisma.measurement.aggregate).toHaveBeenCalledWith(
expect.objectContaining({
where: { userId: "user-9", deletedAt: null, source: "APPLE_HEALTH" },
}),
);
expect(prisma.workout.aggregate).toHaveBeenCalledWith(
expect.objectContaining({
where: { userId: "user-9", source: "APPLE_HEALTH" },
}),
);
});
});
@@ -0,0 +1,63 @@
/**
* First-run Apple Health sync progress (issue #778).
*
* The iOS app drives the HealthKit backfill; the server only ever sees the
* batches that actually arrive. During a first run nothing on the web said
* how far that had come, so a backfill that was quietly working looked
* broken. This module computes the figures the server genuinely holds — how
* many rows carry the `APPLE_HEALTH` source and how far back in time they
* reach — and nothing more: the phone's throttle state, its remaining queue,
* and any ETA live on the device and are deliberately not invented here.
*
* Both the live batch ingest and the one-shot export.zip import write
* `source = APPLE_HEALTH`, so the count is "Apple Health records in
* HealthLog", not "records from one specific pipe" — which is the number a
* user watching a first run actually wants to see grow.
*/
import { prisma } from "@/lib/db";
export interface AppleHealthSyncProgress {
/** Measurement + workout rows carrying the `APPLE_HEALTH` source. */
recordsAccepted: number;
/**
* Earliest instant reached (`measuredAt` for measurements, `startedAt` for
* workouts), as an ISO string; null when nothing has arrived.
*/
oldestMeasuredAt: string | null;
}
/**
* Two grouped aggregates (count + MIN), mirroring the freshness reads in
* `./metric-freshness.ts` which cover the same two tables for the same
* reason: workouts are Apple Health data too, but never `Measurement` rows.
*/
export async function getAppleHealthSyncProgress(
userId: string,
): Promise<AppleHealthSyncProgress> {
const [measurements, workouts] = await Promise.all([
prisma.measurement.aggregate({
where: { userId, deletedAt: null, source: "APPLE_HEALTH" },
_count: { _all: true },
_min: { measuredAt: true },
}),
// `Workout` rows are hard-deleted, so there is no tombstone predicate.
prisma.workout.aggregate({
where: { userId, source: "APPLE_HEALTH" },
_count: { _all: true },
_min: { startedAt: true },
}),
]);
const minima = [measurements._min.measuredAt, workouts._min.startedAt].filter(
(d): d is Date => d instanceof Date,
);
const oldest =
minima.length > 0
? new Date(Math.min(...minima.map((d) => d.getTime())))
: null;
return {
recordsAccepted: measurements._count._all + workouts._count._all,
oldestMeasuredAt: oldest?.toISOString() ?? null,
};
}
+30
View File
@@ -85,6 +85,30 @@ 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.",
});
// 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.
const appleHealthSyncProgress = z
.object({
recordsAccepted: z
.number()
.int()
.describe(
"Measurement + workout rows carrying the `APPLE_HEALTH` source (live batch ingest and the one-shot export import both write it). Soft-deleted measurement rows are excluded.",
),
oldestMeasuredAt: z.iso
.datetime({ offset: true })
.nullable()
.describe(
"Earliest instant reached across those rows (`measuredAt` for measurements, `startedAt` for workouts); null when nothing has arrived. During a first-run backfill this walks backwards as history lands.",
),
})
.meta({
id: "AppleHealthSyncProgress",
description:
"Server-side Apple Health backfill progress: how many rows have been accepted and how far back in time they reach. Only what the server actually knows — no ETA, no device-side queue state.",
});
const healthKitConfigResponse = z
.object({
entries: z.array(healthKitEntry),
@@ -116,6 +140,12 @@ const healthKitConfigResponse = z
.describe(
"Per-metric-type freshness for the `APPLE_HEALTH` source. Present on the GET read; omitted from the PATCH echo.",
),
syncProgress: appleHealthSyncProgress
.nullable()
.optional()
.describe(
"Backfill/sync progress summary. Present on the GET read (null when the progress read failed); omitted from the PATCH echo.",
),
})
.meta({
id: "HealthKitConfigResponse",