# @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.

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```bash
bun add @suaveplan/api-sse
```

## Quick start

```ts
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`](./src/connection/connection.md) — engine-side `SseConnection` interface.
- [`event`](./src/event/event.md) — `SseEvent` Zod schema + interface.
- [`broker`](./src/broker/broker.md) — engine-side publish / subscribe surface.
- [`replay-buffer`](./src/replay-buffer/replay-buffer.md) — per-(tenant, topic) ring buffer powering `Last-Event-Id` resume.
- [`connection-registry`](./src/connection-registry/connection-registry.md) — multi-index registry for active connections.
- [`capability-id`](./src/capability-id/capability-id.md) — `"sse"` slot in the host's `CapabilityMap`.
- [`error-codes`](./src/error-codes/error-codes.md) — `SSE_CODES` registry + `SseError` class.
- [`error-codes/production-throws`](./src/error-codes/production-throws.md) — canonical throw-site factories.
- [`testing/conformance`](./src/testing/conformance.md) — `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.