@jetezra/bridge 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.0.2
+
+- `init({ debug: true })` / `setDebug(true)` — log outbound and inbound bridge messages
+- `init({ allowedOrigins })` — ignore DOM `message` events from unexpected origins
+- `mockHost(options)` — fake host for browser demos and local development
+- `requestCapability(key, options?)` now returns a Promise (awaits `chooga.capabilityResult`)
+- `navigate` accepts `onResult` like other async helpers
+- Extensible `getState()` via `chooga.params` (merge / replace / clear)
+- Preserve extra fields on session, theme, and capability messages
+- Unit tests for params, reject/`no_host`, mock host, debug logs, capability, timeout
+
+## 0.0.1
+
+- Initial public release of `@jetezra/bridge` (npm + CDN)

package/README.md

@@ -1,119 +1,407 @@
 # `@jetezra/bridge`
 
-Client SDK for Chooga mini-apps running inside a host WebView (Awash Superapp and other Chooga hosts).
-
-Works in a normal browser too (`hostConnected === false`) so demos still render without a native shell.
+Client SDK for Chooga mini-apps running inside a host WebView. It also runs in a normal browser for demos: `hostConnected` stays `false`, and any call that expects a host reply rejects with `{ ok: false, reason: 'no_host' }`.
 
 | Doc | Purpose |
 |-----|---------|
-| This README | API + install |
-| [`RELEASE.md`](./RELEASE.md) | **npm + CDN CI release** (Trusted Publishing, tags, CDN URLs) |
-| Host bridge | Awash `Application/Screens/Superapp/bridge/README.md` |
+| This README | API + usage |
+| [`RELEASE.md`](./RELEASE.md) | npm + CDN release |
+
+Released version: **`0.0.2`**.
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for what changed.
+
+---
 
 ## Install
 
+Install from npm:
+
 ```bash
 npm install @jetezra/bridge
-# or yarn add @jetezra/bridge
 ```
 
-### CDN (prefer a pinned version)
+```js
+import ChoogaBridge from '@jetezra/bridge';
+```
+
+Or load the CDN build and use the global `ChoogaBridge`. Pin a version in production. unpkg is usually ready first after a publish; jsDelivr mirrors the same npm package.
 
 ```html
-<!-- jsDelivr -->
-<script src="https://cdn.jsdelivr.net/npm/@jetezra/bridge@1.2.0/dist/chooga-bridge.min.js"></script>
-<!-- unpkg -->
-<script src="https://unpkg.com/@jetezra/bridge@1.2.0/dist/chooga-bridge.min.js"></script>
+<script src="https://unpkg.com/@jetezra/bridge@0.0.2/dist/chooga-bridge.min.js"></script>
+<!-- or https://cdn.jsdelivr.net/npm/@jetezra/bridge@0.0.2/dist/chooga-bridge.min.js -->
 <script>
-  ChoogaBridge.init();
+  ChoogaBridge.init({ debug: true });
 </script>
 ```
 
-Latest (not for production):  
-`https://cdn.jsdelivr.net/npm/@jetezra/bridge/dist/chooga-bridge.min.js`
+Latest (not for production): `https://unpkg.com/@jetezra/bridge/dist/chooga-bridge.min.js`
 
-Build locally: `npm run build && npm test` → `dist/chooga-bridge.{mjs,cjs,min.js,d.ts}`.
+---
 
 ## Quick start
 
+Call `init()` once when your mini-app boots. By default that also posts `chooga.ready` so the host can inject session, user, theme, and host info. Subscribe to state and events, then use the host APIs.
+
 ```js
 import ChoogaBridge from '@jetezra/bridge';
 
-ChoogaBridge.init(); // posts chooga.ready (disable with { autoReady: false })
+ChoogaBridge.init({ debug: true }); // logs every → host / ← host message
+
+ChoogaBridge.subscribe(state => {
+  console.log(state.session, state.user, state.theme);
+});
 
 ChoogaBridge.on('theme.changed', theme => {
-  // host push
+  console.log('theme updated', theme);
 });
 
-const unsub = ChoogaBridge.subscribe(state => {
-  // session, user, theme, safeArea, hostInfo, …
+const { user } = await ChoogaBridge.getUser();
+
+// Prefer checking host capabilities before host-only APIs
+if (ChoogaBridge.has('wallet.pick')) {
+  const wallet = await ChoogaBridge.activity('wallet.pick', { currency: 'ETB' });
+}
+```
+
+### Local browser demos (`mockHost`)
+
+Without a real WebView, async APIs reject with `no_host`. For UI work in a normal browser, install a fake host **before** `init()`:
+
+```js
+ChoogaBridge.mockHost({
+  context: {
+    user: { id: 'u1', name: 'Demo' },
+    params: { locale: 'en' },
+  },
 });
+ChoogaBridge.init({ debug: true });
+```
+
+`mockHost` answers `ready`, activities, `call`, navigate, payments, and capabilities with sensible defaults. Pass `onMessage(msg, reply)` to customize.
+
+---
 
-const { session, user, theme } = ChoogaBridge.getState();
+## How the bridge thinks
+
+Three interaction styles matter:
+
+**Injected state** — After `ready`, the host pushes session, user, theme, safe area, host info, and any custom `params` into the WebView. Read them with `getState()` or `subscribe()`. Custom fields can appear or disappear per host/app without changing this SDK.
+
+**Request / response** — Methods like `activity`, `call`, `navigate`, `getUser`, `getHostInfo`, and `payments.initiate` (default mode) send a message with a `requestId`, wait for the host to finish, then settle a Promise with the host’s return payload. That awaited value *is* what the superapp returned.
+
+**Fire-and-forget** — `toast`, `showProgress`, `close`, `openExternal` post to the host and do not return a result Promise.
+
+**Host capabilities** — `activity`, `payments.initiate`, and some `call` methods only work when the host implements them. After `hostInfo` is injected (or after `getHostInfo()`), check `ChoogaBridge.has('wallet.pick')` / `has('payments')` before calling. Until the mobile shell ships those features, treat them as experimental and use `mockHost` for local demos.
+
+---
+
+## Debug logging
+
+Turn on wire logging while integrating:
+
+```js
+ChoogaBridge.init({ debug: true });
+// or later:
+ChoogaBridge.setDebug(true);
+```
+
+You will see console lines like:
+
+```text
+[ChoogaBridge → host] { type: 'chooga.ready' }
+[ChoogaBridge ← host] { type: 'chooga.session', token: '…', expires_at: '…' }
 ```
 
-## Mental model
+Optional `allowedOrigins` filters DOM `message` events (React Native WebView injects often use an opaque/`null` origin, which is still allowed):
+
+```js
+ChoogaBridge.init({
+  debug: true,
+  allowedOrigins: ['https://mini.example'],
+});
+```
 
-| Kind | API | Notes |
-|------|-----|-------|
-| **Activities** | `activity(name, params)` | Native UI; Promise result |
-| **Services** | `showProgress`, `toast`, `getUser`, … | No full-screen takeover |
-| **Events** | `on` / `off` | Host → mini-app pushes |
+---
 
-## API
+## Async calls: await and onResult
 
-| Method | Description |
-|--------|-------------|
-| `init({ autoReady? })` | Bind listeners; optionally send `ready` |
-| `ready()` | Notify host that the mini-app is ready |
-| `close()` | Ask host to dismiss the WebView |
-| `openExternal(url)` | Open `https://` URL outside the WebView |
-| `requestCapability(key)` | Ask host if `key` is granted |
-| `activity(name, params?)` | Open host activity; await result |
-| `getUser()` / `user.get()` | Fresh user claims from host |
-| `toast(message, tone?)` | Host snackbar |
-| `getHostInfo()` | Refresh capabilities / activities / version |
-| `has(key)` | Capability or activity advertised / granted |
-| `hostVersion()` | Host protocol version string |
-| `on(name, fn)` / `off(name, fn)` | Host push events (`*` = all) |
-| `showProgress(opts?)` / `dismissProgress()` | Host loading overlay |
-| `progress.show` / `progress.dismiss` | Same as above (namespaced) |
-| `navigate({ path?, url?, timeoutMs? })` | In-WebView navigation (Promise) |
-| `payments.initiate(options)` | Host-mediated payment (Promise / `onResult`) |
-| `call(method, params?, options?)` | Generic RPC → host method map |
-| `subscribe(fn)` / `getState()` | Observe injected host context |
+For every request/response API, the bridge generates a `requestId`, posts to the host, and waits for a matching result message. When the host is done, the Promise resolves with the host’s payload (routing fields `type` and `requestId` removed).
 
-### Activity
+You can also pass `onResult`. It receives the **same** object as `await`. The callback runs first, then the Promise settles. Use either style, or both.
 
 ```js
+// await only — result is the host’s return value
 const wallet = await ChoogaBridge.activity('wallet.pick', { currency: 'ETB' });
-// { ok, id, name, currency, … }
 
-await ChoogaBridge.activity('host.confirm', {
-  title: 'Delete?',
-  message: 'This cannot be undone.',
+// callback + await
+const result = await ChoogaBridge.call(
+  'user.get',
+  {},
+  {
+    onResult: r => console.log('host finished', r),
+    timeoutMs: 30000,
+  },
+);
+```
+
+If the host result has `ok: false`, the Promise rejects after `onResult` still runs. The thrown error includes `.result` with the full host payload. If the host never replies, the Promise rejects with a timeout (default **120 seconds**; `getHostInfo` defaults to **15 seconds**).
+
+```js
+try {
+  await ChoogaBridge.navigate({ path: '/secret' });
+} catch (err) {
+  console.error(err.message, err.result);
+}
+```
+
+---
+
+## Lifecycle
+
+### init
+
+`init(options?)` binds host listeners once. Extra calls are safe no-ops for binding, but still update `debug` / `allowedOrigins`. Pass `{ autoReady: false }` if you want to mount UI first and call `ready()` yourself.
+
+```js
+ChoogaBridge.init();
+ChoogaBridge.init({
+  autoReady: false,
+  debug: true,
+  allowedOrigins: ['https://mini.example'],
 });
+// …mount UI…
+ChoogaBridge.ready();
+```
+
+### ready
+
+`ready()` posts `{ type: "chooga.ready" }` so the host knows it can inject context. `init()` does this for you unless `autoReady` is `false`.
+
+### close
+
+`close()` asks the host to dismiss the WebView. Fire-and-forget.
+
+```js
+ChoogaBridge.close();
+```
+
+---
+
+## Reading host state
+
+### getState
+
+`getState()` returns a snapshot of everything the host has injected so far. Known fields are always present (`session`, `user`, `theme`, `safeArea`, `hostInfo`, and so on). They may be `null` until the host sends them.
+
+Hosts can also push **any extra fields** they want via `chooga.params`. Those land in `state.params` and are **spread onto the top level** of the snapshot (reserved keys like `session` always win). That means App B can grow or shrink host context without a bridge schema change:
+
+```js
+const { session, user, locale, featureFlags, cartCount } = ChoogaBridge.getState();
+// same extras also live under:
+const { params } = ChoogaBridge.getState();
+console.log(params.locale, params.featureFlags);
+```
+
+**Host → mini-app** (merge, default):
+
+```json
+{ "type": "chooga.params", "locale": "am", "featureFlags": { "newCheckout": true } }
 ```
 
-### Events
+Or nest them:
+
+```json
+{ "type": "chooga.params", "params": { "locale": "am", "cartCount": 3 } }
+```
+
+Replace the whole bag with `replace: true`. Clear a key on merge by sending `null`:
+
+```json
+{ "type": "chooga.params", "replace": true, "params": { "locale": "en" } }
+{ "type": "chooga.params", "cartCount": null }
+```
+
+Known messages also keep **extra fields** the host attaches (for example extra keys on `chooga.session` or `chooga.theme` are preserved on those objects).
+
+```js
+const { session, user, theme, hostInfo, hostConnected, params } = ChoogaBridge.getState();
+
+if (session?.token) {
+  // use token for your API calls
+}
+```
+
+### subscribe
+
+`subscribe(listener)` runs your listener immediately with the current snapshot, then again on every update. It returns an unsubscribe function.
+
+```js
+const unsub = ChoogaBridge.subscribe(state => {
+  if (state.user) renderProfile(state.user);
+});
+
+// later
+unsub();
+```
+
+After `ready`, the host typically pushes messages such as `chooga.session`, `chooga.user`, `chooga.theme`, `chooga.safeArea`, `chooga.hostInfo`, `chooga.params`, and `chooga.event`. Theme updates also set CSS variables `--chooga-primary` / `--chooga-color-primary` and `data-chooga-theme` on `<html>`.
+
+---
+
+## Events
+
+`on(name, handler)` listens for host pushes delivered as `chooga.event`. These are not request/response and do not use `requestId`. The handler receives the event `detail`. Pass `'*'` to hear every event; the wildcard handler receives `{ name, detail }`.
+
+`on` returns an unsubscribe function. You can also call `off(name, handler)`.
 
 ```js
-const stop = ChoogaBridge.on('user.updated', ({ user }) => {
-  console.log(user);
+const stop = ChoogaBridge.on('user.updated', detail => {
+  console.log(detail.user);
+});
+
+ChoogaBridge.on('*', ({ name, detail }) => {
+  console.log(name, detail);
 });
-// later: stop() or ChoogaBridge.off('user.updated', handler)
+
+stop();
+```
+
+---
+
+## Activities
+
+`activity(name, params?, options?)` opens a native host screen and returns a Promise for its result. The resolved value is whatever the host put on `chooga.activityResult`.
+
+Only call activities the host advertises (`has(name)` / `hostInfo.activities`). Until the shell implements them, use `mockHost` locally.
+
+```js
+const wallet = await ChoogaBridge.activity('wallet.pick', { currency: 'ETB' });
+console.log(wallet.id, wallet.currency);
+
+await ChoogaBridge.activity(
+  'host.confirm',
+  {
+    title: 'Delete?',
+    message: 'This cannot be undone.',
+  },
+  {
+    onResult: r => console.log('confirmed?', r),
+  },
+);
+```
+
+Outbound message shape: `{ type: "chooga.activity", requestId, name, params }`. Check `ChoogaBridge.has('wallet.pick')` after host info is available if you need to know whether an activity is advertised.
+
+---
+
+## Services
+
+### toast
+
+`toast(message, tone?)` shows a short host snackbar. Fire-and-forget. Tone defaults to `success`. You can pass a string or an object.
+
+```js
+ChoogaBridge.toast('Saved');
+ChoogaBridge.toast('Something went wrong', 'error');
+ChoogaBridge.toast({ message: 'Saved', tone: 'success' });
+```
+
+### Progress overlay
+
+`showProgress(options?)` (alias `progress.show`) shows the host loading UI while your mini-app does work. Pass a string as a shorthand for `{ message }`. Always pair it with `dismissProgress()` (`progress.dismiss`) in a `finally` block. Both are fire-and-forget.
+
+```js
+ChoogaBridge.showProgress({ message: 'Fetching orders…' });
+try {
+  await fetch('/api/orders');
+} finally {
+  ChoogaBridge.dismissProgress();
+}
 ```
 
-### User + toast
+### getUser
+
+`getUser(options?)` (alias `user.get()`) asks the host for fresh user claims. Await the result; if the payload includes `user`, bridge state is updated too.
 
 ```js
 const { user } = await ChoogaBridge.getUser();
-ChoogaBridge.toast('Saved', 'success');
+
+await ChoogaBridge.user.get({
+  onResult: r => console.log(r.user),
+});
+```
+
+### getHostInfo
+
+`getHostInfo(options?)` refreshes capabilities, activities, and version into `state.hostInfo`. Default timeout is 15 seconds.
+
+```js
+const info = await ChoogaBridge.getHostInfo();
+console.log(info.activities, info.capabilities, info.granted);
+```
+
+### has and hostVersion
+
+`has(key)` is a local check against `hostInfo` (and the last capability result). It does not round-trip to the host. `hostVersion()` returns the host’s advertised version, or the client `BRIDGE_VERSION` if none is available.
+
+```js
+if (ChoogaBridge.has('wallet.pick')) {
+  await ChoogaBridge.activity('wallet.pick', { currency: 'ETB' });
+}
+
+console.log(ChoogaBridge.hostVersion());
 ```
 
-### Payments
+### requestCapability
 
-**Callback mode (default)** — awaits `chooga.payments.result`:
+`requestCapability(key, options?)` asks the host whether a permission is granted and **returns a Promise**. It settles when the host posts `chooga.capabilityResult` with the same `requestId`. `granted: false` still **resolves** (it is a valid answer, not a transport failure).
+
+```js
+const { granted, reason } = await ChoogaBridge.requestCapability('payments');
+if (granted) {
+  await ChoogaBridge.payments.initiate({ amount: '10', currency: 'ETB' });
+}
+
+await ChoogaBridge.requestCapability('camera', {
+  onResult: r => console.log(r),
+  timeoutMs: 15000,
+});
+```
+
+You can still watch `state.lastCapability` via `subscribe` if you prefer.
+
+### openExternal
+
+`openExternal(url)` asks the host to open an `https://` URL outside the WebView. Fire-and-forget.
+
+```js
+ChoogaBridge.openExternal('https://example.com/help');
+```
+
+---
+
+## Navigate
+
+`navigate({ path?, url?, timeoutMs?, onResult? })` navigates inside the WebView. Use a relative `path` under your mini-app origin, or an allowlisted absolute `url`. The Promise resolves with `{ ok, reason? }` from `chooga.navigateResult`.
+
+```js
+await ChoogaBridge.navigate({ path: '/orders/1' });
+await ChoogaBridge.navigate({
+  url: 'https://mini.example/orders/1',
+  onResult: r => console.log(r),
+});
+```
+
+---
+
+## Payments
+
+`payments.initiate(options)` starts a host-mediated payment. Check `ChoogaBridge.has('payments')` first — the host must advertise and implement this capability.
+
+### Await / callback mode (default)
+
+When `deliverResult` is true (the default), the host posts `chooga.payments.result` when payment finishes. `await` and `onResult` both receive that host payload.
 
 ```js
 const result = await ChoogaBridge.payments.initiate({
@@ -121,66 +409,91 @@ const result = await ChoogaBridge.payments.initiate({
   currency: 'ETB',
   reference: 'ord_123',
   description: 'Checkout',
-  onResult: r => console.log(r), // optional
+  onResult: r => console.log('payment finished', r),
 });
-// result: { ok, status, reference?, … }
+
+console.log(result.ok, result.status, result.reference);
 ```
 
-**Return-URL mode** — host redirects after payment; no result message:
+### Return-URL mode
+
+Set `deliverResult: false` if the host should redirect back to your mini-app (for example with query params) instead of posting a result. The Promise resolves immediately to `{ ok: true, status: 'redirecting' }` and does **not** wait for payment completion. `return_url` must be allowlisted by the host.
 
 ```js
 await ChoogaBridge.payments.initiate({
   amount: '250.00',
   currency: 'ETB',
   deliverResult: false,
-  return_url: 'https://mini.example/paid', // must be allowlisted
+  return_url: 'https://mini.example/paid',
 });
 ```
 
-### Navigate
+---
 
-```js
-await ChoogaBridge.navigate({ path: '/orders/1' });
-// or absolute URL within allowed_origins
-await ChoogaBridge.navigate({ url: 'https://mini.example/orders/1' });
-```
+## call
+
+`call(method, params?, options?)` is the generic RPC into the host method map. Prefer dedicated helpers when they exist; use `call` when you want one entry point or a method that only lives on the host map.
 
-### Call
+The Promise resolves to the host’s return payload from `chooga.callResult`. Pass `onResult` if you want a callback when the host finishes—same object as `await`.
 
 ```js
-await ChoogaBridge.call('navigate', { path: '/home' });
-await ChoogaBridge.call('activity', { name: 'wallet.pick', currency: 'ETB' });
-await ChoogaBridge.call('user.get');
+// Navigate via RPC
+const nav = await ChoogaBridge.call('navigate', { path: '/home' });
+
+// Activity via RPC
+const wallet = await ChoogaBridge.call('activity', {
+  name: 'wallet.pick',
+  currency: 'ETB',
+});
+
+// Fresh user
+const { user } = await ChoogaBridge.call('user.get');
+
+// Payment with callback + await
+const payment = await ChoogaBridge.call(
+  'payments.initiate',
+  {
+    amount: '250.00',
+    currency: 'ETB',
+    reference: 'ord_123',
+  },
+  {
+    onResult: result => {
+      // Host finished — this is the superapp’s return value
+      console.log(result.ok, result.status);
+    },
+    timeoutMs: 180000,
+  },
+);
 ```
 
-Supported methods: `navigate`, `payments.initiate`, `close`, `openExternal`, `requestCapability`, `progress.show`, `progress.dismiss`, `showProgress`, `dismissProgress`, `activity`, `toast`, `user.get`, `host.info`.
+Supported `method` values include: `navigate`, `activity`, `payments.initiate`, `close`, `openExternal`, `requestCapability`, `progress.show`, `showProgress`, `progress.dismiss`, `dismissProgress`, `toast`, `user.get`, and `host.info`. Param shapes are host-defined; keep them aligned with the host bridge contract.
 
-### Progress (host loading overlay)
+Outbound: `{ type: "chooga.call", requestId, method, params }`.  
+Inbound: `{ type: "chooga.callResult", requestId, …hostFields }`.
 
-```js
-ChoogaBridge.showProgress({ message: 'Fetching orders…' });
-try {
-  await fetch('/api/orders');
-} finally {
-  ChoogaBridge.dismissProgress();
-}
-```
+---
+
+## Message cheat sheet
+
+**Host → mini-app (context / pushes):** `chooga.session`, `chooga.user`, `chooga.theme`, `chooga.safeArea`, `chooga.hostInfo`, `chooga.params`, `chooga.event`, `chooga.capabilityResult`.
+
+**Host → mini-app (settle Promises):** `chooga.callResult`, `chooga.activityResult`, `chooga.navigateResult`, `chooga.payments.result`. Each must echo the original `requestId`.
+
+**Mini-app → host:** `chooga.ready`, `chooga.close`, `chooga.openExternal`, `chooga.requestCapability`, `chooga.navigate`, `chooga.payments.initiate`, `chooga.progress.show`, `chooga.progress.dismiss`, `chooga.activity`, `chooga.toast`, `chooga.user.get`, `chooga.hostInfo.get`, `chooga.call`.
+
+All of these strings are also on `ChoogaBridge.BRIDGE` / the exported `BRIDGE` map. `BRIDGE_VERSION` is the client protocol version (`0.0.2`).
+
+---
 
-## Host messages (read-only)
+## Transport
 
-The host injects these after `ready`:
+Outbound messages go through `window.ChoogaHost.postToHost`, which in a React Native WebView becomes `ReactNativeWebView.postMessage(JSON.stringify(msg))`. Inbound messages arrive via `window.ChoogaMiniApp.onHostMessage` and/or DOM `message` events. In a plain browser without a host, outbound posts are no-ops.
 
-- `chooga.session` — `{ token, expires_at }`
-- `chooga.user` — sanitized claims
-- `chooga.theme` — `{ mode, primary_color }` (+ CSS vars `--chooga-primary`)
-- `chooga.safeArea` — `{ insets }`
-- `chooga.hostInfo` — `{ version, activities, capabilities, granted }`
-- `chooga.event` — `{ name, detail, at }` (also delivered via `on`)
+---
 
 ## Versioning & release
 
-Keep message type strings in sync with the host `bridge/types.js`.  
-Bump this package when adding client APIs or changing result shapes.
+Keep wire type strings in sync with the host bridge contract. Bump this package when you add client APIs or change result shapes, and keep `BRIDGE_VERSION` in `src/index.js` equal to `package.json` `"version"`.
 
-**Ship a release:** bump version → tag `vX.Y.Z` → push tag → CI publishes npm + GitHub Release (CDN follows).  
-Full steps, Trusted Publishing, and troubleshooting: **[`RELEASE.md`](./RELEASE.md)**.
+Ship a release by bumping the version, tagging `vX.Y.Z`, and pushing the tag. CI publishes to npm and creates a GitHub Release; CDN mirrors follow. Full steps are in [`RELEASE.md`](./RELEASE.md).