first commit

docs/api-stack/api/api-sse-bun/src/options/options.md

@@ -0,0 +1,91 @@
+# `options`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `options` module declares the public configuration surface accepted by
+`createBunSseEngine` and exposes `resolveOptions`, a Zod-backed validator
+that applies every documented default and fails fast on misconfigured
+input. Splitting this from the engine module lets the engine focus on
+stream lifetime while options handle validation, defaults, and the
+runtime-vs-config split (the broker and authenticator are runtime values
+and bypass the schema; the primitive knobs go through Zod).
+
+## Features
+
+- Zod-validated primitive knobs: buffer size, buffer ttl, keep-alive
+  cadence, per-tenant cap, max event bytes, compression on/off, retry ms.
+- `SseAuthenticator` hook signature for handshake-time auth bridge.
+- `SseHandshakeRequest` minimal request view (`headers`, `url`, `method`)
+  so unit tests can inject synthesised values without a live socket.
+- Fully defaulted `ResolvedBunSseEngineOptions` view consumed downstream.
+- `DEFAULT_MAX_EVENT_BYTES = 64 KiB` exposed so callers can reason about
+  the cap without redeclaring it.
+
+## Usage: Basic
+
+```ts
+import { resolveOptions } from "@suaveplan/api-sse-bun";
+
+const resolved = resolveOptions({
+    authenticate: async () => ({
+        tenantId: "acme" as never,
+        principal: null,
+    }),
+});
+console.log(resolved.eventBufferSize); // 256
+```
+
+## Usage: Advanced
+
+```ts
+import { resolveOptions } from "@suaveplan/api-sse-bun";
+
+const resolved = resolveOptions({
+    eventBufferSize: 1024,
+    eventBufferMs: 600_000,
+    keepAliveCommentMs: 30_000,
+    maxConnectionsPerTenant: 2_000,
+    compressionEnabled: false,
+    retryMs: 5_000,
+    authenticate: async (req) => {
+        const token = req.headers.get("authorization") ?? "";
+        if (token === "") {
+            return { tenantId: null, principal: null };
+        }
+        return {
+            tenantId: "acme" as never,
+            principal: null,
+            topics: ["billing", "audit"],
+        };
+    },
+});
+```
+
+## API Reference
+
+- `interface BunSseEngineOptions` — public options bundle; every primitive
+  field is optional, the `authenticate` hook is required.
+- `interface ResolvedBunSseEngineOptions` — fully-defaulted view; primitive
+  fields are non-optional.
+- `interface SseAuthenticationResult` — `{ tenantId, principal, topics? }`.
+- `type SseAuthenticator = (req) => SseAuthenticationResult | Promise<…>`.
+- `interface SseHandshakeRequest` — minimal `{ headers, url, method }`.
+- `function resolveOptions(options): ResolvedBunSseEngineOptions` —
+  Zod-parses primitives, applies defaults, throws
+  `SSE_BUN.HANDSHAKE_REJECTED` on invalid input.
+- `const DEFAULT_MAX_EVENT_BYTES = 65_536`.
+
+## Implementation Notes
+
+The Zod schema deliberately accepts only the primitive knobs. Runtime
+values (`authenticate`, `broker`, `clock`, `plugin`) bypass schema
+validation because Zod cannot meaningfully describe a function or an
+external broker. The schema uses `.strict()` so a misspelled option key
+fails at boot rather than silently using a default. Defaults are pinned
+to match `api-ws-bun`'s reconnect window so a deployment running both
+engines exhibits the same buffer-life surface to clients on either
+transport.