suaveplan/packages/api-stack/api/api-sse/README.md

@suaveplan/api-sse - Abstract Server-Sent Events contracts for @suaveplan/api: SseConnection, SseBroker, SseEvent (Zod), ReplayBuffer with Last-Event-Id resume, SseConnectionRegistry, SSE_CODES, and runSseEngineConformance harness. Concrete engines plug behind these contracts.

Abstract Server-Sent Events contracts for @suaveplan/api. Stage-1 contract package: defines the engine-side SseConnection, SseBroker, ReplayBuffer (Last-Event-Id resume), SseConnectionRegistry, the SSE_CODES error registry, and the runSseEngineConformance harness every concrete engine must pass.

This package ships no concrete engine — @suaveplan/api-sse-bun (and other transports) land at and plug behind these contracts.

Documentation tree

• broker — SseBroker is the engine-side publish / subscribe surface for Server-Sent Events. It mirrors the shape of `@suaveplan/…
  • broker — SseBroker is the engine-side publish / subscribe surface for Server-Sent Events. It mirrors the shape of `@suaveplan/…
• capability-id — The "sse" CapabilityId slot connects this package to the host's CapabilityMap. Plugin authors declare `requires:…
  • capability-id — The "sse" CapabilityId slot connects this package to the host's CapabilityMap. Plugin authors declare `requires:…
• connection — SseConnection is the engine-side contract for a single Server-Sent-Events stream. Concrete engines (api-sse-bun, `a…
  • connection — SseConnection is the engine-side contract for a single Server-Sent-Events stream. Concrete engines (api-sse-bun, `a…
• connection-registry — SseConnectionRegistry is the multi-index registry for active SSE connections. Engines call add on handshake, `remov…
  • connection-registry — SseConnectionRegistry is the multi-index registry for active SSE connections. Engines call add on handshake, `remov…
• error-codes — SSE_CODES is the stable error-code registry every contract-level failure path in the SSE family raises. Concrete engi…
  • error-codes — SSE_CODES is the stable error-code registry every contract-level failure path in the SSE family raises. Concrete engi…
  • production-throws — production-throws exports the canonical factory functions that the host (and concrete SSE engines) invoke at every do…
• event — SseEvent is the wire-shape contract for a single Server-Sent-Events field block: id, optional event, data, opti…
  • event — SseEvent is the wire-shape contract for a single Server-Sent-Events field block: id, optional event, data, opti…
• replay-buffer — ReplayBuffer is the per-(tenant, topic) ring buffer that powers the Last-Event-Id resume contract. Concrete engin…
  • replay-buffer — ReplayBuffer is the per-(tenant, topic) ring buffer that powers the Last-Event-Id resume contract. Concrete engin…
• testing — runSseEngineConformance is the reusable conformance harness every concrete @suaveplan/api-sse engine MUST pass. Eng…
  • conformance — runSseEngineConformance is the reusable conformance harness every concrete @suaveplan/api-sse engine MUST pass. Eng…

Install

bun add @suaveplan/api-sse

Quick start

import {
    createReplayBuffer,
    createConnectionRegistry,
    SSE_CODES,
} from "@suaveplan/api-sse";

const buffer = createReplayBuffer({ eventBufferSize: 1024 });
const registry = createConnectionRegistry();

buffer.append({ id: "1", data: "hello" });
const since = buffer.since("0").length; // 0 (unknown ids throw SSE_CODES.LAST_EVENT_ID_UNKNOWN)

Modules

• connection — engine-side SseConnection interface.
• event — SseEvent Zod schema + interface.
• broker — engine-side publish / subscribe surface.
• replay-buffer — per-(tenant, topic) ring buffer powering Last-Event-Id resume.
• connection-registry — multi-index registry for active connections.
• capability-id — "sse" slot in the host's CapabilityMap.
• error-codes — SSE_CODES registry + SseError class.
• error-codes/production-throws — canonical throw-site factories.
• testing/conformance — runSseEngineConformance harness.

Status

• Package: @suaveplan/api-sse
• Version: 0.1.0
• Stage: 1 of the API plugin system (contracts).
• Tier: universal — zero browser / Node-only deps; runs everywhere the host runs.