@rentaltide/app-sdk 0.1.0

package/src/app.ts

@@ -0,0 +1,265 @@
+/**
+ * App-side client. Runs inside the embedded iframe and is the only thing most
+ * developers import:
+ *
+ * ```ts
+ * import { createApp } from '@rentaltide/app-sdk';
+ * const app = await createApp();
+ * console.log(app.context.account.customerId);
+ * const res = await app.api.get('/bookings?limit=5');
+ * app.toast('Loaded!', 'success');
+ * ```
+ */
+
+import { BridgeEnvelope, envelope, isBridgeEnvelope } from './protocol';
+import type {
+  ApiMethod,
+  ApiRequest,
+  ApiResponse,
+  HostContext,
+  ThemeTokens,
+  ToastSeverity,
+} from './types';
+
+export const SDK_VERSION = '0.1.0';
+
+export interface CreateAppOptions {
+  /**
+   * Origins of the RentalTide host(s) allowed to talk to this app. Defaults to
+   * the document referrer's origin. Set this in production for defense in depth.
+   */
+  hostOrigins?: string[];
+  /** Auto-report content height to the host so the iframe grows to fit. Default true. */
+  autoResize?: boolean;
+  /** Per-request timeout in ms. Default 15000. */
+  timeoutMs?: number;
+  /** Your app's client id, sent on handshake (optional, useful in logs). */
+  appId?: string;
+}
+
+export interface ApiCallOptions {
+  query?: Record<string, string | number | boolean | undefined>;
+}
+
+export interface RentalTideApp {
+  /** The latest host context. Updated in place as the host pushes changes. */
+  readonly context: HostContext;
+  /** Tell the host the app has finished its initial render. */
+  ready(): void;
+  /** Subscribe to context changes (e.g. user navigates to another booking). Returns an unsubscribe fn. */
+  onContextChange(cb: (ctx: HostContext) => void): () => void;
+  /** Subscribe to host theme changes (e.g. dark-mode toggle). Returns an unsubscribe fn. */
+  onThemeChange(cb: (theme: ThemeTokens) => void): () => void;
+  /** Scoped, host-proxied RentalTide API. The app never sees raw credentials. */
+  api: {
+    request<T = unknown>(req: ApiRequest): Promise<ApiResponse<T>>;
+    get<T = unknown>(path: string, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
+    post<T = unknown>(path: string, body?: unknown, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
+    put<T = unknown>(path: string, body?: unknown, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
+    patch<T = unknown>(
+      path: string,
+      body?: unknown,
+      opts?: ApiCallOptions,
+    ): Promise<ApiResponse<T>>;
+    delete<T = unknown>(path: string, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
+  };
+  /** Show a snackbar in the host UI. */
+  toast(message: string, severity?: ToastSeverity): void;
+  /** Ask the host to navigate to an in-app path. */
+  navigate(path: string): void;
+  /** Manually report height (or omit to measure the document). */
+  resize(height?: number): void;
+  /** Re-fetch the current context from the host. */
+  refreshContext(): Promise<HostContext>;
+  /** Tear down listeners and reject any in-flight requests. */
+  destroy(): void;
+}
+
+interface Pending {
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+function safeOrigin(url: string): string {
+  try {
+    return url ? new URL(url).origin : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Initialize the app bridge. Resolves once the host handshake completes and the
+ * initial {@link HostContext} is available.
+ */
+export async function createApp(options: CreateAppOptions = {}): Promise<RentalTideApp> {
+  if (typeof window === 'undefined' || window.parent === window) {
+    throw new Error('[rentaltide-app-sdk] createApp() must run inside the RentalTide host iframe.');
+  }
+
+  const timeoutMs = options.timeoutMs ?? 15000;
+  const autoResize = options.autoResize ?? true;
+  const referrerOrigin = safeOrigin(document.referrer);
+  const allowedOrigins = options.hostOrigins ?? (referrerOrigin ? [referrerOrigin] : []);
+
+  let hostOrigin: string = referrerOrigin || '*';
+  let context: HostContext | null = null;
+  const pending = new Map<string, Pending>();
+  const contextListeners = new Set<(c: HostContext) => void>();
+  const themeListeners = new Set<(t: ThemeTokens) => void>();
+
+  const originAllowed = (origin: string): boolean =>
+    allowedOrigins.length === 0 || allowedOrigins.includes(origin);
+
+  const post = (env: BridgeEnvelope): void => {
+    window.parent.postMessage(env, hostOrigin);
+  };
+
+  const sendRequest = <T>(type: string, payload?: unknown): Promise<T> => {
+    const env = envelope('request', type, { payload });
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(env.id);
+        reject(new Error(`[rentaltide-app-sdk] "${type}" timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      pending.set(env.id, { resolve: resolve as Pending['resolve'], reject, timer });
+      post(env);
+    });
+  };
+
+  const reportHeight = (): void => {
+    const height = Math.ceil(
+      document.documentElement?.scrollHeight || document.body?.scrollHeight || 0,
+    );
+    post(envelope('request', 'ui.resize', { payload: { height } }));
+  };
+
+  const handleMessage = (event: MessageEvent): void => {
+    if (event.source !== window.parent) return;
+    if (!isBridgeEnvelope(event.data)) return;
+    if (!originAllowed(event.origin)) return;
+    // Lock onto the first valid host origin so subsequent posts are targeted.
+    if (hostOrigin === '*') hostOrigin = event.origin;
+
+    const env = event.data as BridgeEnvelope;
+
+    if (env.kind === 'response' && env.replyTo) {
+      const p = pending.get(env.replyTo);
+      if (!p) return;
+      clearTimeout(p.timer);
+      pending.delete(env.replyTo);
+      if (env.ok === false) {
+        p.reject(new Error(env.error?.message || `Request "${env.type}" failed`));
+      } else {
+        p.resolve(env.payload);
+      }
+      return;
+    }
+
+    if (env.kind === 'event') {
+      if (env.type === 'context.changed') {
+        context = env.payload as HostContext;
+        contextListeners.forEach((cb) => cb(context as HostContext));
+      } else if (env.type === 'theme.changed') {
+        const theme = env.payload as ThemeTokens;
+        if (context) context = { ...context, theme };
+        themeListeners.forEach((cb) => cb(theme));
+      } else if (env.type === 'host.closing') {
+        destroy();
+      }
+    }
+  };
+
+  window.addEventListener('message', handleMessage);
+
+  let resizeObserver: ResizeObserver | null = null;
+  const destroy = (): void => {
+    window.removeEventListener('message', handleMessage);
+    resizeObserver?.disconnect();
+    pending.forEach((p) => {
+      clearTimeout(p.timer);
+      p.reject(new Error('[rentaltide-app-sdk] app bridge destroyed'));
+    });
+    pending.clear();
+    contextListeners.clear();
+    themeListeners.clear();
+  };
+
+  // Handshake — establishes the host origin and initial context.
+  context = await sendRequest<HostContext>('handshake', {
+    appId: options.appId,
+    sdkVersion: SDK_VERSION,
+  });
+
+  if (autoResize && typeof ResizeObserver !== 'undefined') {
+    resizeObserver = new ResizeObserver(() => reportHeight());
+    resizeObserver.observe(document.documentElement);
+    reportHeight();
+  }
+
+  const buildReq = (
+    method: ApiMethod,
+    path: string,
+    body?: unknown,
+    opts?: ApiCallOptions,
+  ): ApiRequest => ({ method, path, body, query: opts?.query });
+
+  const api: RentalTideApp['api'] = {
+    request<T = unknown>(req: ApiRequest) {
+      return sendRequest<ApiResponse<T>>('api.request', req);
+    },
+    get<T = unknown>(path: string, opts?: ApiCallOptions) {
+      return sendRequest<ApiResponse<T>>('api.request', buildReq('GET', path, undefined, opts));
+    },
+    post<T = unknown>(path: string, body?: unknown, opts?: ApiCallOptions) {
+      return sendRequest<ApiResponse<T>>('api.request', buildReq('POST', path, body, opts));
+    },
+    put<T = unknown>(path: string, body?: unknown, opts?: ApiCallOptions) {
+      return sendRequest<ApiResponse<T>>('api.request', buildReq('PUT', path, body, opts));
+    },
+    patch<T = unknown>(path: string, body?: unknown, opts?: ApiCallOptions) {
+      return sendRequest<ApiResponse<T>>('api.request', buildReq('PATCH', path, body, opts));
+    },
+    delete<T = unknown>(path: string, opts?: ApiCallOptions) {
+      return sendRequest<ApiResponse<T>>('api.request', buildReq('DELETE', path, undefined, opts));
+    },
+  };
+
+  return {
+    get context() {
+      return context as HostContext;
+    },
+    ready() {
+      reportHeight();
+    },
+    onContextChange(cb) {
+      contextListeners.add(cb);
+      return () => contextListeners.delete(cb);
+    },
+    onThemeChange(cb) {
+      themeListeners.add(cb);
+      return () => themeListeners.delete(cb);
+    },
+    api,
+    toast(message, severity = 'info') {
+      sendRequest('ui.toast', { message, severity }).catch(() => undefined);
+    },
+    navigate(path) {
+      sendRequest('host.navigate', { path }).catch(() => undefined);
+    },
+    resize(height) {
+      if (typeof height === 'number') {
+        post(envelope('request', 'ui.resize', { payload: { height } }));
+      } else {
+        reportHeight();
+      }
+    },
+    async refreshContext() {
+      const next = await sendRequest<HostContext>('context.get');
+      context = next;
+      return next;
+    },
+    destroy,
+  };
+}

package/src/embedLocations.ts

@@ -0,0 +1,101 @@
+/**
+ * Registry of every surface where an app can embed, with the resource the host
+ * provides there and sensible scope suggestions. Drives the app-creation form,
+ * the sandbox location picker, and the developer docs — one source of truth.
+ */
+
+import type { EmbedLocation, EmbedResourceType } from './types';
+import type { Scope } from './scopes';
+
+export interface EmbedLocationMeta {
+  id: EmbedLocation;
+  label: string;
+  description: string;
+  /** Resource type the host provides in `context.resource` here (null if none). */
+  resourceType: EmbedResourceType | null;
+  /** Scopes an app embedding here will typically need. */
+  suggestedScopes: Scope[];
+  /** Rough shape of the embed surface, for layout hints. */
+  surface: 'sidebar' | 'panel' | 'card' | 'fullwidth';
+}
+
+export const EMBED_LOCATIONS: Record<EmbedLocation, EmbedLocationMeta> = {
+  'dashboard-widget': {
+    id: 'dashboard-widget',
+    label: 'Dashboard widget',
+    description: 'A card on the main operator dashboard. No specific resource in context.',
+    resourceType: null,
+    suggestedScopes: ['read:analytics', 'read:bookings'],
+    surface: 'card',
+  },
+  'order-details': {
+    id: 'order-details',
+    label: 'Order details',
+    description: 'Sidebar panel on an order page. Receives the current order.',
+    resourceType: 'order',
+    suggestedScopes: ['read:bookings'],
+    surface: 'sidebar',
+  },
+  'booking-details': {
+    id: 'booking-details',
+    label: 'Booking details',
+    description: 'Panel on a single booking. Receives the current booking.',
+    resourceType: 'booking',
+    suggestedScopes: ['read:bookings'],
+    surface: 'sidebar',
+  },
+  'customer-profile': {
+    id: 'customer-profile',
+    label: 'Customer profile',
+    description: 'Panel on a customer profile. Receives the current customer.',
+    resourceType: 'customer',
+    suggestedScopes: ['read:customers'],
+    surface: 'panel',
+  },
+  'inventory-detail': {
+    id: 'inventory-detail',
+    label: 'Inventory detail',
+    description: 'Panel on an inventory item. Receives the current inventory item.',
+    resourceType: 'inventory',
+    suggestedScopes: ['read:inventory'],
+    surface: 'panel',
+  },
+  'asset-tracking': {
+    id: 'asset-tracking',
+    label: 'Asset tracking',
+    description: 'Panel on the asset/nav board. Receives the current asset.',
+    resourceType: 'asset',
+    suggestedScopes: ['read:inventory', 'read:bookings'],
+    surface: 'panel',
+  },
+  'checkout-flow': {
+    id: 'checkout-flow',
+    label: 'Checkout flow',
+    description: 'Step injected into the booking checkout. Receives the in-progress cart.',
+    resourceType: 'cart',
+    suggestedScopes: ['read:bookings', 'read:pos'],
+    surface: 'fullwidth',
+  },
+  'pos-cart': {
+    id: 'pos-cart',
+    label: 'POS cart',
+    description: 'Panel beside the point-of-sale cart. Receives the active cart.',
+    resourceType: 'cart',
+    suggestedScopes: ['read:pos', 'write:pos'],
+    surface: 'sidebar',
+  },
+  'settings-panel': {
+    id: 'settings-panel',
+    label: 'Settings panel',
+    description: 'A configuration page reachable from the app-store entry. No resource.',
+    resourceType: null,
+    suggestedScopes: [],
+    surface: 'fullwidth',
+  },
+};
+
+export const EMBED_LOCATION_LIST: EmbedLocationMeta[] = Object.values(EMBED_LOCATIONS);
+
+export function getEmbedLocationMeta(id: string): EmbedLocationMeta | undefined {
+  return (EMBED_LOCATIONS as Record<string, EmbedLocationMeta>)[id];
+}

package/src/events.ts

@@ -0,0 +1,39 @@
+/**
+ * Catalog of outbound webhook events RentalTide can send to your app.
+ *
+ * Register a webhook URL + secret and request the `webhooks:receive` scope to
+ * receive these. Each delivery is signed (see the developer docs for
+ * verification). This list mirrors the server's emitter.
+ */
+
+export interface WebhookEventMeta {
+  event: string;
+  description: string;
+}
+
+export const WEBHOOK_EVENT_CATALOG: WebhookEventMeta[] = [
+  { event: 'booking.created', description: 'A new booking/order was created.' },
+  { event: 'booking.updated', description: 'A booking changed (notes, timing, add-ons, assets).' },
+  { event: 'booking.status_changed', description: 'A booking moved to a new status.' },
+  { event: 'booking.checked_in', description: 'A booking was checked in.' },
+  { event: 'booking.cancelled', description: 'A booking was cancelled.' },
+  { event: 'booking.rescheduled', description: 'A booking was rescheduled.' },
+  { event: 'payment.received', description: 'A payment was recorded against a booking.' },
+  { event: 'payment.refunded', description: 'A refund was issued.' },
+  { event: 'customer.created', description: 'A new customer was created.' },
+  { event: 'customer.updated', description: 'A customer record was updated.' },
+  { event: 'app.installed', description: 'Your app was installed by a merchant.' },
+  { event: 'app.uninstalled', description: 'Your app was uninstalled (deprovision here).' },
+];
+
+export const WEBHOOK_EVENTS = WEBHOOK_EVENT_CATALOG.map((e) => e.event);
+
+export type WebhookEventName = (typeof WEBHOOK_EVENT_CATALOG)[number]['event'];
+
+/** Shape of every webhook request body RentalTide POSTs to your endpoint. */
+export interface WebhookPayload<T = Record<string, unknown>> {
+  event: string;
+  /** ISO-8601 timestamp the payload was created. */
+  timestamp: string;
+  data: T;
+}

package/src/host.ts

@@ -0,0 +1,138 @@
+/**
+ * Host-side bridge. Runs in the RentalTide host (the main app and the developer
+ * sandbox) — one instance per embedded iframe. It answers the app's handshake,
+ * proxies scoped API calls, and forwards UI intents (toast/navigate/resize).
+ *
+ * Security model:
+ *  - Only messages from this iframe's `contentWindow` are accepted.
+ *  - Only messages from the declared `appOrigin` are accepted.
+ *  - `onApiRequest` is responsible for enforcing the installation's granted
+ *    scopes (see {@link requiredScope}/{@link hasScope} in `./scopes`).
+ */
+
+import { BridgeEnvelope, envelope, isBridgeEnvelope } from './protocol';
+import type { ApiRequest, ApiResponse, HostContext, ThemeTokens, ToastSeverity } from './types';
+
+export interface CreateHostBridgeOptions {
+  /** The iframe element the app is mounted in. */
+  iframe: HTMLIFrameElement;
+  /**
+   * The exact origin the app is served from (validated on every message).
+   * Use `'*'` only for trusted local sandboxes; never in production.
+   */
+  appOrigin: string;
+  /** Returns the current host context (called on handshake/context.get). */
+  getContext: () => HostContext;
+  /**
+   * Handle a proxied API request. MUST enforce the installation's granted
+   * scopes before performing the call.
+   */
+  onApiRequest: (req: ApiRequest, ctx: HostContext) => Promise<ApiResponse>;
+  onResize?: (height: number) => void;
+  onToast?: (message: string, severity: ToastSeverity) => void;
+  onNavigate?: (path: string) => void;
+  onClose?: () => void;
+  /** Optional observer of all traffic — used by the sandbox message log. */
+  onMessage?: (direction: 'in' | 'out', env: BridgeEnvelope) => void;
+}
+
+export interface HostBridge {
+  /** Push a fresh context to the app (defaults to `getContext()`). */
+  pushContext(ctx?: HostContext): void;
+  /** Notify the app that the host theme changed. */
+  pushTheme(theme: ThemeTokens): void;
+  /** Tear down the listener and tell the app it's closing. */
+  destroy(): void;
+}
+
+export function createHostBridge(options: CreateHostBridgeOptions): HostBridge {
+  const {
+    iframe,
+    appOrigin,
+    getContext,
+    onApiRequest,
+    onResize,
+    onToast,
+    onNavigate,
+    onClose,
+    onMessage,
+  } = options;
+
+  // `srcdoc`/sandboxed iframes report a `null` origin; postMessage must use '*'.
+  const postTarget = appOrigin === 'null' ? '*' : appOrigin;
+
+  const send = (env: BridgeEnvelope): void => {
+    onMessage?.('out', env);
+    iframe.contentWindow?.postMessage(env, postTarget);
+  };
+
+  const respond = (replyTo: string, type: string, payload?: unknown): void => {
+    send(envelope('response', type, { replyTo, ok: true, payload }));
+  };
+
+  const respondError = (replyTo: string, type: string, code: string, message: string): void => {
+    send(envelope('response', type, { replyTo, ok: false, error: { code, message } }));
+  };
+
+  const handleMessage = async (event: MessageEvent): Promise<void> => {
+    if (event.source !== iframe.contentWindow) return;
+    if (appOrigin !== '*' && appOrigin !== 'null' && event.origin !== appOrigin) return;
+    if (!isBridgeEnvelope(event.data)) return;
+
+    const env = event.data as BridgeEnvelope;
+    if (env.kind !== 'request') return;
+    onMessage?.('in', env);
+
+    try {
+      switch (env.type) {
+        case 'handshake':
+        case 'context.get':
+          respond(env.id, env.type, getContext());
+          break;
+        case 'api.request': {
+          const res = await onApiRequest(env.payload as ApiRequest, getContext());
+          respond(env.id, env.type, res);
+          break;
+        }
+        case 'ui.resize':
+          // Fire-and-forget; the app does not await a response.
+          onResize?.((env.payload as { height: number }).height);
+          break;
+        case 'ui.toast': {
+          const p = env.payload as { message: string; severity?: ToastSeverity };
+          onToast?.(p.message, p.severity ?? 'info');
+          respond(env.id, env.type);
+          break;
+        }
+        case 'host.navigate':
+          onNavigate?.((env.payload as { path: string }).path);
+          respond(env.id, env.type);
+          break;
+        case 'host.close':
+          onClose?.();
+          respond(env.id, env.type);
+          break;
+        default:
+          respondError(env.id, env.type, 'unknown_method', `Unknown method: ${env.type}`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Host error';
+      respondError(env.id, env.type, 'host_error', message);
+    }
+  };
+
+  window.addEventListener('message', handleMessage);
+
+  return {
+    pushContext(ctx) {
+      send(envelope('event', 'context.changed', { payload: ctx ?? getContext() }));
+    },
+    pushTheme(theme) {
+      send(envelope('event', 'theme.changed', { payload: theme }));
+    },
+    destroy() {
+      send(envelope('event', 'host.closing'));
+      window.removeEventListener('message', handleMessage);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @rentaltide/app-sdk — Official SDK for building embedded apps on RentalTide.
+ *
+ * App developers import the app-side client:
+ *   import { createApp } from '@rentaltide/app-sdk';
+ *
+ * The RentalTide host (and the developer sandbox) import the host bridge:
+ *   import { createHostBridge } from '@rentaltide/app-sdk';
+ */
+
+// Data shapes
+export * from './types';
+
+// Wire protocol (envelopes, request/event maps, helpers)
+export * from './protocol';
+
+// OAuth scopes + the API-proxy scope policy
+export * from './scopes';
+
+// Embed-location registry
+export * from './embedLocations';
+
+// Webhook event catalog
+export * from './events';
+
+// App-side client (runs in the iframe)
+export { createApp, SDK_VERSION } from './app';
+export type { CreateAppOptions, ApiCallOptions, RentalTideApp } from './app';
+
+// Host-side bridge (runs in RentalTide / the sandbox)
+export { createHostBridge } from './host';
+export type { CreateHostBridgeOptions, HostBridge } from './host';

package/src/protocol.ts

@@ -0,0 +1,104 @@
+/**
+ * The wire protocol for the RentalTide App Bridge.
+ *
+ * Host and embedded app communicate exclusively over `window.postMessage`.
+ * Every message is a {@link BridgeEnvelope} stamped with a namespace marker and
+ * protocol version so unrelated `message` events (and other postMessage users on
+ * the page) are ignored.
+ */
+
+import type { ApiRequest, ApiResponse, HostContext, ThemeTokens, ToastSeverity } from './types';
+
+export const PROTOCOL_VERSION = '1';
+
+/** Marker present on every bridge message; used to filter foreign messages. */
+export const BRIDGE_NAMESPACE = 'rentaltide-app-bridge';
+
+export type MessageKind = 'request' | 'response' | 'event';
+
+export interface BridgeError {
+  code: string;
+  message: string;
+}
+
+export interface BridgeEnvelope<P = unknown> {
+  /** Always {@link BRIDGE_NAMESPACE}. */
+  __rt: typeof BRIDGE_NAMESPACE;
+  /** Protocol version (see {@link PROTOCOL_VERSION}). */
+  v: string;
+  /** Unique message id used to correlate responses to requests. */
+  id: string;
+  kind: MessageKind;
+  /** Method name (requests/responses) or event name (events). */
+  type: string;
+  payload?: P;
+  /** Present on responses. */
+  ok?: boolean;
+  /** Present on failed responses. */
+  error?: BridgeError;
+  /** Id of the request a response is answering. */
+  replyTo?: string;
+}
+
+/**
+ * App → Host request methods, with their request and response payload types.
+ * This is the canonical reference for what an app may ask the host to do.
+ */
+export interface RequestMap {
+  handshake: { req: { appId?: string; sdkVersion: string }; res: HostContext };
+  'context.get': { req: void; res: HostContext };
+  'api.request': { req: ApiRequest; res: ApiResponse };
+  'ui.toast': { req: { message: string; severity?: ToastSeverity }; res: void };
+  'ui.resize': { req: { height: number }; res: void };
+  'host.navigate': { req: { path: string }; res: void };
+  'host.close': { req: void; res: void };
+}
+export type RequestType = keyof RequestMap;
+
+/** Host → App events, with their payload types. */
+export interface EventMap {
+  'context.changed': HostContext;
+  'theme.changed': ThemeTokens;
+  'host.closing': void;
+}
+export type EventType = keyof EventMap;
+
+/** Narrowing type guard for incoming `message` events. */
+export function isBridgeEnvelope(data: unknown): data is BridgeEnvelope {
+  if (typeof data !== 'object' || data === null) return false;
+  const env = data as Record<string, unknown>;
+  return (
+    env.__rt === BRIDGE_NAMESPACE &&
+    typeof env.id === 'string' &&
+    typeof env.kind === 'string' &&
+    typeof env.type === 'string'
+  );
+}
+
+/** Generates a correlation id (RFC4122 v4 when crypto is available). */
+export function newId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/** Builds a well-formed envelope. */
+export function envelope<P>(
+  kind: MessageKind,
+  type: string,
+  parts: Partial<BridgeEnvelope<P>> = {},
+): BridgeEnvelope<P> {
+  return {
+    __rt: BRIDGE_NAMESPACE,
+    v: PROTOCOL_VERSION,
+    id: parts.id ?? newId(),
+    kind,
+    type,
+    ...parts,
+  };
+}