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