@nominalso/vibe-host 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -27,7 +27,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.3.0";
+var version = "0.4.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {

package/dist/index.d.cts

@@ -3180,6 +3180,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;
@@ -3192,6 +3240,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;
 }
@@ -3710,4 +3765,4 @@ declare class VibeAppHost {
     private respond;
 }
 
-export { BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };
+export { BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type PostHogContext, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };

package/dist/index.d.ts

@@ -3180,6 +3180,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;
@@ -3192,6 +3240,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;
 }
@@ -3710,4 +3765,4 @@ declare class VibeAppHost {
     private respond;
 }
 
-export { BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };
+export { BridgeError, type ContextPayload, type HostContext, type HostHandlers, HttpBridgeError, type InvalidateCachePayload, type InvalidateResult, type NavigateAction, type NavigatePayload, type PostHogContext, type RequestCompleteInfo, type RequestHandlers, type SetSideNavPayload, type SwitchSubsidiaryPayload, type UploadPayload, type UploadProgress, type UploadResponse, type VibeApiClientOptions, VibeAppHost, type VibeAppHostOptions };

package/dist/index.js

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.3.0";
+var version = "0.4.0";
 
 // ../protocol-types/dist/index.js
 function normalizeSubroute(subroute) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nominalso/vibe-host",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Host-side SDK for embedding Nominal Vibe Apps — receives bridge requests over a typed postMessage protocol and dispatches them to Nominal APIs (used by nom-ui).",
   "license": "UNLICENSED",
   "homepage": "https://github.com/nominalso/vibe-apps-sdk#readme",