@nominalso/vibe-bridge 0.0.1 → 0.2.0

package/dist/index.cjs

@@ -21,14 +21,28 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BRIDGE_VERSION: () => version,
+  BridgeError: () => BridgeError,
+  HttpBridgeError: () => HttpBridgeError,
   VibeAppBridge: () => VibeAppBridge
 });
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.0.1";
+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"];
@@ -45,17 +59,353 @@ function isBridgeMessage(data) {
   if (CORRELATED_KINDS_SET.has(d.kind) && typeof d.requestId !== "string") return false;
   return true;
 }
+var BridgeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "BridgeError";
+  }
+};
+var HttpBridgeError = class extends BridgeError {
+  constructor(status, message) {
+    super("REQUEST_FAILED", message);
+    this.status = status;
+    this.name = "HttpBridgeError";
+  }
+};
 
-// src/VibeAppBridge.ts
+// src/data-methods.ts
+var BridgeDataMethods = class {
+  // ---------------------------------------------------------------------------
+  // Operations — Accounting: chart of accounts
+  //
+  // Each method is a typed wrapper over `request('<OP>', payload)`. The payload
+  // and return types come straight from the Nominal API (`RequestRegistry`).
+  // For any operation without a named method, call `request('<OP>', payload)`.
+  // ---------------------------------------------------------------------------
+  /**
+   * Fetch the flat chart of accounts for a subsidiary.
+   *
+   * @example
+   * ```ts
+   * const ctx = await bridge.connect()
+   * const accounts = await bridge.getChartOfAccounts({
+   *   path: { subsidiary_id: ctx.subsidiaryId },
+   * })
+   * ```
+   */
+  getChartOfAccounts(payload) {
+    return this.request("GET_CHART_OF_ACCOUNTS", payload);
+  }
+  /** Fetch the chart of accounts as a hierarchical tree for a subsidiary. */
+  getCoaTree(payload) {
+    return this.request("GET_COA_TREE", payload);
+  }
+  /** Fetch a simplified flat chart of accounts for a subsidiary. */
+  getCoaFlatSimple(payload) {
+    return this.request("GET_COA_FLAT_SIMPLE", payload);
+  }
+  /** Fetch the flat chart of accounts grouped by account group. */
+  getCoaGrouped(payload) {
+    return this.request("GET_COA_GROUPED", payload);
+  }
+  /** Fetch a single chart-of-accounts account by id within a subsidiary. */
+  getCoaAccount(payload) {
+    return this.request("GET_COA_ACCOUNT", payload);
+  }
+  /** List the currencies available to a subsidiary's chart of accounts. */
+  getSubsidiaryAvailableCurrencies(payload) {
+    return this.request("GET_SUBSIDIARY_AVAILABLE_CURRENCIES", payload);
+  }
+  /** Fetch accounts at the tenant level. */
+  getAccounts(payload) {
+    return this.request("GET_ACCOUNTS", payload);
+  }
+  /** Fetch a single account by id. */
+  getAccount(payload) {
+    return this.request("GET_ACCOUNT", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Accounting: exchange rates
+  // ---------------------------------------------------------------------------
+  /** Fetch currency conversion rates for a currency. */
+  getConversionRates(payload) {
+    return this.request("GET_CONVERSION_RATES", payload);
+  }
+  /** Fetch the effective consolidation exchange rate. */
+  getEffectiveExchangeRate(payload) {
+    return this.request("GET_EFFECTIVE_EXCHANGE_RATE", payload);
+  }
+  /** Fetch the exchange-rate period covering a given input date. */
+  getExchangeRateByDate(payload) {
+    return this.request("GET_EXCHANGE_RATE_BY_DATE", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Accounting: dimensions
+  // ---------------------------------------------------------------------------
+  /** List accounting dimensions. */
+  getDimensions(payload) {
+    return this.request("GET_DIMENSIONS", payload);
+  }
+  /** List values for accounting dimensions. */
+  getDimensionValues(payload) {
+    return this.request("GET_DIMENSION_VALUES", payload);
+  }
+  /** List dimension values in hierarchical form. */
+  getDimensionValuesHierarchical(payload) {
+    return this.request("GET_DIMENSION_VALUES_HIERARCHICAL", payload);
+  }
+  /** List account assignments for a dimension/account pair. */
+  getDimensionAccountAssignments(payload) {
+    return this.request("GET_DIMENSION_ACCOUNT_ASSIGNMENTS", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Accounting: journal entries
+  // ---------------------------------------------------------------------------
+  /**
+   * Fetch journal entries for a subsidiary, optionally filtered by date range.
+   *
+   * @example
+   * ```ts
+   * const entries = await bridge.getJournalEntries({
+   *   path: { subsidiary_id: ctx.subsidiaryId },
+   *   query: { from_date: '2026-01-01', to_date: '2026-03-31' },
+   * })
+   * ```
+   */
+  getJournalEntries(payload) {
+    return this.request("GET_JOURNAL_ENTRIES", payload);
+  }
+  /** Fetch journal entry lines for a subsidiary. */
+  getJournalLines(payload) {
+    return this.request("GET_JOURNAL_LINES", payload);
+  }
+  /** Fetch a single journal entry by id within a subsidiary. */
+  getJournalEntry(payload) {
+    return this.request("GET_JOURNAL_ENTRY", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Activity: period instances
+  // ---------------------------------------------------------------------------
+  /** List accounting period instances. */
+  getPeriods(payload) {
+    return this.request("GET_PERIODS", payload);
+  }
+  /** Fetch a single period instance by id. */
+  getPeriodInstance(payload) {
+    return this.request("GET_PERIOD_INSTANCE", payload);
+  }
+  /** Fetch a period instance by its display slug (e.g. `"mar-2026"`). */
+  getPeriodInstanceBySlug(payload) {
+    return this.request("GET_PERIOD_INSTANCE_BY_SLUG", payload);
+  }
+  /** Fetch the close-progress breakdown for a period (by slug). */
+  getPeriodProgressBreakdown(payload) {
+    return this.request("GET_PERIOD_PROGRESS_BREAKDOWN", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Activity: activity definitions
+  // ---------------------------------------------------------------------------
+  /** List activity definitions. */
+  getActivityDefinitions(payload) {
+    return this.request("GET_ACTIVITY_DEFINITIONS", payload);
+  }
+  /** Fetch a single activity definition by id. */
+  getActivityDefinition(payload) {
+    return this.request("GET_ACTIVITY_DEFINITION", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Activity: activity instances
+  // ---------------------------------------------------------------------------
+  /** List activity instances. */
+  getActivityInstances(payload) {
+    return this.request("GET_ACTIVITY_INSTANCES", payload);
+  }
+  /** Fetch a single activity instance by id. */
+  getActivityInstance(payload) {
+    return this.request("GET_ACTIVITY_INSTANCE", payload);
+  }
+  /** Fetch an activity instance for a given period + activity definition. */
+  getActivityInstanceByPeriod(payload) {
+    return this.request("GET_ACTIVITY_INSTANCE_BY_PERIOD", payload);
+  }
+  /** List task instances for an activity instance. */
+  getActivityInstanceTasks(payload) {
+    return this.request("GET_ACTIVITY_INSTANCE_TASKS", payload);
+  }
+  /** List task instances for an activity in a given period. */
+  getActivityPeriodTasks(payload) {
+    return this.request("GET_ACTIVITY_PERIOD_TASKS", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Activity: task definitions
+  // ---------------------------------------------------------------------------
+  /** List task definitions. */
+  getTaskDefinitions(payload) {
+    return this.request("GET_TASK_DEFINITIONS", payload);
+  }
+  /** Fetch a single task definition by id. */
+  getTaskDefinition(payload) {
+    return this.request("GET_TASK_DEFINITION", payload);
+  }
+  /** Create a task definition. */
+  createTaskDefinition(payload) {
+    return this.request("CREATE_TASK_DEFINITION", payload);
+  }
+  /** Update a task definition by id. */
+  updateTaskDefinition(payload) {
+    return this.request("UPDATE_TASK_DEFINITION", payload);
+  }
+  /** Query task definitions by filter. */
+  getTaskDefinitionsByFilter(payload) {
+    return this.request("GET_TASK_DEFINITIONS_BY_FILTER", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Activity: task instances
+  // ---------------------------------------------------------------------------
+  /** List task instances. */
+  getTaskInstances(payload) {
+    return this.request("GET_TASK_INSTANCES", payload);
+  }
+  /** Fetch a single task instance by id. */
+  getTaskInstance(payload) {
+    return this.request("GET_TASK_INSTANCE", payload);
+  }
+  /**
+   * Submit a Close-Management task output. This is the **only write path** back
+   * into Nominal — Vibe Apps never write Nominal data directly.
+   *
+   * @example
+   * ```ts
+   * // `body` carries the task-specific output shape.
+   * await bridge.postTaskOutput({
+   *   path: { task_instance_id: 'task-1' },
+   *   body: {},
+   * })
+   * ```
+   */
+  postTaskOutput(payload) {
+    return this.request("POST_TASK_OUTPUT", payload);
+  }
+  /** Query task instances by filter. */
+  getTaskInstancesByFilter(payload) {
+    return this.request("GET_TASK_INSTANCES_BY_FILTER", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Audit trail
+  // ---------------------------------------------------------------------------
+  /** List audit-trail events. */
+  getAuditEvents(payload) {
+    return this.request("GET_AUDIT_EVENTS", payload);
+  }
+  /** List audit-trail events for a specific entity. */
+  getEntityAuditEvents(payload) {
+    return this.request("GET_ENTITY_AUDIT_EVENTS", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Period manager: fiscal calendars
+  // ---------------------------------------------------------------------------
+  /** List fiscal calendars for a subsidiary. */
+  getFiscalCalendars(payload) {
+    return this.request("GET_FISCAL_CALENDARS", payload);
+  }
+  /** Fetch a single fiscal calendar by id. */
+  getFiscalCalendar(payload) {
+    return this.request("GET_FISCAL_CALENDAR", payload);
+  }
+  // ---------------------------------------------------------------------------
+  // Operations — Tenancy
+  // ---------------------------------------------------------------------------
+  /** List subsidiaries for the tenant. */
+  getSubsidiaries(payload) {
+    return this.request("GET_SUBSIDIARIES", payload);
+  }
+  /** Fetch a single subsidiary by id. */
+  getSubsidiary(payload) {
+    return this.request("GET_SUBSIDIARY", payload);
+  }
+  /** List parent currencies for a subsidiary. */
+  getSubsidiaryParentCurrencies(payload) {
+    return this.request("GET_SUBSIDIARY_PARENT_CURRENCIES", payload);
+  }
+  /** List users for the tenant. */
+  getTenantUsers(payload) {
+    return this.request("GET_TENANT_USERS", payload);
+  }
+  /**
+   * Uploads a file through the host. Converts the `File` to an `ArrayBuffer`
+   * before sending — sandboxed iframes cannot pass `File` handles across
+   * windows. Resolves once Nominal has stored the file.
+   *
+   * @example
+   * ```ts
+   * const input = document.querySelector<HTMLInputElement>('#file')!
+   * const file = input.files![0]
+   * const result = await bridge.upload(file, {
+   *   entityType: 'JOURNAL_ENTRY',
+   *   entityId: '123',
+   *   onProgress: (p) => console.log(`${p.progress}%`),
+   * })
+   * // result.attachmentId, result.name
+   * ```
+   */
+  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);
+  }
+};
+
+// src/timeouts.ts
 var CONNECT_TIMEOUT_MS = 1e4;
 var CONNECT_POLL_MS = 500;
-var VibeAppBridge = class {
-  constructor({ parentOrigin, requestTimeout = 1e4 }) {
+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;
@@ -69,15 +419,38 @@ var VibeAppBridge = class {
     };
     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;
-      })
+      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;
@@ -89,16 +462,28 @@ var VibeAppBridge = class {
     handler(msg.payload);
   }
   /**
-   * Connects to the host and returns the tenant/user context.
-   * Call once on app init — concurrent calls return the same promise.
+   * 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.
+   * 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);
@@ -107,22 +492,34 @@ var VibeAppBridge = class {
       const timer = setTimeout(() => {
         this.stopConnectPolling();
         this.connectPromise = null;
-        reject(new Error("Bridge connect timed out"));
+        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}`
         );
-        if (ctx.subroute && ctx.subroute !== "/") {
+        const initialSubroute = ctx.subroute ? normalizeSubroute(ctx.subroute) : null;
+        if (initialSubroute && initialSubroute !== "/") {
           this.withSubrouteSuppressed(() => {
-            history.replaceState(null, "", ctx.subroute);
+            history.replaceState(null, "", initialSubroute);
             window.dispatchEvent(new PopStateEvent("popstate"));
-            this.lastReportedSubroute = ctx.subroute;
+            this.lastReportedSubroute = initialSubroute;
           });
         } else {
           this.lastReportedSubroute = window.location.pathname + window.location.search;
@@ -131,12 +528,14 @@ var VibeAppBridge = class {
         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: crypto.randomUUID(),
+          requestId,
           payload: { bridgeVersion: version }
         };
         window.parent.postMessage(message, this.parentOrigin);
@@ -146,47 +545,14 @@ var VibeAppBridge = class {
     });
     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}`;
+    const normalized = normalizeSubroute(subroute);
+    if (normalized === null) return;
     this.lastReportedSubroute = normalized;
     this.sendCommand("REPORT_SUBROUTE", { subroute: normalized, replace: options?.replace });
   }
@@ -202,17 +568,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;
   }
@@ -221,6 +638,7 @@ var VibeAppBridge = class {
       clearInterval(this.connectPollInterval);
       this.connectPollInterval = null;
     }
+    this.connectPollIds.clear();
   }
   /**
    * Monkey-patches `history.pushState` and `history.replaceState` to
@@ -269,7 +687,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 });
@@ -280,13 +699,28 @@ var VibeAppBridge = class {
       this.parentOrigin
     );
   }
+  /**
+   * Low-level typed request for **any** operation in {@link RequestRegistry}.
+   * The named methods (e.g. {@link VibeAppBridge.getChartOfAccounts}) wrap this;
+   * use it directly for operations without a named method, or to pass an
+   * `onProgress` callback. `type` autocompletes to every operation name and
+   * narrows `payload`/return to that operation's types.
+   *
+   * @example
+   * ```ts
+   * const accounts = await bridge.request('GET_ACCOUNTS', { query: { account_ids: ['acc-1'] } })
+   * ```
+   */
   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);
@@ -316,7 +750,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);
@@ -324,6 +763,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));
     }
@@ -336,5 +779,7 @@ var VibeAppBridge = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BRIDGE_VERSION,
+  BridgeError,
+  HttpBridgeError,
   VibeAppBridge
 });