@nominalso/vibe-bridge 0.0.1 → 0.2.0

package/docs/connect-lifecycle.md

@@ -0,0 +1,56 @@
+# Connection lifecycle
+
+## Always connect first
+
+```ts
+const ctx = await bridge.connect()
+```
+
+Call `connect()` **once** on app init and `await` it before any data method, `upload()`, or subroute call. Concurrent calls return the same promise, so it's safe to call from multiple init paths.
+
+## What `connect()` returns
+
+A `ContextPayload`:
+
+```ts
+interface ContextPayload {
+  tenant: string
+  subsidiaryId: number
+  subsidiaries: { id: number; displayName: string }[]
+  user: { id: string; displayName: string }
+  subroute?: string // initial deep-link path, if any
+  lastClosedPeriodSlug?: string // e.g. "mar-2026"
+  hostVersion: string // version of @nominalso/vibe-host running in the host
+}
+```
+
+## How it works
+
+The host pushes context to the iframe on load, but the iframe's listener may not be ready when that push arrives. `connect()` solves the race:
+
+1. The bridge starts a 500 ms polling loop, sending `GET_CONTEXT` requests to the host.
+2. The host responds as soon as its listener is mounted, **or** proactively pushes `CONTEXT_PUSH` once it has the iframe's window.
+3. Whichever arrives first resolves `connect()`. Polling stops.
+4. The bridge begins auto-tracking SPA navigation (see below).
+5. If nothing arrives within **10 seconds**, `connect()` rejects with a `BridgeError` (code `'TIMEOUT'`, message `Bridge connect timed out`).
+
+A timeout almost always means a `parentOrigin` mismatch or the host never mounted.
+
+## Initial deep link
+
+If `ctx.subroute` is present (e.g. the user opened a bookmarked deep link), the bridge navigates to it via `history.replaceState` right after connecting, so your router lands on the correct view.
+
+## Subroute sync (usually automatic)
+
+After connecting, the bridge monkey-patches `history.pushState`/`replaceState` to auto-report internal navigation to the host, keeping the Nominal browser URL in sync. For standard SPA routers you need no code.
+
+- **Non-standard / hash routers:** call `bridge.reportSubroute('/assets/123', { replace })` manually.
+- **React to host back/forward:** `const off = bridge.onSubrouteRequest((subroute) => router.navigate(subroute))`. Returns an unsubscribe function. Without one, the SDK uses `history.pushState` + a `popstate` event, which most routers pick up.
+
+## Teardown
+
+```ts
+bridge.destroy()
+```
+
+Removes listeners, rejects any pending requests with a `BridgeError` (code `'DESTROYED'`, message `Bridge destroyed`), and restores the original history methods. Call it on unmount.

package/docs/data-fetching.md

@@ -0,0 +1,71 @@
+# Fetching data & submitting task outputs
+
+All data operations run over the bridge. Two equivalent ways to call them:
+
+```ts
+// Named method (preferred — discoverable via autocomplete):
+const accounts = await bridge.getChartOfAccounts({ path: { subsidiary_id: ctx.subsidiaryId } })
+
+// Typed generic escape hatch (same types; works for every operation):
+const accounts = await bridge.request('GET_CHART_OF_ACCOUNTS', {
+  path: { subsidiary_id: ctx.subsidiaryId },
+})
+```
+
+The named methods simply wrap `request('<OPERATION>', payload)`. Both are fully typed: the payload and return type come from the Nominal API for that operation.
+
+## Payload shape
+
+Payloads follow the generated Nominal API client convention — typically an object with some of:
+
+- `path` — path parameters, e.g. `{ subsidiary_id: 1 }`
+- `query` — query-string parameters, e.g. `{ from_date: '2026-01-01' }`
+- `body` — request body (for writes like `postTaskOutput`)
+
+Let TypeScript guide you: each method's parameter type names exactly which of `path`/`query`/`body` it needs. Pass `{}` when an operation has only optional parameters (e.g. `bridge.getSubsidiaries({})`).
+
+## Writing back: `postTaskOutput`
+
+The **only** write path into Nominal is submitting a Close-Management task output:
+
+```ts
+await bridge.postTaskOutput({
+  path: { task_instance_id: 'task-1' },
+  body: {}, // task-specific output shape
+})
+```
+
+Vibe Apps never write Nominal data directly; everything else is read-only.
+
+## Errors & timeouts
+
+- A rejected operation throws a `BridgeError` (`extends Error`) carrying a machine-readable `code` (e.g. `'RATE_LIMITED'`, `'FILE_TOO_LARGE'`, `'TIMEOUT'`) alongside the host's `message`. Branch on `error.code` rather than string-matching the message. (A failure the host sends without a code falls back to a plain `Error`.) A failed Nominal API call throws the `HttpBridgeError` subtype (`code: 'REQUEST_FAILED'`), which adds the HTTP `status` — branch on `err.status` (e.g. `404`).
+- Each operation times out on a default tuned to how long it realistically takes: API reads/writes **30 000 ms**, `UPLOAD_FILE` **120 000 ms**, `INVALIDATE_CACHE` **10 000 ms**, `GET_CONTEXT` **5 000 ms**. On timeout the call rejects with a `BridgeError` whose `code` is `'TIMEOUT'` (message `Vibe bridge request timed out: <OPERATION>`). Override all of them with one value via `new VibeAppBridge({ parentOrigin, requestTimeout: 45000 })`.
+
+```ts
+import { BridgeError } from '@nominalso/vibe-bridge'
+
+try {
+  const entry = await bridge.getJournalEntry({
+    path: { subsidiary_id: ctx.subsidiaryId, journal_entry_id: '42' },
+  })
+} catch (err) {
+  if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+    // back off and retry
+  }
+  console.error('Fetch failed:', err instanceof Error ? err.message : err)
+}
+```
+
+## Operation catalog
+
+The full list of ~46 named methods and their `GET_*`/`POST_*` operation names is in the package [`README.md`](../README.md#operation-catalog). Highlights:
+
+- **Chart of accounts:** `getChartOfAccounts`, `getCoaTree`, `getCoaFlatSimple`, `getCoaGrouped`, `getCoaAccount`, `getAccounts`, `getAccount`.
+- **Journal entries:** `getJournalEntries`, `getJournalLines`, `getJournalEntry`.
+- **Periods & activities:** `getPeriods`, `getPeriodInstanceBySlug`, `getActivityInstances`, `getActivityInstanceTasks`.
+- **Tasks:** `getTaskDefinitions`, `getTaskInstances`, `postTaskOutput`, `getTaskInstancesByFilter`.
+- **Tenancy:** `getSubsidiaries`, `getSubsidiary`, `getTenantUsers`.
+- **Dimensions, exchange rates, fiscal calendars, audit trail** — see the catalog.
+
+For any operation without a named method, use `bridge.request('<OPERATION>', payload)`.

package/docs/file-upload.md

@@ -0,0 +1,55 @@
+# Uploading files
+
+Upload a file through the host with `bridge.upload`:
+
+```ts
+const result = await bridge.upload(file, {
+  entityType: 'JOURNAL_ENTRY',
+  entityId: '123',
+  onProgress: (p) => console.log(`${p.progress}%`),
+})
+// result: { attachmentId: string, name: string }
+```
+
+## Arguments
+
+- `file: File` — a browser `File` object (e.g. from `<input type="file">` or a drop event). **Not** a path or `FormData`.
+- `options.entityType: string` — the domain entity the file attaches to, e.g. `'JOURNAL_ENTRY'`.
+- `options.entityId?: string | number` — id of that entity, when applicable.
+- `options.onProgress?: (p: { attachmentId: string; progress: number }) => void` — called with incremental progress from `0` to `100`.
+
+## How it works
+
+Sandboxed cross-origin iframes cannot pass `File` handles across windows, so the bridge reads the file into an `ArrayBuffer` and sends that to the host. The host performs the actual storage and streams progress events back, then resolves with the stored attachment's id and name. Any maximum file size is enforced by the host/Nominal backend, not by the bridge.
+
+## Example — file input with a progress bar
+
+```ts
+import { BridgeError } from '@nominalso/vibe-bridge'
+
+const input = document.querySelector<HTMLInputElement>('#file-input')!
+
+input.addEventListener('change', async () => {
+  const file = input.files?.[0]
+  if (!file) return
+
+  try {
+    const result = await bridge.upload(file, {
+      entityType: 'JOURNAL_ENTRY',
+      onProgress: (p) => {
+        progressBar.style.width = `${p.progress}%`
+      },
+    })
+    console.log('Uploaded:', result.attachmentId, result.name)
+  } catch (err) {
+    // A failed upload throws a BridgeError with a code, e.g. 'FILE_TOO_LARGE'
+    // (host limit is 50 MB), 'RATE_LIMITED', or 'TIMEOUT' (uploads allow 120 s).
+    if (err instanceof BridgeError && err.code === 'FILE_TOO_LARGE') {
+      alert('That file is too large (50 MB max).')
+    }
+    console.error('Upload failed:', err instanceof Error ? err.message : err)
+  }
+})
+```
+
+`upload()` resolves only after the host has fully stored the file; progress ticks arrive before it resolves. Import `BridgeError` from `@nominalso/vibe-bridge` to branch on `err.code`.

package/docs/getting-started.md

@@ -0,0 +1,53 @@
+# Getting started
+
+`@nominalso/vibe-bridge` is the iframe-side SDK for a Nominal Vibe App. Install it in your standalone browser app (e.g. a Lovable project) that will be embedded in Nominal via an `<iframe>`.
+
+## Install
+
+```sh
+npm install @nominalso/vibe-bridge
+```
+
+No runtime dependencies. Ships ESM + CJS with self-contained TypeScript types.
+
+## Minimal app
+
+```ts
+import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
+
+const bridge = new VibeAppBridge({
+  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN,
+})
+
+async function main() {
+  const ctx: ContextPayload = await bridge.connect()
+  console.log(`Connected as ${ctx.user.displayName} · tenant ${ctx.tenant}`)
+
+  const accounts = await bridge.getChartOfAccounts({
+    path: { subsidiary_id: ctx.subsidiaryId },
+  })
+  console.log(accounts)
+}
+
+main().catch(console.error)
+```
+
+## `parentOrigin`
+
+`parentOrigin` is the **origin** (scheme + host + port, no path, no trailing slash) of the Nominal app that embeds your iframe. It must match exactly — the bridge ignores messages from any other origin and only posts to this one.
+
+Drive it from an environment variable so the same code works locally and in production:
+
+```sh
+# .env (committed — standalone/dev default)
+VITE_PARENT_ORIGIN=http://localhost:5173
+
+# .env.local (git-ignored — when testing inside nom-ui locally)
+VITE_PARENT_ORIGIN=http://localhost:3000
+```
+
+## Next
+
+- [`connect-lifecycle.md`](./connect-lifecycle.md) — how `connect()` works and the connection lifecycle.
+- [`data-fetching.md`](./data-fetching.md) — reading Nominal data and submitting task outputs.
+- [`file-upload.md`](./file-upload.md) — uploading files with progress.

package/llms.txt

@@ -0,0 +1,20 @@
+# @nominalso/vibe-bridge
+
+> Iframe-side TypeScript SDK for building Nominal Vibe Apps — standalone browser apps (often built with Lovable) embedded in the Nominal platform via a cross-origin iframe. Connects the 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. Browser-only, zero runtime dependencies.
+
+The integration is always the same: construct `VibeAppBridge` with the host `parentOrigin`, `await bridge.connect()` once (it returns the tenant/user `ContextPayload`), then call any of the ~46 typed data methods, `upload(file, options)`, or `postTaskOutput(...)`. Tear down with `bridge.destroy()`. The only write path into Nominal is `postTaskOutput`.
+
+## Docs
+
+- [README](./README.md): install, quickstart, full API, common mistakes, and the operation catalog.
+- [Getting started](./docs/getting-started.md): install + minimal app + `parentOrigin` setup.
+- [Connection lifecycle](./docs/connect-lifecycle.md): `connect()` semantics, `ContextPayload`, timeout, subroute sync, teardown.
+- [Fetching data](./docs/data-fetching.md): named methods vs the typed `request()` escape hatch, payload shapes, errors/timeouts, operation list.
+- [File upload](./docs/file-upload.md): `upload(file, options)`, progress events, constraints.
+- [AGENTS.md](./AGENTS.md): condensed integration guide for AI coding agents.
+
+## Optional
+
+- [Types](./dist/index.d.ts): self-contained TypeScript declarations (the full typed surface, Nominal API types inlined).
+- [Host SDK](https://www.npmjs.com/package/@nominalso/vibe-host): `@nominalso/vibe-host`, the Nominal-side counterpart (you do not install this in a Vibe App).
+- [Repository](https://github.com/nominalso/vibe-apps-sdk#readme): protocol, architecture, and contribution docs.

package/package.json

@@ -1,18 +1,8 @@
 {
   "name": "@nominalso/vibe-bridge",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Iframe-side SDK for building Nominal Vibe Apps — connects an embedded app to its Nominal host over a typed postMessage bridge (context, data fetch, file upload, subroute deep-linking).",
   "license": "UNLICENSED",
-  "keywords": [
-    "nominal",
-    "vibe-apps",
-    "vibe-app",
-    "sdk",
-    "iframe",
-    "postmessage",
-    "bridge",
-    "embed"
-  ],
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",
   "bugs": {
     "url": "https://github.com/nominalso/vibe-apps-sdk/issues"
@@ -34,7 +24,10 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "AGENTS.md",
+    "llms.txt"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",