# `SseEvent` + `sseEventSchema`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`SseEvent` is the wire-shape contract for a single Server-Sent-Events field block: `id`, optional `event`, `data`, optional `retry`. The Zod schema `sseEventSchema` validates the shape at every host → engine boundary so plugin authors catch typos (`eventName` vs `event`) at parse time instead of silently dropping fields on the wire.

The fields follow WHATWG and W3C SSE: every concrete engine serialises the parsed shape onto the wire as `id: <id>\nevent: <event>\ndata: <data>\nretry: <ms>\n\n`. Multi-line `data` is the engine's responsibility — splitting newlines into multiple `data:` lines is a wire-format concern, not part of this contract.

## Features

- `strict()` schema: unknown keys fail parse.
- `id` is non-empty (powers the replay buffer's `since(lastEventId)` lookup).
- `event` is non-empty when supplied; absent stays absent (no default).
- `retry` is a non-negative integer; floats and negatives are rejected at parse.

## Usage: Basic

```ts
import { sseEventSchema } from "@suaveplan/api-sse/event/event";

const event = sseEventSchema.parse({ id: "1", data: "hello" });
```

## Usage: Advanced

```ts
import { sseEventSchema, type SseEvent } from "@suaveplan/api-sse/event/event";

function validatedSend(input: unknown): SseEvent {
    return sseEventSchema.parse(input);
}

const ping: SseEvent = validatedSend({
    id: "evt-42",
    event: "ping",
    data: JSON.stringify({ ts: Date.now() }),
    retry: 15_000,
});
```

## API Reference

- `sseEventSchema: z.ZodObject<...>` — strict Zod schema; `parse(input)` returns a typed `SseEvent`.
- `interface SseEvent` — compile-time view: `{ id: string; event?: string; data: string; retry?: number }`.

## Implementation Notes

The interface is declared separately from the inferred Zod type so consumers can annotate handler arguments without paying for Zod inference cost in their public surface. The runtime schema is the only validator; engines MUST call `sseEventSchema.parse(input)` before queueing for the wire so the replay buffer can rely on a valid `id` field.