@karum/app-bridge

Karum App Bridge SDK — typed postMessage communication layer between embedded partner apps (running inside an iframe in the Karum merchant panel) and the host shell.

This is a typescript-only library shipped as ESM (dist/index.js + dist/index.d.ts). It has zero runtime dependencies.

Status: skeleton. The public surface is stable, but the action surface area will continue to grow in WS-6.

Install

pnpm add @karum/app-bridge

Inside a partner app (iframe)

import { createAppBridge } from "@karum/app-bridge"

const bridge = createAppBridge({
  appId: "my-partner-app",
  hostOrigin: "https://app.karumtek.com",
})

bridge.toast.show({ message: "Saved!", type: "success" })

bridge.modal.open({
  title: "Confirm",
  content: "Publish to all stores?",
  actions: [
    { id: "cancel", label: "Cancel" },
    { id: "publish", label: "Publish", variant: "primary" },
  ],
})

bridge.navigate.to("/products/123")

Inside the merchant panel (host)

import { createAppBridgeHost } from "@karum/app-bridge"

const host = createAppBridgeHost({
  allowedOrigins: ["https://my-partner-app.karum.app"],
})

host.on("toast.show", (payload, meta) => {
  console.log(`[${meta.origin}] toast`, payload.message)
})

host.on("modal.open", (payload) => {
  showHostModal(payload.title, payload.content, payload.actions ?? [])
})

Origin allowlist

The host validates MessageEvent.origin against allowedOrigins. Messages from any other origin are dropped silently. Messages that do not carry the source: "karum-app-bridge" envelope are also ignored, so the channel does not fire on unrelated postMessage traffic.

Message envelope

Every message follows this shape:

type AppBridgeMessage = {
  source: "karum-app-bridge"
  version: 1
  type: AppBridgeAction
  payload: unknown
  correlationId?: string
}

type is a discriminated union; payload is narrowed accordingly.