@nominalso/vibe-bridge 0.0.1 → 0.2.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-var version = "0.0.1";
+var version = "0.2.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,16 +3446,262 @@ interface RequestRegistry {
     };
 }
 
-interface VibeAppBridgeOptions {
-    parentOrigin: string;
-    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;
+    /** Id of the entity the file attaches to, when applicable. */
     entityId?: string | number;
+    /** Called with incremental progress (`0`–`100`) while the upload streams. */
     onProgress?: (p: RequestRegistry['UPLOAD_FILE']['progress']) => void;
 }
-declare class VibeAppBridge {
+/**
+ * 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 abstract class BridgeDataMethods {
+    /**
+     * Low-level typed request for **any** operation in {@link RequestRegistry} —
+     * implemented by {@link VibeAppBridge}. The named methods below wrap this.
+     */
+    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.
+     *
+     * @example
+     * ```ts
+     * const ctx = await bridge.connect()
+     * const accounts = await bridge.getChartOfAccounts({
+     *   path: { subsidiary_id: ctx.subsidiaryId },
+     * })
+     * ```
+     */
+    getChartOfAccounts(payload: RequestRegistry['GET_CHART_OF_ACCOUNTS']['payload']): Promise<RequestRegistry['GET_CHART_OF_ACCOUNTS']['data']>;
+    /** Fetch the chart of accounts as a hierarchical tree for a subsidiary. */
+    getCoaTree(payload: RequestRegistry['GET_COA_TREE']['payload']): Promise<RequestRegistry['GET_COA_TREE']['data']>;
+    /** Fetch a simplified flat chart of accounts for a subsidiary. */
+    getCoaFlatSimple(payload: RequestRegistry['GET_COA_FLAT_SIMPLE']['payload']): Promise<RequestRegistry['GET_COA_FLAT_SIMPLE']['data']>;
+    /** Fetch the flat chart of accounts grouped by account group. */
+    getCoaGrouped(payload: RequestRegistry['GET_COA_GROUPED']['payload']): Promise<RequestRegistry['GET_COA_GROUPED']['data']>;
+    /** Fetch a single chart-of-accounts account by id within a subsidiary. */
+    getCoaAccount(payload: RequestRegistry['GET_COA_ACCOUNT']['payload']): Promise<RequestRegistry['GET_COA_ACCOUNT']['data']>;
+    /** List the currencies available to a subsidiary's chart of accounts. */
+    getSubsidiaryAvailableCurrencies(payload: RequestRegistry['GET_SUBSIDIARY_AVAILABLE_CURRENCIES']['payload']): Promise<RequestRegistry['GET_SUBSIDIARY_AVAILABLE_CURRENCIES']['data']>;
+    /** Fetch accounts at the tenant level. */
+    getAccounts(payload: RequestRegistry['GET_ACCOUNTS']['payload']): Promise<RequestRegistry['GET_ACCOUNTS']['data']>;
+    /** Fetch a single account by id. */
+    getAccount(payload: RequestRegistry['GET_ACCOUNT']['payload']): Promise<RequestRegistry['GET_ACCOUNT']['data']>;
+    /** Fetch currency conversion rates for a currency. */
+    getConversionRates(payload: RequestRegistry['GET_CONVERSION_RATES']['payload']): Promise<RequestRegistry['GET_CONVERSION_RATES']['data']>;
+    /** Fetch the effective consolidation exchange rate. */
+    getEffectiveExchangeRate(payload: RequestRegistry['GET_EFFECTIVE_EXCHANGE_RATE']['payload']): Promise<RequestRegistry['GET_EFFECTIVE_EXCHANGE_RATE']['data']>;
+    /** Fetch the exchange-rate period covering a given input date. */
+    getExchangeRateByDate(payload: RequestRegistry['GET_EXCHANGE_RATE_BY_DATE']['payload']): Promise<RequestRegistry['GET_EXCHANGE_RATE_BY_DATE']['data']>;
+    /** List accounting dimensions. */
+    getDimensions(payload: RequestRegistry['GET_DIMENSIONS']['payload']): Promise<RequestRegistry['GET_DIMENSIONS']['data']>;
+    /** List values for accounting dimensions. */
+    getDimensionValues(payload: RequestRegistry['GET_DIMENSION_VALUES']['payload']): Promise<RequestRegistry['GET_DIMENSION_VALUES']['data']>;
+    /** List dimension values in hierarchical form. */
+    getDimensionValuesHierarchical(payload: RequestRegistry['GET_DIMENSION_VALUES_HIERARCHICAL']['payload']): Promise<RequestRegistry['GET_DIMENSION_VALUES_HIERARCHICAL']['data']>;
+    /** List account assignments for a dimension/account pair. */
+    getDimensionAccountAssignments(payload: RequestRegistry['GET_DIMENSION_ACCOUNT_ASSIGNMENTS']['payload']): Promise<RequestRegistry['GET_DIMENSION_ACCOUNT_ASSIGNMENTS']['data']>;
+    /**
+     * 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: RequestRegistry['GET_JOURNAL_ENTRIES']['payload']): Promise<RequestRegistry['GET_JOURNAL_ENTRIES']['data']>;
+    /** Fetch journal entry lines for a subsidiary. */
+    getJournalLines(payload: RequestRegistry['GET_JOURNAL_LINES']['payload']): Promise<RequestRegistry['GET_JOURNAL_LINES']['data']>;
+    /** Fetch a single journal entry by id within a subsidiary. */
+    getJournalEntry(payload: RequestRegistry['GET_JOURNAL_ENTRY']['payload']): Promise<RequestRegistry['GET_JOURNAL_ENTRY']['data']>;
+    /** List accounting period instances. */
+    getPeriods(payload: RequestRegistry['GET_PERIODS']['payload']): Promise<RequestRegistry['GET_PERIODS']['data']>;
+    /** Fetch a single period instance by id. */
+    getPeriodInstance(payload: RequestRegistry['GET_PERIOD_INSTANCE']['payload']): Promise<RequestRegistry['GET_PERIOD_INSTANCE']['data']>;
+    /** Fetch a period instance by its display slug (e.g. `"mar-2026"`). */
+    getPeriodInstanceBySlug(payload: RequestRegistry['GET_PERIOD_INSTANCE_BY_SLUG']['payload']): Promise<RequestRegistry['GET_PERIOD_INSTANCE_BY_SLUG']['data']>;
+    /** Fetch the close-progress breakdown for a period (by slug). */
+    getPeriodProgressBreakdown(payload: RequestRegistry['GET_PERIOD_PROGRESS_BREAKDOWN']['payload']): Promise<RequestRegistry['GET_PERIOD_PROGRESS_BREAKDOWN']['data']>;
+    /** List activity definitions. */
+    getActivityDefinitions(payload: RequestRegistry['GET_ACTIVITY_DEFINITIONS']['payload']): Promise<RequestRegistry['GET_ACTIVITY_DEFINITIONS']['data']>;
+    /** Fetch a single activity definition by id. */
+    getActivityDefinition(payload: RequestRegistry['GET_ACTIVITY_DEFINITION']['payload']): Promise<RequestRegistry['GET_ACTIVITY_DEFINITION']['data']>;
+    /** List activity instances. */
+    getActivityInstances(payload: RequestRegistry['GET_ACTIVITY_INSTANCES']['payload']): Promise<RequestRegistry['GET_ACTIVITY_INSTANCES']['data']>;
+    /** Fetch a single activity instance by id. */
+    getActivityInstance(payload: RequestRegistry['GET_ACTIVITY_INSTANCE']['payload']): Promise<RequestRegistry['GET_ACTIVITY_INSTANCE']['data']>;
+    /** Fetch an activity instance for a given period + activity definition. */
+    getActivityInstanceByPeriod(payload: RequestRegistry['GET_ACTIVITY_INSTANCE_BY_PERIOD']['payload']): Promise<RequestRegistry['GET_ACTIVITY_INSTANCE_BY_PERIOD']['data']>;
+    /** List task instances for an activity instance. */
+    getActivityInstanceTasks(payload: RequestRegistry['GET_ACTIVITY_INSTANCE_TASKS']['payload']): Promise<RequestRegistry['GET_ACTIVITY_INSTANCE_TASKS']['data']>;
+    /** List task instances for an activity in a given period. */
+    getActivityPeriodTasks(payload: RequestRegistry['GET_ACTIVITY_PERIOD_TASKS']['payload']): Promise<RequestRegistry['GET_ACTIVITY_PERIOD_TASKS']['data']>;
+    /** List task definitions. */
+    getTaskDefinitions(payload: RequestRegistry['GET_TASK_DEFINITIONS']['payload']): Promise<RequestRegistry['GET_TASK_DEFINITIONS']['data']>;
+    /** Fetch a single task definition by id. */
+    getTaskDefinition(payload: RequestRegistry['GET_TASK_DEFINITION']['payload']): Promise<RequestRegistry['GET_TASK_DEFINITION']['data']>;
+    /** Create a task definition. */
+    createTaskDefinition(payload: RequestRegistry['CREATE_TASK_DEFINITION']['payload']): Promise<RequestRegistry['CREATE_TASK_DEFINITION']['data']>;
+    /** Update a task definition by id. */
+    updateTaskDefinition(payload: RequestRegistry['UPDATE_TASK_DEFINITION']['payload']): Promise<RequestRegistry['UPDATE_TASK_DEFINITION']['data']>;
+    /** Query task definitions by filter. */
+    getTaskDefinitionsByFilter(payload: RequestRegistry['GET_TASK_DEFINITIONS_BY_FILTER']['payload']): Promise<RequestRegistry['GET_TASK_DEFINITIONS_BY_FILTER']['data']>;
+    /** List task instances. */
+    getTaskInstances(payload: RequestRegistry['GET_TASK_INSTANCES']['payload']): Promise<RequestRegistry['GET_TASK_INSTANCES']['data']>;
+    /** Fetch a single task instance by id. */
+    getTaskInstance(payload: RequestRegistry['GET_TASK_INSTANCE']['payload']): Promise<RequestRegistry['GET_TASK_INSTANCE']['data']>;
+    /**
+     * 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: RequestRegistry['POST_TASK_OUTPUT']['payload']): Promise<RequestRegistry['POST_TASK_OUTPUT']['data']>;
+    /** Query task instances by filter. */
+    getTaskInstancesByFilter(payload: RequestRegistry['GET_TASK_INSTANCES_BY_FILTER']['payload']): Promise<RequestRegistry['GET_TASK_INSTANCES_BY_FILTER']['data']>;
+    /** List audit-trail events. */
+    getAuditEvents(payload: RequestRegistry['GET_AUDIT_EVENTS']['payload']): Promise<RequestRegistry['GET_AUDIT_EVENTS']['data']>;
+    /** List audit-trail events for a specific entity. */
+    getEntityAuditEvents(payload: RequestRegistry['GET_ENTITY_AUDIT_EVENTS']['payload']): Promise<RequestRegistry['GET_ENTITY_AUDIT_EVENTS']['data']>;
+    /** List fiscal calendars for a subsidiary. */
+    getFiscalCalendars(payload: RequestRegistry['GET_FISCAL_CALENDARS']['payload']): Promise<RequestRegistry['GET_FISCAL_CALENDARS']['data']>;
+    /** Fetch a single fiscal calendar by id. */
+    getFiscalCalendar(payload: RequestRegistry['GET_FISCAL_CALENDAR']['payload']): Promise<RequestRegistry['GET_FISCAL_CALENDAR']['data']>;
+    /** List subsidiaries for the tenant. */
+    getSubsidiaries(payload: RequestRegistry['GET_SUBSIDIARIES']['payload']): Promise<RequestRegistry['GET_SUBSIDIARIES']['data']>;
+    /** Fetch a single subsidiary by id. */
+    getSubsidiary(payload: RequestRegistry['GET_SUBSIDIARY']['payload']): Promise<RequestRegistry['GET_SUBSIDIARY']['data']>;
+    /** List parent currencies for a subsidiary. */
+    getSubsidiaryParentCurrencies(payload: RequestRegistry['GET_SUBSIDIARY_PARENT_CURRENCIES']['payload']): Promise<RequestRegistry['GET_SUBSIDIARY_PARENT_CURRENCIES']['data']>;
+    /** List users for the tenant. */
+    getTenantUsers(payload: RequestRegistry['GET_TENANT_USERS']['payload']): Promise<RequestRegistry['GET_TENANT_USERS']['data']>;
+    /**
+     * 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
+     * ```
+     */
+    upload(file: File, options: UploadOptions): Promise<RequestRegistry['UPLOAD_FILE']['data']>;
+}
+
+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;
+    /**
+     * 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 {
     private readonly parentOrigin;
     private readonly requestTimeout;
     private readonly pendingRequests;
@@ -3441,6 +3710,13 @@ declare class VibeAppBridge {
     private connectPromise;
     private connectPollInterval;
     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;
@@ -3452,29 +3728,30 @@ declare class VibeAppBridge {
     private readonly pushHandlers;
     constructor({ parentOrigin, requestTimeout }: VibeAppBridgeOptions);
     /**
-     * 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(): Promise<ContextPayload>;
-    getChartOfAccounts(payload: RequestRegistry['GET_CHART_OF_ACCOUNTS']['payload']): Promise<RequestRegistry['GET_CHART_OF_ACCOUNTS']['data']>;
-    getSubsidiaries(payload: RequestRegistry['GET_SUBSIDIARIES']['payload']): Promise<RequestRegistry['GET_SUBSIDIARIES']['data']>;
-    getPeriods(payload: RequestRegistry['GET_PERIODS']['payload']): Promise<RequestRegistry['GET_PERIODS']['data']>;
-    postTaskOutput(payload: RequestRegistry['POST_TASK_OUTPUT']['payload']): Promise<RequestRegistry['POST_TASK_OUTPUT']['data']>;
-    getJournalEntries(payload: RequestRegistry['GET_JOURNAL_ENTRIES']['payload']): Promise<RequestRegistry['GET_JOURNAL_ENTRIES']['data']>;
-    getJournalLines(payload: RequestRegistry['GET_JOURNAL_LINES']['payload']): Promise<RequestRegistry['GET_JOURNAL_LINES']['data']>;
-    /**
-     * Uploads a file through the host. Converts the File to an ArrayBuffer
-     * before sending — sandboxed iframes cannot pass File handles across windows.
-     */
-    upload(file: File, options: UploadOptions): Promise<RequestRegistry['UPLOAD_FILE']['data']>;
     /**
      * Manually reports the current subroute to the host.
      * Usually not needed — navigation is auto-detected via the history API.
@@ -3490,6 +3767,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;
     /**
@@ -3503,10 +3829,22 @@ declare class VibeAppBridge {
     private withSubrouteSuppressed;
     private reportCurrentSubroute;
     private sendCommand;
+    /**
+     * 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<K extends keyof RequestRegistry>(type: K, payload: RequestRegistry[K]['payload'], onProgress?: (payload: unknown) => void): Promise<RequestRegistry[K]['data']>;
     private handleMessage;
     private handleResponse;
     private handleProgress;
 }
 
-export { version as BRIDGE_VERSION, 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 };