mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-17 23:52:24 +00:00
chore(withings): document full meastype mapping + API coverage audit
Adds src/lib/withings/mapping.md as the single source of truth for the meastype → MeasurementType table that the client.ts MEASURE_TYPE_MAP mirrors, and .planning/research/withings-api-coverage.md as the full audit of the Withings public API surface (Measure, Sleep, Heart, Activity, Workouts, User, Notify) against HealthLog's ingestion. The audit scores each gap on user-value / effort / schema-impact and slots additions into v1.4.25 (cheap mappings), v1.4.26 (sleep + activity sync, body composition expansion) and v1.5 (ECG, AFib, workouts).
This commit is contained in:
1 parent
4c9c0687b5
commit
d94981e010
2 files changed
+462
No files matched your search
@@ -0,0 +1,90 @@
|
||||
# Withings meastype → HealthLog `MeasurementType` mapping
|
||||
|
||||
Single source of truth for the `MEASURE_TYPE_MAP` table in `client.ts`. When
|
||||
Withings ships a new measurement type, look it up in the Withings developer
|
||||
guide ([Data API → All Available Health Data][1], [Measure-Getmeas][2]) and
|
||||
either extend `MEASURE_TYPE_MAP` here or add a new `MeasurementType` enum
|
||||
value via `prisma/schema.prisma` + a new migration.
|
||||
|
||||
Audit + scoring of the full surface lives in
|
||||
[`.planning/research/withings-api-coverage.md`](../../../.planning/research/withings-api-coverage.md).
|
||||
|
||||
## Ingested today (v1.4.25)
|
||||
|
||||
| meastype | Withings name | DB enum | DB unit | Source devices |
|
||||
|---|---|---|---|---|
|
||||
| 1 | Weight | `WEIGHT` | kg | every Body / Body+ / Body Cardio / Body Comp / Body Scan |
|
||||
| 6 | Fat Ratio | `BODY_FAT` | % | Body+ family |
|
||||
| 9 | Diastolic BP | `BLOOD_PRESSURE_DIA` | mmHg | BPM Connect / Core / Vision |
|
||||
| 10 | Systolic BP | `BLOOD_PRESSURE_SYS` | mmHg | BPM Connect / Core / Vision |
|
||||
| 11 | Heart Pulse | `PULSE` | bpm | BPM cuffs + scales (standing HR) |
|
||||
| 12 | Temperature (legacy Thermo) | `BODY_TEMPERATURE` | celsius | first-gen Thermo (WBT01) |
|
||||
| 35 | SpO2 (alt code) | `OXYGEN_SATURATION` | % | older firmware reports 35 instead of 54 |
|
||||
| 54 | SpO2 | `OXYGEN_SATURATION` | % | ScanWatch / BPM Vision |
|
||||
| 71 | Body Temperature (core) | `BODY_TEMPERATURE` | celsius | current-gen Thermo |
|
||||
| 77 | Hydration / Water Mass | `TOTAL_BODY_WATER` | kg | Body Comp / Body Scan |
|
||||
| 88 | Bone Mass | `BONE_MASS` | kg | Body Comp / Body Scan |
|
||||
| 123 | VO2 max | `VO2_MAX` | mL/(kg·min) | ScanWatch family |
|
||||
|
||||
### Unit handling
|
||||
|
||||
Withings encodes every value as `value × 10^unit` where `unit` is the
|
||||
decimal exponent (e.g. `value: 65750, unit: -3` → `65.750 kg`). The client
|
||||
applies this rule once per measure in `fetchMeasurements()`. New mappings
|
||||
do not need their own conversion as long as the canonical DB unit matches
|
||||
Withings' SI default (kg, %, mmHg, bpm, °C, mL/(kg·min), …).
|
||||
|
||||
### Webhook subscriptions (v1.4.25)
|
||||
|
||||
`POST /notify?action=subscribe` with `appli`:
|
||||
|
||||
- `appli=1` — weight + composition meastypes (1, 5, 6, 8, 88)
|
||||
- `appli=2` — temperature meastypes (12, 71, 73)
|
||||
- `appli=4` — pressure meastypes (9, 10, 11, 54)
|
||||
|
||||
Without all three, BP and temperature readings flow only through the
|
||||
hourly poll fallback. v1.4.25 fixes this for BP and temperature; sleep
|
||||
(`appli=44`) and activity (`appli=16`) ship with the corresponding sync
|
||||
routines in v1.4.26.
|
||||
|
||||
## Deferred — v1.4.26
|
||||
|
||||
| meastype | Withings name | Why deferred |
|
||||
|---|---|---|
|
||||
| 5 | Fat Free Mass | needs new `FAT_FREE_MASS` enum |
|
||||
| 8 | Fat Mass Weight | needs new `FAT_MASS` enum |
|
||||
| 73 | Skin Temperature | distinct physiology from core; needs `SKIN_TEMPERATURE` enum |
|
||||
| 76 | Muscle Mass | needs new `MUSCLE_MASS` enum |
|
||||
| 91 | Pulse Wave Velocity | Body Cardio / Body Scan exclusive; new enum |
|
||||
| 155 | Vascular Age | new enum, composite-derived years |
|
||||
| 170 | Visceral Fat | new enum, rating |
|
||||
|
||||
Plus the new sync routines:
|
||||
|
||||
- **Sleep** (`POST /v2/sleep?action=getsummary`) → `SLEEP_DURATION`,
|
||||
`HEART_RATE_VARIABILITY` (sdnn_1), per-stage rows via existing
|
||||
`SleepStage` enum.
|
||||
- **Activity** (`POST /v2/measure?action=getactivity`) → `ACTIVITY_STEPS`,
|
||||
`WALKING_RUNNING_DISTANCE`, `FLIGHTS_CLIMBED`, `ACTIVE_ENERGY_BURNED`.
|
||||
**Requires OAuth scope upgrade** to `users.activity` — every existing
|
||||
Withings connection has to reconnect once.
|
||||
|
||||
## Deferred — v1.5 (with iOS app)
|
||||
|
||||
ECG signal storage (`Heart v2-Get`), AFib events (`Heart v2-List` +
|
||||
`appli=54`), workouts (`getworkouts`, needs new `Workout` model),
|
||||
segmental composition (174/175), nerve health (167), extracellular /
|
||||
intracellular water (168/169), electrodermal activity (196), connected
|
||||
devices badge (`User v2-Getdevice`), and Height (4) into `User.heightCm`.
|
||||
|
||||
## Skip with rationale
|
||||
|
||||
- **Withings+ derived metrics** (Health Improvement Score, Vitality,
|
||||
Cardio Check-Up review) — not exposed by the public API. HealthLog
|
||||
computes its own Health Score / Coach / Briefing. See
|
||||
`.planning/research/withings-plus-comparison.md` §6.
|
||||
- **Sleep events** `appli=50/51/52` (bed-in / bed-out / inflate) — niche
|
||||
Sleep Analyzer mat events. No plan today.
|
||||
|
||||
[1]: https://developer.withings.com/developer-guide/v3/integration-guide/bulkship-sdk/data-api/all-available-health-data
|
||||
[2]: https://developer.withings.com/api-reference#tag/measure
|
||||
Reference in new issue
Block a user