@nominalso/vibe-bridge 0.0.1

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright © 2026 Nominal. All rights reserved.
+
+This software and its source code are proprietary and confidential.
+The packages published from this repository are marked "UNLICENSED": no
+license or right to use, copy, modify, distribute, or create derivative
+works is granted except under a separate written agreement with Nominal.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

package/README.md

@@ -0,0 +1,38 @@
+# @nominalso/vibe-bridge
+
+Iframe-side SDK for building **Nominal Vibe Apps** — standalone web apps (typically built with Lovable) embedded in the Nominal platform via a cross-origin `<iframe>`. The bridge connects your app to its Nominal host over a typed `postMessage` protocol: fetch Nominal data, submit Close-Management task outputs, upload files, and keep deep-link routing in sync.
+
+## Install
+
+```sh
+npm install @nominalso/vibe-bridge
+```
+
+## Usage
+
+```ts
+import { VibeAppBridge } from '@nominalso/vibe-bridge'
+
+const bridge = new VibeAppBridge({
+  // Must match the Nominal app origin exactly.
+  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN,
+})
+
+// Call once on init — resolves when the host context arrives.
+const ctx = await bridge.connect()
+
+const accounts = await bridge.getChartOfAccounts()
+await bridge.postTaskOutput(payload)
+await bridge.upload(file, { entityType: 'JOURNAL_ENTRY', entityId: '123' })
+
+// On unmount
+bridge.destroy()
+```
+
+The host side is [`@nominalso/vibe-host`](https://www.npmjs.com/package/@nominalso/vibe-host). See the
+[repository](https://github.com/nominalso/vibe-apps-sdk#readme) for the full protocol, architecture, and
+`connect()` semantics.
+
+## License
+
+UNLICENSED — proprietary. © Nominal. All rights reserved.

package/dist/index.cjs

@@ -0,0 +1,340 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BRIDGE_VERSION: () => version,
+  VibeAppBridge: () => VibeAppBridge
+});
+module.exports = __toCommonJS(index_exports);
+
+// package.json
+var version = "0.0.1";
+
+// ../protocol-types/dist/index.js
+var PROTOCOL_ID = "nominal-vibe-bridge";
+var PROTOCOL_VERSION = 1;
+var BRIDGE_KINDS = ["request", "response", "push", "command", "progress"];
+var CORRELATED_KINDS = ["request", "response", "progress"];
+var BRIDGE_KINDS_SET = new Set(BRIDGE_KINDS);
+var CORRELATED_KINDS_SET = new Set(CORRELATED_KINDS);
+function isBridgeMessage(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const d = data;
+  if (d.__protocol !== PROTOCOL_ID) return false;
+  if (d.__version !== PROTOCOL_VERSION) return false;
+  if (typeof d.kind !== "string" || !BRIDGE_KINDS_SET.has(d.kind)) return false;
+  if (typeof d.type !== "string") return false;
+  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);
+  }
+  dispatchPush(msg) {
+    const handler = this.pushHandlers[msg.type];
+    handler(msg.payload);
+  }
+  /**
+   * Connects to the host and returns the tenant/user context.
+   * Call once on app init — 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.
+   *
+   * 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.
+   */
+  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;
+  }
+  getChartOfAccounts(payload) {
+    return this.request("GET_CHART_OF_ACCOUNTS", payload);
+  }
+  getSubsidiaries(payload) {
+    return this.request("GET_SUBSIDIARIES", payload);
+  }
+  getPeriods(payload) {
+    return this.request("GET_PERIODS", payload);
+  }
+  postTaskOutput(payload) {
+    return this.request("POST_TASK_OUTPUT", payload);
+  }
+  getJournalEntries(payload) {
+    return this.request("GET_JOURNAL_ENTRIES", payload);
+  }
+  getJournalLines(payload) {
+    return this.request("GET_JOURNAL_LINES", payload);
+  }
+  /**
+   * Uploads a file through the host. Converts the File to an ArrayBuffer
+   * before sending — sandboxed iframes cannot pass File handles across windows.
+   */
+  async upload(file, options) {
+    const buffer = await file.arrayBuffer();
+    const payload = {
+      buffer,
+      fileName: file.name,
+      fileType: file.type,
+      entityType: options.entityType,
+      entityId: options.entityId
+    };
+    const onProgress = options.onProgress ? (p) => options.onProgress(p) : void 0;
+    return this.request("UPLOAD_FILE", payload, onProgress);
+  }
+  /**
+   * 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}`;
+    this.lastReportedSubroute = normalized;
+    this.sendCommand("REPORT_SUBROUTE", { subroute: normalized, replace: options?.replace });
+  }
+  /**
+   * Registers a callback for host-initiated navigation (browser back/forward).
+   * If no callback is registered, the SDK uses `history.pushState` + a
+   * `popstate` event, which works for most SPA routers automatically.
+   * Returns an unsubscribe function.
+   */
+  onSubrouteRequest(callback) {
+    this.subrouteCallback = callback;
+    return () => {
+      this.subrouteCallback = null;
+    };
+  }
+  destroy() {
+    this.teardownNavigationTracking();
+    this.stopConnectPolling();
+    window.removeEventListener("message", this.boundHandleMessage);
+    for (const pending of this.pendingRequests.values()) {
+      pending.reject(new Error("Bridge destroyed"));
+    }
+    this.pendingRequests.clear();
+    this.context = null;
+    this.connectPromise = null;
+    this.onContextReceived = null;
+    this.subrouteCallback = null;
+    this.lastReportedSubroute = null;
+  }
+  stopConnectPolling() {
+    if (this.connectPollInterval !== null) {
+      clearInterval(this.connectPollInterval);
+      this.connectPollInterval = null;
+    }
+  }
+  /**
+   * Monkey-patches `history.pushState` and `history.replaceState` to
+   * auto-detect SPA navigation and report it to the host. Called after
+   * connect() resolves.
+   */
+  setupNavigationTracking() {
+    if (this.origPushState) return;
+    this.origPushState = history.pushState.bind(history);
+    this.origReplaceState = history.replaceState.bind(history);
+    const origPush = this.origPushState;
+    const origReplace = this.origReplaceState;
+    history.pushState = (...args) => {
+      origPush(...args);
+      this.reportCurrentSubroute(false);
+    };
+    history.replaceState = (...args) => {
+      origReplace(...args);
+      this.reportCurrentSubroute(true);
+    };
+    this.popstateHandler = () => this.reportCurrentSubroute(true);
+    window.addEventListener("popstate", this.popstateHandler);
+  }
+  teardownNavigationTracking() {
+    if (this.origPushState) {
+      history.pushState = this.origPushState;
+      this.origPushState = null;
+    }
+    if (this.origReplaceState) {
+      history.replaceState = this.origReplaceState;
+      this.origReplaceState = null;
+    }
+    if (this.popstateHandler) {
+      window.removeEventListener("popstate", this.popstateHandler);
+      this.popstateHandler = null;
+    }
+  }
+  /** Runs `fn` while suppressing subroute auto-reporting to prevent echo loops. */
+  withSubrouteSuppressed(fn) {
+    this.suppressSubrouteReport = true;
+    try {
+      fn();
+    } finally {
+      this.suppressSubrouteReport = false;
+    }
+  }
+  reportCurrentSubroute(replace) {
+    if (this.suppressSubrouteReport) return;
+    const subroute = window.location.pathname + window.location.search;
+    if (subroute === this.lastReportedSubroute) return;
+    this.lastReportedSubroute = subroute;
+    this.sendCommand("REPORT_SUBROUTE", { subroute, replace });
+  }
+  sendCommand(type, payload) {
+    window.parent.postMessage(
+      { __protocol: PROTOCOL_ID, __version: PROTOCOL_VERSION, kind: "command", type, payload },
+      this.parentOrigin
+    );
+  }
+  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);
+      this.pendingRequests.set(requestId, {
+        resolve: (data) => {
+          clearTimeout(timer);
+          resolve(data);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+        onProgress
+      });
+      const message = {
+        __protocol: PROTOCOL_ID,
+        __version: PROTOCOL_VERSION,
+        kind: "request",
+        type,
+        requestId,
+        payload
+      };
+      window.parent.postMessage(message, this.parentOrigin);
+    });
+  }
+  handleMessage(event) {
+    if (event.origin !== this.parentOrigin) return;
+    if (!isBridgeMessage(event.data)) return;
+    this.kindHandlers[event.data.kind]?.(event.data);
+  }
+  handleResponse(msg) {
+    if (msg.type === "GET_CONTEXT") {
+      if (msg.ok) this.onContextReceived?.(msg.data);
+      return;
+    }
+    const pending = this.pendingRequests.get(msg.requestId);
+    if (!pending) return;
+    this.pendingRequests.delete(msg.requestId);
+    if (msg.ok) {
+      pending.resolve(msg.data);
+    } else {
+      pending.reject(new Error(msg.error));
+    }
+  }
+  handleProgress(msg) {
+    const pending = this.pendingRequests.get(msg.requestId);
+    pending?.onProgress?.(msg.payload);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BRIDGE_VERSION,
+  VibeAppBridge
+});