@condorinst/mobile-bridge 0.19.2 → 0.21.0

package/contract/bridge-contract.json

@@ -1,20 +1,20 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "contractVersion": "0.19.2",
+  "contractVersion": "0.21.0",
   "description": "Machine-readable contract of the Condor Canvas JS<->Native bridge. It states what the TypeScript declarations in dist/index.d.ts cannot express: which keys and commands a sandboxed client can actually reach, which ones need human confirmation, where messages are dropped in silence, the hard limits, and which capability each native version carries. The TypeScript types remain canonical for payload shapes.",
   "audience": "Developers and AI agents building the client bundle that renders inside the Canvas Home.",
 
   "versions": {
     "note": "Four independent numbers coexist. Only nativeVersion tells you what the device can do.",
-    "package": "0.19.2",
+    "package": "0.21.0",
     "shellVersion": "0.6.0",
     "clientProtocolVersion": "0.5.0",
-    "nativeVersion": "0.16.0",
+    "nativeVersion": "0.17.0",
     "capabilityDetection": {
       "how": "await BridgeClient.handshake({ clientVersion }) resolves to { shellVersion, nativeVersion, accepted }. Compare ack.nativeVersion against the minNativeVersion in capabilities[].",
       "acceptedIsAlwaysTrue": true,
       "acceptedWarning": "The native side never rejects a handshake, so `accepted` carries no information. Never branch on it.",
-      "nativeVersionMayBeNull": "null in a plain browser (mock mode) and in bundles compiled against SDK <= 0.16.x, where the shell did not relay it. Treat null as 'assume nothing beyond the 0.13.0 baseline'."
+      "nativeVersionMayBeNull": "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 nothing beyond the 0.13.0 baseline'. The dev harness reports 0.17.0 unless a scenario sets it to null."
     }
   },
 
@@ -80,8 +80,8 @@
   "keys": {
     "note": "13 keys exist; 12 are reachable by the sandboxed client. Subscribe with BridgeClient.on(key, cb). Payload shapes are canonical in dist/index.d.ts under the listed type.",
     "entries": {
-      "pingPong": { "reachableByClient": true, "payloadType": "PingPongPayload", "emittedWhen": "reply to the `ping` command" },
-      "userDevice": { "reachableByClient": true, "payloadType": "UserDevicePayload", "emittedWhen": "reply to the `userDevice` command, and on device roster changes" },
+      "pingPong": { "reachableByClient": true, "payloadType": "PingPongPayload", "emittedWhen": "reply to the `ping` command, once the app's background service is up" },
+      "userDevice": { "reachableByClient": true, "payloadType": "UserDevicePayload", "emittedWhen": "reply to the `userDevice` command when the device list loads, and on device roster changes. Not guaranteed: see silentDropPaths and prefer BridgeClient.requestUserDevices()." },
       "deviceLightSensors": { "reachableByClient": true, "payloadType": "DeviceLightSensorsPayload", "emittedWhen": "real-time stream, only while realTime is on for that device", "discriminator": "type", "variants": ["actlumus", "actlumus2"] },
       "syncTime": { "reachableByClient": true, "payloadType": "SyncTimeAckPayload", "emittedWhen": "ack of the `syncTime` command" },
       "realTime": { "reachableByClient": true, "payloadType": "RealTimeAckPayload", "emittedWhen": "ack of the `realTime` command" },
@@ -99,19 +99,19 @@
   "commands": {
     "note": "Send with BridgeClient.send(command, args). It is fire-and-forget: there is no return value and no throw. Replies arrive on the key named in repliesOn.",
     "entries": {
-      "ping": { "args": {}, "requiresConfirmation": false, "repliesOn": "pingPong" },
-      "userDevice": { "args": { "getFromServer": "boolean, default false" }, "requiresConfirmation": false, "repliesOn": "userDevice" },
-      "realTime": { "args": { "serialNo": "int", "value": "boolean" }, "requiresConfirmation": false, "repliesOn": "realTime", "note": "Off by default. The deviceLightSensors stream only flows while this is on." },
-      "deviceConnection": { "args": { "type": "'add' | 'remove'", "serialNo": "int" }, "requiresConfirmation": false, "repliesOn": "deviceConnection" },
-      "sensorLog": { "args": { "requestId": "string", "serialNo": "int", "bodyPart": "'wrist' | 'necklace', optional", "limit": "1..1000, optional", "startingAfter": "opaque cursor, optional", "endingBefore": "opaque cursor, optional", "startTime": "timestamp, optional, minNativeVersion 0.15.0", "endTime": "timestamp, optional, minNativeVersion 0.15.0" }, "requiresConfirmation": false, "repliesOn": "sensorLog", "prefer": "BridgeClient.fetchSensorLog(query), which correlates requestId and applies a timeout for you." },
+      "ping": { "args": {}, "requiresConfirmation": false, "repliesOn": "pingPong", "note": "Handled by the app's background service: lost without a reply if sent before the service is up. BridgeClient.waitForService() resends it until a pingPong arrives." },
+      "userDevice": { "args": { "getFromServer": "boolean, default false. false: memory or cache while fresh, else the server (use at boot). true: the server first, cache on failure (use for a refresh button)." }, "requiresConfirmation": false, "repliesOn": "userDevice", "prefer": "BridgeClient.requestUserDevices({ getFromServer }), which resends with backoff and resolves { status: 'timeout', hasDevices } instead of waiting forever.", "note": "Handled by the app's background service. A request sent before it is up is lost, and no reply is sent when the list fails to load — including an account with no linked device. An empty list is never sent." },
+      "realTime": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0", "value": "boolean" }, "requiresConfirmation": false, "repliesOn": "realTime", "note": "Off by default. The deviceLightSensors stream only flows while this is on. Always send serialNo; add deviceId to address one device when two share a serialNo." },
+      "deviceConnection": { "args": { "type": "'add' | 'remove'", "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": false, "repliesOn": "deviceConnection", "note": "Pairs nothing. 'add' subscribes to the BLE connection state of a device from the userDevice list; the state arrives on the deviceConnection key on every change. 'remove' stops it." },
+      "sensorLog": { "args": { "requestId": "string", "serialNo": "int", "bodyPart": "'wrist' | 'necklace', optional", "limit": "1..1000, optional", "startingAfter": "opaque cursor, optional", "endingBefore": "opaque cursor, optional", "startTime": "timestamp, optional, minNativeVersion 0.15.0", "endTime": "timestamp, optional, minNativeVersion 0.15.0" }, "requiresConfirmation": false, "repliesOn": "sensorLog", "prefer": "BridgeClient.fetchSensorLog(query), which correlates requestId and applies a timeout for you.", "paging": { "orderWithinPage": "chronological ascending", "noCursorNoRange": "the most recent `limit` logs; older pages with endingBefore while hasPrevious", "withStartTime": "the oldest logs of the range first; newer pages with startingAfter while hasMore", "onlyEndTime": "the most recent logs before endTime", "defaultLimit": 10, "maxLimit": 1000, "logPeriod": "one log per period, programmable per device, default 60 s; derive it from consecutive log_time values" } },
       "openSettings": { "args": {}, "requiresConfirmation": false, "repliesOn": null },
       "requestPermission": { "args": { "permission": "string, must match a native AppPermission name" }, "requiresConfirmation": false, "repliesOn": null, "note": "There is no permission-result key. The OS shows its own prompt and the outcome reaches you as a fresh systemStatus emission." },
       "setStatusBarColor": { "args": { "color": "'#RRGGBB'" }, "requiresConfirmation": false, "repliesOn": null },
       "navigationState": { "args": { "canGoBack": "boolean" }, "requiresConfirmation": false, "repliesOn": null, "prefer": "BridgeClient.reportNavigation(canGoBack)" },
       "language": { "args": {}, "requiresConfirmation": false, "repliesOn": "language", "note": "Pull. The native push happens before window.CondorBridge exists, so a client that mounts later must ask.", "minNativeVersion": "0.14.0" },
       "jsError": { "args": { "message": "string", "stack": "optional", "source": "optional", "lineno": "optional", "colno": "optional" }, "requiresConfirmation": false, "repliesOn": null, "note": "Rate limited: 20 per 10 s, fields truncated at 4 KB." },
-      "syncTime": { "args": { "serialNo": "int" }, "requiresConfirmation": true, "repliesOn": "syncTime" },
-      "deleteMemory": { "args": { "serialNo": "int" }, "requiresConfirmation": true, "repliesOn": "deleteMemory" },
+      "syncTime": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": true, "repliesOn": "syncTime" },
+      "deleteMemory": { "args": { "serialNo": "int", "deviceId": "int, optional, minNativeVersion 0.17.0" }, "requiresConfirmation": true, "repliesOn": "deleteMemory" },
       "logout": { "args": {}, "requiresConfirmation": true, "repliesOn": null },
       "dfu": { "args": {}, "denied": true, "repliesOn": null }
     },
@@ -130,7 +130,7 @@
       "name": "sensorLog failure",
       "channel": "sensorLog key",
       "shape": { "requestId": "string", "success": false, "error": "string code" },
-      "codes": ["CONFLICTING_CURSORS", "INVALID_BODY_PART", "INVALID_LIMIT", "INVALID_START_TIME", "INVALID_END_TIME", "INVALID_TIME_RANGE", "MISSING_DEVICE_SERIAL_NO", "invalid session", "device not found for this user"],
+      "codes": ["CONFLICTING_CURSORS", "INVALID_BODY_PART", "INVALID_LIMIT", "INVALID_START_TIME", "INVALID_END_TIME", "INVALID_TIME_RANGE", "MISSING_DEVICE_SERIAL_NO", "DEVICE_SERIAL_AMBIGUOUS", "invalid session", "device not found for this user"],
       "visibility": "fetchSensorLog RESOLVES with success false. It only rejects on timeout.",
       "warning": "error is a diagnostic code, never user-facing text. Map it to your own copy."
     },
@@ -148,13 +148,16 @@
     { "cause": "unknown command type", "trigger": "typo, or a command added in a newer nativeVersion than the device runs", "observable": "nothing" },
     { "cause": "permission name outside the native enum", "trigger": "requestPermission with an unrecognized string", "observable": "nothing" },
     { "cause": "malformed args", "trigger": "realTime, syncTime, deleteMemory or deviceConnection with wrong types", "observable": "nothing" },
-    { "cause": "postMessage failing schema validation", "trigger": "hand-rolled postMessage instead of BridgeClient", "observable": "nothing" }
+    { "cause": "postMessage failing schema validation", "trigger": "hand-rolled postMessage instead of BridgeClient", "observable": "nothing" },
+    { "cause": "background service not running yet", "trigger": "userDevice or ping sent before the app's background service is up, typically right after a cold start; the app does not re-send the list when the service comes up", "observable": "nothing (the handshake, systemStatus and language already work)", "mitigation": "BridgeClient.requestUserDevices() / waitForService()" },
+    { "cause": "device list did not load", "trigger": "userDevice for an account with no linked device, or when the server request fails (no internet, session problem); the app replies only on success", "observable": "nothing; systemStatus.hasDevices stays false", "mitigation": "BridgeClient.requestUserDevices() resolves { status: 'timeout', hasDevices } after 30 s: render an empty state with a retry" }
   ],
 
   "capabilities": [
     { "feature": "languageKey", "minNativeVersion": "0.14.0", "description": "The language key and the language pull command exist." },
     { "feature": "sensorLogTimeRange", "minNativeVersion": "0.15.0", "description": "sensorLog accepts startTime and endTime." },
     { "feature": "lightSensorRawChannels", "minNativeVersion": "0.16.0", "description": "deviceLightSensors carries the raw light_sensor_* channels and the actlumus2 variant." },
+    { "feature": "deviceIdAddressing", "minNativeVersion": "0.17.0", "description": "realTime, syncTime, deleteMemory and deviceConnection accept an optional deviceId, so one device can be addressed when an ActLumus and a Plus share a serialNo; the acks echo it; deviceConnection, deviceNotification and deviceLightSensors carry it when the serialNo is shared; systemStatus adds deviceSyncErrorById." },
     { "feature": "nativeVersionRelay", "minShellVersion": "0.6.0", "description": "The shell relays nativeVersion into the sandboxed client. Below this, handshake-ack carried only shellVersion and capability detection was impossible from inside the iframe." }
   ],
 
@@ -176,26 +179,68 @@
     "statusBarHook": "<meta name=\"theme-color\" content=\"#RRGGBB\"> in the bundle sets the native status bar colour. The setStatusBarColor command overrides it at runtime."
   },
 
+  "payloadItems": {
+    "note": "Item shapes of userDevice and sensorLog. Canonical types in dist/index.d.ts. Fields not listed here are not part of the public contract — do not read them.",
+    "joinKey": "deviceId. An item of devicesTelemetry or devicesUserConfig without deviceId is legacy data: fall back to serialNo only when that serialNo appears once in devicesConfig.",
+    "hasDevices": "systemStatus.hasDevices is true only after the app loaded a non-empty list from the server; false means no device OR the lookup failed. A hint, never a verdict.",
+    "devicesConfig": {
+      "type": "DeviceConfigItem",
+      "role": "the list of linked devices to render",
+      "fields": { "deviceId": "int, unique", "serialNo": "int, may repeat across an ActLumus and a Plus", "deviceBodyPart": "'wrist' | 'necklace' | null", "modelId": "'actlumus' | 'actlumus_plus', absent = ActLumus (gen1)", "bleConnectionPeriod": "int, minutes", "autosync": "bool", "eraseDeviceMemory": "bool", "autoEraseDeviceMemory": "bool", "autoEraseDeviceMemoryThreshold": "int", "readSensorsMemory": "bool", "startDevice": "bool", "readFullMemory": "bool", "allowFirmwareUpdate": "bool" }
+    },
+    "devicesTelemetry": {
+      "type": "DeviceTelemetryItem",
+      "role": "last state read from each device over BLE; readings are null until the first sync",
+      "fields": { "serialNo": "int", "deviceId": "int, omitted on legacy data", "updataDateTime": "epoch ms | null — last sync; the misspelling is the real field name", "deviceName": "string | null", "deviceVersion": "string | null (firmware)", "hardwareVersion": "string | null", "deviceDateTime": "epoch ms | null", "memoryDataUsage": "number 0-100 (%) | null", "memorySystemUsage": "number 0-100 (%) | null", "batteryLevel": "number 0-100 (%) | null", "batteryVoltage": "number, volts | null", "isCharging": "bool | null", "isOnDock": "bool | null", "syncErrors": "Array<{ serialNo, attemptDate: epoch ms, message: localized string, messageCode: string | null }>" }
+    },
+    "devicesUserConfig": {
+      "type": "DeviceUserConfigItem",
+      "role": "per-device toggles",
+      "fields": { "serialNo": "int", "deviceId": "int, omitted on legacy data", "syncTime": "bool", "realTime": "bool", "deleteMemory": "bool", "readAllMemory": "bool", "readAllSystemLog": "bool" }
+    },
+    "sensorLogItem": {
+      "type": "SensorLogItem",
+      "fields": { "id": "int", "log_time": "'YYYY-MM-DD HH:MM:SS', device-LOCAL time, not UTC", "log_type": "int", "body_part": "'wrist' | 'necklace' | null", "temperature": "°C | null", "lux_photopic": "lux | null", "lux_melanopic": "lux | null", "light_sensor_f1..f8, light_sensor_clear, light_sensor_nir": "raw channels | null (null = the hardware has no such channel)", "act_data_pim, act_data_tat, act_data_zcm": "int | null", "device_log_time, app_log_time": "upload batch markers, not per-log timestamps" }
+    }
+  },
+
+  "devTools": {
+    "harness": "npx condor-mobile-bridge dev -i <index.html|dist|bundle.zip> [--scenario <name>] [--port 5173]",
+    "subpath": "@condorinst/mobile-bridge/dev exports createDevHarness() for a host page; never import it into the bundle (validate fails it with dev-harness-bundled)",
+    "scenarios": ["default", "cold-start", "no-devices", "shared-serial", "offline"],
+    "outsideShell": "BridgeClient.handshake() rejects at once when the page is not inside the shell (opened directly in a browser)."
+  },
+
   "verifiedAgainst": {
     "monorepo": "condorinstprogdev/mobile_applications",
     "branch": "dev_canvas",
-    "commit": "89fe1c792202ca9f066b84a63af44a6f2b993b52",
-    "verifiedOn": "2026-09-23",
+    "commit": "a1a524fd8491e4c266c7ea7bbcd9b1aa334620db",
+    "verifiedOn": "2026-10-20",
     "sources": {
-      "nativeVersion": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:32",
-      "jsToNativePayloadBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:88",
-      "jsErrorPerWindow": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:93-94",
-      "jsErrorFieldBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:97",
-      "acceptedIsAlwaysTrue": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:417-425",
-      "silentDropPaths": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:218-238,291-295,452-467,529-536",
+      "nativeVersion": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:38",
+      "jsToNativePayloadBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:94",
+      "jsErrorPerWindow": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:99-100",
+      "jsErrorFieldBytes": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:103",
+      "acceptedIsAlwaysTrue": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:486-494",
+      "silentDropPaths": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:246-266,319-323,521-536,606-613",
       "bundleZipBytes": "apps/canvas/lib/core/config/whitelabel_bundle_limits.dart:14",
       "bundleGuards": "apps/canvas/lib/data/services/whitelabel_bundle_service.dart:227-398",
       "integrity": "apps/canvas/lib/data/services/whitelabel_bundle_service.dart:244-259",
       "sensorLogValidation": "apps/canvas/lib/domain/entities/sensor_log_entity.dart:70-85",
       "csp": "apps/canvas/web-mock-src/shell.template.html:28",
       "shellPolicy": "apps/canvas/web-mock-src/src/shell.ts:48-98",
-      "webViewPermissionDeny": "apps/canvas/lib/ui/pages/home/home_page.dart:260-268",
-      "opaqueOrigin": "apps/canvas/lib/ui/pages/home/home_page.dart:296-298"
+      "webViewPermissionDeny": "apps/canvas/lib/ui/pages/home/home_page.dart:263-271",
+      "opaqueOrigin": "apps/canvas/lib/ui/pages/home/home_page.dart:299-301",
+      "userDeviceToBackgroundService": "apps/canvas/lib/ui/pages/home/bridge/condor_bridge.dart:671-683",
+      "userDeviceRepliesOnlyOnSuccess": "packages/condor_core/lib/src/data/services/user_devices_service.dart:28-39",
+      "getFromServerSemantics": "packages/condor_core/lib/src/data/repositories/user_devices_repository.dart:49-85",
+      "hasDevices": "apps/canvas/lib/data/services/sys_notification_service.dart:224-237",
+      "deviceConfigItem": "packages/condor_core/lib/src/domain/entities/device_config_entity.dart:61-77",
+      "deviceTelemetryItem": "packages/condor_core/lib/src/domain/entities/device_telemetry_entity.dart:100-117",
+      "deviceUserConfigItem": "packages/condor_core/lib/src/domain/entities/device_user_config_entity.dart:78-88",
+      "deviceSyncErrorItem": "packages/condor_core/lib/src/domain/entities/device_sync_error_entity.dart:16-23",
+      "userDevicesEnvelope": "packages/condor_core/lib/src/domain/entities/user_devices_entity.dart:282-289",
+      "bleConnectionPeriodMinutes": "packages/condor_core/lib/src/domain/entities/device_session_record_entity.dart:25"
     },
     "maintenance": "Re-verify every entry in sources before cutting a release. A published contract that drifts from the app is worse than no contract."
   }