@nominalso/vibe-host 0.0.1 → 0.2.0

package/dist/index.d.cts

@@ -3201,15 +3201,6 @@ interface GetContextPayload {
     bridgeVersion: string;
 }
 
-/**
- * All operations the iframe can invoke on the host, each with a typed request
- * payload and a typed response. Adding a new operation here is all that's
- * required — message union types and handler types below are derived
- * automatically.
- *
- * Operations that also emit intermediate progress events should include a
- * `progress` field with the progress payload type.
- */
 interface UploadPayload {
     buffer: ArrayBuffer;
     fileName: string;
@@ -3220,11 +3211,57 @@ interface UploadPayload {
 interface UploadResponse {
     attachmentId: string;
     name: string;
+    /** Public/presigned URL of the stored file, when the host returns one. */
+    url?: string;
 }
 interface UploadProgress {
     attachmentId: string;
     progress: number;
 }
+/** How the host should apply a navigation. Defaults to `'push'`. */
+type NavigateAction = 'push' | 'replace' | 'refresh';
+/**
+ * Tells the host to navigate. Provide **either** a raw `path` (relative to the
+ * app's tenant/subsidiary base) **or** a named `route` resolved host-side.
+ */
+interface NavigatePayload {
+    /** Raw path relative to the app's base, e.g. `'/journal-entries/123'`. */
+    path?: string;
+    /** Named route key the host resolves, e.g. `'CHART_OF_ACCOUNTS'`. */
+    route?: string;
+    /** Values for route placeholders, e.g. `{ id: '123' }`. */
+    routeParams?: Record<string, string>;
+    /** Navigation method. Defaults to `'push'`. */
+    action?: NavigateAction;
+}
+/** Collapse/expand the host's side navigation. */
+interface SetSideNavPayload {
+    collapsed: boolean;
+}
+/** Switch the host to a different subsidiary. */
+interface SwitchSubsidiaryPayload {
+    subsidiaryId: number;
+}
+/** Targets for a host cache invalidation. */
+interface InvalidateCachePayload {
+    /** API path prefixes to invalidate, e.g. `['/accounting/accounts']`. */
+    paths?: string[];
+    /** Cache tag keys to invalidate, e.g. `['REPORTS', 'SUBSIDIARIES']`. */
+    tags?: string[];
+}
+/** Result of a host cache invalidation. */
+interface InvalidateResult {
+    invalidated: boolean;
+}
+
+/**
+ * All operations the iframe can invoke on the host, each with a typed request
+ * payload and a typed response. Adding a new operation here is all that's
+ * required — message union types and handler types are derived automatically.
+ *
+ * Operations that also emit intermediate progress events should include a
+ * `progress` field with the progress payload type.
+ */
 interface RequestRegistry {
     GET_CHART_OF_ACCOUNTS: {
         payload: Omit<GetCoaFlatApiAccountingSubsidiarySubsidiaryIdCoaAccountGetData, 'url'>;
@@ -3410,6 +3447,10 @@ interface RequestRegistry {
         payload: Omit<GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetData, 'url'>;
         data: GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetResponse;
     };
+    INVALIDATE_CACHE: {
+        payload: InvalidateCachePayload;
+        data: InvalidateResult;
+    };
     GET_CONTEXT: {
         payload: GetContextPayload;
         data: ContextPayload;
@@ -3434,6 +3475,53 @@ type RequestHandlers = {
     } ? (payload: RequestRegistry[K]['payload'], sendProgress: (p: P) => void) => Promise<RequestRegistry[K]['data']> : (payload: RequestRegistry[K]['payload']) => Promise<RequestRegistry[K]['data']>;
 };
 
+/**
+ * An error that crossed the bridge, carrying a machine-readable {@link code}
+ * alongside the human-readable message.
+ *
+ * The host attaches a `code` to failed responses (e.g. `'RATE_LIMITED'`,
+ * `'FILE_TOO_LARGE'`, `'REQUEST_FAILED'`); the bridge rehydrates it into a
+ * `BridgeError` so app `catch` blocks can branch on `error.code` instead of
+ * string-matching `error.message`. A failed Nominal API call rehydrates as the
+ * {@link HttpBridgeError} subtype, which adds the HTTP `status`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccounts({})
+ * } catch (err) {
+ *   if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+ *     // back off and retry
+ *   }
+ * }
+ * ```
+ */
+declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * A {@link BridgeError} for a failed Nominal API call. Its `code` is always
+ * `'REQUEST_FAILED'`; the HTTP {@link status} is carried as a structured field
+ * so callers can branch on it (e.g. `err.status === 404`) instead of parsing
+ * the code string.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccount({ path: { account_id: 'missing' } })
+ * } catch (err) {
+ *   if (err instanceof HttpBridgeError && err.status === 404) {
+ *     // handle not-found
+ *   }
+ * }
+ * ```
+ */
+declare class HttpBridgeError extends BridgeError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
 interface VibeApiClientOptions {
     baseUrl: string;
     /**
@@ -3446,7 +3534,24 @@ interface VibeApiClientOptions {
 
 type HostHandlers = Omit<RequestHandlers, 'GET_CONTEXT'>;
 type HostContext = Omit<ContextPayload, 'hostVersion'>;
+/**
+ * Notified after each request resolves — except the `GET_CONTEXT` connect poll,
+ * which is exempt. Used by nom-ui for SWR busting (SSOT §5j).
+ */
+interface RequestCompleteInfo {
+    /** The operation type, e.g. `'POST_TASK_OUTPUT'`. */
+    type: string;
+    /** Whether the operation succeeded. */
+    ok: boolean;
+    /** The request payload that was handled. */
+    payload: unknown;
+}
 interface VibeAppHostOptions {
+    /**
+     * Iframe origins allowed to talk to this host. Messages from any other origin
+     * are ignored, and context/pushes are only sent to these origins. Must match
+     * the Vibe App's origin exactly (e.g. `'https://my-vibe-app.lovable.app'`).
+     */
     trustedOrigins: string[];
     /** Returns the current context to send to the iframe on connect. */
     getContext: () => HostContext;
@@ -3455,21 +3560,98 @@ interface VibeAppHostOptions {
      * Used to sync the browser URL with the iframe's internal subroute.
      */
     appBasePath: string;
+    /**
+     * Points the built-in handler map at the Nominal API (e.g. nom-ui's proxy
+     * route). The host provides handlers for every protocol operation out of the
+     * box; this just tells them where to send requests. Defaults to
+     * `{ baseUrl: '', stripApiPrefix: false }`.
+     */
     clientConfig?: VibeApiClientOptions;
+    /** Fire-and-forget. Resolve a path / named route and push to the host router. */
+    onNavigate?: (payload: NavigatePayload) => void;
+    /** Fire-and-forget. Collapse/expand the host side nav. */
+    onSetSideNav?: (payload: SetSideNavPayload) => void;
+    /** Fire-and-forget. Switch subsidiary (host owns validation + navigation). */
+    onSwitchSubsidiary?: (payload: SwitchSubsidiaryPayload) => void;
+    /** Awaited. Invalidate host cache by tags/paths. Defaults to a no-op. */
+    onInvalidateCache?: (payload: InvalidateCachePayload) => Promise<InvalidateResult>;
+    /**
+     * Awaited. Real file upload — replaces the built-in stub (DP2). When omitted,
+     * `UPLOAD_FILE` requests reject with a `'NOT_WIRED'` coded error.
+     */
+    onUpload?: (payload: UploadPayload, sendProgress: (p: UploadProgress) => void) => Promise<UploadResponse>;
+    /** Optional. Notified after each request resolves (except the `GET_CONTEXT` connect poll) — used by nom-ui for SWR busting (SSOT §5j). */
+    onRequestComplete?: (info: RequestCompleteInfo) => void;
+    /** Requests/min before a request trips `RATE_LIMITED` (DP5). Default 60. */
+    rateLimit?: number;
 }
+
+/**
+ * Host-side counterpart to `VibeAppBridge`. Construct it with the trusted
+ * iframe origin(s), a `getContext` callback, the app's base path, and a
+ * `clientConfig` pointing at the Nominal API; then call {@link VibeAppHost.mount}
+ * to start listening. The handler map for all protocol API operations is built
+ * automatically — you do not pass those handlers. Non-API side effects
+ * (navigation, side nav, subsidiary switch, cache invalidation, upload) are
+ * supplied via the optional injected callbacks.
+ *
+ * @example
+ * ```tsx
+ * // In a React (nom-ui) component:
+ * const host = new VibeAppHost({
+ *   trustedOrigins: ['https://my-vibe-app.lovable.app'],
+ *   appBasePath: `/${tenant}/${subsidiary}/apps/${slug}`,
+ *   getContext: () => ({ tenant, subsidiaryId, subsidiaries, user, lastClosedPeriodSlug }),
+ *   clientConfig: { baseUrl: '/api/proxy', stripApiPrefix: true },
+ *   onNavigate: (p) => router.push(resolve(p)),
+ *   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])
+ * ```
+ */
 declare class VibeAppHost {
     private readonly trustedOrigins;
     private readonly handlers;
+    private readonly commandHandlers;
     private readonly getContext;
     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;
-    private readonly commandHandlers;
+    /**
+     * Commands: `REPORT_SUBROUTE` is handled internally (transport + traversal
+     * guard, item `l`); navigation/UI side effects are injected by the consumer,
+     * falling back to warn-and-ignore (DP4).
+     */
+    private buildCommandHandlers;
+    /**
+     * Requests: the built-in API map (hey-api), plus the injected/awaited side
+     * effects with safe defaults — unwired `UPLOAD_FILE` rejects with a coded
+     * error; unwired `INVALIDATE_CACHE` resolves to a no-op (DP4).
+     */
     private initializeHandlers;
-    constructor({ trustedOrigins, getContext, appBasePath, clientConfig }: VibeAppHostOptions);
+    constructor(opts: VibeAppHostOptions);
     /**
      * Starts listening for bridge messages and sets up browser back/forward sync.
      * Returns a cleanup function to call on unmount.
@@ -3494,4 +3676,4 @@ declare class VibeAppHost {
     private respond;
 }
 
-export { type HostContext, type HostHandlers, type RequestHandlers, VibeAppHost, type VibeAppHostOptions };
+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 };

package/dist/index.d.ts

@@ -3201,15 +3201,6 @@ interface GetContextPayload {
     bridgeVersion: string;
 }
 
-/**
- * All operations the iframe can invoke on the host, each with a typed request
- * payload and a typed response. Adding a new operation here is all that's
- * required — message union types and handler types below are derived
- * automatically.
- *
- * Operations that also emit intermediate progress events should include a
- * `progress` field with the progress payload type.
- */
 interface UploadPayload {
     buffer: ArrayBuffer;
     fileName: string;
@@ -3220,11 +3211,57 @@ interface UploadPayload {
 interface UploadResponse {
     attachmentId: string;
     name: string;
+    /** Public/presigned URL of the stored file, when the host returns one. */
+    url?: string;
 }
 interface UploadProgress {
     attachmentId: string;
     progress: number;
 }
+/** How the host should apply a navigation. Defaults to `'push'`. */
+type NavigateAction = 'push' | 'replace' | 'refresh';
+/**
+ * Tells the host to navigate. Provide **either** a raw `path` (relative to the
+ * app's tenant/subsidiary base) **or** a named `route` resolved host-side.
+ */
+interface NavigatePayload {
+    /** Raw path relative to the app's base, e.g. `'/journal-entries/123'`. */
+    path?: string;
+    /** Named route key the host resolves, e.g. `'CHART_OF_ACCOUNTS'`. */
+    route?: string;
+    /** Values for route placeholders, e.g. `{ id: '123' }`. */
+    routeParams?: Record<string, string>;
+    /** Navigation method. Defaults to `'push'`. */
+    action?: NavigateAction;
+}
+/** Collapse/expand the host's side navigation. */
+interface SetSideNavPayload {
+    collapsed: boolean;
+}
+/** Switch the host to a different subsidiary. */
+interface SwitchSubsidiaryPayload {
+    subsidiaryId: number;
+}
+/** Targets for a host cache invalidation. */
+interface InvalidateCachePayload {
+    /** API path prefixes to invalidate, e.g. `['/accounting/accounts']`. */
+    paths?: string[];
+    /** Cache tag keys to invalidate, e.g. `['REPORTS', 'SUBSIDIARIES']`. */
+    tags?: string[];
+}
+/** Result of a host cache invalidation. */
+interface InvalidateResult {
+    invalidated: boolean;
+}
+
+/**
+ * All operations the iframe can invoke on the host, each with a typed request
+ * payload and a typed response. Adding a new operation here is all that's
+ * required — message union types and handler types are derived automatically.
+ *
+ * Operations that also emit intermediate progress events should include a
+ * `progress` field with the progress payload type.
+ */
 interface RequestRegistry {
     GET_CHART_OF_ACCOUNTS: {
         payload: Omit<GetCoaFlatApiAccountingSubsidiarySubsidiaryIdCoaAccountGetData, 'url'>;
@@ -3410,6 +3447,10 @@ interface RequestRegistry {
         payload: Omit<GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetData, 'url'>;
         data: GetTenantUsersApiTenancyTenantTenantIdOrNameUsersGetResponse;
     };
+    INVALIDATE_CACHE: {
+        payload: InvalidateCachePayload;
+        data: InvalidateResult;
+    };
     GET_CONTEXT: {
         payload: GetContextPayload;
         data: ContextPayload;
@@ -3434,6 +3475,53 @@ type RequestHandlers = {
     } ? (payload: RequestRegistry[K]['payload'], sendProgress: (p: P) => void) => Promise<RequestRegistry[K]['data']> : (payload: RequestRegistry[K]['payload']) => Promise<RequestRegistry[K]['data']>;
 };
 
+/**
+ * An error that crossed the bridge, carrying a machine-readable {@link code}
+ * alongside the human-readable message.
+ *
+ * The host attaches a `code` to failed responses (e.g. `'RATE_LIMITED'`,
+ * `'FILE_TOO_LARGE'`, `'REQUEST_FAILED'`); the bridge rehydrates it into a
+ * `BridgeError` so app `catch` blocks can branch on `error.code` instead of
+ * string-matching `error.message`. A failed Nominal API call rehydrates as the
+ * {@link HttpBridgeError} subtype, which adds the HTTP `status`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccounts({})
+ * } catch (err) {
+ *   if (err instanceof BridgeError && err.code === 'RATE_LIMITED') {
+ *     // back off and retry
+ *   }
+ * }
+ * ```
+ */
+declare class BridgeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * A {@link BridgeError} for a failed Nominal API call. Its `code` is always
+ * `'REQUEST_FAILED'`; the HTTP {@link status} is carried as a structured field
+ * so callers can branch on it (e.g. `err.status === 404`) instead of parsing
+ * the code string.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await bridge.getAccount({ path: { account_id: 'missing' } })
+ * } catch (err) {
+ *   if (err instanceof HttpBridgeError && err.status === 404) {
+ *     // handle not-found
+ *   }
+ * }
+ * ```
+ */
+declare class HttpBridgeError extends BridgeError {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
 interface VibeApiClientOptions {
     baseUrl: string;
     /**
@@ -3446,7 +3534,24 @@ interface VibeApiClientOptions {
 
 type HostHandlers = Omit<RequestHandlers, 'GET_CONTEXT'>;
 type HostContext = Omit<ContextPayload, 'hostVersion'>;
+/**
+ * Notified after each request resolves — except the `GET_CONTEXT` connect poll,
+ * which is exempt. Used by nom-ui for SWR busting (SSOT §5j).
+ */
+interface RequestCompleteInfo {
+    /** The operation type, e.g. `'POST_TASK_OUTPUT'`. */
+    type: string;
+    /** Whether the operation succeeded. */
+    ok: boolean;
+    /** The request payload that was handled. */
+    payload: unknown;
+}
 interface VibeAppHostOptions {
+    /**
+     * Iframe origins allowed to talk to this host. Messages from any other origin
+     * are ignored, and context/pushes are only sent to these origins. Must match
+     * the Vibe App's origin exactly (e.g. `'https://my-vibe-app.lovable.app'`).
+     */
     trustedOrigins: string[];
     /** Returns the current context to send to the iframe on connect. */
     getContext: () => HostContext;
@@ -3455,21 +3560,98 @@ interface VibeAppHostOptions {
      * Used to sync the browser URL with the iframe's internal subroute.
      */
     appBasePath: string;
+    /**
+     * Points the built-in handler map at the Nominal API (e.g. nom-ui's proxy
+     * route). The host provides handlers for every protocol operation out of the
+     * box; this just tells them where to send requests. Defaults to
+     * `{ baseUrl: '', stripApiPrefix: false }`.
+     */
     clientConfig?: VibeApiClientOptions;
+    /** Fire-and-forget. Resolve a path / named route and push to the host router. */
+    onNavigate?: (payload: NavigatePayload) => void;
+    /** Fire-and-forget. Collapse/expand the host side nav. */
+    onSetSideNav?: (payload: SetSideNavPayload) => void;
+    /** Fire-and-forget. Switch subsidiary (host owns validation + navigation). */
+    onSwitchSubsidiary?: (payload: SwitchSubsidiaryPayload) => void;
+    /** Awaited. Invalidate host cache by tags/paths. Defaults to a no-op. */
+    onInvalidateCache?: (payload: InvalidateCachePayload) => Promise<InvalidateResult>;
+    /**
+     * Awaited. Real file upload — replaces the built-in stub (DP2). When omitted,
+     * `UPLOAD_FILE` requests reject with a `'NOT_WIRED'` coded error.
+     */
+    onUpload?: (payload: UploadPayload, sendProgress: (p: UploadProgress) => void) => Promise<UploadResponse>;
+    /** Optional. Notified after each request resolves (except the `GET_CONTEXT` connect poll) — used by nom-ui for SWR busting (SSOT §5j). */
+    onRequestComplete?: (info: RequestCompleteInfo) => void;
+    /** Requests/min before a request trips `RATE_LIMITED` (DP5). Default 60. */
+    rateLimit?: number;
 }
+
+/**
+ * Host-side counterpart to `VibeAppBridge`. Construct it with the trusted
+ * iframe origin(s), a `getContext` callback, the app's base path, and a
+ * `clientConfig` pointing at the Nominal API; then call {@link VibeAppHost.mount}
+ * to start listening. The handler map for all protocol API operations is built
+ * automatically — you do not pass those handlers. Non-API side effects
+ * (navigation, side nav, subsidiary switch, cache invalidation, upload) are
+ * supplied via the optional injected callbacks.
+ *
+ * @example
+ * ```tsx
+ * // In a React (nom-ui) component:
+ * const host = new VibeAppHost({
+ *   trustedOrigins: ['https://my-vibe-app.lovable.app'],
+ *   appBasePath: `/${tenant}/${subsidiary}/apps/${slug}`,
+ *   getContext: () => ({ tenant, subsidiaryId, subsidiaries, user, lastClosedPeriodSlug }),
+ *   clientConfig: { baseUrl: '/api/proxy', stripApiPrefix: true },
+ *   onNavigate: (p) => router.push(resolve(p)),
+ *   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])
+ * ```
+ */
 declare class VibeAppHost {
     private readonly trustedOrigins;
     private readonly handlers;
+    private readonly commandHandlers;
     private readonly getContext;
     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;
-    private readonly commandHandlers;
+    /**
+     * Commands: `REPORT_SUBROUTE` is handled internally (transport + traversal
+     * guard, item `l`); navigation/UI side effects are injected by the consumer,
+     * falling back to warn-and-ignore (DP4).
+     */
+    private buildCommandHandlers;
+    /**
+     * Requests: the built-in API map (hey-api), plus the injected/awaited side
+     * effects with safe defaults — unwired `UPLOAD_FILE` rejects with a coded
+     * error; unwired `INVALIDATE_CACHE` resolves to a no-op (DP4).
+     */
     private initializeHandlers;
-    constructor({ trustedOrigins, getContext, appBasePath, clientConfig }: VibeAppHostOptions);
+    constructor(opts: VibeAppHostOptions);
     /**
      * Starts listening for bridge messages and sets up browser back/forward sync.
      * Returns a cleanup function to call on unmount.
@@ -3494,4 +3676,4 @@ declare class VibeAppHost {
     private respond;
 }
 
-export { type HostContext, type HostHandlers, type RequestHandlers, VibeAppHost, type VibeAppHostOptions };
+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 };