API reference

This page summarizes the @segmentify/common host bridge APIs relevant to CDP integration. The canonical platform docs ship with the npm package under docs/.

Registry

setHostBridge(bridge: HostBridgeV1): void
getHostBridge(): HostBridgeV1 | null
waitForHostBridge(): Promise<HostBridgeV1>
registerSegmentifyHostApi(instance: SegmentifyWindowApiInstance): HostBridgeV1 // dashboard only

Host adapters

Function	Side	Purpose
`createSegmentifyDashboardBridge(options)`	Dashboard	Wraps SW + CustomEvents + window API
`createDirectConfigBridge(config)`	Partner mount	Programmatic / federation `mount()`
`createPostMessageBridge(options)`	MFE iframe	Receives parent postMessage init
`bindPostMessageHost(iframe, payload, options)`	Partner parent	Drives iframe over postMessage
`initPostMessageEmbed(options)`	MFE iframe	Bootstrap `embed.html` entry

MFE runtime

// CDP HTTP client — never read window at import time
export const cdpApi = createMfeApi({
  useCdpApi: true,
  headers: { "X-Api-Version": "1.0" },
});

// Partner Bearer-token client
createEmbedApiClient({
  baseURL: "https://api.segmentify.com",
  getAuthToken: () => token,
  defaultHeaders: { "X-Switch-User": "…", "X-Switch-Region": "ALL" },
});

Helper	Purpose
`getHostEnvironment()`	Bridge-first environment lookup
`getHostBaseUrl()`	Bridge-first host base URL
`navigateHost(path)`	Request host navigation
`setBreadcrumbOnHost(breadcrumb)`	Update dashboard breadcrumb
`hideBreadcrumbOnHost()`	Clear dashboard breadcrumb
`BridgeHostDataProvider`	React context from `subscribeHostData()`
`useApiKey()` / `useHostData()`	Consume host account context

`HttpClient` interface

Partners injecting their own axios instance must satisfy:

interface HttpClient {
  get<T>(url: string, config?: HttpRequestConfig): Promise<T>;
  post<T>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<T>;
  put<T>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<T>;
  patch?<T>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<T>;
  delete?<T>(url: string, config?: HttpRequestConfig): Promise<T>;
  extend?(options: { baseURL?: string; headers?: Record<string, string> }): HttpClient;
}

`mount` API signature

import type { DirectHostBridgeConfig } from "@segmentify/common";

type MountOptions = {
  host: DirectHostBridgeConfig;
  basename?: string;
};

type MountHandle = {
  unmount: () => void;
  bridge: DirectHostBridge;
  updateHostData: (data: HostData) => void;
};

function mount(container: HTMLElement, options: MountOptions): Promise<MountHandle>;

DirectHostBridgeConfig requires api: HttpClient (Sauron/host API) and accepts optional cdpApi for CDP-specific calls.

PostMessage protocol

All messages: { type: string, version?: '1', payload?: unknown }.

Type	Direction	Purpose
`SEGMENTIFY_MFE_READY`	iframe → parent	MFE loaded, waiting for init
`SEGMENTIFY_HOST_INIT`	parent → iframe	Initial config (required)
`SEGMENTIFY_HOST_DATA_UPDATE`	parent → iframe	Account context update
`SEGMENTIFY_HOST_AUTH_UPDATE`	parent → iframe	Auth token refresh
`SEGMENTIFY_MFE_NAVIGATE`	iframe → parent	Request parent navigation
`SEGMENTIFY_MFE_ERROR`	iframe → parent	Fatal error reporting

See PostMessage protocol for payload shapes.

Window globals

Global / event	Purpose
`window.SEGMENTIFY_HOST_BRIDGE`	Active bridge (shared across federation bundles)
`segmentify:host-bridge-ready`	Custom event when bridge is registered
`window.SEGMENTIFY_API_INSTANCE`	Legacy dashboard global (backward compat)

CDP HTTP routing

Client	Base URL	Notes
`cdpApi`	`cdpBaseUrl`	Adds `X-Api-Version: 1.0` automatically

Switch headers (X-Switch-User, X-Switch-Region) must be provided by the host via requestHeaders (iframe) or createEmbedApiClient({ defaultHeaders }) (mount).

Version history

Version	Highlights
0.0.15	`createMfeApi` headers-only extend; sandbox all-MFE QA
0.0.14	`requestHeaders` on postMessage host init
0.0.13	Auth token refresh, partner sandbox, integration docs
0.0.12	Direct + postMessage adapters, `./mount` / `./embed`
0.0.11	`createMfeApi`, MFE migration off `window`
0.0.10	Host bridge registry, dashboard adapter