@nominalso/vibe-bridge 0.0.1

package/dist/index.js

@@ -0,0 +1,312 @@
+// 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);
+  }
+};
+export {
+  version as BRIDGE_VERSION,
+  VibeAppBridge
+};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@nominalso/vibe-bridge",
+  "version": "0.0.1",
+  "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "github:nominalso/vibe-apps-sdk",
+    "directory": "packages/bridge"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@nominalso/vibe-api-types": "0.0.1",
+    "@nominalso/vibe-protocol-types": "0.0.1"
+  },
+  "tsup": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "cjs",
+      "esm"
+    ],
+    "noExternal": [
+      "@nominalso/vibe-protocol-types",
+      "@nominalso/vibe-api-types"
+    ],
+    "dts": {
+      "resolve": [
+        "@nominalso/vibe-protocol-types",
+        "@nominalso/vibe-api-types"
+      ]
+    },
+    "clean": true
+  },
+  "scripts": {
+    "clean": "rm -rf dist node_modules",
+    "build": "tsup",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}