@condorinst/mobile-bridge 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,350 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.8.0] — 2026-06-23
+
+First **public** release. Runtime is identical to `0.7.0`; this version
+packages the SDK for external White Label partners.
+
+### Changed
+
+- **Package renamed `condor-mobile-bridge` → `@condorinst/mobile-bridge`**
+  (scoped, published to the public npm registry). Update imports accordingly.
+  This is the breaking change behind the minor bump (pre-1.0 semver).
+- `README.md` and `CHANGELOG.md` rewritten in English; internal monorepo
+  references removed.
+- `license` field set to `SEE LICENSE IN LICENSE` (proprietary EULA, unchanged
+  in spirit). `publishConfig.access: public`, `prepublishOnly` (build + test).
+
+### Added
+
+- `docs/client-guide.md` — _"Build your White Label Home"_ onboarding guide.
+- `examples/minimal-home/` — runnable standalone client example.
+- `RELEASING.md` — dev-private → npm + public-repo release flow.
+
+## [0.7.0] — 2026-06-23
+
+### Added
+
+- **`sensorLog` key** in the `BRIDGE_KEYS` catalog (10th key) — read command
+  for the sensor log history. Since `subscribe`/`event` are validated against
+  `picklist(Object.values(BRIDGE_KEYS))`, the key must exist here for the shell
+  to relay the response to the sandboxed iframe (otherwise the message is
+  dropped at `safeParse`).
+- **`SensorLogPayload`** in `payloads.ts` + an entry in `KeyPayloads` →
+  typed `PayloadOf<'sensorLog'>`. Envelope with an echoed `requestId`
+  (correlation of concurrent keyset pagination) + `success`/`error`; on success
+  it carries `logs[]` (ASC, °C, naive UTC timestamps) + opaque cursors +
+  `hasMore`/`hasPrevious`; on error, an `error` with the contract code (e.g.
+  `CONFLICTING_CURSORS`).
+- `tests/messages.test.ts` — catalog updated (9→10), `sensorLog` wire string
+  and `PayloadOf<'sensorLog'>`. Total: **116/116**.
+
+### Notes
+
+- `sensorLog` is **read-only** for the client (it only receives the page/error);
+  sending the command uses the permissive `send` path (`command: v.string()`).
+
+## [0.6.0] — 2026-06-22
+
+### Added
+
+- **Build CLI `condor-mobile-bridge build`** (`bin`) — generates the
+  self-contained white-label `.zip` bundle from the client's `dist/`. Inlines
+  `<script src>` (escaping `</script>`) and `<link rel=stylesheet>`, resolves
+  CSS `url()` and local `<img>`/icons to `data:` URIs, and packs a single
+  `index.html` at the root. Prints `bundleSize` (bytes) and `bundleHash`
+  (`sha256-<hex>`, **deterministic** via fixed mtime) for backend manifest
+  registration; **warns** (does not block) above the 2 MB limit. Flags:
+  `-i/--html`, `-o/--out`, `--max-bytes`.
+- Production deps `node-html-parser` (a real HTML parser, not regex) and
+  `fflate` (100% JS zip, cross-platform — no system `zip` binary). Used **only**
+  by the CLI; they do not enter the iframe runtime bundle.
+- `tests/cli.test.ts` — 18 tests (inliner, recursive `url()`, escaping,
+  preserved external refs, root zip, deterministic hash). Total: **115/115**.
+
+### Notes
+
+- The post-build inliner assumes a **single-chunk** `dist` (one JS + one CSS +
+  assets). Builds with code-splitting / ES modules require a single-file config
+  on the client side (Vite: `vite-plugin-singlefile`; CRA: no split). See README.
+
+## [0.5.1] — 2026-06-09
+
+### Added
+
+- **`BridgeShell.bootstrapClientIframeWithHtml(clientHtml: string)`** — new
+  public method that accepts an HTML string directly instead of fetching it.
+  Required where `fetch` does not work (asset bundled at `file://` in Android
+  WebView, build-time inlined bundle via `esbuild.define`, etc.).
+- 4 new tests covering the new API + the legacy `bootstrapClientIframe` error
+  flow. Total: **98/98 green**.
+
+### Changed
+
+- **`OVERRIDE_PREFIX` fixed** — `value/writable: false` replaced by a **no-op
+  getter/setter** + `configurable: false`. Reason: modern ESM bundles run in
+  strict mode; any `window.X = …` on a non-writable property **throws**,
+  breaking the bootstrap of legacy modules (including this package's own
+  `Bridge`, which sets `window.CondorBridge = {emit}` as a module-load
+  side effect). With a getter/setter, assignment passes silently; the getter
+  always returns undefined; native bridges stay unreachable in the iframe
+  without breaking legitimate JS flows. Validated empirically via an offensive
+  pen test on a physical device.
+- `BridgeShell.bootstrapClientIframe(clientPath)` refactored to delegate
+  internally to `bootstrapClientIframeWithHtml` after the `fetch`. **No
+  observable behavior change**; the legacy API is preserved.
+- `OVERRIDE_PREFIX` extracted as a module constant (was inline in the method).
+
+### Notes
+
+- **No breaking change.** `bootstrapClientIframe(clientPath)` keeps the same
+  signature and behavior as v0.5.0 (modulo the override-prefix fix). A client
+  importing only `BridgeClient` or other APIs is unaffected.
+- The shell version (`shellVersion` in the handshake-ack) now reports `0.5.1`.
+
+## [0.5.0] — 2026-06-09
+
+### Added
+
+- **`BridgeClient`** — API for external client code running inside an
+  `<iframe sandbox="allow-scripts">`. Surface identical to the legacy `Bridge`
+  (`on`/`send`/`openSettings`/`handshake`); internally every call becomes a
+  `window.parent.postMessage`. The client imports `BridgeClient` instead of
+  `Bridge` and never notices it is sandboxed.
+- **`BridgeShell`** — API for the Condor-controlled shell that wraps the
+  iframe. Responsibilities: iframe bootstrap with the override prefix
+  (`bootstrapClientIframe`), iframe attestation (`verifySandbox`),
+  `postMessage` ↔ legacy `Bridge` routing with a default-deny policy, and
+  gating of sensitive commands via the `onConfirmationRequest` callback.
+- **Valibot schemas** (`ClientToShellMessage` / `ShellToClientMessage`) —
+  strict validation of every `postMessage`. Malformed messages are dropped
+  silently. Types: `subscribe`, `unsubscribe`, `send`, `handshake`, `jsError`,
+  `sandbox-verify-response` (client→shell) + `event`, `handshake-ack`, `nack`,
+  `verify-sandbox` (shell→client).
+- **`ShellPolicy`** — declarative interface for gating: `readOnlyKeys`,
+  `allowedCommands`, `requiresConfirmation`, `deniedCommands`. The policy is
+  data provided by the shell (not embedded in the package).
+- 33 new tests (`tests/bridge-client.test.ts` 14 + `tests/bridge-shell.test.ts` 19).
+  Total: **94/94 green** (61 from v0.4.0 + 33 new).
+- New dependency: `valibot` (~3 KB minified, tree-shakeable).
+
+### Layered defense against `window.flutter_inappwebview` propagation to the iframe
+
+Implemented in this release:
+
+- **Layer 1** — `BridgeShell.bootstrapClientIframe(clientPath)`: fetches the
+  client HTML, prepends an override script that `delete`s
+  `window.flutter_inappwebview` and `window.CondorBridge` +
+  `Object.defineProperty(..., configurable: false)`, and sets it as `srcdoc`.
+  The override runs at parse-time, before any client script.
+- **Layer 2** — `BridgeShell.verifySandbox()`: a `verify-sandbox` →
+  `sandbox-verify-response` `postMessage` round-trip. `BridgeClient` answers
+  authoritatively about the state of the bridges in the iframe. The shell
+  aborts the boot if it receives `ok: false`.
+
+Layers 3 (native-validated shell nonce) and 4 (dual-WebView fallback) live on
+the native Flutter side.
+
+### Notes
+
+- The legacy `Bridge` is unchanged — v0.4.0 clients importing `Bridge` keep
+  working identically. Migrating to the sandbox model is optional (but
+  recommended for an external-client audience).
+- `BridgeClient` does **not** expose `installDevPanel`, `mockEmit`, `isMock`,
+  `getMockState` — those APIs are the shell's responsibility.
+- Bundle: `dist/index.js` 29 KB (was 19 KB in v0.4.0; +10 KB for Valibot +
+  BridgeClient + BridgeShell + schemas).
+- No runtime or build-time breaking changes for legacy `Bridge` users.
+
+## [0.4.0] — 2026-06-04
+
+### Added
+
+- **Per-key strict types** in `PayloadOf<K>`. `Bridge.on<K>` now infers the
+  typed payload for a cataloged key. Unknown keys fall back to the permissive
+  `Record<string, unknown>`.
+- **8 per-key DTOs**, derived authoritatively from the native source (services
+  + entities):
+  - `PingPongPayload = { data: 'ping' | 'pong' }`
+  - `UserDevicePayload = { lastUpdate, devicesConfig[], devicesTelemetry[], devicesUserConfig[] }`
+  - `DeviceLightSensorsPayload = { serialNo, type, data: Record<string, unknown> }`
+  - `SyncTimeAckPayload = { serialNo, success }`
+  - `RealTimeAckPayload = { serialNo, success, value }`
+  - `DeleteMemoryAckPayload = { serialNo, success }`
+  - `DeviceNotificationPayload = { serialNo, isConnect, message: string | null, messageCode: string | null, isError }`
+  - `DeviceConnectionPayload = { serialNo, isConnect }`
+- **`KeyPayloads`** mapped type discriminated by key. `PayloadOf<K>` is now
+  `K extends keyof KeyPayloads ? KeyPayloads[K] : Record<string, unknown>`.
+- 9 new tests in `tests/messages.test.ts` using `expectTypeOf` (Vitest) to
+  validate compile-time inference + runtime sanity per key. Total: **61/61
+  green** (52 from v0.3.0 + 9 new).
+
+### Notes
+
+- `dfu` keeps the permissive fallback — reserved.
+- `Bridge.send(type, payload?)` stays permissive in v0.4.0 (JS→BG commands are
+  heterogeneous: `realTime` `{serialNo, value}`, `userDevice` `{getFromServer}`,
+  `deviceConnection` `{type, serialNo}`, etc.). Typing a `send` overload is left
+  for a future release.
+- **Runtime-compatible**, but technically a build-time break for v0.3.0 clients
+  that relied on an `unknown` payload in `Bridge.on`. A client that needs the
+  permissive shape can declare `(payload: Record<string, unknown>) => ...`
+  explicitly.
+- `dist/` grew from ~17 KB to ~17.7 KB (minimal type overhead).
+
+### Migration from v0.3.0 → v0.4.0 (client)
+
+A client that had:
+```typescript
+Bridge.on(BRIDGE_KEYS.realTime, (payload) => {
+  // payload: Record<string, unknown> in v0.3.0
+});
+```
+
+Still compiles. The gain: `payload` is now `RealTimeAckPayload` — accessing
+`payload.serialNo`/`payload.success`/`payload.value` is type-safe without a cast.
+
+## [0.3.0] — 2026-06-04
+
+### Added
+
+- **Auto-respond toggle** in the dev panel — an optional checkbox that, when
+  on, programmatically fires `mockEmit` in response to each `Bridge.send`
+  (closed loop in mock mode without manual intervention). Conditional render:
+  appears only when the client provides the policy in
+  `DevPanelOptions.onSendForAutoRespond`.
+- **`DevPanelOptions.onSendForAutoRespond`** — synchronous callback
+  `(msg: MockMessage) => { key, payload } | null`. The client provides the
+  policy (send → emit mapping); the package provides the mechanism.
+- **`DevPanelOptions.startAutoRespondEnabled`** — initial toggle state.
+  Default: `false` (manual stays default; v0.2.0 semantics preserved). The
+  client can override to `true` to auto-loop from boot.
+- **`DevPanelOptions.autoRespondDelayMs`** — delay between the `send` and the
+  auto-response `mockEmit`. Default: `50` (approximates real native-bridge IPC
+  latency).
+- **`AutoRespondResponse`** type exported: `{ key: string; payload: unknown }`.
+- **`MockAdapter.onCallHandler(listener)`** — registers a listener invoked on
+  each `callHandler`. Returns an unsubscribe function. Errors in listeners are
+  caught + logged (they do not affect other listeners or the bridge pipeline).
+  Useful for runtime-inspection integrations (client tests, dev tooling).
+
+### Behavior
+
+- The "Auto-respond" toggle persists in memory for the panel's lifetime.
+  Re-installing the panel resets it to the declared `startAutoRespondEnabled`.
+- The listener registered by the dev panel is cleaned up automatically on
+  `uninstall()` (no leak between re-installs).
+- Errors in the client policy are caught via try/catch + `console.error` —
+  they do not destabilize `callHandler`.
+
+### Tests
+
+- 52/52 green (40 from v0.2.0 + 12 new: 4 `onCallHandler` + 8 auto-respond).
+
+### Notes
+
+- The Layer 1 API (`handshake`, `on`, `send`, `openSettings`) and the initial
+  Layer 2 API (`isMock`, `mockEmit`, `getMockState`, `installDevPanel`) are
+  **unchanged**. Auto-respond is purely opt-in: a client without a policy sees
+  no change in the panel.
+- `dist/` grew from ~14 KB (v0.2.0) to ~17 KB (v0.3.0) — acceptable overhead.
+- Minor bump (`0.2.0 → 0.3.0`): backward-compatible feature, no breaking
+  changes in API or behavior.
+
+## [0.2.0] — 2026-06-03
+
+### Added
+
+- **Mock mode** — when `window.flutter_inappwebview` is not detected (regular
+  browser, Storybook, Vite dev server), the adapter activates automatically.
+  Unblocks client development in the browser without building the APK.
+- **`Bridge.isMock`** (readonly getter) — `true` when the mock adapter is active.
+- **`Bridge.mockEmit(key, payload?)`** — dispatches `window.CondorBridge.emit`
+  programmatically to simulate native events. Throws outside mock mode.
+- **`Bridge.getMockState()`** — returns `{ isMock, messages, subscriberKeys }`.
+  A snapshot of the mock adapter state for asserts in client tests. Throws
+  outside mock mode.
+- **`Bridge.installDevPanel(options?)`** — injects a floating HTML panel into
+  `document.body` to inspect the bridge in the browser:
+  - Header with a "MOCK" badge, sent counter, minimize/maximize button.
+  - Sent log — last N (default 20) messages (timestamp, type, payload).
+  - Trigger emit — dropdown of `BRIDGE_KEYS` + `handshake-ack` + JSON payload
+    textarea + "Emit" button + "Clear sent" button.
+  - Auto-refresh via `setInterval(500ms)`.
+  - Idempotent — re-install replaces the previous one.
+  - Inline styles + `condor-mock-panel-*` classes (reduces CSS conflicts).
+  - Options: `position`/`maxMessages`/`theme`/`startCollapsed`.
+
+### Behavior
+
+- **Handshake in mock mode is EXPLICIT.** `Bridge.handshake()` does NOT
+  auto-resolve in mock. The client/test must call
+  `Bridge.mockEmit('handshake-ack', {nativeVersion, accepted})` to unblock the
+  Promise. A design decision to force intentional tests.
+- **`Bridge.send` in mock** records `{handlerName, payload, timestamp}` in a
+  FIFO buffer (cap 100) + `console.debug`. The buffer is accessible via
+  `getMockState().messages`.
+
+### Refactor (non-breaking)
+
+- `src/internal/native.ts` refactored to an adapter pattern. `NativeAdapter` is
+  a `RealAdapter | MockAdapter` union discriminated by `readonly isMock`.
+  `getActiveAdapter()` caches detection; `__resetAdapterForTests()` resets it.
+
+### Tests
+
+- 40/40 green (21 from v0.1.0 + 19 new):
+  - `tests/mock.test.ts`: 12 tests (isMock, send, mockEmit, explicit handshake,
+    getMockState, buffer cap).
+  - `tests/dev-panel.test.ts`: 7 tests (DOM injection, interaction, idempotency).
+
+### Notes
+
+- The Layer 1 API (`handshake`, `on`, `send`, `openSettings`) is **unchanged**.
+- The `v0.1.0 → v0.2.0` migration is **automatic** — nothing to adjust in client
+  code; mock mode only activates when running outside the WebView.
+- `dist/` grew from ~3 KB to ~14 KB (ESM) because of the inline dev panel.
+  Considered acceptable for the feature.
+
+## [0.1.0] — 2026-06-03
+
+### Added
+
+- **Layer 1 of the bridge schema/runtime:**
+  - `Bridge.handshake({clientVersion})` — versioned handshake with native.
+    Returns `Promise<HandshakeAck>`. Rejects parallel calls.
+  - `Bridge.on(key, cb)` — typed subscribe to observable keys. Returns
+    `unsubscribe`. An error in one subscriber does not affect others.
+  - `Bridge.send(type, payload?)` — generic command to native via
+    `window.flutter_inappwebview.callHandler`.
+  - `Bridge.openSettings()` — sugar over `send('openSettings')`.
+- **`BRIDGE_KEYS` catalog** — 9 keys in camelCase JS API mirroring the native
+  foreground com keys: `pingPong`, `userDevice`, `deviceLightSensors`,
+  `syncTime`, `realTime`, `deleteMemory`, `deviceNotification`,
+  `deviceConnection`, `dfu`.
+- **Types:** `BridgeKey`, `BridgeIncomingMessage`, `BridgeOutgoingEvent`,
+  `HandshakeAck`, `HandshakeOptions`, `PayloadOf<K>` (permissive in the MVP).
+- **Automatic bootstrap** of `window.CondorBridge.emit` at module load.
+- **Native host detection** — `flutter_inappwebview` cross-platform (Android +
+  iOS). Clear error outside a Flutter WebView (mock mode in v0.2.0).
+- **Tooling:** TypeScript strict + Biome (lint+format) + tsup (dual ESM+CJS
+  build + types) + Vitest (jsdom env) + CI.
+- **21 tests** covering handshake, on/emit, send, openSettings, missing host,
+  and the key catalog.
+
+### Notes
+
+- Payloads use `Record<string, unknown>` in the MVP. Per-key strict types
+  landed once the native shapes crystallized.
+- Only `pingPong` was actually emitted by native in the initial release. The
+  other 8 keys were reserved as a forward-looking contract.
+- Protocol version (`PROTOCOL_VERSION`) = `'0.1.0'`, sent in the `version` of
+  each `BridgeIncomingMessage`. Native accepts any `clientVersion` in the MVP —
+  real semver validation lands once there are 2+ versions in the field.

package/LICENSE

@@ -0,0 +1,14 @@
+Proprietary — Condor Instruments
+
+Copyright (c) 2026 Condor Instruments. All rights reserved.
+
+This package is the canonical TypeScript SDK of the JS↔Native bridge of the
+Condor white-label mobile app (`sleep_whitelabel`). It is distributed under a
+proprietary license to authorized partners of Condor Instruments.
+
+Unauthorized copying, redistribution, modification, reverse engineering, or
+use of this package or any portion of it, by any medium, is strictly
+prohibited without prior written consent from Condor Instruments.
+
+For licensing inquiries, contact Condor Instruments through the official
+support channels.