@nominalso/vibe-bridge 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-var version = "0.3.0";
+var version = "0.5.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -1392,6 +1392,7 @@ type ActivityProviderOperationErrorType = 'Connection Error' | 'Authentication E
 type ActivityReconciliationDefinitionData = {
     type: ActivityReconciliationType;
     task_definition_id: string;
+    currency?: ActivityCurrency | null;
     side_a_entity_type: ActivityReconciliationEntityType;
     side_a_entity_id: string;
     side_b_entity_type: ActivityReconciliationEntityType;
@@ -1405,7 +1406,6 @@ type ActivityReconciliationInstanceDataInput = {
     task_instance_id: string;
     start_date: string;
     end_date: string;
-    currency?: ActivityCurrency | null;
     side_a_value?: number | string | null;
     side_b_value?: number | string | null;
     reconciling_items_balance?: number | string | null;
@@ -1419,7 +1419,6 @@ type ActivityReconciliationInstanceDataOutput = {
     task_instance_id: string;
     start_date: string;
     end_date: string;
-    currency?: ActivityCurrency | null;
     side_a_value?: string | null;
     side_b_value?: string | null;
     reconciling_items_balance?: string | null;
@@ -3182,6 +3181,76 @@ interface BridgeSubsidiary {
     id: number;
     displayName: string;
 }
+/**
+ * PostHog configuration the host supplies so the iframe can record a session
+ * replay (stitched into the host's recording via `recordCrossOriginIframes`)
+ * and emit custom events, all attributed to the **same PostHog person** as
+ * nom-ui.
+ *
+ * The host (nom-ui) is the single source of truth for these values — it knows
+ * the project key, the env-aware ingestion host, and the resolved person — and
+ * delivers it over the bridge (as a one-time `POSTHOG_PUSH`, separate from
+ * {@link ContextPayload}) so the iframe never hardcodes any of it. When the host
+ * has no PostHog config (recording disabled for this env/app), it sends no
+ * `POSTHOG_PUSH` and the bridge initializes nothing.
+ */
+interface PostHogContext {
+    /** Project API key — the same PostHog project the host (nom-ui) uses. */
+    token: string;
+    /**
+     * **Absolute** ingestion host, e.g. `"https://us.i.posthog.com"`.
+     *
+     * Must NOT be the host's relative `/ingest` reverse-proxy path: a relative
+     * path resolves against the iframe's *own* (cross-origin) host and 404s.
+     */
+    apiHost: string;
+    /**
+     * Host-resolved PostHog distinct id. The bridge calls `identify()` with it so
+     * the iframe's recording and events attribute to the same person as the host.
+     */
+    distinctId: string;
+    /**
+     * **Optional.** The host's current PostHog session id (from
+     * `posthog.get_session_id()`). When provided, the bridge seeds it as the
+     * iframe instance's session via `bootstrap.sessionID`, so custom events from
+     * `bridge.track()` share the **same `$session_id`** as the host — letting them
+     * line up with the stitched session replay on one timeline.
+     *
+     * Not needed for *replay* stitching itself (that works via
+     * `recordCrossOriginIframes` on both sides regardless). Must be a valid UUID
+     * v7 — PostHog session ids already are. It is a one-time seed at connect, so
+     * if the host's session later rotates the two can diverge; alignment is
+     * best-effort for the session in progress.
+     */
+    sessionId?: string;
+    /**
+     * Master switch, env- and/or app-gated by the host. The bridge only calls
+     * `posthog.init()` when this is `true`; it stays the kill-switch even though
+     * `posthog-js` is bundled into the bridge.
+     */
+    enabled: boolean;
+}
+/**
+ * Authentication-state change the host pushes to the iframe via `AUTH_CHANGED`.
+ * It carries the security principal the embedded app authenticates and scopes
+ * its own data by. Sent when the Nominal session changes: a logout
+ * (`authenticated: false`) or an identity/tenant switch (`authenticated: true`
+ * with a new `userId`/`tenant`). The initial state is implicit at connect — the
+ * iframe only loads when authenticated, and the current identity/tenant are
+ * {@link ContextPayload.user} / {@link ContextPayload.tenant}, so apps baseline
+ * off those and react to this push.
+ *
+ * Subsidiary/period and other view-level state are NOT here — they ride the
+ * follow-up `CONTEXT_PUSH` (`onContextChange`), per "auth change, then context".
+ */
+interface AuthPayload {
+    /** Whether the Nominal user is still authenticated. */
+    authenticated: boolean;
+    /** The effective Nominal user id when authenticated; omitted on logout. */
+    userId?: string;
+    /** The tenant the user is acting in — the app's data-scoping key (RLS). */
+    tenant?: string;
+}
 interface ContextPayload {
     tenant: string;
     subsidiaryId: number;
@@ -3197,11 +3266,6 @@ interface ContextPayload {
     /** Version of the host SDK (@nominalso/vibe-host) running in nom-ui. */
     hostVersion: string;
 }
-/** Payload sent by the bridge when requesting context from the host. */
-interface GetContextPayload {
-    /** Version of the bridge SDK (@nominalso/vibe-bridge) running in the iframe. */
-    bridgeVersion: string;
-}
 
 interface UploadPayload {
     buffer: ArrayBuffer;
@@ -3435,10 +3499,6 @@ interface RequestRegistry {
         payload: InvalidateCachePayload;
         data: InvalidateResult;
     };
-    GET_CONTEXT: {
-        payload: GetContextPayload;
-        data: ContextPayload;
-    };
     UPLOAD_FILE: {
         payload: UploadPayload;
         data: UploadResponse;
@@ -3693,9 +3753,9 @@ interface VibeAppBridgeOptions {
      *
      * 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.
+     * `120000`, `INVALIDATE_CACHE` `10000`). 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;
 }
@@ -3731,17 +3791,30 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private readonly pendingRequests;
     private readonly boundHandleMessage;
     private context;
+    /**
+     * Set once {@link initPostHog} has successfully called `posthog.init()`.
+     * Guards against a double-init and makes {@link track} a no-op until
+     * recording is actually live.
+     */
+    private posthogInitialized;
     private connectPromise;
     private connectPollInterval;
     private connectTimeout;
     private onContextReceived;
-    private onContextError;
+    /** Rejects an in-flight connect() (used by destroy()); `null` once settled. */
+    private rejectConnect;
+    /**
+     * Persistent subscriber for post-connect context changes (tenant/subsidiary
+     * switch, period close, …). Distinct from {@link onContextReceived}, which only
+     * resolves the connect handshake and is cleared afterward. `null` until
+     * {@link onContextChange} is called.
+     */
+    private contextChangeCallback;
     /**
-     * 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).
+     * Persistent subscriber for host auth changes (Nominal logout or
+     * identity/tenant switch). `null` until {@link onAuthChange} is called.
      */
-    private readonly connectPollIds;
+    private authChangeCallback;
     private lastReportedSubroute;
     private suppressSubrouteReport;
     private subrouteCallback;
@@ -3758,11 +3831,11 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * 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).
+     * Sends a `CONNECT` handshake, re-sending every 500ms until the host replies
+     * by pushing the context (so it works even if the host mounts after the
+     * iframe loads). Context is only ever delivered by push. 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
@@ -3792,6 +3865,35 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * Returns an unsubscribe function.
      */
     onSubrouteRequest(callback: (subroute: string) => void): () => void;
+    /**
+     * Subscribes to post-connect context changes (tenant/subsidiary switch, period
+     * close, …). The callback fires for each {@link ContextPayload} the host pushes
+     * *after* connect — not for the initial context, which {@link connect} already
+     * returns. Returns an unsubscribe function. Single subscriber: a second call
+     * replaces the first. Wire it **before {@link connect}** (the bridge warns at
+     * connect if it isn't).
+     */
+    onContextChange(callback: (ctx: ContextPayload) => void): () => void;
+    /**
+     * Subscribes to host auth changes: a Nominal logout (`authenticated: false` —
+     * sign your backend out) or an identity/tenant switch (`authenticated: true`
+     * with a new `userId`/`tenant` — re-authenticate). Fires for each change the
+     * host pushes after connect. Returns an unsubscribe function. Single
+     * subscriber: a second call replaces the first.
+     *
+     * **Wire this before {@link connect}** — without it the embedded app won't
+     * sign out when the user logs out of Nominal (the bridge warns at connect if
+     * it isn't wired).
+     */
+    onAuthChange(callback: (auth: AuthPayload) => void): () => void;
+    /**
+     * At connect, nudge the app if it hasn't wired the change listeners: every
+     * embedded app should react to a Nominal logout ({@link onAuthChange}) and a
+     * tenant/subsidiary switch ({@link onContextChange}). Fires once during the
+     * connect flow (not speculatively later), so wire both **before** `connect()`.
+     * The skill/codegen does this by default; this catches hand-wired apps.
+     */
+    private warnMissingListeners;
     /**
      * Navigates the host to a raw path relative to this app's tenant/subsidiary
      * base. Fire-and-forget.
@@ -3841,8 +3943,48 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * ```
      */
     invalidateCache(payload: InvalidateCachePayload): Promise<InvalidateResult>;
+    /**
+     * Captures a custom product event from inside the Vibe App, attributed to the
+     * same PostHog person as the host (via the `distinctId` the host supplied at
+     * connect).
+     *
+     * **No-op until {@link connect} has resolved with PostHog enabled by the
+     * host** — if the host didn't send a `posthog` block (older host, or recording
+     * disabled for this env/app), nothing is sent. App authors don't import
+     * `posthog-js` themselves; this is the supported event surface.
+     *
+     * The event is sent **directly** from the iframe's own PostHog instance (only
+     * the session *recording* is forwarded to the parent), so it carries the
+     * iframe instance's `$session_id` rather than the host's — events tie to the
+     * same person, but cross-boundary event↔replay timeline correlation is a known
+     * limitation.
+     *
+     * @param event Event name. Namespacing app events (e.g. `'vibe:<slug>:<action>'`)
+     *   keeps them filterable from the host's own events.
+     * @param properties Optional event properties.
+     * @example
+     * ```ts
+     * bridge.track('vibe:fixed-assets:report_exported', { format: 'csv', rows: 128 })
+     * ```
+     */
+    track(event: string, properties?: Record<string, unknown>): void;
     destroy(): void;
     private stopConnectPolling;
+    /**
+     * Initializes PostHog session recording + analytics from the host-supplied
+     * config carried by a one-time `POSTHOG_PUSH`, **only when the host opted in**
+     * (`config.enabled`).
+     *
+     * The host is the single source of truth: when it sends no `POSTHOG_PUSH`
+     * (recording disabled for this env/app) or `enabled: false`, this does
+     * nothing — `enabled` is the kill-switch even though `posthog-js` is bundled
+     * into the bridge. Cross-origin replay needs `recordCrossOriginIframes` on both
+     * sides so the parent receives the iframe's rrweb frames into one stitched
+     * recording, and `identify()` ties the iframe's recording + events to the same
+     * person as the host. Idempotent (the `posthogInitialized` guard) and wrapped
+     * in try/catch so a duplicate push or a PostHog failure is harmless.
+     */
+    private initPostHog;
     /**
      * Monkey-patches `history.pushState` and `history.replaceState` to
      * auto-detect SPA navigation and report it to the host. Called after
@@ -3878,4 +4020,4 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private handleProgress;
 }
 
-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 };
+export { version as BRIDGE_VERSION, BridgeError, type BridgeSubsidiary, type ContextPayload, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type PostHogContext, type RequestRegistry, type SetSideNavPayload, type UploadOptions, type UploadProgress, type UploadResponse, VibeAppBridge, type VibeAppBridgeOptions };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-var version = "0.3.0";
+var version = "0.5.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -1392,6 +1392,7 @@ type ActivityProviderOperationErrorType = 'Connection Error' | 'Authentication E
 type ActivityReconciliationDefinitionData = {
     type: ActivityReconciliationType;
     task_definition_id: string;
+    currency?: ActivityCurrency | null;
     side_a_entity_type: ActivityReconciliationEntityType;
     side_a_entity_id: string;
     side_b_entity_type: ActivityReconciliationEntityType;
@@ -1405,7 +1406,6 @@ type ActivityReconciliationInstanceDataInput = {
     task_instance_id: string;
     start_date: string;
     end_date: string;
-    currency?: ActivityCurrency | null;
     side_a_value?: number | string | null;
     side_b_value?: number | string | null;
     reconciling_items_balance?: number | string | null;
@@ -1419,7 +1419,6 @@ type ActivityReconciliationInstanceDataOutput = {
     task_instance_id: string;
     start_date: string;
     end_date: string;
-    currency?: ActivityCurrency | null;
     side_a_value?: string | null;
     side_b_value?: string | null;
     reconciling_items_balance?: string | null;
@@ -3182,6 +3181,76 @@ interface BridgeSubsidiary {
     id: number;
     displayName: string;
 }
+/**
+ * PostHog configuration the host supplies so the iframe can record a session
+ * replay (stitched into the host's recording via `recordCrossOriginIframes`)
+ * and emit custom events, all attributed to the **same PostHog person** as
+ * nom-ui.
+ *
+ * The host (nom-ui) is the single source of truth for these values — it knows
+ * the project key, the env-aware ingestion host, and the resolved person — and
+ * delivers it over the bridge (as a one-time `POSTHOG_PUSH`, separate from
+ * {@link ContextPayload}) so the iframe never hardcodes any of it. When the host
+ * has no PostHog config (recording disabled for this env/app), it sends no
+ * `POSTHOG_PUSH` and the bridge initializes nothing.
+ */
+interface PostHogContext {
+    /** Project API key — the same PostHog project the host (nom-ui) uses. */
+    token: string;
+    /**
+     * **Absolute** ingestion host, e.g. `"https://us.i.posthog.com"`.
+     *
+     * Must NOT be the host's relative `/ingest` reverse-proxy path: a relative
+     * path resolves against the iframe's *own* (cross-origin) host and 404s.
+     */
+    apiHost: string;
+    /**
+     * Host-resolved PostHog distinct id. The bridge calls `identify()` with it so
+     * the iframe's recording and events attribute to the same person as the host.
+     */
+    distinctId: string;
+    /**
+     * **Optional.** The host's current PostHog session id (from
+     * `posthog.get_session_id()`). When provided, the bridge seeds it as the
+     * iframe instance's session via `bootstrap.sessionID`, so custom events from
+     * `bridge.track()` share the **same `$session_id`** as the host — letting them
+     * line up with the stitched session replay on one timeline.
+     *
+     * Not needed for *replay* stitching itself (that works via
+     * `recordCrossOriginIframes` on both sides regardless). Must be a valid UUID
+     * v7 — PostHog session ids already are. It is a one-time seed at connect, so
+     * if the host's session later rotates the two can diverge; alignment is
+     * best-effort for the session in progress.
+     */
+    sessionId?: string;
+    /**
+     * Master switch, env- and/or app-gated by the host. The bridge only calls
+     * `posthog.init()` when this is `true`; it stays the kill-switch even though
+     * `posthog-js` is bundled into the bridge.
+     */
+    enabled: boolean;
+}
+/**
+ * Authentication-state change the host pushes to the iframe via `AUTH_CHANGED`.
+ * It carries the security principal the embedded app authenticates and scopes
+ * its own data by. Sent when the Nominal session changes: a logout
+ * (`authenticated: false`) or an identity/tenant switch (`authenticated: true`
+ * with a new `userId`/`tenant`). The initial state is implicit at connect — the
+ * iframe only loads when authenticated, and the current identity/tenant are
+ * {@link ContextPayload.user} / {@link ContextPayload.tenant}, so apps baseline
+ * off those and react to this push.
+ *
+ * Subsidiary/period and other view-level state are NOT here — they ride the
+ * follow-up `CONTEXT_PUSH` (`onContextChange`), per "auth change, then context".
+ */
+interface AuthPayload {
+    /** Whether the Nominal user is still authenticated. */
+    authenticated: boolean;
+    /** The effective Nominal user id when authenticated; omitted on logout. */
+    userId?: string;
+    /** The tenant the user is acting in — the app's data-scoping key (RLS). */
+    tenant?: string;
+}
 interface ContextPayload {
     tenant: string;
     subsidiaryId: number;
@@ -3197,11 +3266,6 @@ interface ContextPayload {
     /** Version of the host SDK (@nominalso/vibe-host) running in nom-ui. */
     hostVersion: string;
 }
-/** Payload sent by the bridge when requesting context from the host. */
-interface GetContextPayload {
-    /** Version of the bridge SDK (@nominalso/vibe-bridge) running in the iframe. */
-    bridgeVersion: string;
-}
 
 interface UploadPayload {
     buffer: ArrayBuffer;
@@ -3435,10 +3499,6 @@ interface RequestRegistry {
         payload: InvalidateCachePayload;
         data: InvalidateResult;
     };
-    GET_CONTEXT: {
-        payload: GetContextPayload;
-        data: ContextPayload;
-    };
     UPLOAD_FILE: {
         payload: UploadPayload;
         data: UploadResponse;
@@ -3693,9 +3753,9 @@ interface VibeAppBridgeOptions {
      *
      * 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.
+     * `120000`, `INVALIDATE_CACHE` `10000`). 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;
 }
@@ -3731,17 +3791,30 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private readonly pendingRequests;
     private readonly boundHandleMessage;
     private context;
+    /**
+     * Set once {@link initPostHog} has successfully called `posthog.init()`.
+     * Guards against a double-init and makes {@link track} a no-op until
+     * recording is actually live.
+     */
+    private posthogInitialized;
     private connectPromise;
     private connectPollInterval;
     private connectTimeout;
     private onContextReceived;
-    private onContextError;
+    /** Rejects an in-flight connect() (used by destroy()); `null` once settled. */
+    private rejectConnect;
+    /**
+     * Persistent subscriber for post-connect context changes (tenant/subsidiary
+     * switch, period close, …). Distinct from {@link onContextReceived}, which only
+     * resolves the connect handshake and is cleared afterward. `null` until
+     * {@link onContextChange} is called.
+     */
+    private contextChangeCallback;
     /**
-     * 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).
+     * Persistent subscriber for host auth changes (Nominal logout or
+     * identity/tenant switch). `null` until {@link onAuthChange} is called.
      */
-    private readonly connectPollIds;
+    private authChangeCallback;
     private lastReportedSubroute;
     private suppressSubrouteReport;
     private subrouteCallback;
@@ -3758,11 +3831,11 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * 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).
+     * Sends a `CONNECT` handshake, re-sending every 500ms until the host replies
+     * by pushing the context (so it works even if the host mounts after the
+     * iframe loads). Context is only ever delivered by push. 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
@@ -3792,6 +3865,35 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * Returns an unsubscribe function.
      */
     onSubrouteRequest(callback: (subroute: string) => void): () => void;
+    /**
+     * Subscribes to post-connect context changes (tenant/subsidiary switch, period
+     * close, …). The callback fires for each {@link ContextPayload} the host pushes
+     * *after* connect — not for the initial context, which {@link connect} already
+     * returns. Returns an unsubscribe function. Single subscriber: a second call
+     * replaces the first. Wire it **before {@link connect}** (the bridge warns at
+     * connect if it isn't).
+     */
+    onContextChange(callback: (ctx: ContextPayload) => void): () => void;
+    /**
+     * Subscribes to host auth changes: a Nominal logout (`authenticated: false` —
+     * sign your backend out) or an identity/tenant switch (`authenticated: true`
+     * with a new `userId`/`tenant` — re-authenticate). Fires for each change the
+     * host pushes after connect. Returns an unsubscribe function. Single
+     * subscriber: a second call replaces the first.
+     *
+     * **Wire this before {@link connect}** — without it the embedded app won't
+     * sign out when the user logs out of Nominal (the bridge warns at connect if
+     * it isn't wired).
+     */
+    onAuthChange(callback: (auth: AuthPayload) => void): () => void;
+    /**
+     * At connect, nudge the app if it hasn't wired the change listeners: every
+     * embedded app should react to a Nominal logout ({@link onAuthChange}) and a
+     * tenant/subsidiary switch ({@link onContextChange}). Fires once during the
+     * connect flow (not speculatively later), so wire both **before** `connect()`.
+     * The skill/codegen does this by default; this catches hand-wired apps.
+     */
+    private warnMissingListeners;
     /**
      * Navigates the host to a raw path relative to this app's tenant/subsidiary
      * base. Fire-and-forget.
@@ -3841,8 +3943,48 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * ```
      */
     invalidateCache(payload: InvalidateCachePayload): Promise<InvalidateResult>;
+    /**
+     * Captures a custom product event from inside the Vibe App, attributed to the
+     * same PostHog person as the host (via the `distinctId` the host supplied at
+     * connect).
+     *
+     * **No-op until {@link connect} has resolved with PostHog enabled by the
+     * host** — if the host didn't send a `posthog` block (older host, or recording
+     * disabled for this env/app), nothing is sent. App authors don't import
+     * `posthog-js` themselves; this is the supported event surface.
+     *
+     * The event is sent **directly** from the iframe's own PostHog instance (only
+     * the session *recording* is forwarded to the parent), so it carries the
+     * iframe instance's `$session_id` rather than the host's — events tie to the
+     * same person, but cross-boundary event↔replay timeline correlation is a known
+     * limitation.
+     *
+     * @param event Event name. Namespacing app events (e.g. `'vibe:<slug>:<action>'`)
+     *   keeps them filterable from the host's own events.
+     * @param properties Optional event properties.
+     * @example
+     * ```ts
+     * bridge.track('vibe:fixed-assets:report_exported', { format: 'csv', rows: 128 })
+     * ```
+     */
+    track(event: string, properties?: Record<string, unknown>): void;
     destroy(): void;
     private stopConnectPolling;
+    /**
+     * Initializes PostHog session recording + analytics from the host-supplied
+     * config carried by a one-time `POSTHOG_PUSH`, **only when the host opted in**
+     * (`config.enabled`).
+     *
+     * The host is the single source of truth: when it sends no `POSTHOG_PUSH`
+     * (recording disabled for this env/app) or `enabled: false`, this does
+     * nothing — `enabled` is the kill-switch even though `posthog-js` is bundled
+     * into the bridge. Cross-origin replay needs `recordCrossOriginIframes` on both
+     * sides so the parent receives the iframe's rrweb frames into one stitched
+     * recording, and `identify()` ties the iframe's recording + events to the same
+     * person as the host. Idempotent (the `posthogInitialized` guard) and wrapped
+     * in try/catch so a duplicate push or a PostHog failure is harmless.
+     */
+    private initPostHog;
     /**
      * Monkey-patches `history.pushState` and `history.replaceState` to
      * auto-detect SPA navigation and report it to the host. Called after
@@ -3878,4 +4020,4 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private handleProgress;
 }
 
-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 };
+export { version as BRIDGE_VERSION, BridgeError, type BridgeSubsidiary, type ContextPayload, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type PostHogContext, type RequestRegistry, type SetSideNavPayload, type UploadOptions, type UploadProgress, type UploadResponse, VibeAppBridge, type VibeAppBridgeOptions };