Merge w11b/a4hrwire into release/v1.19.0

This commit is contained in:
Marc-André Bombeck committed 2026-06-21 10:22:36 +02:00
commit 837f215f66
6 files changed
+540 -19

No files matched your search

@@ -0,0 +1,99 @@
/**
* v1.19.0 (iOS #34) — hourly heart-rate wire-contract helpers.
*
* Covers the externalId minting + well-formedness guard that the batch
* ingest route uses to route the go-forward hourly-average PULSE bucket
* through the existing `stats:` overwrite path.
*/
import { describe, expect, it } from "vitest";
import {
hourlyHeartRateStatsExternalId,
isHourlyHeartRateStatsExternalId,
targetsHourlyHeartRateBucket,
} from "@/lib/measurements/apple-health-mapping";
describe("hourlyHeartRateStatsExternalId", () => {
it("floors to the UTC hour and mints the canonical stats externalId", () => {
const id = hourlyHeartRateStatsExternalId(
new Date("2026-06-21T14:37:42.913Z"),
);
expect(id).toBe(
"stats:HKQuantityTypeIdentifierHeartRate:2026-06-21T14:00:00.000Z",
);
});
it("is stable: two instants in the same UTC hour map to one id", () => {
const a = hourlyHeartRateStatsExternalId(new Date("2026-06-21T14:00:00Z"));
const b = hourlyHeartRateStatsExternalId(new Date("2026-06-21T14:59:59Z"));
expect(a).toBe(b);
});
it("round-trips through the well-formedness guard", () => {
const id = hourlyHeartRateStatsExternalId(new Date("2026-01-02T03:04:05Z"));
expect(isHourlyHeartRateStatsExternalId(id)).toBe(true);
});
});
describe("isHourlyHeartRateStatsExternalId", () => {
it("accepts a zeroed ISO-hour HR bucket", () => {
expect(
isHourlyHeartRateStatsExternalId(
"stats:HKQuantityTypeIdentifierHeartRate:2026-06-21T14:00:00.000Z",
),
).toBe(true);
});
it.each([
// non-zero minutes
"stats:HKQuantityTypeIdentifierHeartRate:2026-06-21T14:30:00.000Z",
// missing millis
"stats:HKQuantityTypeIdentifierHeartRate:2026-06-21T14:00:00Z",
// date-only (the per-day cumulative shape, not hourly)
"stats:HKQuantityTypeIdentifierHeartRate:2026-06-21",
// no trailing Z
"stats:HKQuantityTypeIdentifierHeartRate:2026-06-21T14:00:00.000",
// garbage suffix
"stats:HKQuantityTypeIdentifierHeartRate:not-a-date",
// impossible month still matches the regex shape but fails Date parse
"stats:HKQuantityTypeIdentifierHeartRate:2026-13-01T14:00:00.000Z",
])("rejects malformed suffix %s", (id) => {
expect(isHourlyHeartRateStatsExternalId(id)).toBe(false);
});
it.each([
// a different HK identifier's per-day stats row
"stats:HKQuantityTypeIdentifierStepCount:2026-06-21",
// a per-sample uuid externalId
"B3A1C0DE-0000-4000-8000-000000000000",
null,
undefined,
])("returns false for non-HR-bucket externalId %s", (id) => {
expect(isHourlyHeartRateStatsExternalId(id as string | null)).toBe(false);
});
});
describe("targetsHourlyHeartRateBucket", () => {
it("is true for any HR-bucket prefix, valid or malformed", () => {
expect(
targetsHourlyHeartRateBucket(
"stats:HKQuantityTypeIdentifierHeartRate:2026-06-21T14:00:00.000Z",
),
).toBe(true);
expect(
targetsHourlyHeartRateBucket(
"stats:HKQuantityTypeIdentifierHeartRate:not-a-date",
),
).toBe(true);
});
it("is false for per-day cumulative stats and per-sample uuids", () => {
expect(
targetsHourlyHeartRateBucket(
"stats:HKQuantityTypeIdentifierStepCount:2026-06-21",
),
).toBe(false);
expect(targetsHourlyHeartRateBucket("some-uuid")).toBe(false);
expect(targetsHourlyHeartRateBucket(null)).toBe(false);
});
});
@@ -795,6 +795,90 @@ export function dailyStatsExternalId(
return `stats:${hkIdentifier}:${dateYYYYMMDD}`;
}
/**
* v1.19.0 (iOS #34) — go-forward aggregated heart-rate wire contract.
*
* iOS uploads ONE PULSE row per hourly heart-rate bucket instead of one
* row per raw HealthKit sample (~16k rows/user/day → ~24). The bucket's
* `value` is the hourly AVERAGE bpm; the row reuses the existing
* `stats:` overwrite path so a re-post within the same hour (the running
* average shifts as more samples land) OVERWRITES rather than
* duplicating — identical mechanics to the per-day `stats:<HK>:<day>`
* cumulative rows, but at hourly granularity for the spot HR metric.
*
* Format: `stats:HKQuantityTypeIdentifierHeartRate:<bucket-start>` where
* `<bucket-start>` is the ISO-8601 instant of the hour boundary in UTC
* with a literal `Z` and ZEROED minutes/seconds/millis — e.g.
* `stats:HKQuantityTypeIdentifierHeartRate:2026-06-21T14:00:00.000Z`.
*
* The hour boundary is in UTC (not the user's local hour) so the
* externalId is timezone-stable: a user travelling across zones never
* re-keys the same wall-clock hour to a new bucket. The `measuredAt`
* the client sends (`endDate`) still carries the offset for display.
*
* AVG-ONLY in v1.19.0. The `Measurement` model carries a single `value`
* column; hourly min/max would need a schema migration (companion
* columns or companion `stats:` rows), which is a fast-follow — see the
* iOS-coord note. Until then iOS uploads the hourly mean as PULSE; the
* raw min/max is recoverable from the device's HealthKit store and the
* server-side nightly fold of any residual raw backlog.
*/
const HOURLY_HR_HK_IDENTIFIER = "HKQuantityTypeIdentifierHeartRate";
export function hourlyHeartRateStatsExternalId(bucketStart: Date): string {
const hourFloor = new Date(bucketStart);
hourFloor.setUTCMinutes(0, 0, 0);
return `stats:${HOURLY_HR_HK_IDENTIFIER}:${hourFloor.toISOString()}`;
}
/**
* The exact ISO-hour suffix shape the hourly HR bucket externalId must
* carry: full ISO-8601 UTC instant, minutes/seconds/millis all zero,
* trailing `Z`. Anchored so a partial / malformed suffix is rejected.
*/
const HOURLY_HR_SUFFIX_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:00:00\.000Z$/;
/**
* v1.19.0 (iOS #34) — well-formedness guard for the hourly HR bucket
* externalId. Returns `true` ONLY for a `stats:` externalId that targets
* the heart-rate identifier AND carries a zeroed ISO-hour suffix that
* parses to a real instant. Used by the batch route to reject a
* malformed hourly-HR bucket (`skipped:"malformed_hr_bucket_id"`) rather
* than persisting an un-overwriteable, un-foldable garbage row.
*
* Non-HR `stats:` externalIds (the per-day cumulative rows) are NOT this
* function's concern — it returns `false` for them so the caller leaves
* them on the untouched path.
*/
export function isHourlyHeartRateStatsExternalId(
externalId: string | null | undefined,
): boolean {
if (typeof externalId !== "string") return false;
const prefix = `stats:${HOURLY_HR_HK_IDENTIFIER}:`;
if (!externalId.startsWith(prefix)) return false;
const suffix = externalId.slice(prefix.length);
if (!HOURLY_HR_SUFFIX_RE.test(suffix)) return false;
const parsed = new Date(suffix);
return !Number.isNaN(parsed.getTime());
}
/**
* v1.19.0 (iOS #34) — does this externalId CLAIM to be an hourly HR
* bucket (right prefix + HR identifier) regardless of suffix validity?
* The route uses this to decide a malformed-vs-valid split: a row that
* targets the HR bucket prefix but fails `isHourlyHeartRateStatsExternalId`
* is a malformed bucket (reject), not an unrelated `stats:` row (pass
* through untouched).
*/
export function targetsHourlyHeartRateBucket(
externalId: string | null | undefined,
): boolean {
return (
typeof externalId === "string" &&
externalId.startsWith(`stats:${HOURLY_HR_HK_IDENTIFIER}:`)
);
}
/**
* v1.4.30 — reverse lookup from a HealthLog `MeasurementType` to the
* canonical HealthKit identifier for that type. Used by the drain
+26 -5
View File
@@ -26,7 +26,12 @@ const batchEntrySchema = z
.describe(
"HealthKit identifier (e.g. `HKQuantityTypeIdentifierBodyMass`).",
),
value: z.number().finite(),
value: z
.number()
.finite()
.describe(
"Raw HealthKit reading in Apple's native unit; the server applies any canonical scaling at ingest. For an hourly heart-rate bucket (see `externalId`) this is the hour's AVERAGE bpm — v1.19.0 ships avg-only; min/max are a documented fast-follow.",
),
unit: z.string().min(1).max(60),
startDate: z.iso.datetime({ offset: true }),
endDate: z.iso.datetime({ offset: true }),
@@ -52,7 +57,12 @@ const batchEntrySchema = z
.string()
.min(1)
.max(120)
.describe("HKSample.uuid string — the dedup key."),
.describe(
"Dedup key for the `(userId, type, source, externalId)` composite index. Three shapes:\n" +
"• `HKSample.uuid` — a per-sample reading. First-write-wins: a re-post returns `duplicate` and the stored row is immutable.\n" +
"• `stats:<HKQuantityTypeIdentifier>:<YYYY-MM-DD>` — a per-day cumulative total (Steps, Active Energy, Sleep Duration, Walking/Running Distance, Flights Climbed). A re-post OVERWRITES the row and returns `updated`.\n" +
"• `stats:HKQuantityTypeIdentifierHeartRate:<bucket-start-hour>` — v1.19.0 (iOS #34) hourly heart-rate bucket carrying the hour's AVERAGE bpm as one PULSE row. `<bucket-start-hour>` is the ISO-8601 UTC hour boundary with zeroed minutes/seconds/millis and a trailing `Z` (e.g. `2026-06-21T14:00:00.000Z`). A re-post within the hour OVERWRITES the row and returns `updated`, so iOS uploads ~24 rows/day instead of one per raw HR sample. A row that targets this prefix with a malformed hour suffix is `skipped` with reason `malformed_hr_bucket_id`.",
),
externalSourceVersion: z.string().min(1).max(120).optional(),
// v1.8.6 W6 — optional per-entry source tag. Defaults to
// `APPLE_HEALTH` server-side when omitted, so legacy clients are
@@ -90,16 +100,27 @@ const batchPayloadSchema = z
const batchEntryResult = z
.object({
index: z.number().int().nonnegative(),
status: z.enum(["inserted", "duplicate", "skipped"]),
status: z
.enum(["inserted", "updated", "duplicate", "skipped"])
.describe(
"`inserted`/`duplicate` — the row landed (advance the cursor). `updated` — a `stats:` aggregate (per-day cumulative total or hourly heart-rate bucket) overwrote an existing row. `skipped` — not stored (e.g. unmappable identifier, out-of-range value, or `malformed_hr_bucket_id`); see `reason`.",
),
reason: z.string().optional(),
})
.meta({ id: "AppleHealthBatchEntryResult" });
const batchResponse = z
.object({
processed: z.number().int().nonnegative(),
inserted: z.number().int().nonnegative(),
duplicate: z.number().int().nonnegative(),
skipped: z.number().int().nonnegative(),
updated: z.number().int().nonnegative(),
duplicates: z.number().int().nonnegative(),
skipped: z.array(
z.object({
index: z.number().int().nonnegative(),
reason: z.string(),
}),
),
entries: z.array(batchEntryResult),
})
.meta({ id: "AppleHealthBatchResponse" });