/**
 * `@platform-modules/realtime` — isomorphic wire contract for the realtime substrate.
 *
 * This barrel is TYPE-ONLY and browser-safe: it carries no runtime code and no
 * Workers globals, so a browser/SSR consumer (e.g. `@platform-modules/realtime-react`) can import
 * it without dragging `Queue`/`DurableObjectState` into a DOM compile.
 *
 * The Workers-locked server helpers (Durable Object accept/broadcast, Queue
 * publish/consume, constant-time secret verify) live behind the `/server`
 * subpath (`@platform-modules/realtime/server`) — never imported here, so this
 * barrel stays free of Workers globals.
 */

/**
 * Producer→queue→DO transport event. The module owns the envelope (idempotency id,
 * timestamp, scope, the security-critical targetUserId); the HOST owns `type` + `payload`.
 * Generic so the host's event-type union and payload map are the contract, not `unknown`.
 */
export interface RealtimeEvent<TType extends string = string, TPayload = unknown> {
  id: string // UUID — idempotency on duplicate delivery
  type: TType // host's event-type union
  scope: string // routing key the host names (e.g. tenant id / room name)
  targetUserId?: string // SECURITY: set ⇒ user-scoped delivery only; unset ⇒ scope-wide
  payload: TPayload
  timestamp: string // ISO 8601
}

/**
 * DO→client wire frame convention. `v` is the wire-compat version — the one boundary a
 * connected browser pins against; bump on a breaking frame change. The host extends with
 * its own `type` union + fields. (One prior app already versions its frames `v:1`; another did not
 * — versioning here adopts the more forward-compatible convention as the seam default.)
 */
export interface ServerFrame<TType extends string = string> {
  v: number
  type: TType
}