@saacms/plugin-realtime 0.1.0

package/dist/durable-object.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @saacms/plugin-realtime — v0.3 Durable Object (cross-isolate fan-out +
+ * `Last-Event-ID` replay buffer + DO-side heartbeat).
+ *
+ * On Cloudflare every Worker request is a fresh isolate, so a `publish()`
+ * triggered by a write in isolate A never reaches an SSE subscriber held
+ * open in isolate B's per-instance `Map`. The Durable Object fixes this:
+ * the host wires `binding.idFromName("<slug>:<id>")` so every isolate that
+ * touches a given resource key routes to the SAME DO instance. That DO holds
+ * the open subscriber streams in process-local memory; one DO == one resource
+ * key, so no key filtering is needed inside the DO.
+ *
+ * Frame format is reused verbatim from the v0.1 path (`formatFrame` +
+ * `KEEPALIVE_FRAME` exported by `plugin.ts`) so a subscriber cannot tell
+ * whether it was served in-isolate or via the DO.
+ *
+ * v0.2 scope (still here, behaviourally UNCHANGED):
+ *
+ *   - `GET` + `Accept: text/event-stream` → register the request's stream
+ *     controller in an in-memory `Set`, return the SSE `Response` (first
+ *     frame `:keepalive\n\n`, then `event:/id:/data:` frames).
+ *   - `POST` with a JSON `RealtimeEvent` body → broadcast it to every
+ *     registered controller in THIS DO, return `204`.
+ *   - Dead-controller cleanup on `enqueue` throw + on stream `cancel`.
+ *
+ * v0.3 scope (THIS dispatch — purely additive; the no-`Last-Event-ID`
+ * subscribe path, the binding contract, and the frame format are untouched):
+ *
+ *   1. A bounded in-memory ring buffer. Every published event is pushed
+ *      `{ id, frameBytes, tsMs }` BEFORE fan-out, then evicted oldest-first
+ *      when `length > maxEvents` OR an entry's age exceeds `maxAgeMs`
+ *      (defaults 100 / 1h).
+ *   2. `Last-Event-ID` replay on subscribe. A reconnecting client whose id is
+ *      still in the buffer receives every buffered frame AFTER it (in order)
+ *      BEFORE any live frame; an id older than the buffer (evicted) or never
+ *      seen gets one `event: saacms-resync` frame instead so it knows to
+ *      refetch canonical state (it cannot trust a partial gap). No
+ *      `Last-Event-ID` ⇒ exact v0.2 behaviour (keepalive then live).
+ *   3. A DO-side heartbeat `setInterval` (default 30s), created lazily on the
+ *      first subscriber and cleared when the last one leaves (no leaked timer
+ *      in an idle DO). `stop()` clears it deterministically for tests.
+ *
+ * Retention/heartbeat wiring: the host registers the DO class with the
+ * Workers runtime, which constructs it with no args, so the simplest wiring
+ * that does NOT touch the v0.2 binding contract (`idFromName().get().fetch`)
+ * is: the DO defaults to 100 events / 1h / 30s and accepts an OPTIONAL
+ * constructor override (`new SaacmsRealtimeDO({ retention, heartbeatMs, now })`).
+ * Tests use that seam directly; a host that wants non-default retention
+ * subclasses/wraps the registered class. Threading `RealtimeOptions.retention`
+ * from the plugin through the synthetic binding request is deferred (it would
+ * require widening `RealtimeRouteContext` to forward client headers, which is
+ * out of v0.3's "inside the DO" scope).
+ *
+ * TODO(v0.4): `state.storage`-backed buffer so it survives DO eviction; v0.3
+ *   is in-memory only — a DO eviction loses the buffer, and the resync frame
+ *   is the documented coverage for that case.
+ */
+/** Optional constructor override for retention / heartbeat / clock seam. */
+export interface RealtimeDOConfig {
+    readonly retention?: {
+        readonly maxEvents?: number;
+        readonly maxAgeMs?: number;
+    };
+    /** DO-side heartbeat interval in ms. Default 30_000. */
+    readonly heartbeatMs?: number;
+    /**
+     * Clock seam. Defaults to `Date.now`. Injected by tests so age-based
+     * eviction is deterministic without real sleeps (scope test #5).
+     */
+    readonly now?: () => number;
+}
+/**
+ * One Durable Object instance per resource key. The host registers this class
+ * with the Workers runtime under the `SAACMS_REALTIME` binding (see ADR 0023
+ * §"Architectural lines we draw"). Structurally satisfies the
+ * `SaacmsRealtimeDO` contract declared in `plugin.ts` — TS is structural, so
+ * the matching `fetch(request): Promise<Response>` shape is the conformance;
+ * it is checked at every use site (`DurableObjectStubLike.fetch` delegation
+ * in the binding path + the test mock).
+ */
+export declare class SaacmsRealtimeDO {
+    #private;
+    constructor(config?: RealtimeDOConfig);
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Stop the DO-side heartbeat timer. Auto-invoked when the last subscriber
+     * leaves; exposed so tests can clear it deterministically (mirrors the v0.1
+     * publisher's `stop()`).
+     */
+    stop(): void;
+    /**
+     * Test-only debug accessor — mirrors `RealtimePublisherInternal.
+     * __subscriberCount` so the DO's pruning invariant can be asserted without
+     * poking at the private `Set`. Not part of the host-facing surface.
+     */
+    __subscriberCount(): number;
+    /** Test-only: is the lazy heartbeat interval currently live? */
+    __heartbeatActive(): boolean;
+    /** Test-only: current ring-buffer length (post-eviction). */
+    __bufferSize(): number;
+}
+//# sourceMappingURL=durable-object.d.ts.map

package/dist/durable-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-object.d.ts","sourceRoot":"","sources":["../src/durable-object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAOH,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;QAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAC3B,CAAA;IACD,wDAAwD;IACxD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAaD;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;;gBAYf,MAAM,CAAC,EAAE,gBAAgB;IAO/B,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IA0JhD;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAIZ;;;;OAIG;IACH,iBAAiB,IAAI,MAAM;IAI3B,gEAAgE;IAChE,iBAAiB,IAAI,OAAO;IAI5B,6DAA6D;IAC7D,YAAY,IAAI,MAAM;CAGvB"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @saacms/plugin-realtime — public surface.
+ *
+ * Opt-in SSE/Durable-Object pub-sub plugin per ADR 0023 amendment 2026-05-15.
+ * The framework is feature-complete WITHOUT this plugin via polling + ETag
+ * (the correctness layer); installing this plugin upgrades record-edit
+ * propagation from "≤ Cache-Control max-age" latency to sub-200ms (the
+ * efficiency layer).
+ *
+ * v0.1: single-isolate in-memory fan-out. v0.2: opt-in Durable Object
+ * cross-isolate fan-out when a `DurableObjectNamespace` binding is supplied;
+ * the no-binding path stays byte-for-byte behaviourally identical to v0.1.
+ */
+export { realtime } from "./plugin.ts";
+export type { RealtimeOptions, RealtimeEvent, RealtimePublisher, RealtimePublisherInternal, RealtimeRouteContext, DurableObjectIdLike, DurableObjectStubLike, DurableObjectNamespaceLike, } from "./plugin.ts";
+export { SaacmsRealtimeDO } from "./durable-object.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,aAAa,CAAA;AAMpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/index.js

@@ -0,0 +1,293 @@
+// src/plugin.ts
+var DEFAULT_HEARTBEAT_MS = 30000;
+var KEEPALIVE_FRAME = `:keepalive
+
+`;
+var SUBSCRIBE_ROUTE = "GET /api/saacms/v1/:collection/:id/subscribe";
+function resourceKey(slug, id) {
+  return `${slug}:${id}`;
+}
+function pickEventId(event) {
+  if ((event.type === "snapshot" || event.type === "changed") && event.etag != null) {
+    return event.etag;
+  }
+  return new Date().toISOString();
+}
+function pickEventData(event) {
+  return event.type === "deleted" ? { id: event.id } : event.record;
+}
+function formatFrame(event) {
+  const id = pickEventId(event);
+  const data = JSON.stringify(pickEventData(event));
+  return `event: ${event.type}
+id: ${id}
+data: ${data}
+
+`;
+}
+function realtime(options) {
+  const registry = new Map;
+  const encoder = new TextEncoder;
+  const keepaliveBytes = encoder.encode(KEEPALIVE_FRAME);
+  const heartbeatMs = options?.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+  const binding = options?.binding;
+  function doStub(key) {
+    return binding.get(binding.idFromName(key));
+  }
+  function add(key, handle) {
+    let set = registry.get(key);
+    if (set == null) {
+      set = new Set;
+      registry.set(key, set);
+    }
+    set.add(handle);
+  }
+  function remove(key, handle) {
+    const set = registry.get(key);
+    if (set == null)
+      return;
+    set.delete(handle);
+    if (set.size === 0)
+      registry.delete(key);
+  }
+  function broadcast(key, bytes) {
+    const set = registry.get(key);
+    if (set == null || set.size === 0)
+      return;
+    const dead = [];
+    for (const handle of set) {
+      try {
+        handle.controller.enqueue(bytes);
+      } catch {
+        dead.push(handle);
+      }
+    }
+    for (const h of dead)
+      remove(key, h);
+  }
+  function handleSubscribe(c) {
+    const slug = c.req.param("collection") ?? "";
+    const id = c.req.param("id") ?? "";
+    const key = resourceKey(slug, id);
+    if (binding != null) {
+      return doStub(key).fetch(new Request("https://saacms-realtime-do/subscribe", {
+        method: "GET",
+        headers: { Accept: "text/event-stream" }
+      }));
+    }
+    let handle;
+    const stream = new ReadableStream({
+      start(controller) {
+        handle = { controller };
+        add(key, handle);
+        controller.enqueue(keepaliveBytes);
+      },
+      cancel() {
+        if (handle != null)
+          remove(key, handle);
+      }
+    });
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive"
+      }
+    });
+  }
+  const publisher = {
+    async publish(event) {
+      const key = resourceKey(event.slug, event.id);
+      if (binding != null) {
+        await doStub(key).fetch(new Request("https://saacms-realtime-do/publish", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(event)
+        }));
+        return;
+      }
+      const bytes = encoder.encode(formatFrame(event));
+      broadcast(key, bytes);
+    },
+    stop() {
+      clearInterval(heartbeatTimer);
+    },
+    __subscriberCount(slug, id) {
+      return registry.get(resourceKey(slug, id))?.size ?? 0;
+    }
+  };
+  const heartbeatTimer = setInterval(() => {
+    for (const key of registry.keys())
+      broadcast(key, keepaliveBytes);
+  }, heartbeatMs);
+  heartbeatTimer.unref?.();
+  return {
+    name: "@saacms/plugin-realtime",
+    version: "0.1.0",
+    routes: {
+      [SUBSCRIBE_ROUTE]: handleSubscribe
+    },
+    services: {
+      realtime: publisher
+    }
+  };
+}
+// src/durable-object.ts
+var DEFAULT_MAX_EVENTS = 100;
+var DEFAULT_MAX_AGE_MS = 3600000;
+var DEFAULT_HEARTBEAT_MS2 = 30000;
+
+class SaacmsRealtimeDO {
+  #subscribers = new Set;
+  #encoder = new TextEncoder;
+  #keepaliveBytes = this.#encoder.encode(KEEPALIVE_FRAME);
+  #buffer = [];
+  #maxEvents;
+  #maxAgeMs;
+  #heartbeatMs;
+  #now;
+  #heartbeatTimer;
+  constructor(config) {
+    this.#maxEvents = config?.retention?.maxEvents ?? DEFAULT_MAX_EVENTS;
+    this.#maxAgeMs = config?.retention?.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    this.#heartbeatMs = config?.heartbeatMs ?? DEFAULT_HEARTBEAT_MS2;
+    this.#now = config?.now ?? Date.now;
+  }
+  async fetch(request) {
+    if (request.method === "POST") {
+      return this.#handlePublish(request);
+    }
+    const accept = request.headers.get("Accept") ?? "";
+    if (request.method === "GET" && accept.includes("text/event-stream")) {
+      return this.#handleSubscribe(request);
+    }
+    return new Response("Not Found", { status: 404 });
+  }
+  #idFromFrame(frame) {
+    return frame.split(`
+`, 2)[1].slice("id: ".length);
+  }
+  #prune() {
+    const cutoff = this.#now() - this.#maxAgeMs;
+    while (this.#buffer.length > 0 && this.#buffer[0].tsMs < cutoff) {
+      this.#buffer.shift();
+    }
+    while (this.#buffer.length > this.#maxEvents) {
+      this.#buffer.shift();
+    }
+  }
+  #resyncFrame() {
+    const newest = this.#buffer.length > 0 ? this.#buffer[this.#buffer.length - 1].id : new Date(this.#now()).toISOString();
+    return `event: saacms-resync
+id: ${newest}
+data: {"reason":"buffer-miss"}
+
+`;
+  }
+  #removeSubscriber(controller) {
+    this.#subscribers.delete(controller);
+    if (this.#subscribers.size === 0)
+      this.#stopHeartbeat();
+  }
+  #ensureHeartbeat() {
+    if (this.#heartbeatTimer != null || this.#subscribers.size === 0)
+      return;
+    this.#heartbeatTimer = setInterval(() => {
+      const dead = [];
+      for (const controller of this.#subscribers) {
+        try {
+          controller.enqueue(this.#keepaliveBytes);
+        } catch {
+          dead.push(controller);
+        }
+      }
+      for (const c of dead)
+        this.#removeSubscriber(c);
+    }, this.#heartbeatMs);
+    this.#heartbeatTimer.unref?.();
+  }
+  #stopHeartbeat() {
+    if (this.#heartbeatTimer != null) {
+      clearInterval(this.#heartbeatTimer);
+      this.#heartbeatTimer = undefined;
+    }
+  }
+  #handleSubscribe(request) {
+    const lastEventId = request.headers.get("Last-Event-ID");
+    let replayFrames = [];
+    let resyncBytes;
+    if (lastEventId != null) {
+      this.#prune();
+      const idx = this.#buffer.findIndex((e) => e.id === lastEventId);
+      if (idx === -1) {
+        resyncBytes = this.#encoder.encode(this.#resyncFrame());
+      } else {
+        replayFrames = this.#buffer.slice(idx + 1).map((e) => e.frameBytes);
+      }
+    }
+    let controllerRef;
+    const stream = new ReadableStream({
+      start: (controller) => {
+        controllerRef = controller;
+        controller.enqueue(this.#keepaliveBytes);
+        if (resyncBytes != null)
+          controller.enqueue(resyncBytes);
+        for (const frame of replayFrames)
+          controller.enqueue(frame);
+        this.#subscribers.add(controller);
+        this.#ensureHeartbeat();
+      },
+      cancel: () => {
+        if (controllerRef != null)
+          this.#removeSubscriber(controllerRef);
+      }
+    });
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive"
+      }
+    });
+  }
+  async#handlePublish(request) {
+    const event = await request.json();
+    const frame = formatFrame(event);
+    const frameBytes = this.#encoder.encode(frame);
+    this.#buffer.push({
+      id: this.#idFromFrame(frame),
+      frameBytes,
+      tsMs: this.#now()
+    });
+    this.#prune();
+    const dead = [];
+    for (const controller of this.#subscribers) {
+      try {
+        controller.enqueue(frameBytes);
+      } catch {
+        dead.push(controller);
+      }
+    }
+    for (const c of dead)
+      this.#removeSubscriber(c);
+    return new Response(null, { status: 204 });
+  }
+  stop() {
+    this.#stopHeartbeat();
+  }
+  __subscriberCount() {
+    return this.#subscribers.size;
+  }
+  __heartbeatActive() {
+    return this.#heartbeatTimer != null;
+  }
+  __bufferSize() {
+    return this.#buffer.length;
+  }
+}
+export {
+  realtime,
+  SaacmsRealtimeDO
+};

package/dist/plugin.d.ts

@@ -0,0 +1,168 @@
+/**
+ * @saacms/plugin-realtime — v0.1 (single-isolate, in-memory).
+ *
+ * Ships the contract end-to-end on a single Workers/Bun/Node isolate so the
+ * wiring + SSE frame format are proven before the v0.2 cross-isolate
+ * Durable-Object fan-out lands. The v0.2 dispatch swaps the in-memory
+ * `Map<resourceKey, Set<SubscriberHandle>>` for a `SAACMS_REALTIME`
+ * Durable Object stub bound in `wrangler.toml` per ADR 0023 §"Architectural
+ * lines we draw" + ADR 0024 §"Platform-specific enhancement layer".
+ *
+ * v0.1 scope (this file):
+ *
+ *   1. Per-plugin-instance subscriber registry closed over by `realtime()`.
+ *      State is NOT module-level — two instances created in the same test
+ *      file have independent registries. This is the test #11 invariant.
+ *   2. `GET /api/saacms/v1/<slug>/<id>/subscribe` SSE handler that returns a
+ *      `text/event-stream` ReadableStream. Registers on `start`, unregisters
+ *      on `cancel`. First frame is `:keepalive\n\n` per RFC 8895 §6 comment
+ *      lines so clients see the connection is live before any record event.
+ *   3. `services.realtime.publish(event)` — looks up subscribers by
+ *      `"<slug>:<id>"` and writes one SSE frame per subscriber. Failed
+ *      enqueues (controller closed) drop the subscriber from the registry.
+ *   4. Single `setInterval(heartbeatMs)` per instance walks the registry
+ *      and writes `:keepalive\n\n` to every open subscriber. Default
+ *      30s; tests inject a small value via `opts.heartbeatMs`. The timer
+ *      is `.unref()`-ed so it never keeps the Bun/Node process alive.
+ *
+ * Plugin `routes` shape (test #10 + future runtime adoption):
+ *
+ *   ```ts
+ *   routes: {
+ *     "GET /api/saacms/v1/:collection/:id/subscribe": (c) => Response
+ *   }
+ *   ```
+ *
+ *   One method-plus-path key, one Hono `Context => Response | Promise<Response>`
+ *   handler value. The runtime's plugin-route adoption (a separate dispatch)
+ *   parses the `"<METHOD> <path>"` key and calls `app[method.toLowerCase()]`.
+ *   Tests mount the handler manually on a fresh `new Hono()` and exercise it.
+ *
+ * v0.2 (THIS dispatch) adds — purely additive, the v0.1 path above is
+ * untouched and remains the fallback when no DO binding is supplied:
+ *
+ *   - Cloudflare Durable Object class (`SaacmsRealtimeDO`, in the sibling
+ *     `durable-object.ts`) for cross-isolate fan-out; one DO instance per
+ *     resource key holds the open request handles.
+ *   - A binding-presence branch in `realtime()`: when `options.binding` is
+ *     supplied the subscribe handler + `publish()` route through
+ *     `binding.idFromName("<slug>:<id>").get(...).fetch(...)`; when it is
+ *     absent the v0.1 in-isolate path runs UNCHANGED (no-platform-dependency
+ *     guarantee, ADR 0023 amendment 2026-05-15).
+ *
+ * Deferred to v0.3 (documented TODOs, not built here):
+ *
+ *   - `Last-Event-ID` replay from a DO `state.storage` buffer (RFC 8895 §4).
+ *     v0.2's DO is in-memory `Set` only.
+ *   - A DO-side heartbeat. v0.2's DO does NOT run its own keepalive interval;
+ *     this is acceptable because Cloudflare terminates idle SSE itself and
+ *     the client `EventSource` auto-reconnects. The in-isolate path keeps its
+ *     `setInterval` heartbeat (below) unchanged.
+ *   - OpenAPI spec extender registering the subscribe path.
+ *   - HATEOAS `_links.subscribe` injection into resource envelopes.
+ *   - Per-record access-predicate evaluation on the subscription request +
+ *     per-frame access re-check on publish (ADR 0006 §2 grain).
+ */
+import type { PluginDef } from "@saacms/core";
+/**
+ * Structural shape of the only Hono Context member the handler reads
+ * (`c.req.param("collection")`, `c.req.param("id")`). Typed structurally so the
+ * plugin doesn't take a runtime dep on `hono` — Hono's own Context satisfies
+ * this shape via duck typing when the runtime mounts the route.
+ */
+export interface RealtimeRouteContext {
+    readonly req: {
+        param(name: string): string | undefined;
+    };
+}
+/**
+ * Structural mirror of the Workers `DurableObjectId`. Defined locally so the
+ * plugin takes NO runtime/type dep on `@cloudflare/workers-types` — exactly
+ * how `@saacms/plugin-cache-kv` mirrors `KVNamespace`. The host's real
+ * `DurableObjectId` satisfies this via duck typing.
+ */
+export interface DurableObjectIdLike {
+    toString(): string;
+    readonly name?: string;
+}
+/** Structural mirror of the Workers `DurableObjectStub` (only `fetch`). */
+export interface DurableObjectStubLike {
+    fetch(request: Request): Promise<Response>;
+}
+/** Structural mirror of the Workers `DurableObjectNamespace` binding. */
+export interface DurableObjectNamespaceLike {
+    idFromName(name: string): DurableObjectIdLike;
+    get(id: DurableObjectIdLike): DurableObjectStubLike;
+}
+export interface RealtimeOptions {
+    /**
+     * The Workers `DurableObjectNamespace` binding for cross-isolate fan-out
+     * (v0.2). When supplied, subscribe + publish route through one DO per
+     * resource key. When OMITTED, the v0.1 in-isolate path runs unchanged —
+     * the no-platform-dependency guarantee (ADR 0023 amendment 2026-05-15).
+     */
+    readonly binding?: DurableObjectNamespaceLike;
+    /** Override the Durable Object binding name. Default: SAACMS_REALTIME. */
+    readonly bindingName?: string;
+    /** Per-resource event-buffer retention. Defaults: 100 events / 1h. */
+    readonly retention?: {
+        readonly maxEvents?: number;
+        readonly maxAgeMs?: number;
+    };
+    /**
+     * Heartbeat interval in ms. Default 30_000. Override in tests so the
+     * `:keepalive\n\n` walk can be asserted without real-time waits.
+     */
+    readonly heartbeatMs?: number;
+}
+/** A single record-lifecycle event the plugin fans out. */
+export type RealtimeEvent = {
+    readonly type: "snapshot";
+    readonly slug: string;
+    readonly id: string;
+    readonly record: unknown;
+    readonly etag?: string;
+} | {
+    readonly type: "changed";
+    readonly slug: string;
+    readonly id: string;
+    readonly record: unknown;
+    readonly etag?: string;
+} | {
+    readonly type: "deleted";
+    readonly slug: string;
+    readonly id: string;
+};
+/** Publisher API the runtime calls to fan out a domain event. */
+export interface RealtimePublisher {
+    publish(event: RealtimeEvent): Promise<void>;
+    /**
+     * Stop the heartbeat timer. Tests call this in `afterEach` so the suite
+     * exits cleanly; production code may call it on host shutdown.
+     */
+    stop(): void;
+}
+/**
+ * Internal debug accessor exposed for tests to verify registry-state
+ * invariants (e.g. that cancelled subscribers are removed; that two plugin
+ * instances do not share state). Not part of the public surface — cast to
+ * `RealtimePublisherInternal` only in test code.
+ */
+export interface RealtimePublisherInternal extends RealtimePublisher {
+    __subscriberCount(slug: string, id: string): number;
+}
+/** The Durable Object class shape the host registers with the Workers runtime. */
+export interface SaacmsRealtimeDO {
+    fetch(request: Request): Promise<Response>;
+}
+/** Exported so the v0.2 Durable Object reuses the exact v0.1 frame format. */
+export declare const KEEPALIVE_FRAME = ":keepalive\n\n";
+/** Exported so the v0.2 Durable Object reuses the exact v0.1 frame format. */
+export declare function formatFrame(event: RealtimeEvent): string;
+/**
+ * Build a `@saacms/plugin-realtime` instance. State is closed over by the
+ * returned object so two `realtime()` calls produce independent registries
+ * (test #11). Call `services.realtime.stop()` to clear the heartbeat timer.
+ */
+export declare function realtime(options?: RealtimeOptions): PluginDef;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@saacms/plugin-realtime",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --build --noEmit",
+    "prepack": "cp package.json package.json.pack-bak && bun run ../../scripts/prepack-pkg.ts",
+    "postpack": "mv package.json.pack-bak package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@saacms/core": "workspace:*",
+    "@cloudflare/workers-types": "^4.20240925.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}