mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 07:13:29 +00:00
feat(measurements): accept sleep stages by name on POST /api/measurements
A bridge such as Tasker or Home Assistant could only send sleep stages through the batch route, in HealthKit's terms: the category identifier, a stage codepoint from 0 to 5, and a value it had to work out in minutes. It can now post one segment to `POST /api/measurements` with `type: "SLEEP_DURATION"`, a `sleepStage` of `IN_BED`, `ASLEEP`, `AWAKE`, `CORE`, `DEEP` or `REM`, and either `startDate` + `endDate` or `measuredAt` (the end) + `value` (minutes). The row is the one the batch route writes for the same segment, and the dedupe is the batch route's: the opposite-source same-reading check, then one reconcile over both unique identities. Without an `externalId` the server derives one from the stage and both instants, so a re-post answers 200 `duplicate`, a corrected start answers 200 `updated`, and a new segment answers 201 `inserted`. The narrow `measurements:write` token is accepted and still writes only MANUAL rows. Every other body on this route behaves as before. Requested in #972.
This commit is contained in:
1 parent
be112df972
commit
f443ab6615
5 files changed
+1020
-5
No files matched your search
+203
-2
@@ -3753,6 +3753,12 @@ paths:
|
||||
in request order. Use `/api/measurements/batch` for Apple Health upload streams.
|
||||
|
||||
|
||||
Sleep stages by name (since v1.39.1): an object with `type: SLEEP_DURATION`, a `sleepStage` of `IN_BED`,
|
||||
`ASLEEP`, `AWAKE`, `CORE`, `DEEP` or `REM`, and the segment as `startDate` + `endDate` or as `measuredAt` (its
|
||||
end) + `value` (minutes). It is stored and deduplicated exactly as the batch route stores a HealthKit sleep
|
||||
sample, so a bridge can send stages without the HealthKit codepoints. See `NamedSleepStageEntry`.
|
||||
|
||||
|
||||
Also reachable with a narrow `measurements:write` Bearer, which is the supported way to push readings from a
|
||||
scale, a watch bridge or a home-automation rule. That credential is confined to its owner's own record — a
|
||||
request carrying the account selector is refused 403 before any sharing grant is read, however the record is
|
||||
@@ -3768,12 +3774,21 @@ paths:
|
||||
schema:
|
||||
anyOf:
|
||||
- $ref: "#/components/schemas/CreateMeasurementRequest"
|
||||
- $ref: "#/components/schemas/NamedSleepStageEntry"
|
||||
- type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/CreateMeasurementRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: "Named sleep-stage body only: the segment was already stored (`status: duplicate`) or a stored one was
|
||||
corrected in place (`status: updated`). Every other body answers 201 or an error, as before."
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/NamedSleepStageDuplicateResponse"
|
||||
"201":
|
||||
description: Created. A single resource for the object body; an array of resources, in request order, for the array body.
|
||||
description: "Created. A single resource for the object body; an array of resources, in request order, for the array
|
||||
body; for a named sleep-stage body, the stored row with `status: inserted`."
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
@@ -3782,7 +3797,7 @@ paths:
|
||||
"403": *a9
|
||||
"409":
|
||||
description: A measurement with this data already exists — the `(userId, type, source, externalId)` dedup index rejected
|
||||
the write.
|
||||
the write. Never for a named sleep-stage body, which answers a re-post with 200 instead.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
@@ -22124,6 +22139,61 @@ components:
|
||||
`glucoseContext` stays REQUIRED on a `BLOOD_GLUCOSE` row here: this is the hand-entry surface, where the person
|
||||
taking the reading knows whether it was fasting or after a meal. The bulk ingest paths (CSV import, JSON import,
|
||||
device sync) accept a contextless reading, because a sensor export classifies nothing per sample."
|
||||
NamedSleepStageEntry:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
const: SLEEP_DURATION
|
||||
sleepStage:
|
||||
type: string
|
||||
enum:
|
||||
- IN_BED
|
||||
- ASLEEP
|
||||
- AWAKE
|
||||
- CORE
|
||||
- DEEP
|
||||
- REM
|
||||
startDate:
|
||||
type: string
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
endDate:
|
||||
type: string
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
measuredAt:
|
||||
type: string
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
value:
|
||||
type: number
|
||||
externalId:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 120
|
||||
source:
|
||||
default: MANUAL
|
||||
type: string
|
||||
enum:
|
||||
- MANUAL
|
||||
- APPLE_HEALTH
|
||||
deviceType:
|
||||
anyOf:
|
||||
- type: string
|
||||
minLength: 1
|
||||
maxLength: 32
|
||||
- type: "null"
|
||||
required:
|
||||
- type
|
||||
- sleepStage
|
||||
description: "One sleep-stage segment with the stage named (since v1.39.1), for a bridge that does not speak HealthKit.
|
||||
Chosen whenever the object carries a string `sleepStage`. `type` is `SLEEP_DURATION`. The segment is either
|
||||
`startDate` + `endDate`, or `measuredAt` (its END) + `value` (its length in minutes); a `value` sent beside the
|
||||
dates must agree with them to within a minute. Stored as the batch route stores a HealthKit sleep sample: value
|
||||
in minutes, `measuredAt` at the end, the stage in `sleepStage`. Without an `externalId` the server derives one
|
||||
from the stage and both instants, so sending the same segment again is a `duplicate`, and a segment whose start
|
||||
moved is `updated` rather than added."
|
||||
AppleHealthBatchRequest:
|
||||
type: object
|
||||
properties:
|
||||
@@ -39588,6 +39658,136 @@ components:
|
||||
- limit
|
||||
- offset
|
||||
additionalProperties: false
|
||||
NamedSleepStageDuplicateResponse:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: "#/components/schemas/NamedSleepStageMeasurement"
|
||||
error:
|
||||
type: "null"
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
requestId:
|
||||
type: string
|
||||
additionalProperties: false
|
||||
required:
|
||||
- data
|
||||
- error
|
||||
additionalProperties: false
|
||||
NamedSleepStageMeasurement:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Stored row id, or a synthetic key (`day:<type>:<dayKey>`, `sleep-seg:<dayKey>:<n>`) on the collapsed list
|
||||
modes.
|
||||
type:
|
||||
$ref: "#/components/schemas/MeasurementType"
|
||||
value:
|
||||
type: number
|
||||
unit:
|
||||
type: string
|
||||
measuredAt:
|
||||
type: string
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
source:
|
||||
$ref: "#/components/schemas/MeasurementSource"
|
||||
notes:
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
userId:
|
||||
type: string
|
||||
valueMin:
|
||||
description: Bucket MINIMUM — set only on an hourly heart-rate `stats:` row.
|
||||
anyOf:
|
||||
- type: number
|
||||
- type: "null"
|
||||
valueMax:
|
||||
description: Bucket MAXIMUM — set only on an hourly heart-rate `stats:` row.
|
||||
anyOf:
|
||||
- type: number
|
||||
- type: "null"
|
||||
externalId:
|
||||
description: External-system dedup key; null for manual entries.
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
externalSourceVersion:
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
glucoseContext:
|
||||
description: Set only on BLOOD_GLUCOSE rows, and null there too when the writer recorded no classification (a sensor
|
||||
export, a device sync). Never invent one.
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
sleepStage:
|
||||
description: Set only on SLEEP_DURATION rows.
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
rhythmClassification:
|
||||
description: Device classification verdict; set only on EVENT rows.
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
deviceType:
|
||||
description: "`watch | band | ring | phone | scale | other | unknown`."
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
syncVersion:
|
||||
description: Bumped on every server-side mutation; the last-writer-wins input for cross-device reconciliation.
|
||||
type: integer
|
||||
minimum: -9007199254740991
|
||||
maximum: 9007199254740991
|
||||
deletedAt:
|
||||
description: Soft-delete tombstone; null on a live row.
|
||||
anyOf:
|
||||
- type: string
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
- type: "null"
|
||||
createdAt:
|
||||
type: string
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
updatedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
dayKey:
|
||||
type: string
|
||||
sampleCount:
|
||||
type: integer
|
||||
minimum: -9007199254740991
|
||||
maximum: 9007199254740991
|
||||
partial:
|
||||
description: True on the one bucket whose day was cut off by the read cap, so its sum understates the real total.
|
||||
type: boolean
|
||||
status:
|
||||
type: string
|
||||
enum:
|
||||
- inserted
|
||||
- updated
|
||||
- duplicate
|
||||
description: "`inserted` — a new row (HTTP 201). `duplicate` — the segment was already stored, by this route or the
|
||||
batch route, and nothing changed (HTTP 200). `updated` — a stored segment with the same stage, source and
|
||||
end was corrected in place, for example a later start (HTTP 200)."
|
||||
required:
|
||||
- id
|
||||
- type
|
||||
- value
|
||||
- unit
|
||||
- measuredAt
|
||||
- source
|
||||
- status
|
||||
additionalProperties: false
|
||||
description: The stored SLEEP_DURATION row for a named sleep-stage segment, with what the call did to it.
|
||||
CreateMeasurementResponse:
|
||||
type: object
|
||||
properties:
|
||||
@@ -39597,6 +39797,7 @@ components:
|
||||
- type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/MeasurementResource"
|
||||
- $ref: "#/components/schemas/NamedSleepStageMeasurement"
|
||||
error:
|
||||
type: "null"
|
||||
meta:
|
||||
|
||||
Reference in new issue
Block a user