@nominalso/vibe-bridge 0.0.1 → 0.1.0

package/docs/data-fetching.md

@@ -0,0 +1,66 @@
+# 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 an `Error` whose `message` is the host's error string. Wrap calls in `try/catch`.
+- Requests time out after `requestTimeout` ms (default 10 000) with `Vibe bridge request timed out: <OPERATION>`. Override per-bridge: `new VibeAppBridge({ parentOrigin, requestTimeout: 30000 })`.
+
+```ts
+try {
+  const entry = await bridge.getJournalEntry({
+    path: { subsidiary_id: ctx.subsidiaryId, journal_entry_id: '42' },
+  })
+} catch (err) {
+  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,48 @@
+# 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
+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) {
+    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.

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.1.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/",