@jetezra/bridge 0.0.1

package/LICENSE

@@ -0,0 +1,4 @@
+UNLICENSED
+
+Proprietary — All rights reserved.
+Contact the Chooga / Servicecops maintainers for redistribution terms.

package/README.md

@@ -0,0 +1,186 @@
+# `@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.
+
+| 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` |
+
+## Install
+
+```bash
+npm install @jetezra/bridge
+# or yarn add @jetezra/bridge
+```
+
+### CDN (prefer a pinned version)
+
+```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>
+  ChoogaBridge.init();
+</script>
+```
+
+Latest (not for production):  
+`https://cdn.jsdelivr.net/npm/@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
+
+```js
+import ChoogaBridge from '@jetezra/bridge';
+
+ChoogaBridge.init(); // posts chooga.ready (disable with { autoReady: false })
+
+ChoogaBridge.on('theme.changed', theme => {
+  // host push
+});
+
+const unsub = ChoogaBridge.subscribe(state => {
+  // session, user, theme, safeArea, hostInfo, …
+});
+
+const { session, user, theme } = ChoogaBridge.getState();
+```
+
+## Mental model
+
+| 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
+
+| 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 |
+
+### Activity
+
+```js
+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.',
+});
+```
+
+### Events
+
+```js
+const stop = ChoogaBridge.on('user.updated', ({ user }) => {
+  console.log(user);
+});
+// later: stop() or ChoogaBridge.off('user.updated', handler)
+```
+
+### User + toast
+
+```js
+const { user } = await ChoogaBridge.getUser();
+ChoogaBridge.toast('Saved', 'success');
+```
+
+### Payments
+
+**Callback mode (default)** — awaits `chooga.payments.result`:
+
+```js
+const result = await ChoogaBridge.payments.initiate({
+  amount: '250.00',
+  currency: 'ETB',
+  reference: 'ord_123',
+  description: 'Checkout',
+  onResult: r => console.log(r), // optional
+});
+// result: { ok, status, reference?, … }
+```
+
+**Return-URL mode** — host redirects after payment; no result message:
+
+```js
+await ChoogaBridge.payments.initiate({
+  amount: '250.00',
+  currency: 'ETB',
+  deliverResult: false,
+  return_url: 'https://mini.example/paid', // must be allowlisted
+});
+```
+
+### Navigate
+
+```js
+await ChoogaBridge.navigate({ path: '/orders/1' });
+// or absolute URL within allowed_origins
+await ChoogaBridge.navigate({ url: 'https://mini.example/orders/1' });
+```
+
+### Call
+
+```js
+await ChoogaBridge.call('navigate', { path: '/home' });
+await ChoogaBridge.call('activity', { name: 'wallet.pick', currency: 'ETB' });
+await ChoogaBridge.call('user.get');
+```
+
+Supported methods: `navigate`, `payments.initiate`, `close`, `openExternal`, `requestCapability`, `progress.show`, `progress.dismiss`, `showProgress`, `dismissProgress`, `activity`, `toast`, `user.get`, `host.info`.
+
+### Progress (host loading overlay)
+
+```js
+ChoogaBridge.showProgress({ message: 'Fetching orders…' });
+try {
+  await fetch('/api/orders');
+} finally {
+  ChoogaBridge.dismissProgress();
+}
+```
+
+## Host messages (read-only)
+
+The host injects these after `ready`:
+
+- `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.
+
+**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)**.