docs(api): describe the legacy integration-status fields as still served

The published contract said the nine health-shaped fields that predate
`health` were removed in v1.44, but every status read still sends them:
older native builds decode them, the current one falls back to them against
a server without `health`, and the web card's copied diagnostics read the
failure streak. They stay deprecated, without a removal release.
This commit is contained in:
Marc-André Bombeck committed 2026-10-25 12:12:14 +01:00
1 parent 856eb036f8
commit d6bb7bc905
4 files changed
+48 -46

No files matched your search

@@ -1,7 +1,7 @@
{
"$comment": "Comment lines that open with a release version, per file under src/. Maintained by src/__tests__/version-stamp-ratchet.test.ts.",
"count": 2897,
"total": 9247,
"total": 9246,
"entries": {
"__tests__/account-payload-consumer-guard.test.ts": 2,
"__tests__/acting-account-boundary-guard.test.ts": 7,
@@ -360,7 +360,7 @@
"app/api/integrations/healthkit/__tests__/route.test.ts": 4,
"app/api/integrations/healthkit/route.ts": 3,
"app/api/integrations/status/__tests__/route.test.ts": 2,
"app/api/integrations/status/route.ts": 7,
"app/api/integrations/status/route.ts": 6,
"app/api/integrations/withings/resume/__tests__/route.test.ts": 1,
"app/api/integrations/withings/resume/route.ts": 1,
"app/api/internal/deploy-webhook/__tests__/route.test.ts": 2,
+5 -4
View File
@@ -502,8 +502,8 @@ export const GET = apiHandler(async () => {
} satisfies IntegrationViewModel & NightscoutExtras,
{
...publish(dawarichStatus),
// v1.43 — Dawarich, read by the card through `health`. The ledger core
// rides along like on every entry, and goes with the rest in v1.44.
// Dawarich, read by the card through `health`. The ledger core rides
// along like on every entry.
connected: dawarichConfigured,
configured: dawarichConfigured,
health: health["dawarich"],
@@ -524,8 +524,9 @@ interface IntegrationViewModel {
* health-shaped field on this entry (`state`, `lastError`,
* `consecutiveFailuresByKind`, `syncHealth`, `tokenExpired`, `needsReauth`,
* `hasActivityScope`, `planUnavailable`, `scopeReconnect`) is folded into
* it and goes once the settings cards render `health`; no other client
* reads this envelope.
* it. Those stay on the wire, deprecated in the published document; the
* cards render `health`, and only their copied diagnostics still read
* `consecutiveFailuresByKind`. No native client reads this envelope.
*/
health: ConnectionHealth | null;
state: string;
+7 -5
View File
@@ -75,10 +75,12 @@ const healthKitEntry = z
"One resolved HealthKit metric mapping (defaults merged with the user's stored overrides).",
});
// The health-shaped fields that predate `health` (v1.42.4). They stay on the
// wire through v1.43 so App 1.2.0 keeps decoding, are marked deprecated in the
// document, and go in v1.44.
const LEGACY_HEALTH_FIELD = "Deprecated: removed in v1.44, read `health`.";
// The health-shaped fields that predate `health`. They are marked deprecated
// in the document and stay on the wire: native builds from before `health`
// still decode them, the current one falls back to them only against a server
// that sends no `health`, and the web card's copied diagnostics read the
// failure streak. No removal release is set.
const LEGACY_HEALTH_FIELD = "Deprecated, still served: read `health`.";
function legacy(text?: string): { deprecated: true; description: string } {
return {
@@ -1184,7 +1186,7 @@ const integrationEnvelopeEntry = z
health: connectionHealth
.nullable()
.describe(
"The unified connection state, null when the provider is not connected (and for Fitbit once `retirement.ended`). It supersedes `state`, `lastError`, `consecutiveFailuresByKind`, `syncHealth`, `tokenExpired`, `needsReauth`, `hasActivityScope`, `planUnavailable` and `scopeReconnect` on this entry; those nine are deprecated and removed in v1.44.",
"The unified connection state, null when the provider is not connected (and for Fitbit once `retirement.ended`). It supersedes `state`, `lastError`, `consecutiveFailuresByKind`, `syncHealth`, `tokenExpired`, `needsReauth`, `hasActivityScope`, `planUnavailable` and `scopeReconnect` on this entry; those nine are deprecated and still served for clients that predate `health`.",
),
})
.meta({