@nominalso/vibe-host 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -1390,6 +1390,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;
@@ -1403,7 +1404,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;
@@ -1417,7 +1417,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;
@@ -3188,9 +3187,10 @@ interface BridgeSubsidiary {
  *
  * 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.
+ * 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. */
@@ -3228,6 +3228,27 @@ interface PostHogContext {
      */
     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;
@@ -3240,22 +3261,32 @@ 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;
 }
-/** 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;
-}
 
+/**
+ * Response type for operations whose Nominal OpenAPI `200` response declares
+ * **no content schema**. hey-api generates `200: unknown` for these, so there is
+ * genuinely no concrete type to narrow to at codegen time — the shape is
+ * undocumented upstream, not merely unmapped by this SDK.
+ *
+ * We surface this named alias instead of a bare `unknown` so the gap is
+ * self-documenting: editors show `UntypedApiResponse` (with this doc) rather than
+ * an anonymous `unknown`, signalling that the value must be explicitly asserted
+ * to a known shape (`const p = res as MyPeriod`) rather than trusted. It stays
+ * assignment-compatible with `unknown`, so no runtime or narrowing behaviour
+ * changes.
+ *
+ * The fix is upstream: document these endpoints' response bodies in the owning
+ * Nominal service's OpenAPI (then the registry entry can reference the generated
+ * `*Response` type). Affected ops today: `GET_PERIODS`, `GET_PERIOD_INSTANCE`,
+ * `GET_PERIOD_INSTANCE_BY_SLUG`, `POST_TASK_OUTPUT`, `GET_TASK_INSTANCE`,
+ * `GET_TASK_INSTANCES`, `GET_TASK_DEFINITION`, `GET_ACTIVITY_DEFINITION(S)`,
+ * `GET_ACTIVITY_INSTANCE`, `GET_ACTIVITY_INSTANCE_TASKS`,
+ * `GET_ACTIVITY_PERIOD_TASKS`.
+ */
+type UntypedApiResponse = unknown;
 interface UploadPayload {
     buffer: ArrayBuffer;
     fileName: string;
@@ -3328,11 +3359,11 @@ interface RequestRegistry {
     };
     GET_PERIODS: {
         payload: Omit<GetPeriodInstancesApiActivityPeriodInstanceGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     POST_TASK_OUTPUT: {
         payload: Omit<UpdateTaskInstanceApiActivityTaskInstanceTaskInstanceIdPutData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_DIMENSIONS: {
         payload: Omit<GetDimensionsApiAccountingDimensionGetData, 'url'>;
@@ -3348,7 +3379,7 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_DEFINITIONS: {
         payload: Omit<GetActivityDefinitionsApiActivityActivityDefinitionGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_TASK_DEFINITIONS: {
         payload: Omit<GetAllTasksDefinitionsApiActivityTaskDefinitionGetData, 'url'>;
@@ -3356,7 +3387,7 @@ interface RequestRegistry {
     };
     GET_TASK_INSTANCES: {
         payload: Omit<GetAllTaskInstancesApiActivityTaskInstanceGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_FISCAL_CALENDARS: {
         payload: Omit<GetFiscalCalendarsBySubsidiaryApiPeriodManagerFiscalCalendarBySubsidiarySubsidiaryIdGetData, 'url'>;
@@ -3424,11 +3455,11 @@ interface RequestRegistry {
     };
     GET_PERIOD_INSTANCE: {
         payload: Omit<GetPeriodInstanceApiActivityPeriodInstancePeriodInstanceIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_PERIOD_INSTANCE_BY_SLUG: {
         payload: Omit<GetPeriodInstanceBySlugApiActivityPeriodInstanceBySlugPeriodDisplayIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_PERIOD_PROGRESS_BREAKDOWN: {
         payload: Omit<GetPeriodInstanceProgressBreakdownBySlugApiActivityPeriodInstanceBySlugPeriodDisplayIdProgressBreakdownGetData, 'url'>;
@@ -3436,7 +3467,7 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_DEFINITION: {
         payload: Omit<GetActivityDefinitionByIdApiActivityActivityDefinitionActivityDefinitionIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_ACTIVITY_INSTANCES: {
         payload: Omit<GetActivityInstancesApiActivityActivityInstanceGetData, 'url'>;
@@ -3444,7 +3475,7 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_INSTANCE: {
         payload: Omit<GetActivityInstanceApiActivityActivityInstanceActivityInstanceIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_ACTIVITY_INSTANCE_BY_PERIOD: {
         payload: Omit<GetActivityInstanceByPeriodApiActivityActivityInstanceByPeriodPeriodDisplayIdActivityDefinitionIdGetData, 'url'>;
@@ -3452,15 +3483,15 @@ interface RequestRegistry {
     };
     GET_ACTIVITY_INSTANCE_TASKS: {
         payload: Omit<GetTaskInstancesByActivityApiActivityActivityInstanceActivityInstanceIdTaskGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_ACTIVITY_PERIOD_TASKS: {
         payload: Omit<GetTaskInstancesByActivityPeriodApiActivityActivityInstanceByPeriodPeriodDisplayIdActivityDefinitionIdTaskGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_TASK_DEFINITION: {
         payload: Omit<GetTaskDefinitionByIdApiActivityTaskDefinitionTaskDefinitionIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     CREATE_TASK_DEFINITION: {
         payload: Omit<CreateTaskDefinitionApiActivityTaskDefinitionPostData, 'url'>;
@@ -3476,7 +3507,7 @@ interface RequestRegistry {
     };
     GET_TASK_INSTANCE: {
         payload: Omit<GetTaskInstanceByIdApiActivityTaskInstanceTaskInstanceIdGetData, 'url'>;
-        data: unknown;
+        data: UntypedApiResponse;
     };
     GET_TASK_INSTANCES_BY_FILTER: {
         payload: Omit<GetAllTaskInstancesByFilterApiActivityTaskInstanceQueryPostData, 'url'>;
@@ -3506,10 +3537,6 @@ interface RequestRegistry {
         payload: InvalidateCachePayload;
         data: InvalidateResult;
     };
-    GET_CONTEXT: {
-        payload: GetContextPayload;
-        data: ContextPayload;
-    };
     UPLOAD_FILE: {
         payload: UploadPayload;
         data: UploadResponse;
@@ -3540,12 +3567,24 @@ type RequestHandlers = {
  * string-matching `error.message`. A failed Nominal API call rehydrates as the
  * {@link HttpBridgeError} subtype, which adds the HTTP `status`.
  *
+ * SDK-originated codes you may also see: `'TIMEOUT'` (a request or the connect
+ * handshake timed out), `'DESTROYED'` (the bridge was torn down mid-flight),
+ * `'PARENT_ORIGIN_UNRESOLVED'` (no embedding origin could be resolved) and
+ * `'SERVER_ENVIRONMENT'` (a browser-only method was called where there is no
+ * `window` — e.g. during SSR / in a React Server Component / in a Worker).
+ *
+ * This class is safe to import from any environment (see the module header).
+ *
  * @example
  * ```ts
+ * import { BridgeError } from '@nominalso/vibe-bridge'
+ *
  * try {
  *   await bridge.getAccounts({})
  * } catch (err) {
- *   if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+ *   // `instanceof` works within a single bundle; `isBridgeError` also works
+ *   // across independently-built server/client bundles.
+ *   if (BridgeError.isBridgeError(err) && err.code === 'RATE_LIMITED') {
  *     // back off and retry
  *   }
  * }
@@ -3554,6 +3593,13 @@ type RequestHandlers = {
 declare class BridgeError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
+    /**
+     * Cross-realm-safe type guard. Prefer this over `instanceof BridgeError` when
+     * an error may have been thrown by a differently-built copy of the SDK (e.g.
+     * server bundle vs client bundle) — it matches on a process-global brand
+     * rather than class identity.
+     */
+    static isBridgeError(err: unknown): err is BridgeError;
 }
 /**
  * A {@link BridgeError} for a failed Nominal API call. Its `code` is always
@@ -3563,10 +3609,12 @@ declare class BridgeError extends Error {
  *
  * @example
  * ```ts
+ * import { HttpBridgeError } from '@nominalso/vibe-bridge'
+ *
  * try {
  *   await bridge.getAccount({ path: { account_id: 'missing' } })
  * } catch (err) {
- *   if (err instanceof HttpBridgeError && err.status === 404) {
+ *   if (HttpBridgeError.isHttpBridgeError(err) && err.status === 404) {
  *     // handle not-found
  *   }
  * }
@@ -3575,6 +3623,11 @@ declare class BridgeError extends Error {
 declare class HttpBridgeError extends BridgeError {
     readonly status: number;
     constructor(status: number, message: string);
+    /**
+     * Cross-realm-safe type guard (see {@link BridgeError.isBridgeError}). Returns
+     * `true` only for `HttpBridgeError` instances, not plain `BridgeError`s.
+     */
+    static isHttpBridgeError(err: unknown): err is HttpBridgeError;
 }
 
 interface VibeApiClientOptions {
@@ -3623,6 +3676,13 @@ interface VibeAppHostOptions {
     trustedOrigins: string[];
     /** Returns the current context to send to the iframe on connect. */
     getContext: () => HostContext;
+    /**
+     * Optional PostHog config source. Read **once per iframe** at connect and
+     * delivered via a one-time `POSTHOG_PUSH`, kept separate from `getContext` so
+     * it never re-sends when context or auth later change. Return `undefined` (or
+     * a config with `enabled: false`) to disable in-iframe recording.
+     */
+    getPostHog?: () => PostHogContext | undefined;
     /**
      * The base URL path of this Vibe App in nom-ui, e.g. `/acme/1/apps/fixed-assets`.
      * Used to sync the browser URL with the iframe's internal subroute.
@@ -3675,18 +3735,11 @@ interface VibeAppHostOptions {
  *   onUpload: (p, sendProgress) => uploadToS3(p, sendProgress),
  * })
  *
- * useEffect(() => {
- *   const iframe = iframeRef.current
- *   if (!iframe) return
- *   const unmount = host.mount() // listen before the iframe loads
- *   const onLoad = () => iframe.contentWindow && host.pushContextTo(iframe.contentWindow)
- *   iframe.addEventListener('load', onLoad)
- *   return () => {
- *     iframe.removeEventListener('load', onLoad)
- *     unmount()
- *   }
- * }, [host])
+ * useEffect(() => host.mount(), [host]) // returns the unmount cleanup
  * ```
+ *
+ * `mount()` just starts listening; the iframe identifies itself via its
+ * `CONNECT` handshake, so the host never needs the iframe's `Window` up front.
  */
 declare class VibeAppHost {
     /**
@@ -3699,26 +3752,29 @@ declare class VibeAppHost {
     /** The exact (non-pattern) subset of {@link trustedOrigins} — see {@link concreteTargets}. */
     private readonly exactOrigins;
     /**
-     * Concrete iframe origins observed on validated inbound messages. Because you
-     * cannot `postMessage` to a glob pattern, proactive pushes target these
-     * learned origins (plus the exact allowlist entries) rather than the patterns.
+     * The connected iframe, as two facets of one thing: `connectedWindow` is its
+     * `Window` (identity + the single push target) and `connectedOrigin` is its
+     * origin (what you `postMessage` to — you cannot post to a `Window` ref, nor to
+     * a glob). Both are written together by {@link handleConnect} (the sole writer)
+     * and cleared together on unmount, so they can never diverge.
+     *
+     * There is deliberately no other window reference. The connected window can
+     * only be learned from each `CONNECT` handshake's `event.source`, never at
+     * mount: a reloaded/remounted iframe is a *new* `Window` with the same origin,
+     * so a mount-time window would be stale. The gate blocks every non-`CONNECT`
+     * message whose source isn't `connectedWindow`; every proactive push targets it.
      */
-    private readonly connectedOrigins;
+    private connectedWindow;
+    private connectedOrigin;
     private readonly handlers;
     private readonly commandHandlers;
     private readonly getContext;
+    private readonly getPostHog?;
     private readonly appBasePath;
     private readonly onRequestComplete?;
     private readonly rateLimiter;
     private readonly boundHandleMessage;
     private readonly boundHandlePopState;
-    private iframeWindow;
-    /**
-     * Source windows we've already logged a successful handshake for. The bridge
-     * polls `GET_CONTEXT` on an interval until it connects, so without this the
-     * "Vibe App connected" line repeats on every poll (SSOT §13 F3).
-     */
-    private readonly handshakeLoggedWindows;
     private readonly kindHandlers;
     private dispatchCommand;
     /**
@@ -3738,31 +3794,57 @@ declare class VibeAppHost {
      * Starts listening for bridge messages and sets up browser back/forward sync.
      * Returns a cleanup function to call on unmount.
      *
-     * Pass `iframeWindow` to immediately push context to the iframe. If omitted,
-     * the host will respond to GET_CONTEXT polls from the bridge but won't
-     * proactively push — call `pushContextTo(iframeWindow)` once the iframe has
-     * loaded to trigger the proactive push.
+     * Takes no iframe window: the host learns the iframe from its `CONNECT`
+     * handshake (and re-learns it on every reload), then delivers context as the
+     * reply to that handshake. Just call `mount()` once the host exists.
+     */
+    mount(): () => void;
+    /**
+     * Re-reads `getContext()` and re-pushes it to the connected iframe, so an open
+     * app reacts to a tenant/subsidiary switch or period close without reloading.
+     * PostHog is not re-sent (it rides only the connect handshake). No-op until an
+     * iframe is mounted.
      */
-    mount(iframeWindow?: Window): () => void;
+    refreshContext(): void;
     /**
-     * Pushes the current context to the iframe and updates the stored iframe
-     * window reference. Call this once the iframe has loaded if `mount()` was
-     * called without an `iframeWindow`.
+     * Notifies the connected iframe of a Nominal auth change — a logout
+     * (`authenticated: false`) or an identity/tenant switch (`authenticated: true`
+     * with a new `userId`/`tenant`) — via `AUTH_CHANGED`, so the app re-authenticates
+     * or signs its own backend out. No-op until the iframe has connected. When auth
+     * and context change together, call this *before* {@link refreshContext} ("auth
+     * change, then context").
      */
-    pushContextTo(iframeWindow: Window): void;
+    notifyAuthChange(auth: AuthPayload): void;
     private pushContext;
     private handlePopState;
     private pushToIframe;
+    /**
+     * Sends the host's PostHog config to a freshly connected iframe as a one-time
+     * POSTHOG_PUSH. No-op when no `getPostHog` source is configured or it returns
+     * nothing (recording disabled). Targets the exact handshaking window/origin
+     * (no `concreteTargets` fan-out) since it fires from a validated inbound poll.
+     */
+    private pushPostHog;
     private handleMessage;
+    /**
+     * Handles the CONNECT handshake: records the connecting window/origin (which
+     * opens the connection gate for it) and pushes the initial context + one-time
+     * PostHog config. Only the first CONNECT per origin pushes — later retries are
+     * ignored, so the bridge receives exactly one initial CONTEXT_PUSH (no
+     * spurious onContextChange). A reloaded iframe is a new window and re-connects
+     * normally. If `getContext()` throws, the window is left unconnected so the
+     * bridge's retry can recover.
+     */
+    private handleConnect;
     /**
      * Concrete origins a proactive push may target: the exact allowlist entries
-     * plus any origins seen on validated inbound messages. Never includes glob
-     * patterns (you cannot `postMessage` to one). When only exact origins are
-     * configured this equals the configured set, so behaviour is unchanged.
+     * plus the connected iframe's learned origin. Never includes glob patterns
+     * (you cannot `postMessage` to one). When only exact origins are configured
+     * this equals the configured set, so behaviour is unchanged.
      */
     private concreteTargets;
     private handleRequest;
     private respond;
 }
 
-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 };
+export { type AuthPayload, 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 };