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

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

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

File layout

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.

2.3 KiB Raw Permalink Blame History