@condorinst/mobile-bridge 0.22.0 → 0.23.1

package/dist/index.d.cts

@@ -196,6 +196,10 @@ interface BridgeOutgoingEvent {
  *   There is no hard semver validation — it is **always** `true`, so it carries
  *   no information. Never branch on it.
  */
+/**
+ * Ack of the legacy {@link Bridge} (`createBridge`). With `BridgeClient`, the
+ * ack is {@link BridgeClientHandshakeAck}, whose `nativeVersion` may be `null`.
+ */
 interface HandshakeAck {
     nativeVersion: string;
     accepted: boolean;
@@ -332,16 +336,35 @@ interface DeviceUserConfigItem {
  * — but only when that `serialNo` appears once in `devicesConfig`. A device may
  * have no telemetry yet: render it with empty readings, never drop it.
  *
- * **It is not guaranteed to answer.** Use `BridgeClient.requestUserDevices()`
- * instead of `send('userDevice')`; see `docs/troubleshooting.md`.
+ * **Below `nativeVersion` 0.18.0 it is not guaranteed to answer**: a request
+ * sent while the app's background service starts is lost, and a failed lookup
+ * gets no reply. From 0.18.0 the app re-sends the lost request itself and
+ * answers a failure with empty arrays and `error`. Either way, use
+ * `BridgeClient.requestUserDevices()` instead of `send('userDevice')`; see
+ * `docs/troubleshooting.md`.
  *
  * The app enforces no device cap. A commercial rule currently limits a user to
  * two linked devices, but that can change with no signal in this contract — read
  * the length of the array rather than hard-coding it.
  */
+/**
+ * Why the device list could not be loaded (`UserDevicePayload.error`, from
+ * `nativeVersion` 0.18.0):
+ * - `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 an unrecognised value like `UNKNOWN`.
+ */
+type UserDeviceErrorCode = 'NO_DEVICES' | 'NETWORK' | 'SESSION' | 'UNKNOWN' | (string & {});
 interface UserDevicePayload {
     /** Epoch milliseconds of the snapshot. */
     lastUpdate: number;
+    /**
+     * Present only when the list could not be loaded; the three arrays are then
+     * empty. From `nativeVersion` 0.18.0 — older apps send no reply at all in
+     * that case. `BridgeClient.requestUserDevices()` turns it into a status.
+     */
+    error?: UserDeviceErrorCode;
     devicesConfig: DeviceConfigItem[];
     devicesTelemetry: DeviceTelemetryItem[];
     devicesUserConfig: DeviceUserConfigItem[];
@@ -349,6 +372,8 @@ interface UserDevicePayload {
 /**
  * Raw light-sensor channels, under the names the backend uses in
  * `user_cmd=log` — the same vocabulary for history and for real time.
+ * Relative values with no physical unit (as are the `wavelength*` channels);
+ * only `photopic` / `melanopic` (and `lux_*` in the history) are lux.
  *
  * Present from **nativeVersion 0.16.0**. A bundle compiled against this SDK can
  * run on an older native app that does not emit them: check `nativeVersion`
@@ -387,6 +412,7 @@ type LightSensorsRawChannels = {
  * change between hardware generations.
  */
 type LightSensorsActlumus1Data = LightSensorsRawChannels & {
+    /** When the phone received the reading: epoch ms (UTC), phone clock. */
     time: number;
     wavelength390: number;
     wavelength415: number;
@@ -419,6 +445,7 @@ type LightSensorsActlumus1Data = LightSensorsRawChannels & {
  * Y in the green, X in the red.
  */
 type LightSensorsActlumus2Data = LightSensorsRawChannels & {
+    /** When the phone received the reading: epoch ms (UTC), phone clock. */
     time: number;
     wavelength395: number;
     wavelength426: number;
@@ -503,9 +530,12 @@ interface DeviceConnectionPayload {
     isConnect: boolean;
 }
 /**
- * Device event or status notice. Mirrors `DevicesNotification.toMap()`.
- * `message` is already localized by the app; `messageCode` is the stable
- * identifier to branch on.
+ * One step of a device sync (BLE session). Mirrors `DevicesNotification.toMap()`.
+ * Branch on `messageCode` (`pipeline_done_notification` = the sync succeeded,
+ * `*_error` = a stage failed); `message` is the app's English log line, not
+ * localized and not stable. `isConnect` is `!isError` on sync steps — read
+ * the connection from `deviceConnection`. See `docs/bridge-contract.md`,
+ * "Sync progress".
  */
 interface DeviceNotificationPayload {
     serialNo: number;
@@ -536,8 +566,8 @@ interface SensorLogQueryPayload {
     /** Echoed back in the reply — correlates concurrent requests. */
     requestId: string;
     serialNo: number;
-    /** `wrist` or `necklace`. Omit for no filter. */
-    bodyPart?: string;
+    /** Omit for no filter. */
+    bodyPart?: 'wrist' | 'necklace';
     /** 1..1000 (backend default is 10). Outside the range: `INVALID_LIMIT`. */
     limit?: number;
     startingAfter?: string;
@@ -562,6 +592,11 @@ interface SensorLogItem {
     /** `'YYYY-MM-DD HH:MM:SS'` in **device-local time**, not UTC. */
     log_time: string;
     log_type: number;
+    /**
+     * Where the device was set to be worn (its `deviceBodyPart`) when this log was
+     * uploaded — a setting, not a detection. Whether it was actually worn is
+     * `off_wrist`.
+     */
     body_part: 'wrist' | 'necklace' | null;
     /** Degrees Celsius, already converted by the backend. */
     temperature: number | null;
@@ -594,6 +629,11 @@ interface SensorLogItem {
     act_data_pim?: number | null;
     act_data_tat?: number | null;
     act_data_zcm?: number | null;
+    /**
+     * The device's raw wear flag, and **the name misleads**: `1` = worn, `0` = not
+     * worn (on its dock). Treat any value other than `1` as not worn, and `null`
+     * as unknown.
+     */
     off_wrist?: number | null;
     cap_sensor_1?: number | null;
     cap_sensor_2?: number | null;
@@ -648,6 +688,12 @@ interface SystemStatusPayload {
     internet: boolean;
     permission: boolean;
     hasDevices: boolean;
+    /**
+     * `true` when `hasDevices` is the server's answer; `false` when the app could
+     * not ask (no internet, session) — then `hasDevices: false` does **not** mean
+     * "no device". Absent below `nativeVersion` 0.18.0: treat absent as unknown.
+     */
+    hasDevicesKnown?: boolean;
     /**
      * Optional permissions not yet granted, as `AppPermission` names
      * (e.g. `["notification", "backgroundLocation"]`). Additive and
@@ -688,6 +734,54 @@ interface RequestPermissionPayload {
     /** Name of the permission to request, e.g. `'bluetoothScan'`. */
     permission: string;
 }
+/**
+ * Which device a command is about. `serialNo` is an **integer** and always
+ * goes; add `deviceId` (from `devicesConfig[].deviceId`) when
+ * `nativeVersion` ≥ 0.17.0 — it is the only way to address one of two devices
+ * that share a `serialNo`. A string `serialNo` is dropped by the app in silence.
+ */
+interface DeviceAddress {
+    serialNo: number;
+    deviceId?: number;
+}
+/**
+ * Arguments of every command the client may send, by name. `BridgeClient.send`
+ * checks them at compile time: a command that is not here (or `dfu`, which the
+ * shell denies) has no typed arguments and is refused at run time.
+ */
+interface CommandArgs {
+    ping: Record<string, never> | undefined;
+    userDevice: {
+        getFromServer?: boolean;
+    } | undefined;
+    realTime: DeviceAddress & {
+        value: boolean;
+    };
+    deviceConnection: DeviceAddress & {
+        type: 'add' | 'remove';
+    };
+    sensorLog: SensorLogQueryPayload;
+    openSettings: Record<string, never> | undefined;
+    requestPermission: RequestPermissionPayload;
+    setStatusBarColor: {
+        color: string;
+    };
+    navigationState: NavigationStatePayload;
+    language: Record<string, never> | undefined;
+    jsError: {
+        message: string;
+        stack?: string;
+        source?: string;
+        lineno?: number;
+        colno?: number;
+    };
+    syncTime: DeviceAddress;
+    deleteMemory: DeviceAddress;
+    logout: Record<string, never> | undefined;
+}
+type CommandName = keyof CommandArgs;
+/** The rest-parameters of `send(command, …)`: none, optional or required. */
+type CommandArgsTuple<C extends CommandName> = undefined extends CommandArgs[C] ? [args?: Exclude<CommandArgs[C], undefined>] : [args: CommandArgs[C]];
 /**
  * Payload of the `navigationBack` event (native → client). Empty — the request
  * carries no data; react by going back exactly one internal page.
@@ -906,6 +1000,16 @@ declare const Bridge: CondorBridge;
  * native layer.
  */
 
+/**
+ * A unique `requestId` for `sensorLog`. Built on `crypto.getRandomValues`,
+ * which works in any context — unlike `crypto.randomUUID`, which exists only in
+ * a secure context, and the app's sandboxed iframe is probably not one.
+ */
+declare function createRequestId(): string;
+/** A `sensorLog` query for `fetchSensorLog`: `requestId` is filled in if absent. */
+type SensorLogFetchQuery = Omit<SensorLogQueryPayload, 'requestId'> & {
+    requestId?: string;
+};
 interface BridgeClientHandshakeAck {
     shellVersion: string;
     /**
@@ -916,7 +1020,7 @@ interface BridgeClientHandshakeAck {
      * version negotiation, and a sandboxed client reaches the native side by no
      * other path. For example, the raw light channels (`light_sensor_*` in
      * `deviceLightSensors`) exist from `0.16.0`. Always keep a working branch
-     * for `null`. The dev harness reports `0.17.0` unless a scenario says
+     * for `null`. The dev harness reports `0.18.0` unless a scenario says
      * otherwise.
      */
     nativeVersion: string | null;
@@ -927,6 +1031,31 @@ interface BridgeClientHandshakeAck {
      */
     accepted: boolean;
 }
+/** What {@link CondorBridgeClient.requestUserDevices} resolves with. */
+type UserDevicesResult = 
+/** The list arrived. It may be empty. */
+{
+    status: 'ok';
+    devices: UserDevicePayload;
+}
+/** The server says the account has no linked device (nativeVersion 0.18.0+). */
+ | {
+    status: 'no-devices';
+}
+/** The app could not load the list: `NETWORK`, `SESSION`, `UNKNOWN` (0.18.0+). */
+ | {
+    status: 'error';
+    code: string;
+}
+/**
+ * No answer before the deadline — the only failure an app below 0.18.0 can
+ * produce. `hasDevices` is the last trustworthy `systemStatus.hasDevices`,
+ * or `null`.
+ */
+ | {
+    status: 'timeout';
+    hasDevices: boolean | null;
+};
 interface CondorBridgeClient {
     /** Version of the client-side postMessage protocol. */
     readonly protocolVersion: string;
@@ -950,7 +1079,7 @@ interface CondorBridgeClient {
      * Replies, when a command has one, arrive on the corresponding key — see
      * `docs/bridge-contract.md`.
      */
-    send(command: string, args?: Record<string, unknown>): void;
+    send<C extends CommandName>(command: C, ...args: CommandArgsTuple<C>): void;
     /** Opens the native Settings screen. Equivalent to `send('openSettings')`. */
     openSettings(): void;
     /**
@@ -962,9 +1091,10 @@ interface CondorBridgeClient {
      * Saves you from keeping a `requestId → resolve` map by hand. To sweep a
      * period, chain calls using the returned `startingAfter` until `hasMore`
      * becomes `false`: the cursors are dependent, so pages **cannot** be fetched
-     * in parallel.
+     * in parallel. Leave `requestId` out: one is created for you
+     * ({@link createRequestId}).
      */
-    fetchSensorLog(query: SensorLogQueryPayload, opts?: {
+    fetchSensorLog(query: SensorLogFetchQuery, opts?: {
         timeoutMs?: number;
     }): Promise<SensorLogPayload>;
     /**
@@ -998,19 +1128,23 @@ interface CondorBridgeClient {
     }>;
     /**
      * Requests the user's devices and **keeps asking** until they arrive. Use
-     * this instead of `send('userDevice')`, which may never be answered:
+     * this instead of `send('userDevice')`, which may never be answered on an app
+     * below `nativeVersion` 0.18.0:
      *
      * - on a cold start the first request is lost while the background service
      *   comes up;
      * - an account with no linked device gets no reply at all.
      *
      * Resends with backoff (1.5 s, 3 s, 6 s, then every 10 s) and on every
-     * `systemStatus` while pending. Never rejects. Resolves with
-     * `{ status: 'ok', devices }`, or `{ status: 'timeout', hasDevices }` after
-     * `timeoutMs` (default 30 s), where `hasDevices` is the last
-     * `systemStatus.hasDevices` seen (`null` if none). `false` there **suggests**
-     * an account with no device — show an empty state with a retry button — but
-     * the app also reports `false` when it could not reach the server.
+     * `systemStatus` while pending. Never rejects. Resolves a
+     * {@link UserDevicesResult}:
+     * - `ok` — render `devices`;
+     * - `no-devices` — the server confirmed there is none (0.18.0+);
+     * - `error` — the list could not load (`NETWORK`, `SESSION`, `UNKNOWN`;
+     *   0.18.0+): show it with a retry;
+     * - `timeout` — no answer in `timeoutMs` (default 30 s). On an older app this
+     *   is how both failures look; `hasDevices === false` then **suggests** an
+     *   account with no device, worded so it is true either way.
      *
      * `getFromServer: true` asks the app to refresh from the server; leave it
      * `false` (default) at boot, where the cached list is enough.
@@ -1018,13 +1152,7 @@ interface CondorBridgeClient {
     requestUserDevices(opts?: {
         timeoutMs?: number;
         getFromServer?: boolean;
-    }): Promise<{
-        status: 'ok';
-        devices: UserDevicePayload;
-    } | {
-        status: 'timeout';
-        hasDevices: boolean | null;
-    }>;
+    }): Promise<UserDevicesResult>;
     /**
      * Handshakes with the shell. Resolves with
      * `{ shellVersion, nativeVersion, accepted }` — read `nativeVersion` to learn
@@ -1318,4 +1446,4 @@ declare class BridgeShell {
  */
 declare function versionAtLeast(version: string | null | undefined, min: string): boolean;
 
-export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, type ClientToShellMessage, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceConfigItem, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type DeviceSyncErrorItem, type DeviceTelemetryItem, type DeviceUserConfigItem, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type LightSensorsActlumus1Data, type LightSensorsActlumus2Data, type LightSensorsRawChannels, type MockMessage, type MockState, NATIVE_CHANNEL_NAME, type NavigationBackPayload, type NavigationStatePayload, type OutgoingStamp, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogItem, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, type ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload, versionAtLeast };
+export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, type ClientToShellMessage, type CommandArgs, type CommandArgsTuple, type CommandName, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceAddress, type DeviceConfigItem, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type DeviceSyncErrorItem, type DeviceTelemetryItem, type DeviceUserConfigItem, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type LightSensorsActlumus1Data, type LightSensorsActlumus2Data, type LightSensorsRawChannels, type MockMessage, type MockState, NATIVE_CHANNEL_NAME, type NavigationBackPayload, type NavigationStatePayload, type OutgoingStamp, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogFetchQuery, type SensorLogItem, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, type ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDeviceErrorCode, type UserDevicePayload, type UserDevicesResult, createRequestId, versionAtLeast };

package/dist/index.d.ts

@@ -196,6 +196,10 @@ interface BridgeOutgoingEvent {
  *   There is no hard semver validation — it is **always** `true`, so it carries
  *   no information. Never branch on it.
  */
+/**
+ * Ack of the legacy {@link Bridge} (`createBridge`). With `BridgeClient`, the
+ * ack is {@link BridgeClientHandshakeAck}, whose `nativeVersion` may be `null`.
+ */
 interface HandshakeAck {
     nativeVersion: string;
     accepted: boolean;
@@ -332,16 +336,35 @@ interface DeviceUserConfigItem {
  * — but only when that `serialNo` appears once in `devicesConfig`. A device may
  * have no telemetry yet: render it with empty readings, never drop it.
  *
- * **It is not guaranteed to answer.** Use `BridgeClient.requestUserDevices()`
- * instead of `send('userDevice')`; see `docs/troubleshooting.md`.
+ * **Below `nativeVersion` 0.18.0 it is not guaranteed to answer**: a request
+ * sent while the app's background service starts is lost, and a failed lookup
+ * gets no reply. From 0.18.0 the app re-sends the lost request itself and
+ * answers a failure with empty arrays and `error`. Either way, use
+ * `BridgeClient.requestUserDevices()` instead of `send('userDevice')`; see
+ * `docs/troubleshooting.md`.
  *
  * The app enforces no device cap. A commercial rule currently limits a user to
  * two linked devices, but that can change with no signal in this contract — read
  * the length of the array rather than hard-coding it.
  */
+/**
+ * Why the device list could not be loaded (`UserDevicePayload.error`, from
+ * `nativeVersion` 0.18.0):
+ * - `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 an unrecognised value like `UNKNOWN`.
+ */
+type UserDeviceErrorCode = 'NO_DEVICES' | 'NETWORK' | 'SESSION' | 'UNKNOWN' | (string & {});
 interface UserDevicePayload {
     /** Epoch milliseconds of the snapshot. */
     lastUpdate: number;
+    /**
+     * Present only when the list could not be loaded; the three arrays are then
+     * empty. From `nativeVersion` 0.18.0 — older apps send no reply at all in
+     * that case. `BridgeClient.requestUserDevices()` turns it into a status.
+     */
+    error?: UserDeviceErrorCode;
     devicesConfig: DeviceConfigItem[];
     devicesTelemetry: DeviceTelemetryItem[];
     devicesUserConfig: DeviceUserConfigItem[];
@@ -349,6 +372,8 @@ interface UserDevicePayload {
 /**
  * Raw light-sensor channels, under the names the backend uses in
  * `user_cmd=log` — the same vocabulary for history and for real time.
+ * Relative values with no physical unit (as are the `wavelength*` channels);
+ * only `photopic` / `melanopic` (and `lux_*` in the history) are lux.
  *
  * Present from **nativeVersion 0.16.0**. A bundle compiled against this SDK can
  * run on an older native app that does not emit them: check `nativeVersion`
@@ -387,6 +412,7 @@ type LightSensorsRawChannels = {
  * change between hardware generations.
  */
 type LightSensorsActlumus1Data = LightSensorsRawChannels & {
+    /** When the phone received the reading: epoch ms (UTC), phone clock. */
     time: number;
     wavelength390: number;
     wavelength415: number;
@@ -419,6 +445,7 @@ type LightSensorsActlumus1Data = LightSensorsRawChannels & {
  * Y in the green, X in the red.
  */
 type LightSensorsActlumus2Data = LightSensorsRawChannels & {
+    /** When the phone received the reading: epoch ms (UTC), phone clock. */
     time: number;
     wavelength395: number;
     wavelength426: number;
@@ -503,9 +530,12 @@ interface DeviceConnectionPayload {
     isConnect: boolean;
 }
 /**
- * Device event or status notice. Mirrors `DevicesNotification.toMap()`.
- * `message` is already localized by the app; `messageCode` is the stable
- * identifier to branch on.
+ * One step of a device sync (BLE session). Mirrors `DevicesNotification.toMap()`.
+ * Branch on `messageCode` (`pipeline_done_notification` = the sync succeeded,
+ * `*_error` = a stage failed); `message` is the app's English log line, not
+ * localized and not stable. `isConnect` is `!isError` on sync steps — read
+ * the connection from `deviceConnection`. See `docs/bridge-contract.md`,
+ * "Sync progress".
  */
 interface DeviceNotificationPayload {
     serialNo: number;
@@ -536,8 +566,8 @@ interface SensorLogQueryPayload {
     /** Echoed back in the reply — correlates concurrent requests. */
     requestId: string;
     serialNo: number;
-    /** `wrist` or `necklace`. Omit for no filter. */
-    bodyPart?: string;
+    /** Omit for no filter. */
+    bodyPart?: 'wrist' | 'necklace';
     /** 1..1000 (backend default is 10). Outside the range: `INVALID_LIMIT`. */
     limit?: number;
     startingAfter?: string;
@@ -562,6 +592,11 @@ interface SensorLogItem {
     /** `'YYYY-MM-DD HH:MM:SS'` in **device-local time**, not UTC. */
     log_time: string;
     log_type: number;
+    /**
+     * Where the device was set to be worn (its `deviceBodyPart`) when this log was
+     * uploaded — a setting, not a detection. Whether it was actually worn is
+     * `off_wrist`.
+     */
     body_part: 'wrist' | 'necklace' | null;
     /** Degrees Celsius, already converted by the backend. */
     temperature: number | null;
@@ -594,6 +629,11 @@ interface SensorLogItem {
     act_data_pim?: number | null;
     act_data_tat?: number | null;
     act_data_zcm?: number | null;
+    /**
+     * The device's raw wear flag, and **the name misleads**: `1` = worn, `0` = not
+     * worn (on its dock). Treat any value other than `1` as not worn, and `null`
+     * as unknown.
+     */
     off_wrist?: number | null;
     cap_sensor_1?: number | null;
     cap_sensor_2?: number | null;
@@ -648,6 +688,12 @@ interface SystemStatusPayload {
     internet: boolean;
     permission: boolean;
     hasDevices: boolean;
+    /**
+     * `true` when `hasDevices` is the server's answer; `false` when the app could
+     * not ask (no internet, session) — then `hasDevices: false` does **not** mean
+     * "no device". Absent below `nativeVersion` 0.18.0: treat absent as unknown.
+     */
+    hasDevicesKnown?: boolean;
     /**
      * Optional permissions not yet granted, as `AppPermission` names
      * (e.g. `["notification", "backgroundLocation"]`). Additive and
@@ -688,6 +734,54 @@ interface RequestPermissionPayload {
     /** Name of the permission to request, e.g. `'bluetoothScan'`. */
     permission: string;
 }
+/**
+ * Which device a command is about. `serialNo` is an **integer** and always
+ * goes; add `deviceId` (from `devicesConfig[].deviceId`) when
+ * `nativeVersion` ≥ 0.17.0 — it is the only way to address one of two devices
+ * that share a `serialNo`. A string `serialNo` is dropped by the app in silence.
+ */
+interface DeviceAddress {
+    serialNo: number;
+    deviceId?: number;
+}
+/**
+ * Arguments of every command the client may send, by name. `BridgeClient.send`
+ * checks them at compile time: a command that is not here (or `dfu`, which the
+ * shell denies) has no typed arguments and is refused at run time.
+ */
+interface CommandArgs {
+    ping: Record<string, never> | undefined;
+    userDevice: {
+        getFromServer?: boolean;
+    } | undefined;
+    realTime: DeviceAddress & {
+        value: boolean;
+    };
+    deviceConnection: DeviceAddress & {
+        type: 'add' | 'remove';
+    };
+    sensorLog: SensorLogQueryPayload;
+    openSettings: Record<string, never> | undefined;
+    requestPermission: RequestPermissionPayload;
+    setStatusBarColor: {
+        color: string;
+    };
+    navigationState: NavigationStatePayload;
+    language: Record<string, never> | undefined;
+    jsError: {
+        message: string;
+        stack?: string;
+        source?: string;
+        lineno?: number;
+        colno?: number;
+    };
+    syncTime: DeviceAddress;
+    deleteMemory: DeviceAddress;
+    logout: Record<string, never> | undefined;
+}
+type CommandName = keyof CommandArgs;
+/** The rest-parameters of `send(command, …)`: none, optional or required. */
+type CommandArgsTuple<C extends CommandName> = undefined extends CommandArgs[C] ? [args?: Exclude<CommandArgs[C], undefined>] : [args: CommandArgs[C]];
 /**
  * Payload of the `navigationBack` event (native → client). Empty — the request
  * carries no data; react by going back exactly one internal page.
@@ -906,6 +1000,16 @@ declare const Bridge: CondorBridge;
  * native layer.
  */
 
+/**
+ * A unique `requestId` for `sensorLog`. Built on `crypto.getRandomValues`,
+ * which works in any context — unlike `crypto.randomUUID`, which exists only in
+ * a secure context, and the app's sandboxed iframe is probably not one.
+ */
+declare function createRequestId(): string;
+/** A `sensorLog` query for `fetchSensorLog`: `requestId` is filled in if absent. */
+type SensorLogFetchQuery = Omit<SensorLogQueryPayload, 'requestId'> & {
+    requestId?: string;
+};
 interface BridgeClientHandshakeAck {
     shellVersion: string;
     /**
@@ -916,7 +1020,7 @@ interface BridgeClientHandshakeAck {
      * version negotiation, and a sandboxed client reaches the native side by no
      * other path. For example, the raw light channels (`light_sensor_*` in
      * `deviceLightSensors`) exist from `0.16.0`. Always keep a working branch
-     * for `null`. The dev harness reports `0.17.0` unless a scenario says
+     * for `null`. The dev harness reports `0.18.0` unless a scenario says
      * otherwise.
      */
     nativeVersion: string | null;
@@ -927,6 +1031,31 @@ interface BridgeClientHandshakeAck {
      */
     accepted: boolean;
 }
+/** What {@link CondorBridgeClient.requestUserDevices} resolves with. */
+type UserDevicesResult = 
+/** The list arrived. It may be empty. */
+{
+    status: 'ok';
+    devices: UserDevicePayload;
+}
+/** The server says the account has no linked device (nativeVersion 0.18.0+). */
+ | {
+    status: 'no-devices';
+}
+/** The app could not load the list: `NETWORK`, `SESSION`, `UNKNOWN` (0.18.0+). */
+ | {
+    status: 'error';
+    code: string;
+}
+/**
+ * No answer before the deadline — the only failure an app below 0.18.0 can
+ * produce. `hasDevices` is the last trustworthy `systemStatus.hasDevices`,
+ * or `null`.
+ */
+ | {
+    status: 'timeout';
+    hasDevices: boolean | null;
+};
 interface CondorBridgeClient {
     /** Version of the client-side postMessage protocol. */
     readonly protocolVersion: string;
@@ -950,7 +1079,7 @@ interface CondorBridgeClient {
      * Replies, when a command has one, arrive on the corresponding key — see
      * `docs/bridge-contract.md`.
      */
-    send(command: string, args?: Record<string, unknown>): void;
+    send<C extends CommandName>(command: C, ...args: CommandArgsTuple<C>): void;
     /** Opens the native Settings screen. Equivalent to `send('openSettings')`. */
     openSettings(): void;
     /**
@@ -962,9 +1091,10 @@ interface CondorBridgeClient {
      * Saves you from keeping a `requestId → resolve` map by hand. To sweep a
      * period, chain calls using the returned `startingAfter` until `hasMore`
      * becomes `false`: the cursors are dependent, so pages **cannot** be fetched
-     * in parallel.
+     * in parallel. Leave `requestId` out: one is created for you
+     * ({@link createRequestId}).
      */
-    fetchSensorLog(query: SensorLogQueryPayload, opts?: {
+    fetchSensorLog(query: SensorLogFetchQuery, opts?: {
         timeoutMs?: number;
     }): Promise<SensorLogPayload>;
     /**
@@ -998,19 +1128,23 @@ interface CondorBridgeClient {
     }>;
     /**
      * Requests the user's devices and **keeps asking** until they arrive. Use
-     * this instead of `send('userDevice')`, which may never be answered:
+     * this instead of `send('userDevice')`, which may never be answered on an app
+     * below `nativeVersion` 0.18.0:
      *
      * - on a cold start the first request is lost while the background service
      *   comes up;
      * - an account with no linked device gets no reply at all.
      *
      * Resends with backoff (1.5 s, 3 s, 6 s, then every 10 s) and on every
-     * `systemStatus` while pending. Never rejects. Resolves with
-     * `{ status: 'ok', devices }`, or `{ status: 'timeout', hasDevices }` after
-     * `timeoutMs` (default 30 s), where `hasDevices` is the last
-     * `systemStatus.hasDevices` seen (`null` if none). `false` there **suggests**
-     * an account with no device — show an empty state with a retry button — but
-     * the app also reports `false` when it could not reach the server.
+     * `systemStatus` while pending. Never rejects. Resolves a
+     * {@link UserDevicesResult}:
+     * - `ok` — render `devices`;
+     * - `no-devices` — the server confirmed there is none (0.18.0+);
+     * - `error` — the list could not load (`NETWORK`, `SESSION`, `UNKNOWN`;
+     *   0.18.0+): show it with a retry;
+     * - `timeout` — no answer in `timeoutMs` (default 30 s). On an older app this
+     *   is how both failures look; `hasDevices === false` then **suggests** an
+     *   account with no device, worded so it is true either way.
      *
      * `getFromServer: true` asks the app to refresh from the server; leave it
      * `false` (default) at boot, where the cached list is enough.
@@ -1018,13 +1152,7 @@ interface CondorBridgeClient {
     requestUserDevices(opts?: {
         timeoutMs?: number;
         getFromServer?: boolean;
-    }): Promise<{
-        status: 'ok';
-        devices: UserDevicePayload;
-    } | {
-        status: 'timeout';
-        hasDevices: boolean | null;
-    }>;
+    }): Promise<UserDevicesResult>;
     /**
      * Handshakes with the shell. Resolves with
      * `{ shellVersion, nativeVersion, accepted }` — read `nativeVersion` to learn
@@ -1318,4 +1446,4 @@ declare class BridgeShell {
  */
 declare function versionAtLeast(version: string | null | undefined, min: string): boolean;
 
-export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, type ClientToShellMessage, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceConfigItem, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type DeviceSyncErrorItem, type DeviceTelemetryItem, type DeviceUserConfigItem, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type LightSensorsActlumus1Data, type LightSensorsActlumus2Data, type LightSensorsRawChannels, type MockMessage, type MockState, NATIVE_CHANNEL_NAME, type NavigationBackPayload, type NavigationStatePayload, type OutgoingStamp, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogItem, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, type ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload, versionAtLeast };
+export { type AutoRespondResponse, BRIDGE_KEYS, Bridge, BridgeClient, type BridgeClientHandshakeAck, type BridgeIncomingMessage, type BridgeKey, type BridgeOutgoingEvent, BridgeShell, type BridgeShellOptions, type ClientToShellMessage, type CommandArgs, type CommandArgsTuple, type CommandName, type CondorBridge, type CondorBridgeClient, type ConfirmationRequest, type DeleteMemoryAckPayload, type DevPanelOptions, type DeviceAddress, type DeviceConfigItem, type DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, type DeviceSyncErrorItem, type DeviceTelemetryItem, type DeviceUserConfigItem, type HandshakeAck, type HandshakeOptions, type KeyPayloads, type LanguagePayload, type LightSensorsActlumus1Data, type LightSensorsActlumus2Data, type LightSensorsRawChannels, type MockMessage, type MockState, NATIVE_CHANNEL_NAME, type NavigationBackPayload, type NavigationStatePayload, type OutgoingStamp, type PayloadOf, type PingPongPayload, type RealTimeAckPayload, type RequestPermissionPayload, type SandboxVerifyResult, type SensorLogFetchQuery, type SensorLogItem, type SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, type ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDeviceErrorCode, type UserDevicePayload, type UserDevicesResult, createRequestId, versionAtLeast };