Custom events

Beyond the typed helpers, the bridge is a general two-way message channel. Use send and on for block-specific communication the SDK doesn't model: telling the portal something happened, or reacting to a custom message the portal sends your block.

Most blocks won't need these. Reach for them only when the session, entity, and use-case APIs don't cover your need.

send(event, data?)

Post a message to the parent portal.

import { send } from '@epilot/spark-sdk'

send('custom-event', { action: 'save', value: 42 })

on(event, handler)

Subscribe to messages from the parent portal. Supports a trailing * wildcard and '*' for everything. Returns an Unsubscribe.

import { on } from '@epilot/spark-sdk'

const unsubscribe = on<{ action: string }>('custom-event', (data) => {
  console.log('Received:', data.action)
})

// wildcard: every event starting with "custom-"
on('custom-*', (data) => console.log(data))

// cleanup when done
unsubscribe()

Low-level messaging

The bridge primitives are exported for advanced use: building your own protocol layer, custom origin handling, or testing. The higher-level API above is built on these.

import {
  subscribeToParentMessages,
  sendMessageToParent,
} from '@epilot/spark-sdk'

const off = subscribeToParentMessages('my-event', (msgEvent) => {
  console.log(msgEvent.data)
})

sendMessageToParent('my-event', { hello: 'portal' })

Origin safety. When you pass allowedParentOrigins to initialize(), inbound messages from other origins are dropped and outbound messages target the single configured origin instead of *. Prefer that over leaving the bridge open to any parent.