@telemetryos/sdk-bridge

The postMessage communication layer between platform host environments and TelemetryOS SDK applications running in iframes.

Who This Is For

This package is for platform host developers — the teams building Player-Program, Manager-UI, Studio-UI, and Application-SDK-Program. These host environments embed TelemetryOS applications as iframes and need to send/receive messages with them.

App developers don't use this package directly. The @telemetryos/sdk and @telemetryos/root-sdk packages provide the app-side Client class that communicates with the Bridge automatically.

How It Fits Together

Host environment (Player-Program, Studio-UI, etc.)
  └── Bridge (this package) — listens for ClientMessages, sends BridgeMessages
        ↕ postMessage
  └── iframe: TelemetryOS application
        └── Client (@telemetryos/root-sdk) — sends ClientMessages, listens for BridgeMessages

Installation

npm install @telemetryos/sdk-bridge

Usage

import { Bridge } from '@telemetryos/sdk-bridge'
import type { ClientMessage, BridgeMessage } from '@telemetryos/sdk-bridge'

const bridge = new Bridge()

// Handle messages from SDK applications
bridge.onMessage = (message: ClientMessage) => {
  console.log(`${message.name} from ${message.applicationSpecifier}`)

  // Respond to the application
  if (message.responseName) {
    bridge.send({
      name: message.responseName,
      data: { /* response payload */ },
    })
  }
}

// Start listening for messages
bridge.bind()

// Broadcast a message to all embedded applications
bridge.send({
  name: 'store.valueChanged',
  data: { key: 'theme', value: 'dark' },
})

// Stop listening when done
bridge.unbind()

API

Bridge

| Method | Description | |--------|-------------| | bind() | Attaches a message event listener to the window. Incoming messages are validated against the ClientMessage schema and passed to onMessage. | | unbind() | Removes the event listener. | | send(message: BridgeMessage) | Broadcasts a message to every window.frames[i] via postMessage. | | onMessage?: (message: ClientMessage) => void | Callback invoked when a valid ClientMessage is received from an iframe. |

Message Types

ClientMessage — sent from SDK applications to the host:

| Field | Type | Description | |-------|------|-------------| | telemetrySdkVersion | string | SDK version of the sending application | | applicationSpecifier | string | Unique identifier for the application version | | applicationInstance | string | Instance ID (from URL query params) | | runtime | 'window' \| 'worker' | Execution context of the sender | | name | string | Message type (e.g. store.getValue) | | data | any | Payload | | responseName? | string | Name the host should use when responding | | subscriptionName? | string | Name for ongoing subscription updates | | unsubscribeName? | string | Name to cancel a subscription |

BridgeMessage — sent from the host to SDK applications:

| Field | Type | Description | |-------|------|-------------| | name | string | Message type | | data | any | Payload |

Validators and Formatters

| Export | Description | |--------|-------------| | clientMessageValidator | Zod schema for validating incoming ClientMessage objects | | bridgeMessageValidator | Zod schema for validating BridgeMessage objects | | formatClientMessage(data) | Adds type: 'client' to a ClientMessage for postMessage | | formatBridgeMessage(data) | Adds type: 'bridge' to a BridgeMessage for postMessage |

Key Behaviors

• Zod validation: Incoming messages are parsed with clientMessageValidator.safeParse(). Invalid messages are silently ignored (defensive against browser noise).
• Version mismatch warnings: If a message looks like a ClientMessage (has type: 'client' or known fields) but fails validation, a console warning is logged to help diagnose SDK version mismatches.
• Broadcast: send() posts to all window.frames — individual SDK clients filter for messages relevant to them.
• Self-filtering: Messages from the host's own window (event.source === window) are ignored to prevent loops.