@condorinst/mobile-bridge 0.17.0 → 0.19.0

package/docs/agent-guide.md

@@ -0,0 +1,209 @@
+# Agent guide — building a Canvas client
+
+A working procedure for an AI agent (or a developer) building the client bundle
+that renders as the Home of a Condor Canvas app.
+
+Read `AGENTS.md` first — it is the contract in one screen. This document is the
+procedure: what to do, in what order, and what to check at each stage.
+
+## What you are building
+
+One `.zip` containing one self-contained `index.html`. Condor's app downloads
+it, verifies its SHA-256, and renders it inside a sandboxed iframe as the Home
+screen. Login, settings, Bluetooth and background collection are the app's job.
+Yours is what the person sees when the app opens.
+
+You are not building a website. You have no storage, no network, and no origin.
+Everything you display comes through the bridge, and everything you hold lives
+in memory until the next reload.
+
+## Stage 0 — set up so you can see what you are doing
+
+```bash
+mkdir my-home && cd my-home
+npm init -y
+npm install @condorinst/mobile-bridge
+npm install -D esbuild typescript
+```
+
+Copy `examples/minimal-home/` from the package as your starting point — it is a
+complete, working client in about 160 lines, with a build script that produces
+a single-file bundle:
+
+```bash
+cp -r node_modules/@condorinst/mobile-bridge/examples/minimal-home/. .
+npm install
+```
+
+Pin the SDK to the minor you are building against. Below `1.0.0`, a minor can
+change the contract — `^0.19.0` gives you patches only, which is what you want.
+
+**Open `dist/index.html` in a browser.** With no native host detected, the SDK
+activates mock mode and installs a dev panel in the corner that lets you emit
+native events by hand. This is your entire development loop; you do not need
+the app to build a Home.
+
+Remember that in mock mode `nativeVersion` is `null`. That is not a bug in the
+mock — it is the same value you get from a real app whose shell is older than
+0.6.0, so your code has to handle it either way.
+
+## Stage 1 — render before you connect
+
+Write the screen so it paints correctly with **no data at all**: empty roster,
+unknown status, default language. Then fill it as events arrive.
+
+This is not a nicety. Events are emitted on attach, before your bundle exists,
+and again after the handshake — so there is always a window where you have
+nothing. A Home whose first paint depends on an event shows a blank screen on
+every cold start.
+
+## Stage 2 — handshake, and learn what this device can do
+
+```ts
+import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
+
+const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
+
+const native = ack.nativeVersion;            // string | null
+const has = (min: string) => native !== null && cmp(native, min) >= 0;
+
+const canReadRawChannels = has('0.16.0');
+const canQueryTimeRange  = has('0.15.0');
+const hasLanguageKey     = has('0.14.0');
+```
+
+Write `cmp` as a plain numeric comparison of the three segments. Do not compare
+version strings lexically — `'0.9.0' > '0.16.0'` is `true` as strings and false
+as versions.
+
+**Do not branch on `ack.accepted`.** It is always `true`; the native side never
+refuses a handshake. Anything you gate on it is ungated.
+
+## Stage 3 — subscribe, then ask
+
+Subscribe before sending the command that triggers the reply. The reply can
+arrive before your next line runs.
+
+```ts
+BridgeClient.on(BRIDGE_KEYS.userDevice, (p) => { setDevices(p); render(); });
+BridgeClient.on(BRIDGE_KEYS.systemStatus, (s) => { setStatus(s); render(); });
+BridgeClient.on(BRIDGE_KEYS.deviceConnection, (c) => { setConnected(c); render(); });
+
+BridgeClient.send('userDevice', { getFromServer: false });
+```
+
+`on` returns an unsubscribe function. If your UI has views that mount and
+unmount, call it — otherwise you accumulate handlers that all re-render.
+
+## Stage 4 — handle the environment honestly
+
+`systemStatus` tells you why things are not working. Surface it; do not swallow
+it.
+
+```ts
+if (status.missingEssentialPermissions.length > 0) {
+  // Background collection is OFF. This is blocking — say so.
+  renderBlockingCard(status.missingEssentialPermissions, (name) =>
+    BridgeClient.requestPermission(name));
+} else if (!status.bluetooth) {
+  renderNotice('Bluetooth is off — devices cannot be reached.');
+}
+```
+
+There is no permission-result event. After the person answers the OS prompt,
+the native side re-emits `systemStatus`; your card disappears because the array
+emptied. If you wait for a dedicated ack, you wait forever.
+
+## Stage 5 — real-time, if you need it
+
+Real-time is **off by default**, per device. Turn it on, wait for the ack, and
+only then expect the stream.
+
+```ts
+BridgeClient.on(BRIDGE_KEYS.realTime, (ack) => setRealTime(ack.serialNo, ack.value));
+BridgeClient.on(BRIDGE_KEYS.deviceLightSensors, (p) => {
+  if (p.type === 'actlumus2') { /* 14 channels */ } else { /* 10 channels */ }
+});
+
+BridgeClient.send('realTime', { serialNo, value: true });
+```
+
+`serialNo` is a **number**. A string is dropped in silence.
+
+In a raw channel, `null` means the channel does not exist on that hardware
+generation. It does not mean zero — `0.0` is a valid reading. Coercing `null`
+to `0` invents data, and has previously led to a confident, wrong conclusion
+about a device.
+
+## Stage 6 — history, if you need it
+
+```ts
+const page = await BridgeClient.fetchSensorLog({
+  requestId: crypto.randomUUID(),
+  serialNo,
+  limit: 200,
+});
+if (!page.success) return showError(page.error);   // resolves, does not reject
+renderLogs(page.logs ?? []);
+```
+
+Timestamps are **device-local**. Build ranges with local `Date` getters, never
+`toISOString()` — converting to UTC shifts every series by the timezone offset
+and produces data that looks entirely plausible.
+
+Paginate with the cursors exactly as received. They are opaque.
+
+## Stage 7 — back button
+
+```ts
+BridgeClient.onBack(() => goBackOnePage());
+// call this on every internal navigation, not once at startup
+BridgeClient.reportNavigation(hasInternalHistory);
+```
+
+If you never report `true`, the OS back button stays with the app — which is
+the correct behaviour for a single-screen Home.
+
+## Stage 8 — build and validate
+
+```bash
+npm run build     # your bundler → dist/index.html, single chunk
+npx condor-mobile-bridge build    -i dist/index.html -o dist/bundle.zip
+npx condor-mobile-bridge validate -i dist/bundle.zip --strict
+```
+
+`validate` applies the gates the app applies plus a lint for APIs the sandbox
+blocks. A non-zero exit is a build failure. Errors mean the app would reject
+the bundle outright; warnings mean it installs and then misbehaves on the
+device, which is worse to debug.
+
+Validation is textual, so it cannot see through minification and it cannot know
+whether you checked `nativeVersion` before using a capability. A clean run is
+necessary, not sufficient.
+
+## Stage 9 — before you call it done
+
+- [ ] `validate --strict` exits 0.
+- [ ] First paint works with no events received.
+- [ ] Every capability past the baseline is guarded by a `nativeVersion` check,
+      and the `null` branch renders something sensible.
+- [ ] No spinner can hang forever — the three confirmable commands
+      (`syncTime`, `deleteMemory`, `logout`) may never ack, because the person
+      can decline.
+- [ ] No `localStorage`, no `fetch`, no `eval`. Not even behind a `try`.
+- [ ] `serialNo` is a number everywhere.
+- [ ] Errors are reported through `BridgeClient.send('jsError', …)`, the only
+      channel out.
+- [ ] Tested in the browser mock with `nativeVersion === null`.
+
+## Delivery
+
+Hand Condor the `.zip` along with its size and `sha256-<hex>` hash, both printed
+by the `build` command. The app verifies the hash against the manifest and
+rejects any mismatch. `docs/pilot-onboarding.md` has the full checklist.
+
+## When something does not work
+
+`docs/troubleshooting.md`, which starts from the symptom. The most common one
+is that a command did nothing and said nothing — there are six distinct causes
+for that, and they are enumerated there.

package/docs/bridge-contract.md

@@ -0,0 +1,249 @@
+# Bridge contract
+
+The normative reference for everything the client can observe and everything it
+can ask for. Payload *shapes* are canonical in `dist/index.d.ts` — your editor
+shows them on hover. This document states what a type declaration cannot: what
+is reachable, what needs human consent, what fails in silence, and which native
+version carries which capability.
+
+A machine-readable form of this document lives at
+`contract/bridge-contract.json`, importable as `@condorinst/mobile-bridge/contract`.
+
+## Topology
+
+```
+your bundle  (iframe, sandbox="allow-scripts", origin null)
+     |  window.postMessage, schema-validated both ways
+Condor shell (top-level document, opaque origin)
+     |  native channel, nonce-stamped
+native app   (Flutter)
+```
+
+You never talk to the native side directly — the shell deletes the native
+globals before your bundle runs. Use `BridgeClient`; it speaks the shell
+protocol for you.
+
+## Versions and capability detection
+
+Four numbers coexist. Only one tells you what the device can do.
+
+| Number | Current | What it means |
+| --- | --- | --- |
+| `nativeVersion` | `0.16.0` | **The capability signal.** The bridge schema the app on this device implements. |
+| `shellVersion` | `0.6.0` | The Condor shell wrapping your iframe. |
+| client protocol | `0.5.0` | The postMessage protocol `BridgeClient` speaks. |
+| package | `0.19.0` | The npm version you compiled against. |
+
+```ts
+const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
+// { shellVersion: string, nativeVersion: string | null, accepted: boolean }
+```
+
+Two traps:
+
+**`accepted` is always `true`.** There is no version negotiation and the native
+side never refuses. Branching on it is branching on a constant.
+
+**`nativeVersion` can be `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 only the baseline" and keep a working default. Your browser
+development environment always hits this path, so it is not a rare case — it is
+the one you see most.
+
+### Capability matrix
+
+| Capability | Requires |
+| --- | --- |
+| Baseline: devices, real-time, acks, `systemStatus`, `sensorLog` | any |
+| `language` key and the `language` pull command | `nativeVersion` ≥ 0.14.0 |
+| `sensorLog` accepts `startTime` / `endTime` | `nativeVersion` ≥ 0.15.0 |
+| `deviceLightSensors` carries raw `light_sensor_*` channels, and the `actlumus2` variant | `nativeVersion` ≥ 0.16.0 |
+| `nativeVersion` reaches the client at all | `shellVersion` ≥ 0.6.0 |
+
+`CHANGELOG.md` is the precise record of when each of these landed.
+
+## Observable keys
+
+Thirteen keys exist; **twelve are reachable** by a sandboxed client. Subscribe
+with `BridgeClient.on(key, cb)`, which returns an unsubscribe function.
+
+| Key | Payload type | Emitted when |
+| --- | --- | --- |
+| `pingPong` | `PingPongPayload` | reply to the `ping` command |
+| `userDevice` | `UserDevicePayload` | reply to `userDevice`, and on roster changes |
+| `deviceLightSensors` | `DeviceLightSensorsPayload` | real-time stream, only while `realTime` is on for that device |
+| `deviceConnection` | `DeviceConnectionPayload` | a device connects or disconnects |
+| `deviceNotification` | `DeviceNotificationPayload` | device-level notice, including errors |
+| `realTime` | `RealTimeAckPayload` | ack of `realTime` |
+| `syncTime` | `SyncTimeAckPayload` | ack of `syncTime` |
+| `deleteMemory` | `DeleteMemoryAckPayload` | ack of `deleteMemory` |
+| `sensorLog` | `SensorLogPayload` | reply to `sensorLog`; correlate by `requestId` |
+| `systemStatus` | `SystemStatusPayload` | on attach, again right after handshake, and on every change |
+| `language` | `LanguagePayload` | same cadence as `systemStatus`; needs native ≥ 0.14.0 |
+| `navigationBack` | `NavigationBackPayload` (empty) | OS back pressed while you had reported `canGoBack: true` |
+| `dfu` | — | **not reachable.** Firmware traffic. Subscribing is answered with `nack: not-read-only`. |
+
+### Emission cadence you must design around
+
+`systemStatus` and `language` are emitted **on attach, before your bundle
+exists**, then again right after the handshake. The first emission is lost to
+you; the second is the one you receive. This is why `language` also exists as a
+pull command — a client that mounts late can ask.
+
+Render a skeleton synchronously and fill it as events arrive. Do not make first
+paint depend on any event.
+
+### `deviceLightSensors` is a discriminated union
+
+```ts
+if (payload.type === 'actlumus2') {
+  // 14 wavelength channels, 395–800 nm, plus raw light_sensor_f1..f8 / clear / nir
+} else {
+  // 'actlumus': 10 channels, 390–750 nm
+}
+```
+
+A `null` in a raw channel means **that channel does not exist on this hardware
+generation** — never "the reading was zero". `0.0` is a valid reading. Do not
+collapse `null` to `0`: doing so fabricates data, and it has produced wrong
+conclusions before.
+
+### `systemStatus` carries the permission state
+
+```ts
+{
+  bluetooth: boolean; internet: boolean; permission: boolean; hasDevices: boolean;
+  missingEssentialPermissions: string[];  // e.g. ["bluetoothScan", "bluetoothConnect"]
+  missingOptionalPermissions: string[];   // e.g. ["notification", "backgroundLocation"]
+  deviceSyncError: Record<number, string>; // serialNo → message, already localized
+}
+```
+
+`missingEssentialPermissions` being non-empty means background collection is
+off. Render a blocking card; wire its button to
+`BridgeClient.requestPermission(name)` with a name taken from that array.
+
+## Commands
+
+`BridgeClient.send(command, args)` is **fire-and-forget**: no return value, no
+exception, no delivery confirmation. Replies arrive on the key in the last
+column.
+
+| Command | Arguments | Confirmation | Replies on |
+| --- | --- | --- | --- |
+| `ping` | — | no | `pingPong` |
+| `userDevice` | `{ getFromServer?: boolean }` | no | `userDevice` |
+| `realTime` | `{ serialNo: number, value: boolean }` | no | `realTime` |
+| `deviceConnection` | `{ type: 'add' \| 'remove', serialNo: number }` | no | `deviceConnection` |
+| `sensorLog` | see below | no | `sensorLog` |
+| `openSettings` | — | no | — |
+| `requestPermission` | `{ permission: string }` | no | — (re-emits `systemStatus`) |
+| `setStatusBarColor` | `{ color: '#RRGGBB' }` | no | — |
+| `navigationState` | `{ canGoBack: boolean }` | no | — |
+| `language` | — | no | `language` |
+| `jsError` | `{ message, stack?, source?, lineno?, colno? }` | no | — |
+| `syncTime` | `{ serialNo: number }` | **yes** | `syncTime` |
+| `deleteMemory` | `{ serialNo: number }` | **yes** | `deleteMemory` |
+| `logout` | — | **yes** | — |
+| `dfu` | — | denied | — |
+
+`serialNo` is an integer. Passing a string makes the native side drop the
+message in silence.
+
+### Commands that need human confirmation
+
+`syncTime`, `deleteMemory` and `logout` open a modal owned by the Condor shell.
+If the person declines, the shell answers `nack` with reason `user-rejected`,
+which reaches you only as a `console.warn`. **The ack simply never arrives.**
+
+Design for that: show an optimistic state only if you can undo it, and put a
+timeout on any spinner.
+
+### Typed helpers
+
+Prefer these over raw `send` — they add correlation, timeouts and types:
+
+```ts
+BridgeClient.fetchSensorLog(query, { timeoutMs })  // correlates requestId, 10 s default
+BridgeClient.requestPermission(name)
+BridgeClient.reportNavigation(canGoBack)
+BridgeClient.onBack(cb)
+BridgeClient.openSettings()
+```
+
+### `sensorLog` in detail
+
+```ts
+const page = await BridgeClient.fetchSensorLog({
+  requestId: crypto.randomUUID(),
+  serialNo,
+  bodyPart: 'wrist',        // or 'necklace'; omit for no filter
+  limit: 200,               // 1..1000, backend default 10
+  startTime: '2026-09-01 00:00:00',  // native >= 0.15.0
+  endTime:   '2026-09-02 00:00:00',
+});
+```
+
+It **resolves** with `{ success: false, error }` on failure and only **rejects**
+on timeout. Check `success` before reading `logs`.
+
+Two things that have caused real bugs:
+
+**Timestamps are device-local, not UTC.** `log_time` passes through from the
+device RTC. Build your range with local `Date` getters — `getFullYear()`,
+`getHours()` — and **never** with `toISOString()`. Converting shifts every
+series by the timezone offset, producing plausible data and no error at all.
+
+**Cursors are opaque.** `startingAfter` and `endingBefore` are mutually
+exclusive; echo back exactly what you received and never construct one.
+
+With a time range, `hasMore` and `hasPrevious` are computed *within* the
+period, so `hasMore: false` means "this period is complete", not "no more data
+exists".
+
+## Error shapes
+
+There are three, and none of them is a thrown exception.
+
+**1. `nack`** — shell to client, reasons `not-read-only`, `denied`,
+`no-confirmation-handler`, `confirmation-error`, `user-rejected`, `not-allowed`.
+Visible only as `console.warn`.
+
+**2. `sensorLog` failure** — `{ requestId, success: false, error }`. The codes
+are `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`.
+`error` is a **diagnostic code, never user-facing text** — map it to your own
+copy.
+
+**3. Silence** — nothing reaches JavaScript. This is the dominant failure mode.
+The six paths that produce it are enumerated in `docs/troubleshooting.md`.
+
+## The back button
+
+The app owns the OS back button and will delegate it to you only if you ask.
+
+```ts
+BridgeClient.reportNavigation(true);          // "I have internal history"
+BridgeClient.onBack(() => history.back());    // go back exactly one page
+```
+
+Report `false` when you are at your root, and the app handles back itself.
+Report state on every internal navigation, not once at startup.
+
+## Status bar
+
+Two ways, in precedence order:
+
+```html
+<meta name="theme-color" content="#0A2540">   <!-- static, read from the bundle -->
+```
+```ts
+BridgeClient.send('setStatusBarColor', { color: '#0A2540' });  // runtime, wins
+```
+
+## Session
+
+When the session token dies, the app shows its own native banner above your
+bundle and keeps rendering you. **You receive no event for this** — there is no
+session key. Do not try to detect it; the app handles re-authentication.