@condorinst/mobile-bridge 0.22.0 → 0.23.1

package/docs/bridge-contract.md

@@ -27,12 +27,12 @@ protocol for you.
 
 Four numbers coexist. Only one tells you what the device can do.
 
-| Number | Current | What it means |
+| Number | Latest | What it means |
 | --- | --- | --- |
-| `nativeVersion` | `0.17.0` | **The capability signal.** The bridge schema the app on this device implements. |
+| `nativeVersion` | `0.18.0` | **The capability signal.** The bridge schema the app on this device implements. No Canvas release is in the field yet; the first one implements `0.18.0`. Later releases will coexist with it on phones for a while, so read it at runtime — never assume the latest. |
 | `shellVersion` | `0.6.0` | The Condor shell wrapping your iframe. |
 | client protocol | `0.5.0` | The postMessage protocol `BridgeClient` speaks. |
-| package | `0.22.0` | The npm version you compiled against. |
+| package | `0.23.1` | The npm version you compiled against. |
 
 ```ts
 const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
@@ -47,7 +47,7 @@ side never refuses. Branching on it is branching on a constant.
 **`nativeVersion` can be `null`.** When the shell could not reach the native
 side, and in bundles compiled against SDK ≤ 0.16.x, where the shell did not
 relay it. Treat `null` as "assume only the baseline" and keep a working
-default. The dev harness reports `0.17.0` by default; `--native-version null`
+default. The dev harness reports `0.18.0` by default (`--native-version 0.17.0` reproduces an app that may stay silent); `--native-version null`
 exercises this path.
 
 ### Capability matrix
@@ -59,6 +59,7 @@ exercises this path.
 | `sensorLog` accepts `startTime` / `endTime` | `nativeVersion` ≥ 0.15.0 |
 | `deviceLightSensors` carries raw `light_sensor_*` channels, and the `actlumus2` variant | `nativeVersion` ≥ 0.16.0 |
 | Address one device by `deviceId` when two share a `serialNo` (`realTime`, `syncTime`, `deleteMemory`, `deviceConnection`); `deviceId` in the device events; `systemStatus.deviceSyncErrorById` | `nativeVersion` ≥ 0.17.0 |
+| `userDevice` always answers (re-sent after a cold start; `error` when the list could not load); `systemStatus.hasDevicesKnown`; payload limited to the contract fields | `nativeVersion` ≥ 0.18.0 |
 | `nativeVersion` reaches the client at all | `shellVersion` ≥ 0.6.0 |
 
 `CHANGELOG.md` is the precise record of when each of these landed.
@@ -92,7 +93,24 @@ you; the second is the one you receive. This is why `language` also exists as a
 pull command — a client that mounts late can ask.
 
 Render a skeleton synchronously and fill it as events arrive. Do not make first
-paint depend on any event.
+paint depend on any event. **No order is guaranteed between events.** On the
+phone the post-handshake `systemStatus` usually arrives before the answer to
+your first `userDevice` (that answer is a round trip to the background
+service), but nothing promises it, and `systemStatus` is re-emitted on every
+change. Don't hold a request waiting for `systemStatus`: a `sensorLog` sent
+offline fails at once with an error you already handle.
+
+`deviceLightSensors` arrives at the device's pace — about once per second, set
+by the firmware, not throttled by the app (an observation, not a guarantee).
+Treat "no reading for a few seconds" as the device leaving its session, and
+let `deviceConnection` confirm it.
+
+**`data.time`** is when the **phone** received the reading: epoch milliseconds
+(UTC) from the phone clock, stamped on arrival — not the device clock, and not
+shifted by the timezone like `log_time`. Each reading is forwarded as it
+arrives, with no queue. To join live readings to the history, compare in the
+same frame: format `data.time` with local `Date` getters (as you build
+`log_time` ranges), or parse `log_time` as local time.
 
 ### `deviceLightSensors` is a discriminated union
 
@@ -104,6 +122,13 @@ if (payload.type === 'actlumus2') {
 }
 ```
 
+**Units.** `photopic` and `melanopic` are lux (photopic illuminance and
+melanopic EDI) — the same as `lux_photopic` / `lux_melanopic` in the history.
+The `wavelength*` and `light_sensor_*` channels have **no physical unit**: they
+are relative values (arbitrary units). Use them for the shape of the spectrum
+and for comparisons on the same device generation; do not label them W/m², µW/cm²
+or lux, and do not compare an ActLumus with an ActLumus Plus channel by channel.
+
 A `null` in a raw channel means **that channel does not exist on this hardware
 generation** — never "the reading was zero". `0.0` is a valid reading. Do not
 collapse `null` to `0`: doing so fabricates data, and it has produced wrong
@@ -125,23 +150,144 @@ conclusions before.
 off. Render a blocking card; wire its button to
 `BridgeClient.requestPermission(name)` with a name taken from that array.
 
+The names, for your labels (never send a name you typed — take it from the
+arrays):
+
+| Name | Platform | Essential? | What `requestPermission` does |
+| --- | --- | --- | --- |
+| `bluetoothScan`, `bluetoothConnect` | Android | yes | system prompt; app settings if permanently denied |
+| `fineLocation` | Android ≤ 11 | yes | system prompt; app settings if permanently denied |
+| `bluetooth` | iOS | yes | system prompt; app settings as fallback |
+| `notification` | both | no | system prompt (Android) / iOS permission request |
+| `batteryOptimization` | Android | no | battery-optimization exemption screen |
+| `exactAlarm` | Android | no | exact-alarm settings, when battery optimization is not exempt |
+| `backgroundLocation` | Android ≤ 11 | no | system prompt, else app settings |
+
+An unknown name is dropped.
+
+`deviceSyncErrorById` (and `deviceSyncError`) hold only the **last** error per
+device, already in the app language (the app translates the `messageCode`; an
+error with `messageCode: null` never lands here). The entry is removed when
+newer telemetry of that device arrives — and a failed sync saves telemetry too
+(with the error added to its `syncErrors`), so the entry can vanish seconds
+after it appeared. Use it for a live banner, not as the record of the last
+failure: that is the newest item of `devicesTelemetry[].syncErrors` (compare
+its `attemptDate` with the telemetry's `updataDateTime` to know whether a
+later sync succeeded). `deviceNotification` is the live feed of
+a sync — see the next section.
+
+### Sync progress: `deviceNotification`
+
+Every BLE session of a device is one sync, and the app reports it step by step
+— dozens of events per session, for **every** linked device (no subscription
+needed). Payload: `{ serialNo, deviceId?, isConnect, message, messageCode,
+isError }`.
+
+- **Branch on `messageCode`**, never on `message`. `message` is the app's log
+  line in English (`[Start] Get data log`, `[Error] Send data log: …`), not
+  localized and not stable; show your own text per code. Some progress events
+  have `messageCode: null` — ignore them.
+- **`isConnect` is not the connection state** here: it is `!isError` on pipeline
+  events. Read connection from `deviceConnection`.
+- `deviceId` only when the `serialNo` is shared, as in every device event.
+
+A successful session, in order:
+
+| `messageCode` | Step |
+| --- | --- |
+| `null`, `message: 'Device connected'` | the session starts |
+| `enable_ble_periodic_notification`, then `…_not_needed_notification` if there was nothing to do | device setup |
+| `set_ble_period_notification`, then `…_not_needed_notification` likewise | device setup |
+| `set_sync_time_notification`, then `set_sync_time_not_needed_notification` likewise | the clock (a pending `syncTime` runs here) |
+| `get_data_log_notification`, `send_data_log_notification`, `set_last_data_log_sent_to_server_notification` | reading and uploading the measurements |
+| `get_system_log_notification`, `send_system_log_notification` | system log |
+| `get_full_charge_log_notification`, `send_full_charge_log_notification` | charge log |
+| `set_erase_memory_notification`, `erase_memory_notification` (or `escape_erase_memory_notification`: postponed) | a pending `deleteMemory`, after the upload |
+| `get_device_telemetry_notification`, `save_device_telemetry_notification` | battery, memory, last sync |
+| **`pipeline_done_notification`** | **the sync succeeded** — the only success marker |
+| `null`, `message: 'Device disconnected'`, `isConnect: false` | the session ends |
+
+Every stage emits its `…_notification` code when it **starts**, whether or not
+it has work to do; it does not mean "done". A stage is done when a later stage
+starts without its `…_error`. The three log stages run in parallel: their events
+interleave in any order. Codes may repeat; treat every event as idempotent.
+
+**When is a pending `syncTime` / `deleteMemory` done?** Count it done when the
+sync reaches `pipeline_done_notification`. If the sync fails first, it may still
+be pending — the app keeps a request it could not carry out (a clock it could
+not set, an erase postponed by `escape_erase_memory_notification` or by a failed
+upload) and runs it at the next session. Say "will happen at the next sync"
+until then. With a `syncTime` pending, the clock stage never reports
+`set_sync_time_not_needed_notification`: it sets the clock.
+
+**History and live readings overlap in time, not in data.** Live readings are
+not logs and never enter the history. While it streams, the device keeps
+logging at its own period; those logs reach the history when a sync uploads
+them (`send_data_log`). So the history ends at the last upload, live readings
+cover the time after it, and the next sync fills that span with logs. Prefer
+the history for any span it covers, and use live readings only after its last
+`log_time`.
+
+**A failed sync** has no "failed" event: the failing stage emits
+`<stage>_error` (`isError: true`) and **`pipeline_done_notification` never
+comes**. Every `*_error` ends the sync — `enable_ble_periodic_error`,
+`set_ble_period_error`, `set_sync_time_error`, `get_data_log_error`,
+`send_data_log_error`, `set_last_data_log_sent_to_server_error`,
+`get_system_log_error`, `send_system_log_error`,
+`set_last_system_log_sent_to_server_error`, `get_full_charge_log_error`,
+`send_full_charge_log_error`, `set_erase_memory_error`,
+`get_device_telemetry_error` — except two, which are `isError: true` while the
+sync goes on: `config_write_not_persisted` (a setting did not stick; the sync
+continues to `pipeline_done_notification`) and `save_device_telemetry_error`
+(the final save failed; the outcome is already decided). A failure loading the
+device list ends the sync with `messageCode: null`. After an ending error the
+app mutes that device's **pipeline** events for about 3 s, so a second error
+from a parallel log stage may never reach you; the first one is the cause.
+
+**The session start and end are the two events with `messageCode: null` you
+can rely on**, without reading `message`:
+- **end:** `isConnect: false` **and** `isError: false` — no other event has
+  that pair (pipeline events have `isConnect === !isError`). It is not muted.
+- **start:** the first event of the device after an end (or after your bundle
+  loaded). A `deviceConnection` with `isConnect: true` says the same if you
+  subscribed with `add`.
+
+Rule for a progress UI: "syncing" from the start, the step from each code,
+**success** on `pipeline_done_notification`, **failure** when the end arrives
+after an ending `*_error` without `pipeline_done_notification`. Keep a time-out
+of your own (a few minutes without events): if the disconnect itself fails, the
+app sends no end event.
+
 **`hasDevices` is a hint.** It is `true` only after the app loaded a non-empty
 device list from the server. `false` means "no linked device" **or** "the app
-could not ask" (no internet, session problem). Do not show "you have no device"
-on `false` alone; see the next section.
+could not ask" (no internet, session problem). From `nativeVersion` 0.18.0,
+`hasDevicesKnown: true` says `hasDevices` is the server's answer, and `false`
+says the lookup failed. Do not show "you have no device" on `hasDevices: false`
+alone; see the next section.
 
 ### `userDevice` in detail
 
-**It is not guaranteed to answer.** `userDevice` (and `ping`) are handled by
-the app's background service, which starts after your bundle is running; a
-request sent before it is up is lost. And the app replies only when the list
-loads: an account with no linked device, or a failed request, gets **no reply
-at all** — never an empty list. Use the helper, which resends with backoff and
-tells you when to give up:
+**From `nativeVersion` 0.18.0 it always answers.** The app re-sends a request
+lost while its background service starts, and a failed lookup arrives as the
+three arrays empty plus `error`:
+
+| `error` | Meaning |
+| --- | --- |
+| `NO_DEVICES` | the server says the account has no linked device |
+| `NETWORK` | no answer from the server (offline, timeout) or a 5xx |
+| `SESSION` | no session, or the server ended it |
+| `UNKNOWN` | anything else; treat unknown values the same way |
+
+**Below 0.18.0 it is not guaranteed to answer.** `userDevice` (and `ping`) are
+handled by the background service, which starts after your bundle is running;
+a request sent before it is up is lost. And a failed lookup — including an
+account with no device — gets **no reply at all**. Use the helper, which covers
+both versions:
 
 ```ts
 const r = await BridgeClient.requestUserDevices();          // getFromServer: false
-// { status: 'ok', devices } | { status: 'timeout', hasDevices: boolean | null }
+// { status: 'ok', devices } | { status: 'no-devices' } | { status: 'error', code }
+// | { status: 'timeout', hasDevices: boolean | null }
 ```
 
 **`getFromServer`.** `false` (default) answers from the app's memory or cache
@@ -155,7 +301,7 @@ the server first and falls back to the cache if that fails — use it for a
 | Array | Holds | Notable fields |
 | --- | --- | --- |
 | `devicesConfig` | one item per linked device — **the list to render** | `deviceId`, `serialNo`, `modelId` (`'actlumus'`, `'actlumus_plus'`; absent = ActLumus), `deviceBodyPart` (`'wrist'` \| `'necklace'` \| `null`), `bleConnectionPeriod` (minutes) |
-| `devicesTelemetry` | last state read from each device | `deviceName`, `batteryLevel` (0–100 %), `memoryDataUsage` (0–100 %), `updataDateTime` (epoch ms, last sync — the misspelling is the real name), `deviceVersion`, `isCharging`, `isOnDock`, `syncErrors[]` |
+| `devicesTelemetry` | last state read from each device | `deviceName`, `batteryLevel` (0–100 %), `memoryDataUsage` (0–100 %, the measurement memory — the one to show as "memory used"; `memorySystemUsage` is the device's internal log, diagnostics only), `updataDateTime` (epoch ms, last sync — the misspelling is the real name), `deviceVersion`, `isCharging`, `isOnDock`, `syncErrors[]` |
 | `devicesUserConfig` | per-device toggles | `syncTime`, `realTime`, `deleteMemory`, `readAllMemory`, `readAllSystemLog` |
 
 The name and battery of a device are in **telemetry**, not in the config. A
@@ -167,15 +313,82 @@ device that never synced may have no telemetry item, or one with every reading
 only when that `serialNo` appears once in `devicesConfig`.
 
 **Sync errors.** `devicesTelemetry[].syncErrors` is the per-device history
-(`attemptDate`, `message`, `messageCode`); `systemStatus.deviceSyncErrorById`
+(`attemptDate`, `message`, `messageCode`). `messageCode` is the `…_error` code
+of the stage that failed — the same vocabulary as `deviceNotification` (see
+"Sync progress") — or `null`; `message` is the app's English log line, not for
+display. Map the codes to your own words; `systemStatus.deviceSyncErrorById`
 is the current error per device, already localized. Show the current one; use
 the history for detail screens.
 
+### `language` — which language to render
+
+The app tells you **two** languages, and the distinction between them is the
+whole point of the channel:
+
+```typescript
+BridgeClient.on(BRIDGE_KEYS.language, ({ deviceLocale, appLanguage, resolvedLanguage }) => {
+  // Your precedence rule. This one honours an explicit choice, else the device.
+  const lang = appLanguage ?? pickSupported(deviceLocale) ?? 'en';
+  renderIn(lang);
+});
+```
+
+- **`deviceLocale`** — the raw device locale as a BCP-47 tag (`"pt-BR"`,
+  `"es-419"`, `"ja-JP"`), exactly as the OS reports it, region included.
+- **`appLanguage`** — the language the user explicitly picked in the app
+  Settings (`"en" | "pt" | "de" | "fr"`), or **`null`** when they never picked
+  one.
+- **`resolvedLanguage`** — the language the native chrome (splash, Settings,
+  loading/error screens) is rendering right now.
+
+**Why two raw values instead of one answer.** The app itself ships four
+languages and collapses everything else to English. Your bundle has no such
+limit — it may ship Spanish, Italian, Japanese. If we sent you only the resolved
+language, a device set to Spanish would reach you as `en` and you would render
+English while holding a Spanish bundle. The information would have been
+destroyed on our side before reaching you. So we send both and let you decide:
+
+| `deviceLocale` | `appLanguage` | a reasonable decision |
+|---|---|---|
+| `es-ES` | `null` | render **Spanish** — you have it, we don't. Our chrome stays English while your content is Spanish, which is better, not worse |
+| `es-ES` | `"pt"` | render **Portuguese** — an explicit choice outranks the device |
+| `pt-BR` | `null` | render Portuguese |
+| `ja-JP` | `"de"` | render German (the explicit choice), or Japanese if you'd rather honour the device — your call, with both values in hand |
+
+`appLanguage` is `null` when — and only when — the user never chose. It is never
+a fallback in disguise, so `null` is a real signal you can branch on. Use
+`resolvedLanguage` when you'd rather stay visually consistent with the native
+frame around your page than follow the device.
+
+**When it arrives — and how to ask for it.** The app pushes this key on attach,
+again right after the handshake ack, and on every change in the app Settings, so
+a page already loaded re-renders without a restart. But the first push happens
+while the WebView is still being created, before your bundle exists, so **send
+the `language` command once after your handshake** to pull the current state:
+
+```typescript
+BridgeClient.send('language', {});   // replies with a `language` event
+```
+
+Without that pull, a first launch would show your default language until the
+user changed it in Settings. Subscribe first, then pull.
+
+Do not read `navigator.language` instead: it follows the system, not the in-app
+choice, and you would end up in Spanish while the native chrome around you is in
+Portuguese.
+
+**Older app versions.** There is no version negotiation. An app older than
+native `0.14.0` never emits this key, so the event simply never arrives — keep a
+default language for that case, and read `nativeVersion` from the handshake ack
+if you need to branch on it explicitly.
+
 ## Commands
 
 `BridgeClient.send(command, args)` is **fire-and-forget**: no return value, no
 exception, no delivery confirmation. Replies arrive on the key in the last
-column.
+column. Its arguments are typed per command (`CommandArgs`): a string
+`serialNo`, a missing `value` or an unknown command is a compile error, not a
+silent drop.
 
 | Command | Arguments | Confirmation | Replies on |
 | --- | --- | --- | --- |
@@ -184,7 +397,7 @@ column.
 | `realTime` | `{ serialNo: number, deviceId?: number, value: boolean }` | no | `realTime` |
 | `deviceConnection` | `{ type: 'add' \| 'remove', serialNo: number, deviceId?: number }` — subscribe to / stop following one device's connection state | no | `deviceConnection` |
 | `sensorLog` | see below | no | `sensorLog` |
-| `openSettings` | — | no | — |
+| `openSettings` | — (opens the Canvas settings screen: language, notifications, Bluetooth, refresh device list, date format; not the OS settings, no logout) | no | — |
 | `requestPermission` | `{ permission: string }` | no | — (re-emits `systemStatus`) |
 | `setStatusBarColor` | `{ color: '#RRGGBB' }` | no | — |
 | `navigationState` | `{ canGoBack: boolean }` | no | — |
@@ -199,9 +412,50 @@ column.
 message in silence.
 
 `deviceConnection` **pairs nothing.** `type: 'add'` asks the app to report the
-BLE connection state of a device you already have from `userDevice`; the state
-then arrives on the `deviceConnection` key whenever it changes. `'remove'` stops
-it. Send `add` for each device after the list arrives.
+BLE connection state of a device you already have from `userDevice`. `'remove'`
+stops it. Send `add` for each device after the list arrives.
+
+- **`add` does not report the current state.** The app reports **changes**: a
+  device already connected (or already disconnected) when you subscribe sends
+  nothing until its next BLE session starts or ends. Start every device as
+  "connection unknown" and switch on the first event. The one exception: a
+  device the app does not know answers `isConnect: false` at once.
+- **"Disconnected" is the normal state.** An ActLumus is not connected all the
+  time: it opens a short BLE session to sync every few minutes
+  (`devicesConfig[].bleConnectionPeriod`, in minutes) and the app disconnects
+  it as soon as the sync ends, successful or not. With `realTime` on, the app
+  does not disconnect it, but the session still ends within minutes (below).
+  Show the last sync time (`devicesTelemetry[].updataDateTime`) rather than a
+  red "offline" badge.
+
+### What an ack means
+
+`realTime`, `syncTime` and `deleteMemory` do not need the device to be
+connected, and their ack does **not** mean "done":
+
+| Command | `success: true` means | When it happens on the device |
+| --- | --- | --- |
+| `syncTime` | the request is recorded | at the next BLE session; the device clock is set to the phone's local time (its time zone included) |
+| `deleteMemory` | the request is recorded | at the end of the next sync, **only after the data was uploaded**; if the upload fails, it stays pending and is retried. Unsent data is never erased. Not reversible once done. |
+| `realTime` (`value: true`) | real time is switched on for that device | readings flow on `deviceLightSensors` while it is connected; it starts by itself at the next session if it is not connected now |
+
+- `success: false` means the app could not record the request (for example,
+  a shared `serialNo` sent without `deviceId`), never "device not connected".
+- **Do not disable these actions while the device is disconnected.** Say what
+  will happen instead: "The clock will be set at the next sync" / "The memory
+  will be erased after the next sync uploads its data".
+- **A live session is short.** With `realTime` on, the app does not
+  disconnect the device after the sync, and switching `realTime` off ends the
+  session. But on a real device (an ActLumus Plus on an Android tablet, twice)
+  the session ended about **3 minutes** after it started, with `realTime` still
+  on — the link or the device ends it, not the app. Design "live" as a few
+  minutes per sync, not a continuous stream: say "connected now" only while
+  readings arrive, and expect the next readings at the next session
+  (`bleConnectionPeriod`). Readings stop when the session ends and resume at
+  its next session while `realTime` stays on. There is no "last connection" field: the last sync
+  (`devicesTelemetry[].updataDateTime`) is the closest one. The app switches `realTime` off for every
+  device when it restarts — switch it on again from your screen when you need
+  it, and off when the person leaves that screen.
 
 ### Two devices with the same `serialNo`
 
@@ -227,7 +481,9 @@ the wrong device (erasing the wrong memory, for instance).
   unaddressable).
 - `sensorLog` takes no `deviceId` yet: for a shared `serialNo` the backend
   answers with the error code `DEVICE_SERIAL_AMBIGUOUS`. Show your own copy for
-  it; do not retry.
+  it ("history is not available for these two devices yet"); do not retry, and
+  do not filter another query's result to work around it. Real time, commands
+  and the device list still work for both devices, by `deviceId`.
 
 ### Commands that need human confirmation
 
@@ -238,6 +494,13 @@ which reaches you only as a `console.warn`. **The ack simply never arrives.**
 Design for that: show an optimistic state only if you can undo it, and put a
 timeout on any spinner.
 
+**Do not add your own confirmation dialog in front of these three.** The app's
+dialog is the confirmation; a second one makes the person confirm twice. Explain
+the consequence on your screen, next to the button, before it is pressed.
+
+**`logout` has no reply.** Once confirmed, the app returns to its login screen
+and your page is unloaded; nothing comes back. Show nothing that waits for it.
+
 ### Typed helpers
 
 Prefer these over raw `send` — they add correlation, timeouts and types:
@@ -256,7 +519,6 @@ BridgeClient.openSettings()
 
 ```ts
 const page = await BridgeClient.fetchSensorLog({
-  requestId: crypto.randomUUID(),
   serialNo,
   bodyPart: 'wrist',        // or 'necklace'; omit for no filter
   limit: 200,               // 1..1000, backend default 10
@@ -266,7 +528,15 @@ const page = await BridgeClient.fetchSensorLog({
 ```
 
 It **resolves** with `{ success: false, error }` on failure and only **rejects**
-on timeout. Check `success` before reading `logs`.
+on timeout (10 s by default; the app's own server timeout is 50 s, so raise
+`timeoutMs` on slow networks rather than retrying at once). Check `success`
+before reading `logs`. Leave `requestId` out: `fetchSensorLog` creates one
+(`createRequestId()`, which does not need `crypto.randomUUID`).
+
+There is no rate limit on the app side, but every page is a server request
+under the person's single session: fetch pages one after another (they depend
+on each other anyway), never several sweeps in parallel, and refresh on a
+human scale — minutes, not seconds.
 
 Two things that have caused real bugs:
 
@@ -274,6 +544,11 @@ Two things that have caused real bugs:
 device RTC. Build your range with local `Date` getters — `getFullYear()`,
 `getHours()` — and **never** with `toISOString()`. Converting shifts every
 series by the timezone offset, producing plausible data and no error at all.
+A "day" is the date part of `log_time` (`log_time.slice(0, 10)`): the
+device's local day, on the clock `syncTime` set to the phone's local time. The
+log carries no timezone, so after the participant changes timezone the logs
+stay on the old clock until the next `syncTime` — say so if your report is per
+day.
 
 **Cursors are opaque.** `startingAfter` and `endingBefore` are mutually
 exclusive; echo back exactly what you received and never construct one.
@@ -286,7 +561,7 @@ const logs: SensorLogItem[] = [];
 let startingAfter: string | undefined;
 for (;;) {
   const page = await BridgeClient.fetchSensorLog({
-    requestId: crypto.randomUUID(), serialNo, limit: 1000,
+    serialNo, limit: 1000,
     startTime: '2026-10-13 00:00:00', endTime: '2026-10-20 00:00:00', // local time
     ...(startingAfter ? { startingAfter } : {}),
   });
@@ -318,9 +593,25 @@ Pages depend on the previous cursor, so they cannot be fetched in parallel.
 **Fields.** Each log is a `SensorLogItem`: `log_time`, `body_part`,
 `temperature` (°C), `lux_photopic` and `lux_melanopic` (lux), the raw light
 channels and the activity counters. `null` on a channel means the hardware does
-not have it, never zero. `device_log_time` and `app_log_time` mark the upload
+not have it, never zero. `device_id` is the server device id — the same value as
+`devicesConfig[].deviceId` — so you can check that a log belongs to the device
+you asked for. `device_log_time` and `app_log_time` mark the upload
 batch, not the log — do not plot them.
 
+**Was the device worn?** Read `off_wrist`, and mind its name: it is the
+device's raw wear flag, **`1` = worn, `0` = not worn** (on its dock); treat any
+other value as not worn and `null` as unknown. `body_part` (`'wrist'` or
+`'necklace'`) is where the device was *set* to be worn when the log was uploaded
+— a setting, not a detection; it can differ from today's `deviceBodyPart`.
+
+**Time worn per day** (one reasonable recipe, not an official metric): count the
+logs of that local day with `off_wrist === 1` and multiply by the log period
+derived from consecutive `log_time` values. A missing log is time not recorded,
+not time worn. Ask for the day with `startTime` = local midnight and `endTime`
+= the next local midnight: `startTime` is inclusive and `endTime` exclusive.
+At the default 60 s, one day is about 1 440 logs — two pages of 1 000 — and 14
+days about 20 pages per device, so compute once and refresh on a human scale.
+
 ## Error shapes
 
 There are three, and none of them is a thrown exception.