Riftix Console Bridge

Install:

pnpm add @riftix/console-bridge-host

`ConsoleHost`

The central class that manages all iframe channels.

import { createConsoleHost, ConsoleHost } from "@riftix/console-bridge-host";

const host = createConsoleHost(options);

Or use the React provider (preferred) — see React Integration.

`ConsoleHostOptions`

interface ConsoleHostOptions {
  /** Fallback context for channels that don't supply their own. */
  defaultContextProvider?: ContextProvider;

  /** Fallback authorization for channels that don't supply their own. */
  defaultAuthorizationProvider?: AuthorizationProvider;

  /** Extra capability strings advertised in the ready envelope. Default: []. */
  defaultCapabilities?: readonly string[];
}

type ContextProvider       = (channel: IframeChannel) => HostContext | Promise<HostContext>
type AuthorizationProvider = (channel: IframeChannel) => BridgeAuthorization | null | Promise<BridgeAuthorization | null>

`host.register(options)`

host.register({
  iframe:       HTMLIFrameElement;      // the DOM element
  origin:       string;                 // exact origin to accept (e.g. "https://billing.example.com")
  productId:    string;                 // arbitrary product identifier
  contextProvider?:       ContextProvider;
  authorizationProvider?: AuthorizationProvider;
  handlers?:    Partial<Record<BridgeMethodName, MethodHandler<BridgeMethodName>>>;
  capabilities?: readonly string[];
}): IframeChannel

Throws if the host is disposed, the iframe is already registered, or no contextProvider is available (neither per-channel nor default).

`host.unregister(iframe)`

Unregister and dispose the channel for a given iframe element.

host.unregister(iframe: HTMLIFrameElement): void

`host.handle(method, handler)`

host.handle<M extends BridgeMethodName>(
  method:  M,
  handler: MethodHandler<M>
): () => void

type MethodHandler<M> = (
  payload: BridgeMethodRequest<M>,
  context: { channel: IframeChannel }
) => BridgeMethodResponse<M> | Promise<BridgeMethodResponse<M>>

navigation.setBreadcrumbs is handled automatically — the host registers a built-in handler in the constructor. Do not register your own handler for it.

`host.broadcastContext(next)`

Send context:changed to every registered channel.

host.broadcastContext(next: HostContext): void

`host.setAuthorizationForProduct(productId, next)`

Send authorization:changed to every channel whose productId matches.

host.setAuthorizationForProduct(productId: string, next: BridgeAuthorization | null): void

`host.broadcast(event, payload)`

Send any event to every registered channel.

host.broadcast<E extends BridgeEventName>(event: E, payload: BridgeEventPayload<E>): void

Channel lifecycle callbacks

host.onChannelRegistered(handler: (channel: IframeChannel) => void): () => void
host.onChannelUnregistered(handler: (channel: IframeChannel) => void): () => void

Querying channels

host.getChannels(): readonly IframeChannel[]
host.getChannelsForProduct(productId: string): readonly IframeChannel[]

`host.dispose()`

Disposes all channels and removes all listeners. Idempotent.

`IframeChannel`

Returned by host.register(). Represents a single iframe connection.

Public properties

readonly productId: string
readonly origin:    string
readonly iframe:    HTMLIFrameElement

`channel.whenReady`

Promise<void> that resolves after the handshake completes.

`channel.emit(event, payload)`

Send an event to this specific channel.

channel.emit<E extends BridgeEventName>(event: E, payload: BridgeEventPayload<E>): void

No-op before handshake.

Context and authorization

channel.setContext(next: HostContext): void
channel.setAuthorization(next: BridgeAuthorization | null): void
channel.getContext(): HostContext | null
channel.getAuthorization(): BridgeAuthorization | null

Breadcrumbs

channel.getBreadcrumbs(): ReadonlyArray<BridgeBreadcrumb>
channel.onBreadcrumbsChanged(
  handler: (crumbs: ReadonlyArray<BridgeBreadcrumb>) => void
): () => void    // returns unsubscribe

Location

/** Returns the most recently reported path from the client, or null if not yet received. */
channel.getLocation(): string | null

/**
 * Subscribe to location changes reported by the client via navigation.locationChanged.
 * Returns an unsubscribe function.
 */
channel.onLocationChanged(handler: (path: string) => void): () => void

The navigation.locationChanged RPC is handled automatically — you do not register a handler for it. Use onLocationChanged to react to URL changes in the iframe (e.g. to update the host URL bar).

`channel.dispose()`

Tears down the channel. Idempotent.

Host Overview