@nominalso/vibe-bridge 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-var version = "0.2.0";
+var version = "0.4.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -3182,6 +3182,54 @@ 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 them over the bridge so the iframe never hardcodes any of it. When
+ * the host omits the {@link ContextPayload.posthog} block entirely (older host,
+ * or recording disabled for this env/app), 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;
+}
 interface ContextPayload {
     tenant: string;
     subsidiaryId: number;
@@ -3194,6 +3242,13 @@ interface ContextPayload {
     subroute?: string;
     /** Slug of the last closed accounting period, e.g. "mar-2026". */
     lastClosedPeriodSlug?: string;
+    /**
+     * PostHog config for in-iframe session recording + custom events. **Absent
+     * when recording is off** (older host, or disabled for this env/app), in which
+     * case the bridge initializes no analytics. Optional so old hosts/bridges stay
+     * compatible.
+     */
+    posthog?: PostHogContext;
     /** Version of the host SDK (@nominalso/vibe-host) running in nom-ui. */
     hostVersion: string;
 }
@@ -3659,13 +3714,34 @@ declare abstract class BridgeDataMethods {
 
 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.
+     * 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;
+    parentOrigin?: string | string[];
     /**
      * Global per-request timeout in milliseconds before a call rejects with a
      * `BridgeError` whose `code` is `'TIMEOUT'`.
@@ -3702,13 +3778,23 @@ interface VibeAppBridgeOptions {
  * ```
  */
 declare class VibeAppBridge extends BridgeDataMethods {
-    private readonly parentOrigin;
+    /** 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;
+    /**
+     * 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;
     /**
@@ -3726,7 +3812,7 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private readonly kindHandlers;
     private dispatchPush;
     private readonly pushHandlers;
-    constructor({ parentOrigin, requestTimeout }: VibeAppBridgeOptions);
+    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
@@ -3816,8 +3902,47 @@ 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, **only when the host opted in** (`ctx.posthog?.enabled`).
+     *
+     * The host is the single source of truth: when it sends no `posthog` block
+     * (older nom-ui, or 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. Wrapped in try/catch so a PostHog failure is
+     * best-effort and never blocks `connect()`.
+     */
+    private initPostHog;
     /**
      * Monkey-patches `history.pushState` and `history.replaceState` to
      * auto-detect SPA navigation and report it to the host. Called after
@@ -3842,9 +3967,15 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * ```
      */
     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, 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.2.0";
+var version = "0.4.0";
 
 type AccountingAccountDimensionValues = {
     account_id: string;
@@ -3182,6 +3182,54 @@ 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 them over the bridge so the iframe never hardcodes any of it. When
+ * the host omits the {@link ContextPayload.posthog} block entirely (older host,
+ * or recording disabled for this env/app), 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;
+}
 interface ContextPayload {
     tenant: string;
     subsidiaryId: number;
@@ -3194,6 +3242,13 @@ interface ContextPayload {
     subroute?: string;
     /** Slug of the last closed accounting period, e.g. "mar-2026". */
     lastClosedPeriodSlug?: string;
+    /**
+     * PostHog config for in-iframe session recording + custom events. **Absent
+     * when recording is off** (older host, or disabled for this env/app), in which
+     * case the bridge initializes no analytics. Optional so old hosts/bridges stay
+     * compatible.
+     */
+    posthog?: PostHogContext;
     /** Version of the host SDK (@nominalso/vibe-host) running in nom-ui. */
     hostVersion: string;
 }
@@ -3659,13 +3714,34 @@ declare abstract class BridgeDataMethods {
 
 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.
+     * 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;
+    parentOrigin?: string | string[];
     /**
      * Global per-request timeout in milliseconds before a call rejects with a
      * `BridgeError` whose `code` is `'TIMEOUT'`.
@@ -3702,13 +3778,23 @@ interface VibeAppBridgeOptions {
  * ```
  */
 declare class VibeAppBridge extends BridgeDataMethods {
-    private readonly parentOrigin;
+    /** 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;
+    /**
+     * 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;
     /**
@@ -3726,7 +3812,7 @@ declare class VibeAppBridge extends BridgeDataMethods {
     private readonly kindHandlers;
     private dispatchPush;
     private readonly pushHandlers;
-    constructor({ parentOrigin, requestTimeout }: VibeAppBridgeOptions);
+    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
@@ -3816,8 +3902,47 @@ 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, **only when the host opted in** (`ctx.posthog?.enabled`).
+     *
+     * The host is the single source of truth: when it sends no `posthog` block
+     * (older nom-ui, or 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. Wrapped in try/catch so a PostHog failure is
+     * best-effort and never blocks `connect()`.
+     */
+    private initPostHog;
     /**
      * Monkey-patches `history.pushState` and `history.replaceState` to
      * auto-detect SPA navigation and report it to the host. Called after
@@ -3842,9 +3967,15 @@ declare class VibeAppBridge extends BridgeDataMethods {
      * ```
      */
     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, 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 };