@nominalso/vibe-bridge 0.1.0 → 0.3.0

package/AGENTS.md

@@ -15,9 +15,7 @@ The host counterpart is `@nominalso/vibe-host` (used by Nominal's own app — yo
 ```ts
 import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 
-const bridge = new VibeAppBridge({
-  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN, // exact origin of the embedding Nominal app
-})
+const bridge = new VibeAppBridge() // no config — auto-detects the embedding Nominal app
 
 const ctx: ContextPayload = await bridge.connect() // call ONCE, await before anything else
 
@@ -32,15 +30,18 @@ bridge.destroy() // on unmount
 
 ## Core surface
 
-- `new VibeAppBridge({ parentOrigin, requestTimeout? })`
-- `connect(): Promise<ContextPayload>` — call once; rejects after 10 s on `parentOrigin` mismatch / host not mounted.
+- `new VibeAppBridge({ parentOrigin?, requestTimeout? })` — both optional; `new VibeAppBridge()` auto-detects the host. `requestTimeout` omitted → tuned per-op defaults (API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000` ms).
+- `connect(): Promise<ContextPayload>` — call once; rejects after 10 s on a host that never mounts, or immediately with code `PARENT_ORIGIN_UNRESOLVED` if no host could be detected/pinned.
 - ~46 typed data methods, e.g. `getChartOfAccounts`, `getSubsidiaries`, `getPeriods`, `getJournalEntries`, `getAccounts`, `postTaskOutput`. Each takes the operation's `payload` and returns its `data`.
 - `request('<OPERATION>', payload, onProgress?)` — typed escape hatch for any operation; `'<OPERATION>'` autocompletes and narrows the payload/return types.
 - `upload(file: File, { entityType, entityId?, onProgress? }): Promise<{ attachmentId, name }>`.
+- `navigate`/`navigateTo`/`refresh` and `ui.setSideNav`/`ui.switchSubsidiary` — drive the host's chrome (router, side nav, subsidiary switcher); `invalidateCache(...)` busts host caches.
 - `reportSubroute(subroute, { replace? })`, `onSubrouteRequest(cb): () => void` — usually unnecessary; standard SPA navigation is auto-tracked.
 - `destroy()`.
 
-Exported types: `VibeAppBridgeOptions`, `UploadOptions`, `ContextPayload`, `BridgeSubsidiary`, `UploadResponse`, `UploadProgress`, `RequestRegistry`, and `BRIDGE_VERSION`.
+A failed operation throws a `BridgeError` (`extends Error`) with a machine-readable `code` (`'RATE_LIMITED'`, `'FILE_TOO_LARGE'`, `'TIMEOUT'`, …); branch on `err.code` rather than the message. A failed Nominal API call throws the `HttpBridgeError` subtype (`code: 'REQUEST_FAILED'`) carrying the HTTP `status` — branch on `err.status` (e.g. `404`).
+
+Exported values/types: `VibeAppBridge`, `BridgeError`, `BRIDGE_VERSION`, and types `VibeAppBridgeOptions`, `UploadOptions`, `ContextPayload`, `BridgeSubsidiary`, `UploadResponse`, `UploadProgress`, `RequestRegistry`.
 
 `ContextPayload` shape: `{ tenant, subsidiaryId, subsidiaries: { id, displayName }[], user: { id, displayName }, subroute?, lastClosedPeriodSlug?, hostVersion }`.
 
@@ -49,7 +50,7 @@ The full method/operation list is in `README.md` ("Operation catalog") and in `d
 ## Gotchas (wrong → right)
 
 - **Don't call data methods before `connect()` resolves.** Always `await bridge.connect()` first.
-- **`parentOrigin` is an origin, not a URL.** `https://app.nominal.so` ✅ — not `https://app.nominal.so/app` and not a trailing slash. A mismatch makes `connect()` time out after 10 s.
+- **`parentOrigin` is optional** — omit it and the bridge auto-detects the embedding host. If you do pass it, it's an origin or list of origins (not a URL): `https://app.nominal.so` ✅ — not `https://app.nominal.so/app`, no trailing slash. For preview testing pass a list with a glob: `['https://app.nominal.so', 'https://*.vercel.app']` — patterns match only when the app itself runs on a preview host.
 - **`upload()` takes a `File`**, not a path or `FormData`.
 - **Writes go through `postTaskOutput` only.** Vibe Apps never write Nominal data directly.
 - **Call `bridge.destroy()` on unmount** to remove listeners and reject pending requests.
@@ -57,5 +58,5 @@ The full method/operation list is in `README.md` ("Operation catalog") and in `d
 ## Don't
 
 - Don't poll or busy-wait for context — `await connect()` resolves when it's ready.
-- Don't hardcode `parentOrigin`; read it from an env var so dev and prod differ.
+- Don't pass `parentOrigin` unless you mean to pin the host; the default auto-detects it. If you pin, read it from an env var (and add a preview pattern to the list when testing deploy previews).
 - Don't import from `@nominalso/vibe-protocol-types` / `vibe-api-types` — they are not published; all public types are re-exported from `@nominalso/vibe-bridge`.

package/README.md

@@ -2,7 +2,7 @@
 
 Iframe-side SDK for building **Nominal Vibe Apps** — standalone web apps (typically built with [Lovable](https://lovable.dev)) embedded in the Nominal platform via a cross-origin `<iframe>`. The bridge connects your app to its Nominal host over a typed `postMessage` protocol: read Nominal data, submit Close-Management task outputs, upload files, and keep deep-link routing in sync.
 
-> **For AI agents / Lovable:** this is a browser-only SDK. The wiring is always the same — construct `VibeAppBridge` with the host `parentOrigin`, `await bridge.connect()` **once**, then call data methods. Copy the quickstart below verbatim; it is the complete happy path.
+> **For AI agents / Lovable:** this is a browser-only SDK. The wiring is always the same — `new VibeAppBridge()` (no config — it auto-detects the Nominal host), `await bridge.connect()` **once**, then call data methods. Copy the quickstart below verbatim; it is the complete happy path.
 
 ## Install
 
@@ -17,11 +17,10 @@ Zero runtime dependencies. Ships ESM + CJS and self-contained TypeScript types.
 ```ts
 import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 
-// 1. Construct with the origin of the Nominal app embedding this iframe.
-//    Must match exactly — drive it from an env var.
-const bridge = new VibeAppBridge({
-  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN,
-})
+// 1. Construct. No config needed — the bridge auto-detects the Nominal app
+//    that embeds it. (Pin the host origin explicitly only if you want to;
+//    see "Pinning the host origin" below.)
+const bridge = new VibeAppBridge()
 
 // 2. Connect ONCE on init and await it before any other call.
 //    Resolves with the tenant/user context (or rejects after 10s).
@@ -47,28 +46,47 @@ await bridge.postTaskOutput({ path: { task_instance_id: 'task-1' }, body: {} })
 bridge.destroy()
 ```
 
-`parentOrigin` via environment variable:
+### Pinning the host origin (optional)
 
-```sh
-# .env (committed — standalone/dev default)
-VITE_PARENT_ORIGIN=http://localhost:5173
+By default you pass **nothing** — the bridge talks only to the Nominal page that
+actually embeds it. That's safe because Nominal serves Vibe Apps behind a
+`frame-ancestors` CSP, so only nom-ui can frame your app. Most apps need nothing
+more.
 
-# .env.local (git-ignored — override when testing inside nom-ui)
+Pass `parentOrigin` to pin explicitly — defense in depth, or when running
+outside Nominal's edge. Drive it from an env var, or use a list / **glob
+patterns** to accept dynamic preview deployments:
+
+```ts
+new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
+new VibeAppBridge({ parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app'] })
+```
+
+```sh
+# .env.local
 VITE_PARENT_ORIGIN=http://localhost:3000
 ```
 
+A pattern's `*` matches exactly one DNS label or port (anchored, scheme
+literal): `https://*.vercel.app` matches `https://pr-7.vercel.app` but not
+`https://a.b.vercel.app` or `https://pr-7.vercel.app.evil.com`. **Patterns are
+honoured only when this app's own page is served from a recognised preview host**
+(`*.vercel.app`, `*.lovable.app`, `localhost`, …) — on a production custom
+domain pattern entries are ignored and only exact origins match. Always include
+at least one exact origin alongside any patterns.
+
 ## API
 
 ### `new VibeAppBridge(options)`
 
-| Option           | Type     | Default | Description                                                                              |
-| ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
-| `parentOrigin`   | `string` | —       | Origin of the Nominal app embedding this iframe. **Must match the host origin exactly.** |
-| `requestTimeout` | `number` | `10000` | Per-request timeout in milliseconds before a call rejects.                               |
+| Option           | Type                 | Default  | Description                                                                                                                                                                                               |
+| ---------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parentOrigin`   | `string \| string[]` | _auto_   | **Optional.** Omit to auto-detect the embedding Nominal host. Pass to pin: exact origins always match; glob patterns (`https://*.vercel.app`) match only when this app runs on a preview host. See above. |
+| `requestTimeout` | `number`             | _per-op_ | Global timeout (ms) before a call rejects with `BridgeError` code `'TIMEOUT'`. Omit to use per-operation defaults: API `30000`, `UPLOAD_FILE` `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000`. |
 
 ### `connect(): Promise<ContextPayload>`
 
-Call **once** on init and `await` it before anything else. Polls the host every 500 ms until context arrives; rejects with `Bridge connect timed out` after 10 s (usually a `parentOrigin` mismatch or the host hasn't mounted). Concurrent calls return the same promise.
+Call **once** on init and `await` it before anything else. Polls the host every 500 ms until context arrives; rejects with `Bridge connect timed out` after 10 s (usually a `parentOrigin` mismatch or the host hasn't mounted). If no concrete parent origin can be resolved (e.g. a pattern-only `parentOrigin` on a non-preview host), it rejects immediately with `BridgeError` code `PARENT_ORIGIN_UNRESOLVED`. Concurrent calls return the same promise.
 
 ### Data operations
 
@@ -102,7 +120,7 @@ Removes listeners, rejects pending requests, and restores patched history method
 
 ### Exports
 
-`VibeAppBridge`, `BRIDGE_VERSION`, and the types `VibeAppBridgeOptions`, `UploadOptions`, `ContextPayload`, `BridgeSubsidiary`, `UploadResponse`, `UploadProgress`, `RequestRegistry`.
+`VibeAppBridge`, `BridgeError`, `BRIDGE_VERSION`, and the types `VibeAppBridgeOptions`, `UploadOptions`, `ContextPayload`, `BridgeSubsidiary`, `UploadResponse`, `UploadProgress`, `RequestRegistry`.
 
 ## Common recipes
 
@@ -115,7 +133,7 @@ import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
 function useVibeBridge() {
   const [ctx, setCtx] = useState<ContextPayload | null>(null)
   useEffect(() => {
-    const bridge = new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
+    const bridge = new VibeAppBridge()
     bridge.connect().then(setCtx).catch(console.error)
     return () => bridge.destroy()
   }, [])
@@ -138,6 +156,26 @@ await bridge.upload(file, {
 const events = await bridge.request('GET_AUDIT_EVENTS', {})
 ```
 
+**Handle a failure by its code:**
+
+A rejected operation throws a `BridgeError` carrying the host's `code` (`'RATE_LIMITED'`, `'FILE_TOO_LARGE'`, `'TIMEOUT'`, …); branch on it instead of string-matching the message. A failed Nominal API call throws the `HttpBridgeError` subtype (`code: 'REQUEST_FAILED'`), which adds the HTTP `status` — branch on `err.status` (e.g. `404`).
+
+```ts
+import { BridgeError, HttpBridgeError } from '@nominalso/vibe-bridge'
+
+try {
+  await bridge.getAccounts({})
+} catch (err) {
+  if (err instanceof HttpBridgeError && err.status === 404) {
+    // handle not-found
+  }
+  if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+    // back off and retry
+  }
+  throw err
+}
+```
+
 ## Common mistakes
 
 ```ts
@@ -152,13 +190,15 @@ const accounts = await bridge.getChartOfAccounts({ path: { subsidiary_id: ctx.su
 ```
 
 ```ts
-// ❌ WRONG — parentOrigin must be an ORIGIN, not a URL with a path, and must match exactly.
+// ❌ WRONG — each entry must be an ORIGIN (scheme + host + port), not a URL with a path.
 new VibeAppBridge({ parentOrigin: 'https://app.nominal.so/some/path' })
 // ❌ a trailing slash or wrong port also fails → connect() times out after 10s.
 new VibeAppBridge({ parentOrigin: 'http://localhost:3000/' })
 
-// ✅ CORRECT — scheme + host + port only, exact match to the embedding app.
+// ✅ CORRECT — scheme + host + port only, matching the embedding app.
 new VibeAppBridge({ parentOrigin: 'https://app.nominal.so' })
+// ✅ CORRECT — a list with a preview pattern (honoured only on a preview host).
+new VibeAppBridge({ parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app'] })
 ```
 
 ```ts