@condorinst/mobile-bridge 0.22.0 → 0.23.0

package/dist/dev.d.cts

@@ -105,20 +105,167 @@ 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[];
 }
+/**
+ * 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`
+ * from the handshake ack before depending on them, or read defensively. They
+ * are deliberately **not** optional in the type — optional would hide the
+ * version skew instead of making it explicit.
+ *
+ * ⚠️ `nativeVersion` only reaches the client from **SDK 0.17.0**: up to
+ * `0.16.x` the shell answered the client handshake with `shellVersion` alone,
+ * so this check was impossible to satisfy from inside the iframe.
+ *
+ * `null` means **the channel does not exist on this hardware generation**,
+ * never "the reading was zero" — `0.0` is a valid reading. Coercing `null` to
+ * `0` fabricates data.
+ */
+type LightSensorsRawChannels = {
+    light_sensor_f1: number;
+    light_sensor_f2: number;
+    light_sensor_f3: number;
+    light_sensor_f4: number;
+    light_sensor_f5: number;
+    light_sensor_f6: number;
+    light_sensor_f7: number;
+    light_sensor_f8: number;
+    /** Total light (`visible` on the device wire format). */
+    light_sensor_clear: number;
+    /** Near infrared. */
+    light_sensor_nir: number;
+};
+/**
+ * A real-time reading from an ActLumus gen1 (`type: 'actlumus'`).
+ *
+ * Mirrors `LightSensorsActlumus1GraphicData.toMap()` in `condor_interactors`.
+ * Gen1 has neither the tristimulus channels nor flicker detect — those four
+ * keys arrive as `null`, present in the schema so that its shape does not
+ * change between hardware generations.
+ */
+type LightSensorsActlumus1Data = LightSensorsRawChannels & {
+    /** When the phone received the reading: epoch ms (UTC), phone clock. */
+    time: number;
+    wavelength390: number;
+    wavelength415: number;
+    wavelength445: number;
+    wavelength480: number;
+    wavelength515: number;
+    wavelength555: number;
+    wavelength590: number;
+    wavelength630: number;
+    wavelength680: number;
+    wavelength750: number;
+    melanopic: number;
+    photopic: number;
+    light_sensor_z: null;
+    light_sensor_y: null;
+    light_sensor_x: null;
+    light_sensor_fd: null;
+};
+/**
+ * A real-time reading from an ActLumus Plus / gen2 (`type: 'actlumus2'`).
+ *
+ * Mirrors `LightSensorsActlumus2GraphicData.toMap()` in `condor_interactors`.
+ *
+ * ⚠️ The wavelengths are **not** the gen1 ones: 14 of them (395…800) against
+ * 10 (390…750), with no value in common. A chart that reads the gen1 list on a
+ * gen2 device finds `undefined` in every series and renders empty. Always
+ * discriminate on `type`.
+ *
+ * `light_sensor_z/_y/_x` are the CIE 1931 tristimulus values — Z in the blue,
+ * 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;
+    wavelength457: number;
+    wavelength488: number;
+    wavelength520: number;
+    wavelength551: number;
+    wavelength582: number;
+    wavelength613: number;
+    wavelength644: number;
+    wavelength675: number;
+    wavelength707: number;
+    wavelength738: number;
+    wavelength769: number;
+    wavelength800: number;
+    melanopic: number;
+    photopic: number;
+    light_sensor_z: number;
+    light_sensor_y: number;
+    light_sensor_x: number;
+    /** Flicker detect. Not part of the spectrum matrix. */
+    light_sensor_fd: number;
+};
+/**
+ * Real-time light-sensor stream. Shape:
+ * `{ serialNo, deviceId?, type, data }`.
+ *
+ * `deviceId` is the server id of the device and is **optional**: the app only
+ * sends it when more than one device on the account shares that `serialNo` (an
+ * ActLumus and an ActLumus Plus can). With a unique `serialNo` it is absent, so
+ * keep matching on `serialNo` in that case. Present from `nativeVersion` 0.17.0.
+ *
+ * A union discriminated by `type`, which is the `DeviceType.name` on the Dart
+ * side. `data` carries **both the derived spectrum and the raw channels it came
+ * from** — before 0.16.0 only the spectrum crossed the bridge, and a probe
+ * looking up a raw channel by name read `undefined`.
+ *
+ * This stream only flows while real-time is on for that device; it is off by
+ * default. See the `realTime` command.
+ */
+type DeviceLightSensorsPayload = {
+    serialNo: number;
+    deviceId?: number;
+    type: 'actlumus';
+    data: LightSensorsActlumus1Data;
+} | {
+    serialNo: number;
+    deviceId?: number;
+    type: 'actlumus2';
+    data: LightSensorsActlumus2Data;
+};
 /**
  * Parameters of the `sensorLog` command.
  *
@@ -139,8 +286,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;
@@ -165,6 +312,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;
@@ -197,6 +349,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;
@@ -251,6 +408,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
@@ -299,6 +462,28 @@ declare function twoDevices(now?: number): UserDevicePayload;
  */
 declare function sharedSerial(now?: number): UserDevicePayload;
 declare function systemStatus(overrides?: Partial<SystemStatusPayload>): SystemStatusPayload;
+/**
+ * One `deviceLightSensors` reading for a device, shaped by its generation
+ * (`modelId` `'actlumus_plus'` → `type: 'actlumus2'`). The harness emits one
+ * per second while `realTime` is on for that device. Values are plausible,
+ * not measured.
+ */
+declare function lightSensorsReading(device: Pick<DeviceConfigItem, 'serialNo' | 'deviceId' | 'modelId'>, epochMs?: number, withDeviceId?: boolean): DeviceLightSensorsPayload;
+/**
+ * What the simulated history contains. The default: 14 days up to now, one log
+ * per `logPeriodS`, worn all day except the dock hour 07:00–08:00 (local), no
+ * gaps.
+ */
+interface HistoryOptions {
+    /** Days of history before now. Default 14. */
+    days?: number;
+    /** Local hours (0–23) the device sits on its dock: `off_wrist` 0, no light. Default `[7]`. */
+    dockHours?: number[];
+    /** Local hours (0–23) with no log at all, every day (device off, or memory full). */
+    gapHours?: number[];
+    /** Local dates (`YYYY-MM-DD`) with no log at all. */
+    gapDates?: string[];
+}
 /**
  * Answers a `sensorLog` query with the backend's paging semantics:
  * - no range: the most recent `limit` logs; older pages through `endingBefore`;
@@ -311,6 +496,9 @@ declare function sensorLogPage(query: SensorLogQueryPayload, opts?: {
     now?: number;
     periodS?: number;
     deviceId?: number;
+    /** `body_part` of every log: the device's `deviceBodyPart`. Default `'wrist'`. */
+    bodyPart?: SensorLogItem['body_part'];
+    history?: HistoryOptions;
 }): SensorLogPayload;
 
 /**
@@ -547,7 +735,7 @@ interface MockAdapter {
  */
 
 /** Native schema version the harness reports by default. */
-declare const HARNESS_NATIVE_VERSION = "0.17.0";
+declare const HARNESS_NATIVE_VERSION = "0.18.0";
 interface Scenario {
     /** Shown in the harness toolbar. */
     description: string;
@@ -566,12 +754,30 @@ interface Scenario {
      */
     serviceStartMs: number;
     /**
-     * `userDevice` never answers. Today the app replies only when the device
-     * list loads, so an account with no linked device gets silence.
+     * The device lookup fails with this code (`NO_DEVICES`, `NETWORK`, …). From
+     * nativeVersion 0.18.0 the app answers `userDevice` with empty arrays and
+     * `error`; below it, the bundle gets no reply at all.
      */
-    userDeviceSilent: boolean;
+    userDeviceError?: string;
     /** When set, every `sensorLog` reply fails with this `error`. */
     sensorLogError?: string;
+    /** The Nth `sensorLog` request (1-based) fails once with `Connection failed`. */
+    sensorLogFailOnRequest?: number;
+    /** What the simulated history contains — see `HistoryOptions`. */
+    history?: HistoryOptions;
+    /**
+     * After this many ms the first device starts a BLE session (a
+     * `deviceConnection` with `isConnect: true`). Only `default` sets it; absent,
+     * no device connects by itself (a scenario file can pass `null`).
+     */
+    firstSessionAfterMs?: number | null;
+    /**
+     * The pipeline stage at which every simulated BLE session fails, e.g.
+     * `'get_data_log'`: `deviceNotification` then ends with `<stage>_error`
+     * instead of `pipeline_done_notification`. Without internet the sessions
+     * fail at `'send_data_log'` anyway.
+     */
+    sessionFailAt?: string;
     /** Log period of the devices, in seconds (programmable; default 60). */
     logPeriodS: number;
     systemStatus: SystemStatusPayload;
@@ -613,7 +819,12 @@ interface HarnessLogEntry {
     kind: 'sent' | 'reply' | 'dropped' | 'info';
     command?: string;
     key?: string;
+    /** One line for humans; arguments are shortened. */
     detail: string;
+    /** `sent`: the command's arguments, complete. */
+    args?: Record<string, unknown>;
+    /** `reply`: the payload the bundle received, complete. */
+    payload?: unknown;
 }
 interface DevHarnessOptions {
     /** The bundle's `index.html`, self-contained, as a string. */
@@ -639,6 +850,23 @@ interface DevHarness {
     readonly log: readonly HarnessLogEntry[];
     /** Emits a native event to the bundle, as the app would. */
     emit(key: string, payload: unknown): void;
+    /**
+     * Merges into the simulated `systemStatus` and emits it, as the app does on
+     * every change — e.g. `setStatus({ internet: false })`.
+     */
+    setStatus(patch: Partial<SystemStatusPayload>): void;
+    /**
+     * Starts or ends the BLE session of one device: emits `deviceConnection`
+     * (when the bundle subscribed to it with `add`) and starts or stops its
+     * `deviceLightSensors` stream if `realTime` is on.
+     */
+    setConnected(deviceId: number, connected: boolean): void;
+    /**
+     * How the app's confirmation dialog (`syncTime`, `deleteMemory`, `logout`)
+     * is answered: `'ask'` (an in-page dialog, the default), `'accept'` or
+     * `'decline'` — the last two for scripted tests.
+     */
+    setConfirmations(mode: 'ask' | 'accept' | 'decline'): void;
     /**
      * Presses the OS back button. Emits `navigationBack` only when the bundle
      * last reported `canGoBack: true`, as the app does; otherwise the app keeps
@@ -658,6 +886,8 @@ declare function createSimulatedNative(adapter: MockAdapter, scenario: Scenario,
 }): {
     readonly log: readonly HarnessLogEntry[];
     pressBack(): void;
+    setStatus(patch: Partial<SystemStatusPayload>): void;
+    setConnected(deviceId: number, connected: boolean): void;
     dispose(): void;
 };
 /**
@@ -680,4 +910,4 @@ declare const CANVAS_POLICY: ShellPolicy;
 /** CSP of the app shell, inherited by the client's `srcdoc` iframe. */
 declare const CANVAS_CSP: string;
 
-export { CANVAS_CSP, CANVAS_POLICY, DEFAULT_LOG_PERIOD_S, DEV_HARNESS_MARKER, type DevHarness, type DevHarnessOptions, HARNESS_NATIVE_VERSION, type HarnessLogEntry, SCENARIOS, type Scenario, type ScenarioName, createDevHarness, createSimulatedNative, formatLocalTimestamp, parseLocalTimestamp, resolveScenario, sensorLogPage, sharedSerial, systemStatus, twoDevices };
+export { CANVAS_CSP, CANVAS_POLICY, DEFAULT_LOG_PERIOD_S, DEV_HARNESS_MARKER, type DevHarness, type DevHarnessOptions, HARNESS_NATIVE_VERSION, type HarnessLogEntry, type HistoryOptions, SCENARIOS, type Scenario, type ScenarioName, createDevHarness, createSimulatedNative, formatLocalTimestamp, lightSensorsReading, parseLocalTimestamp, resolveScenario, sensorLogPage, sharedSerial, systemStatus, twoDevices };