@nominalso/vibe-bridge 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-var version = "0.1.0";
+var version = "0.3.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -3203,15 +3203,6 @@ interface GetContextPayload {
     bridgeVersion: string;
 }
 
-/**
- * All operations the iframe can invoke on the host, each with a typed request
- * payload and a typed response. Adding a new operation here is all that's
- * required — message union types and handler types below are derived
- * automatically.
- *
- * Operations that also emit intermediate progress events should include a
- * `progress` field with the progress payload type.
- */
 interface UploadPayload {
     buffer: ArrayBuffer;
     fileName: string;
@@ -3222,11 +3213,39 @@ interface UploadPayload {
 interface UploadResponse {
     attachmentId: string;
     name: string;
+    /** Public/presigned URL of the stored file, when the host returns one. */
+    url?: string;
 }
 interface UploadProgress {
     attachmentId: string;
     progress: number;
 }
+/** How the host should apply a navigation. Defaults to `'push'`. */
+type NavigateAction = 'push' | 'replace' | 'refresh';
+/** Collapse/expand the host's side navigation. */
+interface SetSideNavPayload {
+    collapsed: boolean;
+}
+/** Targets for a host cache invalidation. */
+interface InvalidateCachePayload {
+    /** API path prefixes to invalidate, e.g. `['/accounting/accounts']`. */
+    paths?: string[];
+    /** Cache tag keys to invalidate, e.g. `['REPORTS', 'SUBSIDIARIES']`. */
+    tags?: string[];
+}
+/** Result of a host cache invalidation. */
+interface InvalidateResult {
+    invalidated: boolean;
+}
+
+/**
+ * All operations the iframe can invoke on the host, each with a typed request
+ * payload and a typed response. Adding a new operation here is all that's
+ * required — message union types and handler types are derived automatically.
+ *
+ * Operations that also emit intermediate progress events should include a
+ * `progress` field with the progress payload type.
+ */
 interface RequestRegistry {
     GET_CHART_OF_ACCOUNTS: {
         payload: Omit<GetCoaFlatApiAccountingSubsidiarySubsidiaryIdCoaAccountGetData, 'url'>;
@@ -3412,6 +3431,10 @@ interface RequestRegistry {
         payload: Omit<GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetData, 'url'>;
         data: GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetResponse;
     };
+    INVALIDATE_CACHE: {
+        payload: InvalidateCachePayload;
+        data: InvalidateResult;
+    };
     GET_CONTEXT: {
         payload: GetContextPayload;
         data: ContextPayload;
@@ -3423,18 +3446,53 @@ interface RequestRegistry {
     };
 }
 
-interface VibeAppBridgeOptions {
-    /**
-     * Origin of the Nominal app embedding this iframe (e.g.
-     * `https://app.nominal.so` or `http://localhost:3000`). Must match the host
-     * origin **exactly** — messages from any other origin are ignored, and the
-     * bridge only `postMessage`s to this origin. Drive it from an env var so the
-     * same code works locally and in production.
-     */
-    parentOrigin: string;
-    /** Per-request timeout in milliseconds before a call rejects. Default `10000`. */
-    requestTimeout?: number;
+/**
+ * An error that crossed the bridge, carrying a machine-readable {@link code}
+ * alongside the human-readable message.
+ *
+ * The host attaches a `code` to failed responses (e.g. `'RATE_LIMITED'`,
+ * `'FILE_TOO_LARGE'`, `'REQUEST_FAILED'`); the bridge rehydrates it into a
+ * `BridgeError` so app `catch` blocks can branch on `error.code` instead of
+ * string-matching `error.message`. A failed Nominal API call rehydrates as the
+ * {@link HttpBridgeError} subtype, which adds the HTTP `status`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccounts({})
+ * } catch (err) {
+ *   if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+ *     // back off and retry
+ *   }
+ * }
+ * ```
+ */
+declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
 }
+/**
+ * A {@link BridgeError} for a failed Nominal API call. Its `code` is always
+ * `'REQUEST_FAILED'`; the HTTP {@link status} is carried as a structured field
+ * so callers can branch on it (e.g. `err.status === 404`) instead of parsing
+ * the code string.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccount({ path: { account_id: 'missing' } })
+ * } catch (err) {
+ *   if (err instanceof HttpBridgeError && err.status === 404) {
+ *     // handle not-found
+ *   }
+ * }
+ * ```
+ */
+declare class HttpBridgeError extends BridgeError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
 interface UploadOptions {
     /** Domain entity the file attaches to, e.g. `'JOURNAL_ENTRY'`. */
     entityType: string;
@@ -3444,72 +3502,17 @@ interface UploadOptions {
     onProgress?: (p: RequestRegistry['UPLOAD_FILE']['progress']) => void;
 }
 /**
- * Iframe-side bridge to the Nominal host. One instance per app: construct it,
- * `await connect()` once, then call data methods, `upload()`, and subroute
- * helpers. Tear down with `destroy()` on unmount.
- *
- * Every data method delegates to {@link VibeAppBridge.request}; the ~46 named
- * methods (e.g. {@link VibeAppBridge.getChartOfAccounts}) are the typed,
- * discoverable surface, and `request('<OP>', payload)` is the escape hatch for
- * any operation in {@link RequestRegistry}.
- *
- * @example
- * ```ts
- * import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
- *
- * const bridge = new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
- *
- * const ctx: ContextPayload = await bridge.connect()
- * const accounts = await bridge.getChartOfAccounts({ path: { subsidiary_id: ctx.subsidiaryId } })
- *
- * // cleanup
- * bridge.destroy()
- * ```
+ * The typed Nominal data methods (~46) plus {@link BridgeDataMethods.upload},
+ * factored onto a base class so {@link VibeAppBridge} stays focused on
+ * connection/transport. Each method is a thin typed wrapper over `request()`;
+ * `VibeAppBridge` provides the concrete `request` implementation.
  */
-declare class VibeAppBridge {
-    private readonly parentOrigin;
-    private readonly requestTimeout;
-    private readonly pendingRequests;
-    private readonly boundHandleMessage;
-    private context;
-    private connectPromise;
-    private connectPollInterval;
-    private onContextReceived;
-    private lastReportedSubroute;
-    private suppressSubrouteReport;
-    private subrouteCallback;
-    private origPushState;
-    private origReplaceState;
-    private popstateHandler;
-    private readonly kindHandlers;
-    private dispatchPush;
-    private readonly pushHandlers;
-    constructor({ parentOrigin, requestTimeout }: VibeAppBridgeOptions);
+declare abstract class BridgeDataMethods {
     /**
-     * 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
-     * ```
+     * Low-level typed request for **any** operation in {@link RequestRegistry} —
+     * implemented by {@link VibeAppBridge}. The named methods below wrap this.
      */
-    connect(): Promise<ContextPayload>;
+    abstract request<K extends keyof RequestRegistry>(type: K, payload: RequestRegistry[K]['payload'], onProgress?: (payload: unknown) => void): Promise<RequestRegistry[K]['data']>;
     /**
      * Fetch the flat chart of accounts for a subsidiary.
      *
@@ -3652,6 +3655,128 @@ declare class VibeAppBridge {
      * ```
      */
     upload(file: File, options: UploadOptions): Promise<RequestRegistry['UPLOAD_FILE']['data']>;
+}
+
+interface VibeAppBridgeOptions {
+    /**
+     * Origin(s) of the Nominal app embedding this iframe. **Optional.**
+     *
+     * **Omit it** (the recommended default) and the bridge auto-detects the
+     * Nominal page that actually embeds it and talks only to that origin. This is
+     * safe because Nominal serves Vibe Apps behind a `frame-ancestors` CSP, so
+     * only nom-ui can frame the app — a hostile site can't embed it to intercept
+     * what the iframe sends out (`postTaskOutput` bodies, file uploads). Most apps
+     * need nothing here.
+     *
+     * Provide a value to **pin explicitly** — defense in depth, or when deploying
+     * outside Nominal's edge:
+     *
+     * ```ts
+     * parentOrigin: 'https://app.nominal.so'                           // one exact origin
+     * parentOrigin: ['https://app.nominal.so', 'https://*.vercel.app']  // exact + preview pattern
+     * ```
+     *
+     * A pattern's `*` matches exactly one DNS label or port — anchored, scheme
+     * literal — so `https://*.vercel.app` matches `https://pr-7.vercel.app` but
+     * not `https://a.b.vercel.app` or `https://pr-7.vercel.app.evil.com`. Patterns
+     * are honoured only when this app's own page is served from a recognised
+     * preview host (`*.vercel.app`, `*.lovable.app`, `localhost`, …); on a
+     * production custom domain only exact origins match.
+     *
+     * If neither an explicit value nor an auto-detected parent is available,
+     * `connect()` rejects with `BridgeError` code `PARENT_ORIGIN_UNRESOLVED`.
+     */
+    parentOrigin?: string | string[];
+    /**
+     * Global per-request timeout in milliseconds before a call rejects with a
+     * `BridgeError` whose `code` is `'TIMEOUT'`.
+     *
+     * When omitted, each operation uses an operation-specific default tuned to
+     * how long it realistically takes (API reads `30000`, `UPLOAD_FILE`
+     * `120000`, `INVALIDATE_CACHE` `10000`, `GET_CONTEXT` `5000`). Setting this
+     * overrides all of them with a single value — only do that if you have a
+     * specific reason; the defaults already match the host's expectations.
+     */
+    requestTimeout?: number;
+}
+/**
+ * Iframe-side bridge to the Nominal host. One instance per app: construct it,
+ * `await connect()` once, then call data methods, `upload()`, and subroute
+ * helpers. Tear down with `destroy()` on unmount.
+ *
+ * Every data method delegates to {@link VibeAppBridge.request}; the ~46 named
+ * methods (e.g. {@link VibeAppBridge.getChartOfAccounts}) are the typed,
+ * discoverable surface, and `request('<OP>', payload)` is the escape hatch for
+ * any operation in {@link RequestRegistry}.
+ *
+ * @example
+ * ```ts
+ * import { VibeAppBridge, type ContextPayload } from '@nominalso/vibe-bridge'
+ *
+ * const bridge = new VibeAppBridge({ parentOrigin: import.meta.env.VITE_PARENT_ORIGIN })
+ *
+ * const ctx: ContextPayload = await bridge.connect()
+ * const accounts = await bridge.getChartOfAccounts({ path: { subsidiary_id: ctx.subsidiaryId } })
+ *
+ * // cleanup
+ * bridge.destroy()
+ * ```
+ */
+declare class VibeAppBridge extends BridgeDataMethods {
+    /** Concrete origin to `postMessage` to, or `null` if none could be resolved. */
+    private readonly targetOrigin;
+    /** Validates an inbound `event.origin` against the configured allowlist. */
+    private readonly isTrustedOrigin;
+    private readonly requestTimeout;
+    private readonly pendingRequests;
+    private readonly boundHandleMessage;
+    private context;
+    private connectPromise;
+    private connectPollInterval;
+    private connectTimeout;
+    private onContextReceived;
+    private onContextError;
+    /**
+     * 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).
+     */
+    private readonly connectPollIds;
+    private lastReportedSubroute;
+    private suppressSubrouteReport;
+    private subrouteCallback;
+    private origPushState;
+    private origReplaceState;
+    private popstateHandler;
+    private readonly kindHandlers;
+    private dispatchPush;
+    private readonly pushHandlers;
+    constructor({ parentOrigin, requestTimeout }?: VibeAppBridgeOptions);
+    /**
+     * 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(): Promise<ContextPayload>;
     /**
      * Manually reports the current subroute to the host.
      * Usually not needed — navigation is auto-detected via the history API.
@@ -3667,6 +3792,55 @@ declare class VibeAppBridge {
      * Returns an unsubscribe function.
      */
     onSubrouteRequest(callback: (subroute: string) => void): () => void;
+    /**
+     * 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: string, action?: NavigateAction): void;
+    /**
+     * 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: string, routeParams?: Record<string, string>, action?: NavigateAction): void;
+    /** Refreshes the host's current route (re-fetches its server data). Fire-and-forget. */
+    refresh(): void;
+    /**
+     * Commands targeting the host's UI chrome. All fire-and-forget.
+     *
+     * @example
+     * ```ts
+     * bridge.ui.setSideNav({ collapsed: true })
+     * bridge.ui.switchSubsidiary(42)
+     * ```
+     */
+    readonly ui: {
+        /** Collapse or expand the host's side navigation. */
+        setSideNav: (payload: SetSideNavPayload) => void;
+        /** Switch the host to a different subsidiary. */
+        switchSubsidiary: (subsidiaryId: number) => void;
+    };
+    /**
+     * 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: InvalidateCachePayload): Promise<InvalidateResult>;
     destroy(): void;
     private stopConnectPolling;
     /**
@@ -3693,9 +3867,15 @@ declare class VibeAppBridge {
      * ```
      */
     request<K extends keyof RequestRegistry>(type: K, payload: RequestRegistry[K]['payload'], onProgress?: (payload: unknown) => void): Promise<RequestRegistry[K]['data']>;
+    /**
+     * Posts to the embedding host. No-op when no concrete target origin could be
+     * resolved (a config/embedding error) — `connect()` rejects fast in that case
+     * so calls never silently hang waiting on a timeout.
+     */
+    private postToParent;
     private handleMessage;
     private handleResponse;
     private handleProgress;
 }
 
-export { version as BRIDGE_VERSION, type BridgeSubsidiary, type ContextPayload, type RequestRegistry, type UploadOptions, type UploadProgress, type UploadResponse, VibeAppBridge, type VibeAppBridgeOptions };
+export { version as BRIDGE_VERSION, BridgeError, type BridgeSubsidiary, type ContextPayload, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type RequestRegistry, type SetSideNavPayload, type UploadOptions, type UploadProgress, type UploadResponse, VibeAppBridge, type VibeAppBridgeOptions };