opinionated-machine 10.4.0 → 10.5.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # opinionated-machine
 
+## 10.5.0
+
+### Minor Changes
+
+- c2c7154: Read SSE responses as they are written, and with the contract's typing, on both test paths.
+  
+  - `injectApiSSE` now injects with Fastify's `payloadAsStream` and exposes `head` (status and headers, as soon as the handler calls `sse.start()`) and `stream(signal?)`, which yields the contract's typed, validated events as the handler writes them. Progressive delivery can be asserted without `app.listen()`, a base URL or manual connection cleanup. `closed`, `events()` and `bodyForStatus()` are unchanged.
+  - `connectApiSSE(baseUrl, contract, params, options?)` connects over real HTTP using the contract for method, path, query params, headers and body, and reads the stream as the same discriminated union `injectApiSSE().events()` returns. `SSEHttpClient` gained `apiEvents(contract, signal?)` and `collectApiEvents(contract, countOrPredicate, timeout?)` for connections that already exist.
+  - A payload that fails its SSE event schema no longer reaches the test as an event that is simply missing: routes built with `buildApiRoute` report the failed send — event name, Zod issues and payload — to the helper reading the stream. A failure that ended the stream early is thrown by `events()` / `stream()` / the `connectApiSSE` readers; one the route caught and streamed around is recorded instead, so a handler with a working fallback keeps passing. `injectApiSSE(...).sendFailures()` and `connectApiSSE(...).sendFailures()` expose every record, `handled` flag included. Test-only, keyed on a header that only the helpers produce and that is ignored unless it names a diagnostics scope open in the same process.
+  - `connectApiSSE`'s readers reject a response that is not an event stream with its status and body, instead of waiting out the collection timeout on a stream that was never going to arrive, and invoke a caller's `collectEvents` predicate exactly once per event.
+
 ## 10.4.0
 
 ### Minor Changes

package/README.md

@@ -75,6 +75,8 @@ Very opinionated DI framework for fastify, built on top of awilix
     - [SSEHttpClient](#ssehttpclient)
     - [SSEInjectClient](#sseinjectclient)
     - [Contract-Aware Inject Helpers](#contract-aware-inject-helpers)
+    - [Contract-Aware HTTP Helpers](#contract-aware-http-helpers)
+    - [When a Handler Fails to Send an Event](#when-a-handler-fails-to-send-an-event)
 - [Dual-Mode Controllers (SSE + Sync)](#dual-mode-controllers-sse--sync)
   - [Overview](#overview)
   - [Defining Dual-Mode Contracts](#defining-dual-mode-contracts)
@@ -1484,7 +1486,7 @@ The test client depends on the session mode:
 | Session Mode | Test Client | Why |
 |-------------|-------------|--------|
 | `autoClose` | `SSEInjectClient` or `injectSSE`/`injectPayloadSSE` | Handler completes and closes connection; all events available at once |
-| `keepAlive` | `SSEHttpClient` | Connection stays open; events arrive incrementally via server push |
+| `keepAlive` | `SSEHttpClient` (`connectApiSSE` for `defineApiContract` contracts) | Connection stays open; events arrive incrementally via server push |
 
 Enable the connection spy by passing `isTestMode: true` in diOptions (required for `awaitServerConnection`).
 
@@ -1654,8 +1656,29 @@ it('returns the documented 400 body for an empty segment', async () => {
 })
 ```
 
+```ts
+it('sends each issue as soon as it is found', async () => {
+  const { head, stream } = injectApiSSE(app, lqaSegmentContract, { body: { segment: 'hello' } })
+
+  // The head is on the wire as soon as the handler calls sse.start()
+  expect((await head).statusCode).toBe(200)
+
+  for await (const event of stream()) {
+    // Each event is observed while the handler is still producing the next one
+    if (event.event === 'issue') expect(handlerFinished).toBe(false)
+  }
+})
+```
+
 `closed` and `bodyForStatus` behave as they do on `injectSSE`, except that `bodyForStatus` resolves its schema from `responsesByStatusCode`, following the same exact → range → `'default'` precedence as the contract client. `events()` is additionally available: it parses the SSE body and validates each event against the contract's SSE schemas, throwing when the response isn't a stream, when an event name isn't declared, or when a payload fails its schema.
 
+Two accessors read the response before it completes, so an inject-based suite can assert *progressive delivery* without opening a real port for it:
+
+- `head` — `{ statusCode, headers }`, resolved as soon as the response head is on the wire (for a streaming handler, at `sse.start()`).
+- `stream(signal?)` — the same typed, validated events `events()` returns, yielded as the handler writes them. The request is injected with Fastify's `payloadAsStream`; events are buffered from the moment it is injected, so a generator started late replays the stream from its first event, a consumer that breaks early leaves `closed` / `events()` intact, and the handler is never blocked waiting to be read.
+
+`closed` and `events()` still wait for the response to complete, so a route that never closes its stream (a `keepAlive` session) can only be read through `stream()` — or over real HTTP with [`connectApiSSE`](#contract-aware-http-helpers).
+
 The request always carries `accept: text/event-stream`, so a status that declares a stream answers with it — including a dual-mode status whose content map also carries a JSON schema. Those statuses are therefore not callable through `bodyForStatus`; read them with `events()`, or use `injectByApiContract` when you want the JSON side. Conversely, a contract that declares no SSE response at all types `events` as `never`, so calling it is a compile error rather than a guaranteed throw. `events()` is typed from the SSE schemas of *every* declared status, merged the same way the runtime merges them, so a contract streaming on both `200` and `'4xx'` yields the union of both event sets. See [ApiContract controller docs](./lib/api-contracts/docs.md#testing) for the full testing guide.
 
 ### SSESessionSpy API
@@ -2241,7 +2264,7 @@ The library provides utilities for testing SSE endpoints.
 | Session Mode | Test Client | Reason |
 |-------------|-------------|--------|
 | `autoClose` | `SSEInjectClient` or `injectSSE`/`injectPayloadSSE` | Handler completes and closes connection; all events available at once |
-| `keepAlive` | `SSEHttpClient` | Connection stays open; events arrive incrementally via server push |
+| `keepAlive` | `SSEHttpClient` (`connectApiSSE` for `defineApiContract` contracts) | Connection stays open; events arrive incrementally via server push |
 
 `SSEInjectClient` and `injectSSE`/`injectPayloadSSE` do the same thing (Fastify inject), but `injectSSE`/`injectPayloadSSE` provide type safety via contracts while `SSEInjectClient` works with raw URLs. Contracts built with `defineApiContract` use `injectApiSSE` instead of `injectSSE`/`injectPayloadSSE`.
 
@@ -2254,7 +2277,7 @@ The library provides utilities for testing SSE endpoints.
 | **Connection lifecycle** | Handler must close for request to complete | Can stay open indefinitely |
 | **Server requirement** | No `listen()` needed | Requires a listening server (`SSETestServer.start(app)` or manual `app.listen()`) |
 | **Request body** | `injectPayloadSSE` / `connectWithBody` | `method` + `body` connect options |
-| **Assertions before the handler finishes** | Not possible (response is buffered) | `client.response` is available as soon as headers arrive |
+| **Assertions before the handler finishes** | `injectApiSSE`'s `head` / `stream()` (other inject helpers buffer the whole response) | `client.response` is available as soon as headers arrive |
 | **Best for** | `autoClose` SSE (OpenAI-style, batch exports) | `keepAlive` SSE (notifications, live feeds, rooms), streams whose headers must be asserted mid-handler |
 | **Dual-mode sync** | Use `app.inject()` with `accept: 'application/json'` | Same |
 
@@ -2506,6 +2529,66 @@ const result = await closed
 const events = parseSSEEvents(result.body)
 ```
 
+For contracts built with `defineApiContract`, use `injectApiSSE` — it types and validates the events for you, and `stream()` yields them as the handler writes them. See [Contracts built with `defineApiContract`: `injectApiSSE`](#contracts-built-with-defineapicontract-injectapisse).
+
+#### Contract-Aware HTTP Helpers
+
+`connectApiSSE` is the real-HTTP counterpart of `injectApiSSE`: the same typed, validated event union, over a connection that can stay open. Use it for `keepAlive` routes, whose response never completes, and wherever a suite needs a real socket.
+
+```ts
+import { connectApiSSE, SSETestServer } from 'opinionated-machine'
+
+const server = await SSETestServer.start(app)
+
+// Method, path, query params, headers and body all come from the contract
+const client = await connectApiSSE(server.baseUrl, lqaSegmentContract, {
+  body: { segment: 'hello' },
+})
+
+expect(client.response.status).toBe(200) // asserted while the handler is still working
+
+for await (const event of client.events()) {
+  if (event.event === 'issue') expect(event.data.severity).toBe('minor') // typed by the contract
+  if (event.event === 'review') break
+}
+
+client.close()
+await server.close()
+```
+
+- `client.events(signal?)` and `client.collectEvents(countOrPredicate, timeout?)` mirror `SSEHttpClient`'s readers, with each event validated against the contract's SSE schemas and typed as a union on `event` — the predicate sees the narrowed type too, and is invoked exactly once per event.
+- Both readers reject a response that isn't an event stream (a documented `400`/`401` raised before `sse.start()`, say) with its status and body, rather than reporting a stream that produced no events. `client.response` is still readable afterwards, so the JSON body can be asserted.
+- `client.response` is the fetch `Response`, available before any event is consumed.
+- `client.raw` is the underlying `SSEHttpClient`, for anything this wrapper doesn't cover.
+- Pass `{ awaitServerConnection: { spy } }` as a fourth argument (with a spy from `createSSESessionSpy()`) to also wait for the server-side session of a `keepAlive` route; the call then resolves to `{ client, serverConnection }`.
+
+On a connection you already have, the same typing is available per read: `client.apiEvents(contract)` and `client.collectApiEvents(contract, countOrPredicate)` on any `SSEHttpClient`.
+
+#### When a Handler Fails to Send an Event
+
+`session.send(name, payload)` validates the payload against the contract's schema for that event and throws when it doesn't match. The throw happens inside the handler: the event never reaches the wire, the stream ends early with HTTP 200, and the reason only lands in the server log — leaving the test to explain an event that is simply missing.
+
+Routes built with `buildApiRoute` report those failures to whichever helper is reading the stream. When the failure is what cut the stream short — nothing caught it — `events()`, `stream()` and the `connectApiSSE` readers throw with the offending event name, its Zod issues and the rejected payload:
+
+```
+events() — 1 SSE send failure recorded for this request:
+  - event "issue" was never sent: severity: Invalid option: expected one of "neutral"|"minor"|"major"|"critical"; payload: {"severity":"min"}
+```
+
+A failure the route *recovered* from does not fail the read. A handler that catches its own best-effort send and streams a fallback instead produced exactly the response it meant to, so the readers deliver it and record the failure as context; the same goes for a `sendStream()` source that throws while producing its next message, which is reported as the source failing rather than blamed on the last event that did reach the client.
+
+Both `injectApiSSE(...).sendFailures()` and `connectApiSSE(...).sendFailures()` return every record (`{ eventName?, data?, message, issues?, error, handled }`) — including the recovered ones — for assertions the thrown message doesn't cover:
+
+```ts
+const { closed, events, sendFailures } = injectApiSSE(app, lqaSegmentContract, { body })
+await closed
+
+expect(await events()).toHaveLength(2) // the fallback stream is intact
+expect(sendFailures()).toMatchObject([{ eventName: 'issue', handled: true }])
+```
+
+This is test-only and costs production traffic nothing: the helpers tag their requests with an `x-om-sse-diagnostics-id` header, and a session is instrumented only when that header names a diagnostics scope open in the same process — something only those helpers create. A stale or forged header matches nothing.
+
 ## Dual-Mode Controllers (SSE + Sync)
 
 Dual-mode controllers handle both SSE streaming and sync responses on the same route path, automatically branching based on the `Accept` header. This is ideal for APIs that support both real-time streaming and traditional request-response patterns.

package/dist/lib/api-contracts/apiRouteBuilder.d.ts

@@ -1,4 +1,4 @@
-import type { ApiContract } from '@lokalise/api-contracts';
+import { type ApiContract } from '@lokalise/api-contracts';
 import { type ApiRouteOptions as FastifyApiRouteOptions, type InferApiHandler } from '@lokalise/fastify-api-contracts';
 import type { RouteOptions } from 'fastify';
 import type { GatewayMetadata } from '../gateway/gatewayTypes.ts';

package/dist/lib/api-contracts/apiRouteBuilder.js

@@ -1,5 +1,7 @@
+import { getSseSchemaByEventName, } from '@lokalise/api-contracts';
 import { buildFastifyApiRoute, } from '@lokalise/fastify-api-contracts';
 import { attachGatewayMetadata } from "../gateway/withGatewayMetadata.js";
+import { attachSSESendDiagnostics, reportSSEHandlerOutcome } from "../sse/sseSendDiagnostics.js";
 /**
  * Build a Fastify `RouteOptions` object from an `ApiContract` + handler.
  *
@@ -19,7 +21,40 @@ import { attachGatewayMetadata } from "../gateway/withGatewayMetadata.js";
 export function buildApiRoute(contract, handler, options) {
     // Gateway metadata is stamped via Symbol, not spread into Fastify options.
     const { gatewayMetadata, ...fastifyOptions } = options ?? {};
-    const route = buildFastifyApiRoute(contract, handler, fastifyOptions);
+    const schemaByEventName = getSseSchemaByEventName(contract);
+    const built = buildFastifyApiRoute(contract, handler, schemaByEventName ? withSendDiagnostics(fastifyOptions, schemaByEventName) : fastifyOptions);
+    // Recording a failed send is only half of the diagnostic: whether the route recovered from
+    // it decides whether a test reading the stream should fail on it. That is what the handler's
+    // own outcome says, so it is observed here — for scoped requests only.
+    const route = schemaByEventName
+        ? { ...built, handler: reportSSEHandlerOutcome(built.handler) }
+        : built;
     return gatewayMetadata !== undefined ? attachGatewayMetadata(route, gatewayMetadata) : route;
 }
+/**
+ * Instrument the sessions of an SSE route so a send the handler could not make is reported to
+ * the test that is reading the stream, instead of only to the server log.
+ *
+ * A payload that fails the contract's schema for its event makes `session.send()` throw from
+ * inside the handler: the event never reaches the wire, the stream just ends early, and the
+ * test sees a missing event with no reason attached. The SSE test helpers (`injectApiSSE`,
+ * `connectApiSSE`) tag their requests with a diagnostics header and surface what was recorded
+ * for them.
+ *
+ * Costs nothing outside a test run: the hook is only added for contracts that declare SSE
+ * events, and it does nothing unless the request names a diagnostics scope open in this
+ * process — something only those helpers produce.
+ */
+function withSendDiagnostics(options, schemaByEventName) {
+    const { onConnect } = options;
+    return {
+        ...options,
+        // Called synchronously by `sse.start()` before the session reaches the handler, so the
+        // instrumentation is in place before the handler's first send.
+        onConnect: (session) => {
+            attachSSESendDiagnostics(session, schemaByEventName);
+            return onConnect?.(session);
+        },
+    };
+}
 //# sourceMappingURL=apiRouteBuilder.js.map

package/dist/lib/api-contracts/apiRouteBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"apiRouteBuilder.js","sourceRoot":"","sources":["../../../lib/api-contracts/apiRouteBuilder.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,GAGrB,MAAM,iCAAiC,CAAA;AAGxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AAgDzE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAkB,EAClB,OAAkC,EAClC,OAAmC;IAEnC,2EAA2E;IAC3E,MAAM,EAAE,eAAe,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAC5D,MAAM,KAAK,GAAG,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,cAAc,CAAC,CAAA;IACrE,OAAO,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAC9F,CAAC"}
+{"version":3,"file":"apiRouteBuilder.js","sourceRoot":"","sources":["../../../lib/api-contracts/apiRouteBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,uBAAuB,GAExB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,oBAAoB,GAGrB,MAAM,iCAAiC,CAAA;AAGxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AACzE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAgDhG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAkB,EAClB,OAAkC,EAClC,OAAmC;IAEnC,2EAA2E;IAC3E,MAAM,EAAE,eAAe,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAC5D,MAAM,iBAAiB,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAA;IAC3D,MAAM,KAAK,GAAG,oBAAoB,CAChC,QAAQ,EACR,OAAO,EACP,iBAAiB,CAAC,CAAC,CAAC,mBAAmB,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,cAAc,CAC5F,CAAA;IACD,2FAA2F;IAC3F,6FAA6F;IAC7F,uEAAuE;IACvE,MAAM,KAAK,GAAG,iBAAiB;QAC7B,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,uBAAuB,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE;QAC/D,CAAC,CAAC,KAAK,CAAA;IACT,OAAO,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAC9F,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,mBAAmB,CAC1B,OAA+B,EAC/B,iBAAkC;IAElC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAA;IAC7B,OAAO;QACL,GAAG,OAAO;QACV,uFAAuF;QACvF,+DAA+D;QAC/D,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;YACrB,wBAAwB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAA;YACpD,OAAO,SAAS,EAAE,CAAC,OAAO,CAAC,CAAA;QAC7B,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/lib/sse/index.d.ts

@@ -5,4 +5,5 @@ export { defineEvent, type SSEEventDefinition } from './defineEvent.js';
 export { defineRoom, InMemoryAdapter, type PreDeliveryFilter, type RoomBroadcastOptions, type RoomNameResolver, type SSERoomAdapter, SSERoomBroadcaster, SSERoomManager, type SSERoomManagerConfig, type SSERoomMessageHandler, type SSERoomOperations, } from './rooms/index.js';
 export { type SpiedSSESession, type SSESessionEvent, SSESessionSpy } from './SSESessionSpy.js';
 export { type ParsedSSEEvent, type ParseSSEBufferResult, parseSSEBuffer, parseSSEEvents, } from './sseParser.js';
+export { SSE_DIAGNOSTICS_HEADER, type SSEDiagnosticsScope, type SSESendFailure, } from './sseSendDiagnostics.js';
 export { defineEventMetadata, type ExtractMetadata, type FilterVerdict, type IncomingEvent, type MetadataGuard, type MetadataGuards, type PublishResult, type ResolverResult, SSESubscriptionManager, type SSESubscriptionManagerConfig, type SubscriptionContext, type SubscriptionPolicy, type SubscriptionResolver, } from './subscriptions/index.js';

package/dist/lib/sse/index.js

@@ -6,6 +6,7 @@ export { defineEvent } from './defineEvent.js';
 export { defineRoom, InMemoryAdapter, SSERoomBroadcaster, SSERoomManager, } from './rooms/index.js';
 export { SSESessionSpy } from './SSESessionSpy.js';
 export { parseSSEBuffer, parseSSEEvents, } from './sseParser.js';
+export { SSE_DIAGNOSTICS_HEADER, } from './sseSendDiagnostics.js';
 // SSE Subscriptions
 export { defineEventMetadata, SSESubscriptionManager, } from './subscriptions/index.js';
 //# sourceMappingURL=index.js.map

package/dist/lib/sse/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/sse/index.ts"],"names":[],"mappings":"AAUA,2CAA2C;AAC3C,OAAO,EAEL,iBAAiB,EACjB,YAAY,GAUb,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,qBAAqB,GAKtB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,WAAW,EAA2B,MAAM,kBAAkB,CAAA;AACvE,mCAAmC;AACnC,OAAO,EACL,UAAU,EACV,eAAe,EAKf,kBAAkB,EAClB,cAAc,GAIf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAA8C,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAC9F,OAAO,EAGL,cAAc,EACd,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EAQnB,sBAAsB,GAKvB,MAAM,0BAA0B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/sse/index.ts"],"names":[],"mappings":"AAUA,2CAA2C;AAC3C,OAAO,EAEL,iBAAiB,EACjB,YAAY,GAUb,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,qBAAqB,GAKtB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EAAE,WAAW,EAA2B,MAAM,kBAAkB,CAAA;AACvE,mCAAmC;AACnC,OAAO,EACL,UAAU,EACV,eAAe,EAKf,kBAAkB,EAClB,cAAc,GAIf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAA8C,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAC9F,OAAO,EAGL,cAAc,EACd,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,sBAAsB,GAGvB,MAAM,yBAAyB,CAAA;AAChC,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EAQnB,sBAAsB,GAKvB,MAAM,0BAA0B,CAAA"}

package/dist/lib/sse/sseSendDiagnostics.d.ts

@@ -0,0 +1,134 @@
+import type { SSEEventSchemas } from '@lokalise/api-contracts';
+import type { SSESession } from '@lokalise/fastify-api-contracts';
+import type { RouteHandlerMethod } from 'fastify';
+import type { z } from 'zod';
+/**
+ * Request header carrying the id of an open diagnostics scope.
+ *
+ * The SSE test helpers (`injectApiSSE`, `connectApiSSE`) set it on every request they make;
+ * routes built with `buildApiRoute` honour it by instrumenting the session they hand to the
+ * handler. A value that does not name a scope opened in this process is ignored, so the
+ * header is inert outside a test run — a client cannot make a production server record
+ * anything by sending it.
+ */
+export declare const SSE_DIAGNOSTICS_HEADER = "x-om-sse-diagnostics-id";
+/**
+ * One `session.send()` / `session.sendStream()` call that threw.
+ *
+ * Almost always a payload that failed the contract's schema for that event: the send throws,
+ * the event never reaches the wire, and the stream just ends early — so the event the test
+ * asserts on is missing while the reason lives in the server log.
+ */
+export type SSESendFailure = {
+    /**
+     * Name of the event the handler tried to send.
+     *
+     * Absent when the failure came from the message source of `sendStream()` rather than from
+     * a send: the source threw while producing the next message, so no event was in flight.
+     */
+    eventName?: string;
+    /** Payload the handler passed, as-is. Absent together with {@link eventName}. */
+    data?: unknown;
+    /** Message of the thrown error. */
+    message: string;
+    /**
+     * Zod issues from re-validating `data` against the contract's schema for `eventName`.
+     * Absent when the contract declares no schema for the event, or when the send failed for
+     * a reason other than validation (a dead connection, say).
+     */
+    issues?: z.core.$ZodIssue[];
+    /** The thrown error itself, for assertions the fields above don't cover. */
+    error: unknown;
+    /**
+     * Whether the route recovered from this failure.
+     *
+     * `true` when the handler caught the error and went on to complete the response — the
+     * stream the test read is the one the route meant to produce, so the failure is context,
+     * not a verdict. `false` when the error escaped the handler (or was raised after it
+     * returned, on a `keepAlive` session): nothing recovered, and the stream ended where the
+     * send failed.
+     *
+     * Only final once the response completed; the test helpers only read it then.
+     */
+    handled: boolean;
+};
+/**
+ * A registered diagnostics scope: the header to send, and the failures recorded for it.
+ *
+ * Opened by the SSE test helpers, one per request they issue. Instrumented sessions match a
+ * request to a scope by the {@link SSE_DIAGNOSTICS_HEADER} value.
+ */
+export type SSEDiagnosticsScope = {
+    /** Scope id, as sent in {@link SSE_DIAGNOSTICS_HEADER}. */
+    id: string;
+    /** Headers to merge into the request this scope observes. */
+    headers: Record<string, string>;
+    /**
+     * The failures recorded so far. After {@link SSEDiagnosticsScope.dispose}, the snapshot
+     * taken at that moment — so a result object can still report them long after the response
+     * completed, without keeping the scope registered.
+     */
+    failures(): SSESendFailure[];
+    /**
+     * Snapshot the failures and unregister the scope. Idempotent, and safe to call while a
+     * response is still in flight (nothing recorded afterwards is kept).
+     */
+    dispose(): void;
+};
+/**
+ * Open a diagnostics scope for a single request.
+ *
+ * @internal Used by the SSE test helpers; tests reach the failures through the helper they
+ * called, not through this registry.
+ */
+export declare function openSSEDiagnosticsScope(): SSEDiagnosticsScope;
+/**
+ * How many diagnostics scopes are registered right now.
+ *
+ * @internal Exists so the helpers' own specs can prove that every path out of a request
+ * unregisters its scope: a leaked one keeps its records alive for the rest of the process and
+ * costs every later request the fast path below.
+ */
+export declare function countOpenSSEDiagnosticsScopes(): number;
+/**
+ * Instrument an SSE session so that failed sends are recorded against the diagnostics scope
+ * the request names, then rethrown unchanged.
+ *
+ * A no-op unless the request carries {@link SSE_DIAGNOSTICS_HEADER} with the id of a scope
+ * open in this process, which only the SSE test helpers ever produce.
+ *
+ * @param session - The session handed to the handler by `sse.start()`
+ * @param schemaByEventName - The contract's merged SSE event schemas, used to recover the
+ *   Zod issues behind a validation failure
+ *
+ * @internal Called by `buildApiRoute`; not part of the application-facing API.
+ */
+export declare function attachSSESendDiagnostics(session: SSESession, schemaByEventName: SSEEventSchemas): void;
+/**
+ * Wrap a route handler so the diagnostics scope learns whether the route recovered from the
+ * sends it could not make.
+ *
+ * A send that throws is only a reason for a test to fail when nothing caught it: a handler
+ * that catches its own failed send and streams a fallback instead produced exactly the
+ * response it meant to. Observing how the handler settled is what tells the two apart —
+ * {@link SSESendFailure.handled}.
+ *
+ * A no-op for requests that name no open diagnostics scope: outside a test run this is one
+ * `Map.size` check per request on SSE routes.
+ *
+ * @internal Applied by `buildApiRoute` to SSE-capable routes.
+ */
+export declare function reportSSEHandlerOutcome(handler: RouteHandlerMethod): RouteHandlerMethod;
+/**
+ * The failures the route did not recover from — the ones that truncated the response, and so
+ * explain an event a test waited for and never saw.
+ *
+ * @internal
+ */
+export declare function unhandledSendFailures(failures: SSESendFailure[]): SSESendFailure[];
+/**
+ * Render recorded failures as the message of the error the test helpers throw.
+ *
+ * @internal
+ */
+export declare function describeSendFailures(failures: SSESendFailure[]): string;

package/dist/lib/sse/sseSendDiagnostics.js

@@ -0,0 +1,277 @@
+/**
+ * Request header carrying the id of an open diagnostics scope.
+ *
+ * The SSE test helpers (`injectApiSSE`, `connectApiSSE`) set it on every request they make;
+ * routes built with `buildApiRoute` honour it by instrumenting the session they hand to the
+ * handler. A value that does not name a scope opened in this process is ignored, so the
+ * header is inert outside a test run — a client cannot make a production server record
+ * anything by sending it.
+ */
+export const SSE_DIAGNOSTICS_HEADER = 'x-om-sse-diagnostics-id';
+/** Cap per scope, so a handler failing in a loop can't grow the registry without bound. */
+const MAX_FAILURES_PER_SCOPE = 50;
+/** How far to walk an error's `cause` chain when matching it to a recorded failure. */
+const MAX_CAUSE_DEPTH = 10;
+/**
+ * The failures of one observed request, plus whether the route recovered from them.
+ *
+ * Split from {@link SSEDiagnosticsScope} because the two ends see different things: the scope
+ * is the reader's handle (it can only snapshot and unregister), while the recorder is what the
+ * instrumented route writes to.
+ */
+class SSEDiagnosticsRecorder {
+    failures = [];
+    settled = false;
+    /** Record a send that threw, and the Zod issues behind it when the payload explains it. */
+    recordSendFailure(schemaByEventName, eventName, data, error) {
+        if (this.failures.length >= MAX_FAILURES_PER_SCOPE) {
+            return;
+        }
+        const issues = issuesFor(schemaByEventName, eventName, data);
+        this.failures.push({
+            eventName,
+            data,
+            message: messageOf(error),
+            ...(issues && { issues }),
+            error,
+            handled: false,
+        });
+    }
+    /** Record a `sendStream()` source that threw while producing its next message. */
+    recordSourceFailure(error) {
+        if (this.failures.length >= MAX_FAILURES_PER_SCOPE) {
+            return;
+        }
+        this.failures.push({ message: messageOf(error), error, handled: false });
+    }
+    /**
+     * The route handler settled: everything recorded so far that did not escape it was caught
+     * by the route, which went on to produce the rest of the response.
+     *
+     * Called once per request, before the response ends, so the helpers reading the stream see
+     * final `handled` flags. Failures recorded afterwards — a send on a `keepAlive` session the
+     * handler already returned from — stay unhandled: nothing observably recovered from them.
+     *
+     * @param escaped - The error the handler threw, if it threw
+     */
+    settle(escaped) {
+        if (this.settled) {
+            return;
+        }
+        this.settled = true;
+        for (const failure of this.failures) {
+            failure.handled = !causedBy(escaped, failure.error);
+        }
+    }
+}
+const openScopes = new Map();
+let nextScopeId = 0;
+/**
+ * Open a diagnostics scope for a single request.
+ *
+ * @internal Used by the SSE test helpers; tests reach the failures through the helper they
+ * called, not through this registry.
+ */
+export function openSSEDiagnosticsScope() {
+    const id = `sse-diag-${++nextScopeId}`;
+    openScopes.set(id, new SSEDiagnosticsRecorder());
+    let snapshot;
+    return {
+        id,
+        headers: { [SSE_DIAGNOSTICS_HEADER]: id },
+        failures: () => snapshot ?? [...(openScopes.get(id)?.failures ?? [])],
+        dispose: () => {
+            if (!snapshot) {
+                snapshot = [...(openScopes.get(id)?.failures ?? [])];
+                openScopes.delete(id);
+            }
+        },
+    };
+}
+/**
+ * How many diagnostics scopes are registered right now.
+ *
+ * @internal Exists so the helpers' own specs can prove that every path out of a request
+ * unregisters its scope: a leaked one keeps its records alive for the rest of the process and
+ * costs every later request the fast path below.
+ */
+export function countOpenSSEDiagnosticsScopes() {
+    return openScopes.size;
+}
+/** The recorder a request writes to, or `undefined` when it belongs to no open scope. */
+function resolveRecorder(headers) {
+    // Fast path for production traffic: with no scope open the header can't match anything.
+    if (openScopes.size === 0) {
+        return undefined;
+    }
+    const header = headers[SSE_DIAGNOSTICS_HEADER];
+    const id = Array.isArray(header) ? header[0] : header;
+    return id === undefined ? undefined : openScopes.get(id);
+}
+/** Re-validate a payload to recover the structured issues the thrown error only carries as text. */
+function issuesFor(schemaByEventName, eventName, data) {
+    const schema = schemaByEventName[eventName];
+    if (!schema) {
+        return undefined;
+    }
+    const result = schema.safeParse(data);
+    return result.success ? undefined : result.error.issues;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Whether `error` is `candidate`, or was thrown wrapping it as a `cause`.
+ *
+ * A handler that rethrows the send error as-is is the common case; one that wraps it in its
+ * own error still did not recover from it, so the chain is walked (to a bounded depth, since
+ * a `cause` chain can be cyclic).
+ */
+function causedBy(error, candidate) {
+    let current = error;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && current !== undefined && current !== null; depth++) {
+        if (current === candidate) {
+            return true;
+        }
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return false;
+}
+/**
+ * Instrument an SSE session so that failed sends are recorded against the diagnostics scope
+ * the request names, then rethrown unchanged.
+ *
+ * A no-op unless the request carries {@link SSE_DIAGNOSTICS_HEADER} with the id of a scope
+ * open in this process, which only the SSE test helpers ever produce.
+ *
+ * @param session - The session handed to the handler by `sse.start()`
+ * @param schemaByEventName - The contract's merged SSE event schemas, used to recover the
+ *   Zod issues behind a validation failure
+ *
+ * @internal Called by `buildApiRoute`; not part of the application-facing API.
+ */
+export function attachSSESendDiagnostics(session, schemaByEventName) {
+    const recorder = resolveRecorder(session.request.headers);
+    if (!recorder) {
+        return;
+    }
+    const originalSend = session.send.bind(session);
+    session.send = async (eventName, data, options) => {
+        try {
+            return await originalSend(eventName, data, options);
+        }
+        catch (error) {
+            recorder.recordSendFailure(schemaByEventName, eventName, data, error);
+            throw error;
+        }
+    };
+    const originalSendStream = session.sendStream.bind(session);
+    session.sendStream = async (messages) => {
+        // The send that throws happens inside `sendStream`, which reports neither the event name
+        // nor the payload. Wrapping the source names it: `pending` holds the message handed to
+        // the sender, and is cleared when the sender comes back for the next one — which only
+        // happens once the previous send resolved. So a rejection with `pending` set is a failed
+        // send of that message, and one without is the source itself throwing.
+        let pending;
+        async function* tracked() {
+            for await (const message of messages) {
+                pending = message;
+                yield message;
+                pending = undefined;
+            }
+        }
+        try {
+            await originalSendStream(tracked());
+        }
+        catch (error) {
+            if (pending) {
+                recorder.recordSendFailure(schemaByEventName, pending.event, pending.data, error);
+            }
+            else {
+                recorder.recordSourceFailure(error);
+            }
+            throw error;
+        }
+    };
+}
+/**
+ * Wrap a route handler so the diagnostics scope learns whether the route recovered from the
+ * sends it could not make.
+ *
+ * A send that throws is only a reason for a test to fail when nothing caught it: a handler
+ * that catches its own failed send and streams a fallback instead produced exactly the
+ * response it meant to. Observing how the handler settled is what tells the two apart —
+ * {@link SSESendFailure.handled}.
+ *
+ * A no-op for requests that name no open diagnostics scope: outside a test run this is one
+ * `Map.size` check per request on SSE routes.
+ *
+ * @internal Applied by `buildApiRoute` to SSE-capable routes.
+ */
+export function reportSSEHandlerOutcome(handler) {
+    const instrumented = function instrumentedHandler(request, reply) {
+        const recorder = resolveRecorder(request.headers);
+        if (!recorder) {
+            return handler.call(this, request, reply);
+        }
+        let result;
+        try {
+            result = handler.call(this, request, reply);
+        }
+        catch (error) {
+            // A handler that throws before returning a promise never opened a stream to recover in.
+            recorder.settle(error);
+            throw error;
+        }
+        return Promise.resolve(result).then((value) => {
+            recorder.settle();
+            // Whatever the wrapped handler resolves to is what Fastify sends: pass it through.
+            return value;
+        }, (error) => {
+            recorder.settle(error);
+            throw error;
+        });
+    };
+    return instrumented;
+}
+/**
+ * The failures the route did not recover from — the ones that truncated the response, and so
+ * explain an event a test waited for and never saw.
+ *
+ * @internal
+ */
+export function unhandledSendFailures(failures) {
+    return failures.filter((failure) => !failure.handled);
+}
+/**
+ * Render recorded failures as the message of the error the test helpers throw.
+ *
+ * @internal
+ */
+export function describeSendFailures(failures) {
+    const lines = failures.map((failure) => `  - ${describeSendFailure(failure)}`);
+    const subject = failures.length === 1 ? 'failure' : 'failures';
+    return `${failures.length} SSE send ${subject} recorded for this request:\n${lines.join('\n')}`;
+}
+function describeSendFailure(failure) {
+    const recovered = failure.handled ? ' (caught by the route, which completed the response)' : '';
+    if (failure.eventName === undefined) {
+        return `the sendStream() source threw before the next event: ${failure.message}${recovered}`;
+    }
+    const detail = failure.issues
+        ? failure.issues
+            .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+            .join('; ')
+        : failure.message;
+    return `event "${failure.eventName}" was never sent: ${detail}; payload: ${safeStringify(failure.data)}${recovered}`;
+}
+/** JSON for an error message, degrading to `String()` for anything JSON can't take. */
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=sseSendDiagnostics.js.map