@nominalso/vibe-bridge 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,7 +1,19 @@
 // package.json
-var version = "0.1.0";
+var version = "0.2.0";
 
 // ../protocol-types/dist/index.js
+function normalizeSubroute(subroute) {
+  const normalized = subroute.startsWith("/") ? subroute : `/${subroute}`;
+  const path = normalized.split(/[?#]/)[0];
+  let decoded = path;
+  let prev;
+  do {
+    prev = decoded;
+    decoded = decoded.replace(/%25/gi, "%").replace(/%2e/gi, ".").replace(/%2f/gi, "/");
+  } while (decoded !== prev);
+  if (decoded.split("/").some((segment) => segment === "..")) return null;
+  return normalized;
+}
 var PROTOCOL_ID = "nominal-vibe-bridge";
 var PROTOCOL_VERSION = 1;
 var BRIDGE_KINDS = ["request", "response", "push", "command", "progress"];
@@ -18,119 +30,23 @@ function isBridgeMessage(data) {
   if (CORRELATED_KINDS_SET.has(d.kind) && typeof d.requestId !== "string") return false;
   return true;
 }
-
-// src/VibeAppBridge.ts
-var CONNECT_TIMEOUT_MS = 1e4;
-var CONNECT_POLL_MS = 500;
-var VibeAppBridge = class {
-  constructor({ parentOrigin, requestTimeout = 1e4 }) {
-    this.pendingRequests = /* @__PURE__ */ new Map();
-    this.context = null;
-    this.connectPromise = null;
-    this.connectPollInterval = null;
-    this.onContextReceived = null;
-    this.lastReportedSubroute = null;
-    this.suppressSubrouteReport = false;
-    this.subrouteCallback = null;
-    this.origPushState = null;
-    this.origReplaceState = null;
-    this.popstateHandler = null;
-    this.kindHandlers = {
-      response: (msg) => this.handleResponse(msg),
-      push: (msg) => this.dispatchPush(msg),
-      progress: (msg) => this.handleProgress(msg)
-    };
-    this.pushHandlers = {
-      CONTEXT_PUSH: (payload) => this.onContextReceived?.(payload),
-      SUBROUTE_PUSH: (payload) => this.withSubrouteSuppressed(() => {
-        if (this.subrouteCallback) {
-          this.subrouteCallback(payload.subroute);
-        } else {
-          history.pushState(null, "", payload.subroute);
-          window.dispatchEvent(new PopStateEvent("popstate"));
-        }
-        this.lastReportedSubroute = payload.subroute;
-      })
-    };
-    this.parentOrigin = parentOrigin;
-    this.requestTimeout = requestTimeout;
-    this.boundHandleMessage = this.handleMessage.bind(this);
-    window.addEventListener("message", this.boundHandleMessage);
+var BridgeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BridgeError";
   }
-  dispatchPush(msg) {
-    const handler = this.pushHandlers[msg.type];
-    handler(msg.payload);
-  }
-  /**
-   * Connects to the host and returns the tenant/user {@link ContextPayload}.
-   * **Call this once on app init and await it before any other method** — data
-   * methods, `upload()`, and subroute reporting all require an established
-   * connection. Concurrent calls return the same promise.
-   *
-   * Actively polls the host every 500ms until a response arrives, which
-   * handles the race condition where the host's initial context push arrives
-   * before this listener is ready. Rejects with `Bridge connect timed out`
-   * after 10 seconds if no context arrives (usually a `parentOrigin` mismatch
-   * or the host hasn't mounted).
-   *
-   * After connecting, if the context includes an initial subroute (e.g. from
-   * a deep link), the bridge navigates to it and starts auto-tracking
-   * internal navigation via the history API.
-   *
-   * @returns The tenant/user/subsidiary context for this app session.
-   * @throws If no context is received within 10 seconds.
-   * @example
-   * ```ts
-   * const ctx = await bridge.connect()
-   * // ctx.tenant, ctx.subsidiaryId, ctx.subsidiaries, ctx.user, ctx.lastClosedPeriodSlug
-   * ```
-   */
-  connect() {
-    if (this.context) return Promise.resolve(this.context);
-    if (this.connectPromise) return this.connectPromise;
-    this.connectPromise = new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.stopConnectPolling();
-        this.connectPromise = null;
-        reject(new Error("Bridge connect timed out"));
-      }, CONNECT_TIMEOUT_MS);
-      this.onContextReceived = (ctx) => {
-        clearTimeout(timer);
-        this.stopConnectPolling();
-        this.context = ctx;
-        this.connectPromise = null;
-        this.onContextReceived = null;
-        console.log(
-          `[vibe-bridge] Connected \u2014 bridge: ${version}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
-        );
-        if (ctx.subroute && ctx.subroute !== "/") {
-          this.withSubrouteSuppressed(() => {
-            history.replaceState(null, "", ctx.subroute);
-            window.dispatchEvent(new PopStateEvent("popstate"));
-            this.lastReportedSubroute = ctx.subroute;
-          });
-        } else {
-          this.lastReportedSubroute = window.location.pathname + window.location.search;
-        }
-        this.setupNavigationTracking();
-        resolve(ctx);
-      };
-      const poll = () => {
-        const message = {
-          __protocol: PROTOCOL_ID,
-          __version: PROTOCOL_VERSION,
-          kind: "request",
-          type: "GET_CONTEXT",
-          requestId: crypto.randomUUID(),
-          payload: { bridgeVersion: version }
-        };
-        window.parent.postMessage(message, this.parentOrigin);
-      };
-      poll();
-      this.connectPollInterval = setInterval(poll, CONNECT_POLL_MS);
-    });
-    return this.connectPromise;
+};
+var HttpBridgeError = class extends BridgeError {
+  constructor(status, message) {
+    super("REQUEST_FAILED", message);
+    this.status = status;
+    this.name = "HttpBridgeError";
   }
+};
+
+// src/data-methods.ts
+var BridgeDataMethods = class {
   // ---------------------------------------------------------------------------
   // Operations — Accounting: chart of accounts
   //
@@ -416,13 +332,198 @@ var VibeAppBridge = class {
     const onProgress = options.onProgress ? (p) => options.onProgress(p) : void 0;
     return this.request("UPLOAD_FILE", payload, onProgress);
   }
+};
+
+// src/timeouts.ts
+var CONNECT_TIMEOUT_MS = 1e4;
+var CONNECT_POLL_MS = 500;
+var DEFAULT_TIMEOUTS = {
+  /** Typed Nominal API reads/writes (`GET_*` / `POST_*` / `CREATE_*` / ...). */
+  api: 3e4,
+  /** `GET_CONTEXT` re-fetch (the initial fetch is governed by `connect()`). */
+  context: 5e3,
+  /** `INVALIDATE_CACHE`. */
+  invalidate: 1e4,
+  /** `UPLOAD_FILE` — large payloads + presigned S3 PUT take a while. */
+  upload: 12e4
+};
+function resolveRequestTimeout(type, requestTimeout) {
+  if (requestTimeout !== void 0) return requestTimeout;
+  switch (type) {
+    case "UPLOAD_FILE":
+      return DEFAULT_TIMEOUTS.upload;
+    case "INVALIDATE_CACHE":
+      return DEFAULT_TIMEOUTS.invalidate;
+    case "GET_CONTEXT":
+      return DEFAULT_TIMEOUTS.context;
+    default:
+      return DEFAULT_TIMEOUTS.api;
+  }
+}
+
+// src/VibeAppBridge.ts
+var VibeAppBridge = class extends BridgeDataMethods {
+  constructor({ parentOrigin, requestTimeout }) {
+    super();
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.context = null;
+    this.connectPromise = null;
+    this.connectPollInterval = null;
+    this.onContextReceived = null;
+    this.onContextError = null;
+    /**
+     * Request ids of the current connect()'s GET_CONTEXT polls. Used to ignore a
+     * late response from a *previous* connect attempt, which would otherwise
+     * resolve/reject the new one (a stale error could reject a healthy reconnect).
+     */
+    this.connectPollIds = /* @__PURE__ */ new Set();
+    this.lastReportedSubroute = null;
+    this.suppressSubrouteReport = false;
+    this.subrouteCallback = null;
+    this.origPushState = null;
+    this.origReplaceState = null;
+    this.popstateHandler = null;
+    this.kindHandlers = {
+      response: (msg) => this.handleResponse(msg),
+      push: (msg) => this.dispatchPush(msg),
+      progress: (msg) => this.handleProgress(msg)
+    };
+    this.pushHandlers = {
+      CONTEXT_PUSH: (payload) => this.onContextReceived?.(payload),
+      SUBROUTE_PUSH: (payload) => {
+        const safe = normalizeSubroute(payload.subroute);
+        if (!safe) return;
+        this.withSubrouteSuppressed(() => {
+          if (this.subrouteCallback) {
+            this.subrouteCallback(safe);
+          } else {
+            history.pushState(null, "", safe);
+            window.dispatchEvent(new PopStateEvent("popstate"));
+          }
+          this.lastReportedSubroute = safe;
+        });
+      }
+    };
+    /**
+     * Commands targeting the host's UI chrome. All fire-and-forget.
+     *
+     * @example
+     * ```ts
+     * bridge.ui.setSideNav({ collapsed: true })
+     * bridge.ui.switchSubsidiary(42)
+     * ```
+     */
+    this.ui = {
+      /** Collapse or expand the host's side navigation. */
+      setSideNav: (payload) => {
+        this.sendCommand("SET_SIDE_NAV", payload);
+      },
+      /** Switch the host to a different subsidiary. */
+      switchSubsidiary: (subsidiaryId) => {
+        this.sendCommand("SWITCH_SUBSIDIARY", { subsidiaryId });
+      }
+    };
+    this.parentOrigin = parentOrigin;
+    this.requestTimeout = requestTimeout;
+    this.boundHandleMessage = this.handleMessage.bind(this);
+    window.addEventListener("message", this.boundHandleMessage);
+  }
+  dispatchPush(msg) {
+    const handler = this.pushHandlers[msg.type];
+    handler(msg.payload);
+  }
+  /**
+   * Connects to the host and returns the tenant/user {@link ContextPayload}.
+   * **Call this once on app init and await it before any other method** — data
+   * methods, `upload()`, and subroute reporting all require an established
+   * connection. Concurrent calls return the same promise.
+   *
+   * Actively polls the host every 500ms until a response arrives, which
+   * handles the race condition where the host's initial context push arrives
+   * before this listener is ready. Rejects with `Bridge connect timed out`
+   * after 10 seconds if no context arrives (usually a `parentOrigin` mismatch
+   * or the host hasn't mounted).
+   *
+   * After connecting, if the context includes an initial subroute (e.g. from
+   * a deep link), the bridge navigates to it and starts auto-tracking
+   * internal navigation via the history API.
+   *
+   * @returns The tenant/user/subsidiary context for this app session.
+   * @throws If no context is received within 10 seconds.
+   * @example
+   * ```ts
+   * const ctx = await bridge.connect()
+   * // ctx.tenant, ctx.subsidiaryId, ctx.subsidiaries, ctx.user, ctx.lastClosedPeriodSlug
+   * ```
+   */
+  connect() {
+    if (this.context) return Promise.resolve(this.context);
+    if (this.connectPromise) return this.connectPromise;
+    this.connectPromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.stopConnectPolling();
+        this.connectPromise = null;
+        this.onContextReceived = null;
+        this.onContextError = null;
+        reject(new BridgeError("TIMEOUT", "Bridge connect timed out"));
+      }, CONNECT_TIMEOUT_MS);
+      this.onContextError = (error) => {
+        clearTimeout(timer);
+        this.stopConnectPolling();
+        this.connectPromise = null;
+        this.onContextReceived = null;
+        this.onContextError = null;
+        reject(error);
+      };
+      this.onContextReceived = (ctx) => {
+        clearTimeout(timer);
+        this.stopConnectPolling();
+        this.context = ctx;
+        this.connectPromise = null;
+        this.onContextReceived = null;
+        this.onContextError = null;
+        console.log(
+          `[vibe-bridge] Connected \u2014 bridge: ${version}, host: ${ctx.hostVersion}, tenant: ${ctx.tenant}, user: ${ctx.user.displayName}`
+        );
+        const initialSubroute = ctx.subroute ? normalizeSubroute(ctx.subroute) : null;
+        if (initialSubroute && initialSubroute !== "/") {
+          this.withSubrouteSuppressed(() => {
+            history.replaceState(null, "", initialSubroute);
+            window.dispatchEvent(new PopStateEvent("popstate"));
+            this.lastReportedSubroute = initialSubroute;
+          });
+        } else {
+          this.lastReportedSubroute = window.location.pathname + window.location.search;
+        }
+        this.setupNavigationTracking();
+        resolve(ctx);
+      };
+      const poll = () => {
+        const requestId = crypto.randomUUID();
+        this.connectPollIds.add(requestId);
+        const message = {
+          __protocol: PROTOCOL_ID,
+          __version: PROTOCOL_VERSION,
+          kind: "request",
+          type: "GET_CONTEXT",
+          requestId,
+          payload: { bridgeVersion: version }
+        };
+        window.parent.postMessage(message, this.parentOrigin);
+      };
+      poll();
+      this.connectPollInterval = setInterval(poll, CONNECT_POLL_MS);
+    });
+    return this.connectPromise;
+  }
   /**
    * Manually reports the current subroute to the host.
    * Usually not needed — navigation is auto-detected via the history API.
    * Use this for hash-based routers or non-standard navigation patterns.
    */
   reportSubroute(subroute, options) {
-    const normalized = subroute.startsWith("/") ? subroute : `/${subroute}`;
+    const normalized = normalizeSubroute(subroute);
+    if (normalized === null) return;
     this.lastReportedSubroute = normalized;
     this.sendCommand("REPORT_SUBROUTE", { subroute: normalized, replace: options?.replace });
   }
@@ -438,17 +539,68 @@ var VibeAppBridge = class {
       this.subrouteCallback = null;
     };
   }
+  // ---------------------------------------------------------------------------
+  // Host navigation & UI commands
+  //
+  // These drive the *host* (nom-ui) chrome — its router, side nav, and
+  // subsidiary switcher — rather than the iframe's own internal routing
+  // (`reportSubroute`). Navigation/UI commands are fire-and-forget;
+  // `invalidateCache` is awaited.
+  // ---------------------------------------------------------------------------
+  /**
+   * Navigates the host to a raw path relative to this app's tenant/subsidiary
+   * base. Fire-and-forget.
+   *
+   * @example
+   * ```ts
+   * bridge.navigate('/journal-entries/123')
+   * bridge.navigate('/journal-entries/123', 'replace')
+   * ```
+   */
+  navigate(path, action = "push") {
+    this.sendCommand("NAVIGATE", { path, action });
+  }
+  /**
+   * Navigates the host to a named Nominal route, with optional params for
+   * placeholder segments. Fire-and-forget.
+   *
+   * @example
+   * ```ts
+   * bridge.navigateTo('CHART_OF_ACCOUNTS')
+   * bridge.navigateTo('JOURNAL_ENTRY', { id: '123' }, 'replace')
+   * ```
+   */
+  navigateTo(route, routeParams, action = "push") {
+    this.sendCommand("NAVIGATE", { route, routeParams, action });
+  }
+  /** Refreshes the host's current route (re-fetches its server data). Fire-and-forget. */
+  refresh() {
+    this.sendCommand("NAVIGATE", { action: "refresh" });
+  }
+  /**
+   * Asks the host to invalidate cached data by path prefix and/or cache tag so
+   * subsequent reads see fresh values. Awaited.
+   *
+   * @example
+   * ```ts
+   * await bridge.invalidateCache({ tags: ['SUBSIDIARIES'], paths: ['/accounting/accounts'] })
+   * ```
+   */
+  invalidateCache(payload) {
+    return this.request("INVALIDATE_CACHE", payload);
+  }
   destroy() {
     this.teardownNavigationTracking();
     this.stopConnectPolling();
     window.removeEventListener("message", this.boundHandleMessage);
     for (const pending of this.pendingRequests.values()) {
-      pending.reject(new Error("Bridge destroyed"));
+      pending.reject(new BridgeError("DESTROYED", "Bridge destroyed"));
     }
     this.pendingRequests.clear();
     this.context = null;
     this.connectPromise = null;
     this.onContextReceived = null;
+    this.onContextError = null;
     this.subrouteCallback = null;
     this.lastReportedSubroute = null;
   }
@@ -457,6 +609,7 @@ var VibeAppBridge = class {
       clearInterval(this.connectPollInterval);
       this.connectPollInterval = null;
     }
+    this.connectPollIds.clear();
   }
   /**
    * Monkey-patches `history.pushState` and `history.replaceState` to
@@ -505,7 +658,8 @@ var VibeAppBridge = class {
   }
   reportCurrentSubroute(replace) {
     if (this.suppressSubrouteReport) return;
-    const subroute = window.location.pathname + window.location.search;
+    const subroute = normalizeSubroute(window.location.pathname + window.location.search);
+    if (subroute === null) return;
     if (subroute === this.lastReportedSubroute) return;
     this.lastReportedSubroute = subroute;
     this.sendCommand("REPORT_SUBROUTE", { subroute, replace });
@@ -531,10 +685,13 @@ var VibeAppBridge = class {
   request(type, payload, onProgress) {
     return new Promise((resolve, reject) => {
       const requestId = crypto.randomUUID();
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(requestId);
-        reject(new Error(`Vibe bridge request timed out: ${type}`));
-      }, this.requestTimeout);
+      const timer = setTimeout(
+        () => {
+          this.pendingRequests.delete(requestId);
+          reject(new BridgeError("TIMEOUT", `Vibe bridge request timed out: ${type}`));
+        },
+        resolveRequestTimeout(type, this.requestTimeout)
+      );
       this.pendingRequests.set(requestId, {
         resolve: (data) => {
           clearTimeout(timer);
@@ -564,7 +721,12 @@ var VibeAppBridge = class {
   }
   handleResponse(msg) {
     if (msg.type === "GET_CONTEXT") {
-      if (msg.ok) this.onContextReceived?.(msg.data);
+      if (!this.connectPollIds.has(msg.requestId)) return;
+      if (msg.ok) {
+        this.onContextReceived?.(msg.data);
+      } else {
+        this.onContextError?.(new BridgeError(msg.code ?? "CONTEXT_ERROR", msg.error));
+      }
       return;
     }
     const pending = this.pendingRequests.get(msg.requestId);
@@ -572,6 +734,10 @@ var VibeAppBridge = class {
     this.pendingRequests.delete(msg.requestId);
     if (msg.ok) {
       pending.resolve(msg.data);
+    } else if (msg.status !== void 0) {
+      pending.reject(new HttpBridgeError(msg.status, msg.error));
+    } else if (msg.code) {
+      pending.reject(new BridgeError(msg.code, msg.error));
     } else {
       pending.reject(new Error(msg.error));
     }
@@ -583,5 +749,7 @@ var VibeAppBridge = class {
 };
 export {
   version as BRIDGE_VERSION,
+  BridgeError,
+  HttpBridgeError,
   VibeAppBridge
 };

package/docs/connect-lifecycle.md

@@ -32,7 +32,7 @@ The host pushes context to the iframe on load, but the iframe's listener may not
 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 `Bridge connect timed out`.
+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.
 
@@ -53,4 +53,4 @@ After connecting, the bridge monkey-patches `history.pushState`/`replaceState` t
 bridge.destroy()
 ```
 
-Removes listeners, rejects pending requests with `Bridge destroyed`, and restores the original history methods. Call it on unmount.
+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

@@ -39,15 +39,20 @@ 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 })`.
+- 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)
 }
 ```

package/docs/file-upload.md

@@ -25,6 +25,8 @@ Sandboxed cross-origin iframes cannot pass `File` handles across windows, so the
 ## 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 () => {
@@ -40,9 +42,14 @@ input.addEventListener('change', async () => {
     })
     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.
+`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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nominalso/vibe-bridge",
-  "version": "0.1.0",
+  "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",
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",