@condorinst/mobile-bridge 0.20.0 → 0.22.0

package/dist/index.d.cts

@@ -225,23 +225,126 @@ interface HandshakeOptions {
 interface PingPongPayload {
     data: 'ping' | 'pong';
 }
+/**
+ * One linked device, as configured on the server. Mirrors
+ * `DeviceConfig.toMap()` in `condor_core`
+ * (`domain/entities/device_config_entity.dart`).
+ *
+ * `deviceId` is the server id and is unique. `serialNo` is printed on the
+ * device and **can repeat**: an ActLumus and an ActLumus Plus may share one.
+ */
+interface DeviceConfigItem {
+    /** Server id. Unique — the join key across the three arrays. */
+    deviceId: number;
+    /** Printed serial number. Not unique: an ActLumus and a Plus may share one. */
+    serialNo: number;
+    /** Where the device is worn. `null` when not set. */
+    deviceBodyPart: 'wrist' | 'necklace' | null;
+    /**
+     * Device model id. Absent when the server did not send one, which means an
+     * ActLumus (gen1); the Plus always carries it. Never a display name.
+     */
+    modelId?: 'actlumus' | 'actlumus_plus' | (string & {});
+    /** BLE advertising period, in minutes, set by the Condor web system. */
+    bleConnectionPeriod: number;
+    autosync: boolean;
+    eraseDeviceMemory: boolean;
+    autoEraseDeviceMemory: boolean;
+    autoEraseDeviceMemoryThreshold: number;
+    readSensorsMemory: boolean;
+    startDevice: boolean;
+    readFullMemory: boolean;
+    allowFirmwareUpdate: boolean;
+}
+/**
+ * One failed sync attempt. Mirrors `DeviceSyncError.toMap()`
+ * (`domain/entities/device_sync_error_entity.dart`).
+ */
+interface DeviceSyncErrorItem {
+    serialNo: number;
+    /** Epoch milliseconds. */
+    attemptDate: number;
+    /** Already localized by the app. Show it; do not branch on it. */
+    message: string;
+    /** Stable identifier to branch on. `null` for legacy errors. */
+    messageCode: string | null;
+}
+/**
+ * Last known state of one device, as read over BLE. Mirrors
+ * `DeviceTelemetry.toMap()` (`domain/entities/device_telemetry_entity.dart`).
+ *
+ * Every reading is `null` until the device has synced at least once.
+ */
+interface DeviceTelemetryItem {
+    serialNo: number;
+    /**
+     * Server id. **Omitted** on legacy data the app could not attribute, so join
+     * by `deviceId` when present and fall back to `serialNo` only when that
+     * `serialNo` is unique in `devicesConfig`.
+     */
+    deviceId?: number;
+    /**
+     * Last successful sync, epoch milliseconds. The misspelling (`updata`) is the
+     * real field name — do not "fix" it.
+     */
+    updataDateTime: number | null;
+    /** Display name reported by the device. Not in `devicesConfig`. */
+    deviceName: string | null;
+    /** Firmware version. */
+    deviceVersion: string | null;
+    hardwareVersion: string | null;
+    /** Device clock at the last sync, epoch milliseconds. */
+    deviceDateTime: number | null;
+    /** Data memory used, percent 0–100. */
+    memoryDataUsage: number | null;
+    /** System memory used, percent 0–100. */
+    memorySystemUsage: number | null;
+    /** Battery charge, percent 0–100. */
+    batteryLevel: number | null;
+    /** Battery voltage, volts. */
+    batteryVoltage: number | null;
+    isCharging: boolean | null;
+    isOnDock: boolean | null;
+    /** Sync failures of this device. Empty when there are none. */
+    syncErrors: DeviceSyncErrorItem[];
+}
+/**
+ * Per-device toggles of the user. Mirrors `DeviceUserConfig.toMap()`
+ * (`domain/entities/device_user_config_entity.dart`).
+ */
+interface DeviceUserConfigItem {
+    serialNo: number;
+    /** Server id. Omitted on legacy data — see `DeviceTelemetryItem.deviceId`. */
+    deviceId?: number;
+    syncTime: boolean;
+    realTime: boolean;
+    deleteMemory: boolean;
+    readAllMemory: boolean;
+    readAllSystemLog: boolean;
+}
 /**
  * Snapshot of the user's device store. Mirrors `UserDevices.toMap()` in
  * `condor_core`.
  *
- * The inner arrays are `Record<string, unknown>`: each item has its own
- * `toMap()` on the Dart side (device config, telemetry, user config), and
- * strict typing for them is deferred until a client needs it.
+ * **Joining the three arrays.** `devicesConfig` lists the devices; the other
+ * two describe them. Join on `deviceId`. When an item of `devicesTelemetry` or
+ * `devicesUserConfig` has no `deviceId` (legacy data), fall back to `serialNo`
+ * — 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`.
  *
  * 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.
  */
 interface UserDevicePayload {
+    /** Epoch milliseconds of the snapshot. */
     lastUpdate: number;
-    devicesConfig: Array<Record<string, unknown>>;
-    devicesTelemetry: Array<Record<string, unknown>>;
-    devicesUserConfig: Array<Record<string, unknown>>;
+    devicesConfig: DeviceConfigItem[];
+    devicesTelemetry: DeviceTelemetryItem[];
+    devicesUserConfig: DeviceUserConfigItem[];
 }
 /**
  * Raw light-sensor channels, under the names the backend uses in
@@ -444,6 +547,63 @@ interface SensorLogQueryPayload {
     /** Exclusive, `YYYY-MM-DD HH:MM:SS`, in device-local time. */
     endTime?: string;
 }
+/**
+ * One sensor log, passed through from the backend `get_log` contract.
+ *
+ * **Cadence.** The device writes one log per period, which is programmable per
+ * device (default 60 s). Never assume one per minute: size pagination from the
+ * gaps between `log_time` values you actually receive.
+ *
+ * `null` on a channel means the hardware does not have it, never zero.
+ */
+interface SensorLogItem {
+    /** Stable id of the log. */
+    id: number;
+    /** `'YYYY-MM-DD HH:MM:SS'` in **device-local time**, not UTC. */
+    log_time: string;
+    log_type: number;
+    body_part: 'wrist' | 'necklace' | null;
+    /** Degrees Celsius, already converted by the backend. */
+    temperature: number | null;
+    /** Photopic illuminance, lux. */
+    lux_photopic: number | null;
+    /** Melanopic illuminance (melanopic EDI), lux. */
+    lux_melanopic: number | null;
+    company_id?: number;
+    user_id?: number;
+    device_id?: number;
+    orientation?: number | null;
+    light_sensor_f1?: number | null;
+    light_sensor_f2?: number | null;
+    light_sensor_f3?: number | null;
+    light_sensor_f4?: number | null;
+    light_sensor_f5?: number | null;
+    light_sensor_f6?: number | null;
+    light_sensor_f7?: number | null;
+    light_sensor_f8?: number | null;
+    light_sensor_clear?: number | null;
+    light_sensor_nir?: number | null;
+    /** ActLumus Plus only (`null` on gen1). Approximates CIE X; not an exact CIE value. */
+    light_sensor_x?: number | null;
+    /** ActLumus Plus only (`null` on gen1). */
+    light_sensor_y?: number | null;
+    /** ActLumus Plus only (`null` on gen1). */
+    light_sensor_z?: number | null;
+    /** ActLumus Plus only (`null` on gen1). Reserved by the firmware; do not interpret. */
+    light_sensor_fd?: number | null;
+    act_data_pim?: number | null;
+    act_data_tat?: number | null;
+    act_data_zcm?: number | null;
+    off_wrist?: number | null;
+    cap_sensor_1?: number | null;
+    cap_sensor_2?: number | null;
+    event?: number | null;
+    state?: number | null;
+    from_service?: boolean;
+    /** Batch markers of the upload, not per-log timestamps. Do not plot them. */
+    device_log_time?: string | null;
+    app_log_time?: string | null;
+}
 /**
  * Reply to the `sensorLog` command.
  *
@@ -464,7 +624,8 @@ interface SensorLogQueryPayload {
 interface SensorLogPayload {
     requestId: string;
     success: boolean;
-    logs?: Array<Record<string, unknown>>;
+    /** Chronological ascending. Without a cursor or range: the most recent page. */
+    logs?: SensorLogItem[];
     startingAfter?: string | null;
     endingBefore?: string | null;
     hasMore?: boolean;
@@ -735,7 +896,9 @@ declare const Bridge: CondorBridge;
  * deletes them before your bundle runs.
  *
  * It deliberately does **not** expose `installDevPanel`, `mockEmit`, `isMock`
- * or `getMockState`: those belong to the shell (`BridgeShell`).
+ * or `getMockState`: those belong to the shell (`BridgeShell`). To run a bundle
+ * in a browser, use the dev harness (`npx condor-mobile-bridge dev`, or
+ * `createDevHarness` from `@condorinst/mobile-bridge/dev`).
  *
  * The module also answers the shell's `verify-sandbox` probe — the iframe
  * attesting whether it can still see the native globals. If any is reachable,
@@ -747,14 +910,14 @@ interface BridgeClientHandshakeAck {
     shellVersion: string;
     /**
      * Schema version of the **native** side, relayed by the shell. `null` when
-     * the native side has not answered, does not exist (browser mock mode), or
-     * the shell is older than 0.6.0.
+     * the native side has not answered, or the shell is older than 0.6.0.
      *
      * **This number is the only capability signal a client gets.** There is no
      * 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`: your browser development environment always hits it.
+     * for `null`. The dev harness reports `0.17.0` unless a scenario says
+     * otherwise.
      */
     nativeVersion: string | null;
     /**
@@ -815,13 +978,62 @@ interface CondorBridgeClient {
      * native enum is dropped in silence.
      */
     requestPermission(permission: string): void;
+    /**
+     * Resolves when the app's **background service** answers a `ping`.
+     *
+     * Commands that need device data (`userDevice`, `ping`) travel to a service
+     * the app starts after your bundle is already running. A command sent before
+     * the service is up is **lost without a reply** — the handshake, `systemStatus`
+     * and `language` work earlier, which makes the bridge look ready when it is
+     * not. This helper resends `ping` with backoff (1.5 s, 3 s, 6 s, then every
+     * 10 s) until a `pingPong` arrives.
+     *
+     * Never rejects: resolves `{ status: 'timeout' }` after `timeoutMs`
+     * (default 30 s).
+     */
+    waitForService(opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        status: 'ready' | 'timeout';
+    }>;
+    /**
+     * Requests the user's devices and **keeps asking** until they arrive. Use
+     * this instead of `send('userDevice')`, which may never be answered:
+     *
+     * - 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.
+     *
+     * `getFromServer: true` asks the app to refresh from the server; leave it
+     * `false` (default) at boot, where the cached list is enough.
+     */
+    requestUserDevices(opts?: {
+        timeoutMs?: number;
+        getFromServer?: boolean;
+    }): Promise<{
+        status: 'ok';
+        devices: UserDevicePayload;
+    } | {
+        status: 'timeout';
+        hasDevices: boolean | null;
+    }>;
     /**
      * Handshakes with the shell. Resolves with
      * `{ shellVersion, nativeVersion, accepted }` — read `nativeVersion` to learn
      * what this device can do, and ignore `accepted`, which is always `true`.
      *
-     * Rejects after 5 s if the shell does not answer. Only one handshake may be
-     * in flight at a time.
+     * Rejects after 5 s if the shell does not answer, and **at once** when the
+     * page is not inside the Condor shell (opened directly in a browser) — run
+     * `npx condor-mobile-bridge dev` instead. Only one handshake may be in flight
+     * at a time.
      */
     handshake(opts: {
         clientVersion: string;
@@ -1096,4 +1308,14 @@ declare class BridgeShell {
     private postToClient;
 }
 
-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 DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, 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 SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, type ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload };
+/**
+ * `versionAtLeast(ack.nativeVersion, '0.17.0')` — the capability check every
+ * client needs. Compares the three numeric segments; `null` (an unknown native
+ * side) is never at least anything, so it always takes the baseline branch.
+ *
+ * Do not compare version strings directly: `'0.9.0' > '0.16.0'` is `true` as
+ * strings and false as versions.
+ */
+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 };

package/dist/index.d.ts

@@ -225,23 +225,126 @@ interface HandshakeOptions {
 interface PingPongPayload {
     data: 'ping' | 'pong';
 }
+/**
+ * One linked device, as configured on the server. Mirrors
+ * `DeviceConfig.toMap()` in `condor_core`
+ * (`domain/entities/device_config_entity.dart`).
+ *
+ * `deviceId` is the server id and is unique. `serialNo` is printed on the
+ * device and **can repeat**: an ActLumus and an ActLumus Plus may share one.
+ */
+interface DeviceConfigItem {
+    /** Server id. Unique — the join key across the three arrays. */
+    deviceId: number;
+    /** Printed serial number. Not unique: an ActLumus and a Plus may share one. */
+    serialNo: number;
+    /** Where the device is worn. `null` when not set. */
+    deviceBodyPart: 'wrist' | 'necklace' | null;
+    /**
+     * Device model id. Absent when the server did not send one, which means an
+     * ActLumus (gen1); the Plus always carries it. Never a display name.
+     */
+    modelId?: 'actlumus' | 'actlumus_plus' | (string & {});
+    /** BLE advertising period, in minutes, set by the Condor web system. */
+    bleConnectionPeriod: number;
+    autosync: boolean;
+    eraseDeviceMemory: boolean;
+    autoEraseDeviceMemory: boolean;
+    autoEraseDeviceMemoryThreshold: number;
+    readSensorsMemory: boolean;
+    startDevice: boolean;
+    readFullMemory: boolean;
+    allowFirmwareUpdate: boolean;
+}
+/**
+ * One failed sync attempt. Mirrors `DeviceSyncError.toMap()`
+ * (`domain/entities/device_sync_error_entity.dart`).
+ */
+interface DeviceSyncErrorItem {
+    serialNo: number;
+    /** Epoch milliseconds. */
+    attemptDate: number;
+    /** Already localized by the app. Show it; do not branch on it. */
+    message: string;
+    /** Stable identifier to branch on. `null` for legacy errors. */
+    messageCode: string | null;
+}
+/**
+ * Last known state of one device, as read over BLE. Mirrors
+ * `DeviceTelemetry.toMap()` (`domain/entities/device_telemetry_entity.dart`).
+ *
+ * Every reading is `null` until the device has synced at least once.
+ */
+interface DeviceTelemetryItem {
+    serialNo: number;
+    /**
+     * Server id. **Omitted** on legacy data the app could not attribute, so join
+     * by `deviceId` when present and fall back to `serialNo` only when that
+     * `serialNo` is unique in `devicesConfig`.
+     */
+    deviceId?: number;
+    /**
+     * Last successful sync, epoch milliseconds. The misspelling (`updata`) is the
+     * real field name — do not "fix" it.
+     */
+    updataDateTime: number | null;
+    /** Display name reported by the device. Not in `devicesConfig`. */
+    deviceName: string | null;
+    /** Firmware version. */
+    deviceVersion: string | null;
+    hardwareVersion: string | null;
+    /** Device clock at the last sync, epoch milliseconds. */
+    deviceDateTime: number | null;
+    /** Data memory used, percent 0–100. */
+    memoryDataUsage: number | null;
+    /** System memory used, percent 0–100. */
+    memorySystemUsage: number | null;
+    /** Battery charge, percent 0–100. */
+    batteryLevel: number | null;
+    /** Battery voltage, volts. */
+    batteryVoltage: number | null;
+    isCharging: boolean | null;
+    isOnDock: boolean | null;
+    /** Sync failures of this device. Empty when there are none. */
+    syncErrors: DeviceSyncErrorItem[];
+}
+/**
+ * Per-device toggles of the user. Mirrors `DeviceUserConfig.toMap()`
+ * (`domain/entities/device_user_config_entity.dart`).
+ */
+interface DeviceUserConfigItem {
+    serialNo: number;
+    /** Server id. Omitted on legacy data — see `DeviceTelemetryItem.deviceId`. */
+    deviceId?: number;
+    syncTime: boolean;
+    realTime: boolean;
+    deleteMemory: boolean;
+    readAllMemory: boolean;
+    readAllSystemLog: boolean;
+}
 /**
  * Snapshot of the user's device store. Mirrors `UserDevices.toMap()` in
  * `condor_core`.
  *
- * The inner arrays are `Record<string, unknown>`: each item has its own
- * `toMap()` on the Dart side (device config, telemetry, user config), and
- * strict typing for them is deferred until a client needs it.
+ * **Joining the three arrays.** `devicesConfig` lists the devices; the other
+ * two describe them. Join on `deviceId`. When an item of `devicesTelemetry` or
+ * `devicesUserConfig` has no `deviceId` (legacy data), fall back to `serialNo`
+ * — 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`.
  *
  * 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.
  */
 interface UserDevicePayload {
+    /** Epoch milliseconds of the snapshot. */
     lastUpdate: number;
-    devicesConfig: Array<Record<string, unknown>>;
-    devicesTelemetry: Array<Record<string, unknown>>;
-    devicesUserConfig: Array<Record<string, unknown>>;
+    devicesConfig: DeviceConfigItem[];
+    devicesTelemetry: DeviceTelemetryItem[];
+    devicesUserConfig: DeviceUserConfigItem[];
 }
 /**
  * Raw light-sensor channels, under the names the backend uses in
@@ -444,6 +547,63 @@ interface SensorLogQueryPayload {
     /** Exclusive, `YYYY-MM-DD HH:MM:SS`, in device-local time. */
     endTime?: string;
 }
+/**
+ * One sensor log, passed through from the backend `get_log` contract.
+ *
+ * **Cadence.** The device writes one log per period, which is programmable per
+ * device (default 60 s). Never assume one per minute: size pagination from the
+ * gaps between `log_time` values you actually receive.
+ *
+ * `null` on a channel means the hardware does not have it, never zero.
+ */
+interface SensorLogItem {
+    /** Stable id of the log. */
+    id: number;
+    /** `'YYYY-MM-DD HH:MM:SS'` in **device-local time**, not UTC. */
+    log_time: string;
+    log_type: number;
+    body_part: 'wrist' | 'necklace' | null;
+    /** Degrees Celsius, already converted by the backend. */
+    temperature: number | null;
+    /** Photopic illuminance, lux. */
+    lux_photopic: number | null;
+    /** Melanopic illuminance (melanopic EDI), lux. */
+    lux_melanopic: number | null;
+    company_id?: number;
+    user_id?: number;
+    device_id?: number;
+    orientation?: number | null;
+    light_sensor_f1?: number | null;
+    light_sensor_f2?: number | null;
+    light_sensor_f3?: number | null;
+    light_sensor_f4?: number | null;
+    light_sensor_f5?: number | null;
+    light_sensor_f6?: number | null;
+    light_sensor_f7?: number | null;
+    light_sensor_f8?: number | null;
+    light_sensor_clear?: number | null;
+    light_sensor_nir?: number | null;
+    /** ActLumus Plus only (`null` on gen1). Approximates CIE X; not an exact CIE value. */
+    light_sensor_x?: number | null;
+    /** ActLumus Plus only (`null` on gen1). */
+    light_sensor_y?: number | null;
+    /** ActLumus Plus only (`null` on gen1). */
+    light_sensor_z?: number | null;
+    /** ActLumus Plus only (`null` on gen1). Reserved by the firmware; do not interpret. */
+    light_sensor_fd?: number | null;
+    act_data_pim?: number | null;
+    act_data_tat?: number | null;
+    act_data_zcm?: number | null;
+    off_wrist?: number | null;
+    cap_sensor_1?: number | null;
+    cap_sensor_2?: number | null;
+    event?: number | null;
+    state?: number | null;
+    from_service?: boolean;
+    /** Batch markers of the upload, not per-log timestamps. Do not plot them. */
+    device_log_time?: string | null;
+    app_log_time?: string | null;
+}
 /**
  * Reply to the `sensorLog` command.
  *
@@ -464,7 +624,8 @@ interface SensorLogQueryPayload {
 interface SensorLogPayload {
     requestId: string;
     success: boolean;
-    logs?: Array<Record<string, unknown>>;
+    /** Chronological ascending. Without a cursor or range: the most recent page. */
+    logs?: SensorLogItem[];
     startingAfter?: string | null;
     endingBefore?: string | null;
     hasMore?: boolean;
@@ -735,7 +896,9 @@ declare const Bridge: CondorBridge;
  * deletes them before your bundle runs.
  *
  * It deliberately does **not** expose `installDevPanel`, `mockEmit`, `isMock`
- * or `getMockState`: those belong to the shell (`BridgeShell`).
+ * or `getMockState`: those belong to the shell (`BridgeShell`). To run a bundle
+ * in a browser, use the dev harness (`npx condor-mobile-bridge dev`, or
+ * `createDevHarness` from `@condorinst/mobile-bridge/dev`).
  *
  * The module also answers the shell's `verify-sandbox` probe — the iframe
  * attesting whether it can still see the native globals. If any is reachable,
@@ -747,14 +910,14 @@ interface BridgeClientHandshakeAck {
     shellVersion: string;
     /**
      * Schema version of the **native** side, relayed by the shell. `null` when
-     * the native side has not answered, does not exist (browser mock mode), or
-     * the shell is older than 0.6.0.
+     * the native side has not answered, or the shell is older than 0.6.0.
      *
      * **This number is the only capability signal a client gets.** There is no
      * 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`: your browser development environment always hits it.
+     * for `null`. The dev harness reports `0.17.0` unless a scenario says
+     * otherwise.
      */
     nativeVersion: string | null;
     /**
@@ -815,13 +978,62 @@ interface CondorBridgeClient {
      * native enum is dropped in silence.
      */
     requestPermission(permission: string): void;
+    /**
+     * Resolves when the app's **background service** answers a `ping`.
+     *
+     * Commands that need device data (`userDevice`, `ping`) travel to a service
+     * the app starts after your bundle is already running. A command sent before
+     * the service is up is **lost without a reply** — the handshake, `systemStatus`
+     * and `language` work earlier, which makes the bridge look ready when it is
+     * not. This helper resends `ping` with backoff (1.5 s, 3 s, 6 s, then every
+     * 10 s) until a `pingPong` arrives.
+     *
+     * Never rejects: resolves `{ status: 'timeout' }` after `timeoutMs`
+     * (default 30 s).
+     */
+    waitForService(opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        status: 'ready' | 'timeout';
+    }>;
+    /**
+     * Requests the user's devices and **keeps asking** until they arrive. Use
+     * this instead of `send('userDevice')`, which may never be answered:
+     *
+     * - 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.
+     *
+     * `getFromServer: true` asks the app to refresh from the server; leave it
+     * `false` (default) at boot, where the cached list is enough.
+     */
+    requestUserDevices(opts?: {
+        timeoutMs?: number;
+        getFromServer?: boolean;
+    }): Promise<{
+        status: 'ok';
+        devices: UserDevicePayload;
+    } | {
+        status: 'timeout';
+        hasDevices: boolean | null;
+    }>;
     /**
      * Handshakes with the shell. Resolves with
      * `{ shellVersion, nativeVersion, accepted }` — read `nativeVersion` to learn
      * what this device can do, and ignore `accepted`, which is always `true`.
      *
-     * Rejects after 5 s if the shell does not answer. Only one handshake may be
-     * in flight at a time.
+     * Rejects after 5 s if the shell does not answer, and **at once** when the
+     * page is not inside the Condor shell (opened directly in a browser) — run
+     * `npx condor-mobile-bridge dev` instead. Only one handshake may be in flight
+     * at a time.
      */
     handshake(opts: {
         clientVersion: string;
@@ -1096,4 +1308,14 @@ declare class BridgeShell {
     private postToClient;
 }
 
-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 DeviceConnectionPayload, type DeviceLightSensorsPayload, type DeviceNotificationPayload, 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 SensorLogPayload, type SensorLogQueryPayload, type ShellPolicy, type ShellToClientMessage, type SyncTimeAckPayload, type SystemStatusPayload, type UserDevicePayload };
+/**
+ * `versionAtLeast(ack.nativeVersion, '0.17.0')` — the capability check every
+ * client needs. Compares the three numeric segments; `null` (an unknown native
+ * side) is never at least anything, so it always takes the baseline branch.
+ *
+ * Do not compare version strings directly: `'0.9.0' > '0.16.0'` is `true` as
+ * strings and false as versions.
+ */
+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 };