opinionated-machine 10.4.0 → 10.5.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"sseSendDiagnostics.js","sourceRoot":"","sources":["../../../lib/sse/sseSendDiagnostics.ts"],"names":[],"mappings":"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"}

package/dist/lib/testing/apiSseEventValidation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Contract-aware SSE event validation, shared by the inject helpers (`injectApiSSE`) and the
+ * real-HTTP ones (`connectApiSSE`, `SSEHttpClient.apiEvents`) so both paths produce the same
+ * discriminated union, validated against the same schemas and reporting the same errors.
+ *
+ * @internal
+ */
+import type { SSEEventSchemas } from '@lokalise/api-contracts';
+import { type ApiContract } from '@lokalise/api-contracts';
+import type { ParsedSSEEvent } from '../sse/sseParser.ts';
+import type { ApiSSEEvent } from './apiSseTestTypes.ts';
+/**
+ * The contract's SSE schemas, merged across every declared status, or a thrown error naming
+ * the reader that asked for them.
+ */
+export declare function resolveApiSseSchemas(contract: ApiContract, reader: string): SSEEventSchemas;
+/**
+ * Validate one parsed event against the contract's schemas and return it as a member of the
+ * contract's event union.
+ *
+ * @param reader - Name of the calling reader (`events()`, `stream()`, …), used as the error prefix
+ * @throws if the contract declares no schema for the event name, if `data` isn't valid JSON,
+ *   or if the payload doesn't match the declared schema
+ */
+export declare function validateApiSseEvent<Contract extends ApiContract>(schemaByEventName: SSEEventSchemas, event: ParsedSSEEvent, reader: string): ApiSSEEvent<Contract>;
+/** Media type an SSE response must carry. */
+export declare const SSE_CONTENT_TYPE = "text/event-stream";
+/** Strip `; charset=…` style parameters from a media type. */
+export declare function mediaTypeOf(contentType: string | undefined): string | undefined;
+/**
+ * Reject a response that is not an event stream, naming the reader that asked for one.
+ *
+ * Shared by both read paths so an endpoint answering with a JSON error (a 401 before
+ * `sse.start()`, say) fails with its status and body on either — rather than as zero events,
+ * which reads as a timeout on the HTTP path and an empty array on the inject one.
+ *
+ * @param reader - Name of the calling reader (`events()`, `stream()`, …), used as the error prefix
+ * @param body - Response body, when the caller can produce it without consuming a live stream
+ */
+export declare function assertSSEResponse(statusCode: number, contentType: string | undefined, reader: string, body?: string): void;

package/dist/lib/testing/apiSseEventValidation.js

@@ -0,0 +1,78 @@
+/**
+ * Contract-aware SSE event validation, shared by the inject helpers (`injectApiSSE`) and the
+ * real-HTTP ones (`connectApiSSE`, `SSEHttpClient.apiEvents`) so both paths produce the same
+ * discriminated union, validated against the same schemas and reporting the same errors.
+ *
+ * @internal
+ */
+import { getSseSchemaByEventName } from '@lokalise/api-contracts';
+import { truncateBody } from "./sseInjectShared.js";
+/**
+ * The contract's SSE schemas, merged across every declared status, or a thrown error naming
+ * the reader that asked for them.
+ */
+export function resolveApiSseSchemas(contract, reader) {
+    const schemaByEventName = getSseSchemaByEventName(contract);
+    if (!schemaByEventName) {
+        throw new Error(`${reader} — the contract declares no SSE response`);
+    }
+    return schemaByEventName;
+}
+/**
+ * Validate one parsed event against the contract's schemas and return it as a member of the
+ * contract's event union.
+ *
+ * @param reader - Name of the calling reader (`events()`, `stream()`, …), used as the error prefix
+ * @throws if the contract declares no schema for the event name, if `data` isn't valid JSON,
+ *   or if the payload doesn't match the declared schema
+ */
+export function validateApiSseEvent(schemaByEventName, event, reader) {
+    // An SSE event without an `event:` field is a `message` event per the spec.
+    const name = event.event ?? 'message';
+    const schema = schemaByEventName[name];
+    if (!schema) {
+        throw new Error(`${reader} — the contract declares no schema for event "${name}"`);
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(event.data);
+    }
+    catch (err) {
+        throw new Error(`${reader} — data of event "${name}" is not valid JSON: ${err.message}; data: ${truncateBody(event.data)}`);
+    }
+    const parsed = schema.safeParse(parsedJson);
+    if (!parsed.success) {
+        throw new Error(`${reader} — data of event "${name}" does not match the declared schema: ${parsed.error.message}; data: ${truncateBody(event.data)}`);
+    }
+    return {
+        ...(event.id !== undefined && { id: event.id }),
+        ...(event.retry !== undefined && { retry: event.retry }),
+        event: name,
+        data: parsed.data,
+    };
+}
+/** Media type an SSE response must carry. */
+export const SSE_CONTENT_TYPE = 'text/event-stream';
+/** Strip `; charset=…` style parameters from a media type. */
+export function mediaTypeOf(contentType) {
+    return contentType?.split(';')[0]?.trim().toLowerCase();
+}
+/**
+ * Reject a response that is not an event stream, naming the reader that asked for one.
+ *
+ * Shared by both read paths so an endpoint answering with a JSON error (a 401 before
+ * `sse.start()`, say) fails with its status and body on either — rather than as zero events,
+ * which reads as a timeout on the HTTP path and an empty array on the inject one.
+ *
+ * @param reader - Name of the calling reader (`events()`, `stream()`, …), used as the error prefix
+ * @param body - Response body, when the caller can produce it without consuming a live stream
+ */
+export function assertSSEResponse(statusCode, contentType, reader, body) {
+    const mediaType = mediaTypeOf(contentType);
+    if (mediaType === SSE_CONTENT_TYPE) {
+        return;
+    }
+    const bodySuffix = body === undefined || body === '' ? '' : ` Body: ${truncateBody(body)}`;
+    throw new Error(`${reader} — response is not an SSE stream (status ${statusCode}, content-type ${mediaType ?? 'absent'}); use bodyForStatus(${statusCode}) for declared error responses.${bodySuffix}`);
+}
+//# sourceMappingURL=apiSseEventValidation.js.map

package/dist/lib/testing/apiSseEventValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiSseEventValidation.js","sourceRoot":"","sources":["../../../lib/testing/apiSseEventValidation.ts"],"names":[],"mappings":"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"}

package/dist/lib/testing/apiSseHttpHelpers.d.ts

@@ -0,0 +1,168 @@
+import { type ApiContract } from '@lokalise/api-contracts';
+import type { SpiedSSESession, SSESessionSpy } from '../sse/SSESessionSpy.ts';
+import { type SSEDiagnosticsScope, type SSESendFailure } from '../sse/sseSendDiagnostics.ts';
+import type { ApiSSEEvent, InjectApiSSEParams } from './apiSseTestTypes.ts';
+import { SSEHttpClient } from './sseHttpClient.ts';
+/**
+ * Request params for {@link connectApiSSE}, derived from a `defineApiContract` contract.
+ *
+ * The same shape `injectApiSSE` takes — `pathParams`, `body`, `queryParams` and `headers` are
+ * each required only when the contract declares the matching request schema, `headers` also
+ * accepts a (sync or async) factory, and `pathPrefix` is always optional.
+ */
+export type ConnectApiSSEParams<Contract extends ApiContract> = InjectApiSSEParams<Contract>;
+/** Options for waiting on server-side registration, driven by a standalone session spy. */
+export type ConnectApiSSEWithSpyOptions<TSession extends SpiedSSESession> = {
+    /**
+     * Wait for server-side connection registration after HTTP headers are received, removing
+     * the race between `connect()` returning and the handler finishing its registration.
+     *
+     * Only meaningful for `keepAlive` sessions — an `autoClose` route closes its session as the
+     * handler returns, before the wait can claim it.
+     */
+    awaitServerConnection: {
+        /** A standalone spy, wired to the route via `createSSESessionSpy()`'s `routeOptions` */
+        spy: SSESessionSpy<TSession>;
+        /** Timeout in milliseconds (default: 5000) */
+        timeout?: number;
+    };
+};
+/** Result of {@link connectApiSSE} when `awaitServerConnection` is used. */
+export type ConnectApiSSEResult<Contract extends ApiContract, TSession extends SpiedSSESession> = {
+    client: ApiSSEHttpClient<Contract>;
+    serverConnection: TSession;
+};
+/**
+ * A live SSE connection over real HTTP, read through the contract that declares it.
+ *
+ * The contract-typed counterpart of {@link SSEHttpClient}: events arrive incrementally, as
+ * they do there, but each one is JSON-parsed, validated against the contract's `sseResponse` /
+ * `sseBody` schemas and typed as a discriminated union on `event` — the same events
+ * `injectApiSSE` produces, so a suite can move an assertion between the two paths unchanged.
+ */
+export declare class ApiSSEHttpClient<Contract extends ApiContract> {
+    /** The underlying untyped client, for the parts of it this wrapper doesn't cover. */
+    readonly raw: SSEHttpClient;
+    private readonly contract;
+    private readonly scope;
+    /** @internal Built by {@link connectApiSSE}. */
+    constructor(raw: SSEHttpClient, contract: Contract, scope: SSEDiagnosticsScope);
+    /**
+     * The fetch `Response`, available before any event is consumed — so status and headers can
+     * be asserted while the handler is still producing events.
+     */
+    get response(): Response;
+    /**
+     * Yield the contract's events as they arrive, typed and validated per event name.
+     *
+     * Throws — before yielding anything — if the endpoint answered with something other than an
+     * event stream (an error raised before `sse.start()`, say), naming its status and body
+     * instead of reporting an empty stream.
+     *
+     * @param signal - Optional `AbortSignal` to stop the generator early
+     *
+     * @example
+     * ```typescript
+     * for await (const event of client.events()) {
+     *   if (event.event === 'issue') expect(event.data.severity).toBe('minor')
+     *   if (event.event === 'review') break
+     * }
+     * ```
+     */
+    events(signal?: AbortSignal): AsyncGenerator<ApiSSEEvent<Contract>, void, unknown>;
+    /**
+     * Collect events until a count is reached or a predicate matches, each one typed and
+     * validated against the contract.
+     *
+     * A collection that ends short — the stream closed early, or the wait timed out — usually
+     * means the handler failed to send an event it was supposed to; when that is what happened,
+     * the thrown error names the event and its validation issues instead of leaving the test to
+     * report a missing event with no reason.
+     *
+     * Throws straight away if the endpoint answered with something other than an event stream,
+     * rather than waiting out the timeout on a stream that was never going to arrive.
+     *
+     * @param countOrPredicate - Number of events to collect, or a predicate that ends collection
+     *   (the matching event is included). The predicate is invoked exactly once per event.
+     * @param timeout - Maximum time to wait in milliseconds (default: 5000)
+     */
+    collectEvents(countOrPredicate: number | ((event: ApiSSEEvent<Contract>) => boolean), timeout?: number): Promise<ApiSSEEvent<Contract>[]>;
+    /**
+     * Throw what the handler failed to send and did not recover from, if anything was recorded
+     * for this connection.
+     *
+     * A failure the route caught and streamed around left the response it meant to produce, so
+     * it is reported through {@link ApiSSEHttpClient.sendFailures} instead of failing the read.
+     */
+    private assertNoSendFailures;
+    /**
+     * Reject a response that is not an event stream, with its status and body.
+     *
+     * Without this a `401` (or any other pre-stream error response) reads as a stream that
+     * never produced an event: `collectEvents` waits out its full timeout and reports "got 0",
+     * with the actual status nowhere in the failure.
+     */
+    private assertStreamResponse;
+    /**
+     * Unregister the diagnostics scope once the stream is over, keeping what it recorded.
+     *
+     * `close()` is the usual trigger; a test that reads a stream to its end and never closes the
+     * client would otherwise leave the scope registered for the rest of the process.
+     */
+    private releaseScopeIfClosed;
+    /**
+     * The sends the handler could not make on this connection — a payload that failed the
+     * contract's schema for its event, say — recorded instead of being left in the server log.
+     *
+     * Includes the failures the route recovered from (`handled: true`), which the readers pass
+     * over precisely because the response was still the one the route meant to produce.
+     *
+     * Only routes built with this package's `buildApiRoute` report them.
+     */
+    sendFailures(): SSESendFailure[];
+    /** Close the connection from the client side. */
+    close(): void;
+}
+/**
+ * Connect to an SSE endpoint over real HTTP using a contract built with `defineApiContract`.
+ *
+ * The contract-aware counterpart of `SSEHttpClient.connect`: the method, path, query params,
+ * headers and body all come from the contract instead of being repeated as string literals
+ * next to it, and the events are typed and validated the way `injectApiSSE().events()` types
+ * them — so the tests that read a stream as it arrives keep the contract typing rather than
+ * casting `ParsedSSEEvent.data` by hand.
+ *
+ * Use this (over `injectApiSSE`) when the endpoint keeps its connection open: a `keepAlive`
+ * session never completes its response, so only a real HTTP connection can read it.
+ *
+ * @param baseUrl - Base URL of the running server (e.g. `SSETestServer.baseUrl`)
+ * @param contract - Contract built with `defineApiContract`
+ * @param params - Request params derived from the contract
+ * @param options - `awaitServerConnection`, to also wait for server-side registration
+ *
+ * @example
+ * ```typescript
+ * const client = await connectApiSSE(server.baseUrl, lqaTextSegmentContract, { body })
+ *
+ * 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
+ * }
+ * client.close()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // keepAlive route: wait for the server-side session, then drive it from the test
+ * const { spy, routeOptions } = createSSESessionSpy()
+ * const { client, serverConnection } = await connectApiSSE(
+ *   server.baseUrl,
+ *   tickStreamContract,
+ *   { pathParams: { channelId: 'c1' }, queryParams: { count: 2 }, headers },
+ *   { awaitServerConnection: { spy } },
+ * )
+ * await serverConnection.send('tick', { channelId: 'c1', n: 1 })
+ * ```
+ */
+export declare function connectApiSSE<const Contract extends ApiContract>(baseUrl: string, contract: Contract, params: ConnectApiSSEParams<Contract>): Promise<ApiSSEHttpClient<Contract>>;
+export declare function connectApiSSE<const Contract extends ApiContract, TSession extends SpiedSSESession>(baseUrl: string, contract: Contract, params: ConnectApiSSEParams<Contract>, options: ConnectApiSSEWithSpyOptions<TSession>): Promise<ConnectApiSSEResult<Contract, TSession>>;

package/dist/lib/testing/apiSseHttpHelpers.js

@@ -0,0 +1,214 @@
+import { buildRequestPath } from '@lokalise/api-contracts';
+import { describeSendFailures, openSSEDiagnosticsScope, unhandledSendFailures, } from "../sse/sseSendDiagnostics.js";
+import { assertSSEResponse, mediaTypeOf, SSE_CONTENT_TYPE } from "./apiSseEventValidation.js";
+import { SSEHttpClient } from "./sseHttpClient.js";
+/**
+ * A live SSE connection over real HTTP, read through the contract that declares it.
+ *
+ * The contract-typed counterpart of {@link SSEHttpClient}: events arrive incrementally, as
+ * they do there, but each one is JSON-parsed, validated against the contract's `sseResponse` /
+ * `sseBody` schemas and typed as a discriminated union on `event` — the same events
+ * `injectApiSSE` produces, so a suite can move an assertion between the two paths unchanged.
+ */
+export class ApiSSEHttpClient {
+    /** The underlying untyped client, for the parts of it this wrapper doesn't cover. */
+    raw;
+    contract;
+    scope;
+    /** @internal Built by {@link connectApiSSE}. */
+    constructor(raw, contract, scope) {
+        this.raw = raw;
+        this.contract = contract;
+        this.scope = scope;
+    }
+    /**
+     * The fetch `Response`, available before any event is consumed — so status and headers can
+     * be asserted while the handler is still producing events.
+     */
+    get response() {
+        return this.raw.response;
+    }
+    /**
+     * Yield the contract's events as they arrive, typed and validated per event name.
+     *
+     * Throws — before yielding anything — if the endpoint answered with something other than an
+     * event stream (an error raised before `sse.start()`, say), naming its status and body
+     * instead of reporting an empty stream.
+     *
+     * @param signal - Optional `AbortSignal` to stop the generator early
+     *
+     * @example
+     * ```typescript
+     * for await (const event of client.events()) {
+     *   if (event.event === 'issue') expect(event.data.severity).toBe('minor')
+     *   if (event.event === 'review') break
+     * }
+     * ```
+     */
+    async *events(signal) {
+        await this.assertStreamResponse('events()');
+        yield* this.raw.apiEvents(this.contract, signal);
+        if (!signal?.aborted) {
+            // The server ended the stream: anything the handler failed to send is known now, and
+            // is why an expected event never arrived.
+            this.assertNoSendFailures('events()');
+            this.releaseScopeIfClosed();
+        }
+    }
+    /**
+     * Collect events until a count is reached or a predicate matches, each one typed and
+     * validated against the contract.
+     *
+     * A collection that ends short — the stream closed early, or the wait timed out — usually
+     * means the handler failed to send an event it was supposed to; when that is what happened,
+     * the thrown error names the event and its validation issues instead of leaving the test to
+     * report a missing event with no reason.
+     *
+     * Throws straight away if the endpoint answered with something other than an event stream,
+     * rather than waiting out the timeout on a stream that was never going to arrive.
+     *
+     * @param countOrPredicate - Number of events to collect, or a predicate that ends collection
+     *   (the matching event is included). The predicate is invoked exactly once per event.
+     * @param timeout - Maximum time to wait in milliseconds (default: 5000)
+     */
+    async collectEvents(countOrPredicate, timeout) {
+        await this.assertStreamResponse('collectEvents()');
+        // Whether the caller's predicate matched is remembered as it runs, so satisfaction can be
+        // decided afterwards without invoking it a second time on the events it already saw.
+        let matched = false;
+        const target = typeof countOrPredicate === 'number'
+            ? countOrPredicate
+            : (event) => {
+                matched = countOrPredicate(event) || matched;
+                return matched;
+            };
+        let collected;
+        try {
+            collected = await this.raw.collectApiEvents(this.contract, target, timeout);
+        }
+        catch (err) {
+            // The collection failed outright: every recorded failure is context worth reporting,
+            // including the ones the route recovered from.
+            const failures = this.scope.failures();
+            this.releaseScopeIfClosed();
+            if (failures.length === 0) {
+                throw err;
+            }
+            throw new Error(`collectEvents() — ${describeSendFailures(failures)}\nRaised while collecting: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // `collectEvents` also returns short when the server closed the stream before the target
+        // was met, which is exactly what a failed send looks like from here.
+        const satisfied = typeof countOrPredicate === 'number' ? collected.length >= countOrPredicate : matched;
+        if (!satisfied) {
+            this.assertNoSendFailures('collectEvents()');
+        }
+        this.releaseScopeIfClosed();
+        return collected;
+    }
+    /**
+     * Throw what the handler failed to send and did not recover from, if anything was recorded
+     * for this connection.
+     *
+     * A failure the route caught and streamed around left the response it meant to produce, so
+     * it is reported through {@link ApiSSEHttpClient.sendFailures} instead of failing the read.
+     */
+    assertNoSendFailures(reader) {
+        const failures = unhandledSendFailures(this.scope.failures());
+        if (failures.length > 0) {
+            throw new Error(`${reader} — ${describeSendFailures(failures)}`);
+        }
+    }
+    /**
+     * Reject a response that is not an event stream, with its status and body.
+     *
+     * Without this a `401` (or any other pre-stream error response) reads as a stream that
+     * never produced an event: `collectEvents` waits out its full timeout and reports "got 0",
+     * with the actual status nowhere in the failure.
+     */
+    async assertStreamResponse(reader) {
+        const { response } = this.raw;
+        const contentType = response.headers.get('content-type') ?? undefined;
+        let body;
+        if (mediaTypeOf(contentType) !== SSE_CONTENT_TYPE) {
+            // Only read the body once the response is known not to be a stream, and never from the
+            // live response, whose body the client still needs.
+            body = await readBodySnapshot(response);
+            this.scope.dispose();
+        }
+        assertSSEResponse(response.status, contentType, reader, body);
+    }
+    /**
+     * Unregister the diagnostics scope once the stream is over, keeping what it recorded.
+     *
+     * `close()` is the usual trigger; a test that reads a stream to its end and never closes the
+     * client would otherwise leave the scope registered for the rest of the process.
+     */
+    releaseScopeIfClosed() {
+        if (this.raw.isClosed) {
+            this.scope.dispose();
+        }
+    }
+    /**
+     * The sends the handler could not make on this connection — a payload that failed the
+     * contract's schema for its event, say — recorded instead of being left in the server log.
+     *
+     * Includes the failures the route recovered from (`handled: true`), which the readers pass
+     * over precisely because the response was still the one the route meant to produce.
+     *
+     * Only routes built with this package's `buildApiRoute` report them.
+     */
+    sendFailures() {
+        return this.scope.failures();
+    }
+    /** Close the connection from the client side. */
+    close() {
+        this.scope.dispose();
+        this.raw.close();
+    }
+}
+/** The body of a non-stream response, for an error message; never worth failing over. */
+async function readBodySnapshot(response) {
+    try {
+        return await response.clone().text();
+    }
+    catch {
+        // Already consumed, or aborted mid-read: the status and content-type still say enough.
+        return undefined;
+    }
+}
+export async function connectApiSSE(baseUrl, contract, params, options) {
+    // biome-ignore lint/suspicious/noExplicitAny: params shape depends on the contract
+    const requestParams = params;
+    const path = buildRequestPath(contract.pathResolver(requestParams.pathParams), requestParams.pathPrefix);
+    // `headers` may be a factory, exactly as the contract client and `injectApiSSE` accept it.
+    const callerHeaders = typeof requestParams.headers === 'function'
+        ? await requestParams.headers()
+        : requestParams.headers;
+    // Records the sends the handler could not make, matched to this connection by a header the
+    // route builder honours only for scopes open in this process.
+    const scope = openSSEDiagnosticsScope();
+    const connectOptions = {
+        method: contract.method,
+        headers: { ...callerHeaders, ...scope.headers },
+        ...(requestParams.queryParams !== undefined && { query: requestParams.queryParams }),
+        ...(requestParams.body !== undefined && { body: requestParams.body }),
+    };
+    // A connection that never happened has no reader to dispose its scope later, and a scope
+    // left registered outlives the test that opened it.
+    try {
+        if (!options) {
+            const raw = await SSEHttpClient.connect(baseUrl, path, connectOptions);
+            return new ApiSSEHttpClient(raw, contract, scope);
+        }
+        const { client: raw, serverConnection } = await SSEHttpClient.connect(baseUrl, path, {
+            ...connectOptions,
+            awaitServerConnection: options.awaitServerConnection,
+        });
+        return { client: new ApiSSEHttpClient(raw, contract, scope), serverConnection };
+    }
+    catch (error) {
+        scope.dispose();
+        throw error;
+    }
+}
+//# sourceMappingURL=apiSseHttpHelpers.js.map

package/dist/lib/testing/apiSseHttpHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiSseHttpHelpers.js","sourceRoot":"","sources":["../../../lib/testing/apiSseHttpHelpers.ts"],"names":[],"mappings":"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"}

package/dist/lib/testing/apiSseInjectHelpers.d.ts

@@ -31,8 +31,12 @@ export declare function bindApiEvents<Contract extends ApiContract>(contract: Co
  * statuses expose no JSON body through `bodyForStatus`; read them with `events()`, or use
  * `injectByApiContract` when you want the JSON side.
  *
- * Best for SSE endpoints that complete — Fastify's `inject()` waits for the whole response.
- * For long-lived connections, use `SSEHttpClient` against a real HTTP server.
+ * The response is injected as a stream, so `head` resolves as soon as the handler starts
+ * streaming and `stream()` yields each event as it is written — a test can assert
+ * progressive delivery without a listening server. `closed` and `events()` still wait for
+ * the response to complete, so an endpoint that never closes its stream (a `keepAlive`
+ * session) can only be read through `stream()`; use `SSEHttpClient` / `connectApiSSE`
+ * against a real server for those.
  *
  * @param app - Fastify instance
  * @param contract - Contract built with `defineApiContract`
@@ -55,6 +59,17 @@ export declare function bindApiEvents<Contract extends ApiContract>(contract: Co
  *
  * @example
  * ```typescript
+ * // Progressive delivery: each event is observed while the handler is still working
+ * const { head, stream } = injectApiSSE(app, lqaTextSegmentContract, { body: { segment } })
+ * expect((await head).statusCode).toBe(200)
+ *
+ * for await (const event of stream()) {
+ *   if (event.event === 'issue') expect(handlerFinished).toBe(false)
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
  * // A documented pre-stream error response, typed by the contract's 400 schema
  * const { bodyForStatus } = injectApiSSE(app, lqaTextSegmentContract, { body: { segment: '' } })
  * const error = await bodyForStatus(400)