# OpenSpec Change: enterprise-api-plugin-sse

- **Change ID**: enterprise-api-plugin-sse
- **Package**: `@suaveplan/api-plugin-sse`
- **Category**: api/data
- **Target path**: `api/data/api-plugin-sse`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-sse.md`

---

## Summary

Deliver `@suaveplan/api-plugin-sse` on the genesis branch from scratch at enterprise quality. Server-Sent Events plugin: per-client event streams keyed by user/topic, fan-out from `@suaveplan/events` bus to connected clients, heartbeat keepalive, backpressure via bounded send queues, auth-gated connections, connection lifecycle tracking. Routes under `/sse`. Events: `sse:client:connected`, `sse:client:disconnected`. Used by analytics dashboard, notifications, real-time feeds.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
| `@suaveplan/api-plugin-auth` (`workspace:^`) | `requireAuth` |
| `@suaveplan/events` (`workspace:^`) | Bus subscriptions for fan-out |
| `@suaveplan/error` (`workspace:^`) | `SseError` hierarchy |
| `@suaveplan/rate-limiter` (`workspace:^`) | Connection rate limits |
| `hono` (`catalog:server`) | SSE helpers |
| `zod` (`catalog:forms`) | Schemas |
| `@opentelemetry/api` | OTel |

---

## Public API surface

```ts
function createSsePlugin(config?: SsePluginConfig): PluginDescriptor

// Registered service:
interface SseService {
  publish(topic: string, event: SseEvent): void
  broadcast(event: SseEvent): void
  connectionCount(): number
  getTopicConnectionCount(topic: string): number
}

interface SseEvent { type: string; data: unknown; id?: string }
interface SsePluginConfig { heartbeatIntervalMs?: number; sendQueueSize?: number; allowedOrigins?: string[] }
```

### Error codes

```ts
type SseErrorCode =
  | "SSE_TOO_MANY_CONNECTIONS"
  | "SSE_AUTH_FAILED"
  | "SSE_TOPIC_INVALID"
```

---

## File layout

```text
api/data/api-plugin-sse/
  package.json  tsconfig.json  vitest.config.ts
  src/
    index.ts  events.ts  types/  errors/
    core/connection-manager/  core/heartbeat/
    services/sse/
    routes/sse/
  tests/integration.test.ts
```

---

## Impact

Prerequisites: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/events`, `@suaveplan/rate-limiter`.