@nominalso/vibe-bridge 0.0.1 → 0.1.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-var version = "0.0.1";
+var version = "0.1.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -3424,14 +3424,48 @@ 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;
 }
 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;
 }
+/**
+ * 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 {
     private readonly parentOrigin;
     private readonly requestTimeout;
@@ -3452,27 +3486,170 @@ 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>;
+    /**
+     * 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']>;
-    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']>;
+    /** 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.
+     * 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']>;
     /**
@@ -3503,10 +3680,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, type BridgeSubsidiary, type ContextPayload, type RequestRegistry, type UploadOptions, type UploadProgress, type UploadResponse, VibeAppBridge, type VibeAppBridgeOptions };

package/dist/index.js

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.0.1";
+var version = "0.1.0";
 
 // ../protocol-types/dist/index.js
 var PROTOCOL_ID = "nominal-vibe-bridge";
@@ -62,16 +62,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);
@@ -119,27 +131,278 @@ var VibeAppBridge = class {
     });
     return this.connectPromise;
   }
+  // ---------------------------------------------------------------------------
+  // 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);
   }
-  getSubsidiaries(payload) {
-    return this.request("GET_SUBSIDIARIES", payload);
+  /** Fetch the chart of accounts as a hierarchical tree for a subsidiary. */
+  getCoaTree(payload) {
+    return this.request("GET_COA_TREE", payload);
   }
-  getPeriods(payload) {
-    return this.request("GET_PERIODS", payload);
+  /** Fetch a simplified flat chart of accounts for a subsidiary. */
+  getCoaFlatSimple(payload) {
+    return this.request("GET_COA_FLAT_SIMPLE", payload);
   }
-  postTaskOutput(payload) {
-    return this.request("POST_TASK_OUTPUT", 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);
+  }
   /**
-   * Uploads a file through the host. Converts the File to an ArrayBuffer
-   * before sending — sandboxed iframes cannot pass File handles across windows.
+   * 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();
@@ -253,6 +516,18 @@ 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();

package/docs/connect-lifecycle.md

@@ -0,0 +1,56 @@
+# Connection lifecycle
+
+## Always connect first
+
+```ts
+const ctx = await bridge.connect()
+```
+
+Call `connect()` **once** on app init and `await` it before any data method, `upload()`, or subroute call. Concurrent calls return the same promise, so it's safe to call from multiple init paths.
+
+## What `connect()` returns
+
+A `ContextPayload`:
+
+```ts
+interface ContextPayload {
+  tenant: string
+  subsidiaryId: number
+  subsidiaries: { id: number; displayName: string }[]
+  user: { id: string; displayName: string }
+  subroute?: string // initial deep-link path, if any
+  lastClosedPeriodSlug?: string // e.g. "mar-2026"
+  hostVersion: string // version of @nominalso/vibe-host running in the host
+}
+```
+
+## How it works
+
+The host pushes context to the iframe on load, but the iframe's listener may not be ready when that push arrives. `connect()` solves the race:
+
+1. The bridge starts a 500 ms polling loop, sending `GET_CONTEXT` requests to the host.
+2. The host responds as soon as its listener is mounted, **or** proactively pushes `CONTEXT_PUSH` once it has the iframe's window.
+3. Whichever arrives first resolves `connect()`. Polling stops.
+4. The bridge begins auto-tracking SPA navigation (see below).
+5. If nothing arrives within **10 seconds**, `connect()` rejects with `Bridge connect timed out`.
+
+A timeout almost always means a `parentOrigin` mismatch or the host never mounted.
+
+## Initial deep link
+
+If `ctx.subroute` is present (e.g. the user opened a bookmarked deep link), the bridge navigates to it via `history.replaceState` right after connecting, so your router lands on the correct view.
+
+## Subroute sync (usually automatic)
+
+After connecting, the bridge monkey-patches `history.pushState`/`replaceState` to auto-report internal navigation to the host, keeping the Nominal browser URL in sync. For standard SPA routers you need no code.
+
+- **Non-standard / hash routers:** call `bridge.reportSubroute('/assets/123', { replace })` manually.
+- **React to host back/forward:** `const off = bridge.onSubrouteRequest((subroute) => router.navigate(subroute))`. Returns an unsubscribe function. Without one, the SDK uses `history.pushState` + a `popstate` event, which most routers pick up.
+
+## Teardown
+
+```ts
+bridge.destroy()
+```
+
+Removes listeners, rejects pending requests with `Bridge destroyed`, and restores the original history methods. Call it on unmount.