opinionated-machine 9.0.0 → 10.2.0

package/dist/lib/routes/sseResponseSchema.js

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+/**
+ * Shape of the error bodies Fastify and the SSE route builders emit themselves, rather than
+ * the handler: `FST_ERR_VALIDATION` when a request fails schema validation, whatever an
+ * application-level `setErrorHandler` returns, and the `{ statusCode, error, message }`
+ * envelope the builders send when a handler throws before streaming starts.
+ *
+ * A declared status schema is unioned with this so those bodies stay serializable. Without it
+ * Fastify serializes them against the handler's schema, fails, and turns a declared 400 or 404
+ * into a 500 `FST_ERR_FAILED_ERROR_SERIALIZATION`. Loose so a custom error handler's extra
+ * fields survive; `statusCode` and `message` are what keeps it from matching handler bodies.
+ * `error` and `code` are listed even though loose mode would carry them anyway, because
+ * Fastify defines them as non-enumerable properties that key enumeration would skip.
+ */
+const frameworkErrorSchema = z.looseObject({
+    statusCode: z.number(),
+    message: z.string(),
+    error: z.string().optional(),
+    code: z.string().optional(),
+});
+/**
+ * Combine alternative body schemas for one status.
+ *
+ * A single schema is returned as-is rather than wrapped, so a status with only one possible
+ * body does not pick up a pointless `anyOf` in the generated spec.
+ *
+ * @returns The combined schema, or `undefined` when there is nothing to describe
+ */
+function unionOf(schemas) {
+    const [first, ...rest] = schemas;
+    if (!first) {
+        return undefined;
+    }
+    return rest.length === 0 ? first : z.union(schemas);
+}
+/**
+ * Describe an SSE stream as the union of its event envelopes, following the OpenAPI 3.x
+ * convention for `text/event-stream`: one object schema per event type (`{ id?, event, data,
+ * retry? }`), discriminated on the `event` name so the contract's event payloads show up in
+ * the generated spec as a `oneOf` of envelopes with a `const` event name.
+ *
+ * Mirrors what `@lokalise/fastify-api-contracts` produces for an `sseBody()` response, so
+ * legacy SSE / dual-mode contracts and `ApiContract` ones document the same way.
+ *
+ * @returns The event envelope schema, or `undefined` when the contract declares no events
+ */
+export function buildSseEventSchema(serverSentEventSchemas) {
+    const eventSchemas = Object.entries(serverSentEventSchemas).map(([eventName, dataSchema]) => z.object({
+        id: z.string().optional(),
+        event: z.literal(eventName),
+        data: dataSchema,
+        retry: z.int().optional(),
+    }));
+    const [firstEventSchema, ...restEventSchemas] = eventSchemas;
+    if (!firstEventSchema) {
+        return undefined;
+    }
+    return restEventSchemas.length === 0
+        ? firstEventSchema
+        : z.discriminatedUnion('event', [firstEventSchema, ...restEventSchemas]);
+}
+/**
+ * Build the JSON schema for one declared status code.
+ *
+ * A status's schema has to accept every body the runtime can put out at that status,
+ * because Fastify serializes against it and rejects anything that does not match:
+ *
+ * - 2xx on a dual-mode contract: `handleSyncMode` validates the sync body against
+ *   `successResponseBodySchema` while `processSSEHandlerResult` validates `sse.respond()`
+ *   against the contract's schema for that status, so both shapes are possible.
+ * - Non-2xx: the handler's declared body, or a framework error envelope.
+ */
+function buildStatusSchema(statusCode, declaredSchema, syncSuccessSchema) {
+    const isSuccessStatus = statusCode >= 200 && statusCode < 300;
+    if (isSuccessStatus) {
+        return unionOf([syncSuccessSchema, declaredSchema].filter((schema) => schema !== undefined));
+    }
+    return declaredSchema && z.union([declaredSchema, frameworkErrorSchema]);
+}
+/**
+ * Build the `schema.response` map for an SSE or dual-mode route from its contract.
+ *
+ * The 200 entry uses Fastify's per-media-type form so a single status can describe both the
+ * event stream and the JSON body: `text/event-stream` carries the event envelopes, and
+ * `application/json` carries the sync body (dual-mode), the body the contract declares for
+ * 200 (an SSE route that answers `sse.respond(200, ...)` before streaming starts), or both.
+ *
+ * Populating this drives both the OpenAPI spec and Fastify's serializer, so a status code the
+ * contract declares is now serialized against its schema instead of plain `JSON.stringify`.
+ *
+ * @param serverSentEventSchemas - Contract's event name to payload schema map
+ * @param responseBodySchemasByStatusCode - Contract's per-status response schemas, if any
+ * @param syncSuccessSchema - Dual-mode sync 2xx body schema; omit for SSE-only contracts
+ */
+export function buildSseResponseSchemas(serverSentEventSchemas, responseBodySchemasByStatusCode, syncSuccessSchema) {
+    const { 200: declaredOkSchema, ...otherStatusSchemas } = responseBodySchemasByStatusCode ?? {};
+    const jsonOkSchema = buildStatusSchema(200, declaredOkSchema, syncSuccessSchema);
+    const eventSchema = buildSseEventSchema(serverSentEventSchemas);
+    const okContent = {
+        ...(eventSchema && { 'text/event-stream': { schema: eventSchema } }),
+        ...(jsonOkSchema && { 'application/json': { schema: jsonOkSchema } }),
+    };
+    const responseSchemas = {};
+    if (Object.keys(okContent).length > 0) {
+        responseSchemas[200] = { content: okContent };
+    }
+    for (const [statusCode, declaredSchema] of Object.entries(otherStatusSchemas)) {
+        const schema = buildStatusSchema(Number(statusCode), declaredSchema, syncSuccessSchema);
+        if (schema) {
+            responseSchemas[statusCode] = schema;
+        }
+    }
+    return responseSchemas;
+}
+//# sourceMappingURL=sseResponseSchema.js.map

package/dist/lib/routes/sseResponseSchema.js.map

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

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

@@ -1,21 +1,39 @@
 import type { SSESession } from './AbstractSSEController.ts';
-export type SSESessionEvent = {
+/**
+ * Minimal shape of an SSE session the spy needs in order to track it.
+ *
+ * Both the `SSESession` produced by this package's own SSE routes and the one
+ * produced by `@lokalise/fastify-api-contracts` (used by `buildApiRoute`)
+ * satisfy it, which lets a single spy be attached to either route style.
+ */
+export type SpiedSSESession = {
+    id: string;
+    request: {
+        url: string;
+    };
+};
+export type SSESessionEvent<TSession extends SpiedSSESession = SSESession> = {
     type: 'connect' | 'disconnect';
     connectionId: string;
-    connection?: SSESession;
+    connection?: TSession;
 };
 /**
  * Connection spy for testing SSE controllers.
  * Tracks connection and disconnection events separately.
+ *
+ * @template TSession - The session type the spy observes. Defaults to this
+ *   package's `SSESession`, which is what `AbstractSSEController` reports.
+ *   Tests wiring the spy to `buildApiRoute` routes get it parameterized with
+ *   the contracts package session type via `createSSESessionSpy()`.
  */
-export declare class SSESessionSpy {
+export declare class SSESessionSpy<TSession extends SpiedSSESession = SSESession> {
     private events;
     private activeConnections;
     private claimedConnections;
     private connectionWaiters;
     private disconnectionWaiters;
     /** @internal Called when a connection is established */
-    addConnection(connection: SSESession): void;
+    addConnection(connection: TSession): void;
     /** @internal Called when a connection is closed */
     addDisconnection(connectionId: string): void;
     /**
@@ -40,8 +58,18 @@ export declare class SSESessionSpy {
      */
     waitForConnection(options?: {
         timeout?: number;
-        predicate?: (connection: SSESession) => boolean;
-    }): Promise<SSESession>;
+        predicate?: (connection: TSession) => boolean;
+    }): Promise<TSession>;
+    /**
+     * Explain a timeout that had matching connections which were already gone.
+     *
+     * `waitForConnection` only hands back sessions that are still active, since a
+     * closed session can no longer be sent events. A route that streams with
+     * `autoClose` closes its session as the handler returns, so its connection is
+     * registered and closed before a test can claim it — without this hint that
+     * shows up as a bare timeout with no indication of what went wrong.
+     */
+    private describeMissedConnections;
     /** Wait for a specific connection to disconnect */
     waitForDisconnection(connectionId: string, options?: {
         timeout?: number;
@@ -49,7 +77,7 @@ export declare class SSESessionSpy {
     /** Check if a connection is currently active */
     isConnected(connectionId: string): boolean;
     /** Get all connection events in order, optionally filtered by connectionId */
-    getEvents(connectionId?: string): SSESessionEvent[];
+    getEvents(connectionId?: string): SSESessionEvent<TSession>[];
     /** Clear all events and cancel pending waiters */
     clear(): void;
 }

package/dist/lib/sse/SSESessionSpy.js

@@ -1,6 +1,11 @@
 /**
  * Connection spy for testing SSE controllers.
  * Tracks connection and disconnection events separately.
+ *
+ * @template TSession - The session type the spy observes. Defaults to this
+ *   package's `SSESession`, which is what `AbstractSSEController` reports.
+ *   Tests wiring the spy to `buildApiRoute` routes get it parameterized with
+ *   the contracts package session type via `createSSESessionSpy()`.
  */
 export class SSESessionSpy {
     events = [];
@@ -75,11 +80,35 @@ export class SSESessionSpy {
                 if (index !== -1) {
                     this.connectionWaiters.splice(index, 1);
                 }
-                reject(new Error(`Timeout waiting for connection after ${timeout}ms`));
+                reject(new Error(`Timeout waiting for connection after ${timeout}ms${this.describeMissedConnections(predicate)}`));
             }, timeout);
             this.connectionWaiters.push({ resolve, reject, timeoutId, predicate });
         });
     }
+    /**
+     * Explain a timeout that had matching connections which were already gone.
+     *
+     * `waitForConnection` only hands back sessions that are still active, since a
+     * closed session can no longer be sent events. A route that streams with
+     * `autoClose` closes its session as the handler returns, so its connection is
+     * registered and closed before a test can claim it — without this hint that
+     * shows up as a bare timeout with no indication of what went wrong.
+     */
+    describeMissedConnections(predicate) {
+        const missed = this.events.filter((e) => e.type === 'connect' &&
+            e.connection &&
+            !this.activeConnections.has(e.connection.id) &&
+            (!predicate || predicate(e.connection)));
+        if (missed.length === 0) {
+            return '';
+        }
+        const ids = missed.map((e) => e.connectionId).join(', ');
+        return (`. ${missed.length} matching connection(s) were registered but had already closed: ${ids}. ` +
+            'Only sessions that are still open can be awaited, since a closed one can no longer be sent ' +
+            'events. A session started with `autoClose` closes as its handler returns, so a route that ' +
+            'uses one cannot be awaited at all - omit `awaitServerConnection` there and assert on the ' +
+            'events the client received instead.');
+    }
     /** Wait for a specific connection to disconnect */
     waitForDisconnection(connectionId, options) {
         const timeout = options?.timeout ?? 5000;

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

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

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

@@ -3,6 +3,6 @@ export { type BuildFastifySSERoutesReturnType, buildFastifyRoute, buildHandler,
 export { AbstractSSEController, type SSEControllerConfig, type SSEEventSender, type SSELogger, type SSEMessage, } from './AbstractSSEController.js';
 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 SSESessionEvent, SSESessionSpy } from './SSESessionSpy.js';
+export { type SpiedSSESession, type SSESessionEvent, SSESessionSpy } from './SSESessionSpy.js';
 export { type ParsedSSEEvent, type ParseSSEBufferResult, parseSSEBuffer, parseSSEEvents, } from './sseParser.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.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,EAAwB,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACxE,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,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EAQnB,sBAAsB,GAKvB,MAAM,0BAA0B,CAAA"}

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

@@ -0,0 +1,64 @@
+import { type ApiContract } from '@lokalise/api-contracts';
+import type { AnyFastifyInstance } from './AnyFastifyInstance.ts';
+import type { ApiSSEEventReader, InjectApiSSEParams, InjectApiSSEResult } from './apiSseTestTypes.ts';
+import type { SSEResponse } from './sseTestTypes.ts';
+/**
+ * Build a `bodyForStatus` accessor bound to one `injectApiSSE` call.
+ *
+ * @internal Exported only for unit testing — not part of the public API
+ * (the testing barrel re-exports `injectApiSSE` by name).
+ */
+export declare function bindApiBodyForStatus<Contract extends ApiContract>(contract: Contract, closed: Promise<SSEResponse>): InjectApiSSEResult<Contract>['bodyForStatus'];
+/**
+ * Build an `events` accessor bound to one `injectApiSSE` call: parses the SSE body and
+ * validates every event against the contract's `sseBody` schemas.
+ *
+ * @internal Exported only for unit testing — not part of the public API.
+ */
+export declare function bindApiEvents<Contract extends ApiContract>(contract: Contract, closed: Promise<SSEResponse>): ApiSSEEventReader<Contract>;
+/**
+ * Inject an SSE request using a contract built with `defineApiContract` + `sseResponse` /
+ * `sseBody` (the newer `@lokalise/api-contracts` API).
+ *
+ * The `defineApiContract` counterpart of `injectSSE` / `injectPayloadSSE`, which are typed
+ * against the legacy `SSEContractDefinition`. One function covers every method: the HTTP verb
+ * comes from the contract, and `params` (`pathParams` / `queryParams` / `headers` / `body` /
+ * `pathPrefix`) is the same shape `injectByApiContract` takes, so a body is required exactly
+ * when the contract declares `requestBodySchema`.
+ *
+ * The request always carries `accept: text/event-stream` (a caller-supplied `accept` still
+ * wins), so a status declaring a stream answers with it — dual-mode statuses included. Those
+ * 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.
+ *
+ * @param app - Fastify instance
+ * @param contract - Contract built with `defineApiContract`
+ * @param params - Request params derived from the contract
+ *
+ * @example
+ * ```typescript
+ * const { closed, bodyForStatus, events } = injectApiSSE(app, lqaTextSegmentContract, {
+ *   body: { segment: 'hello' },
+ * })
+ *
+ * // Typed events, validated against the contract's sseResponse schemas
+ * for (const event of await events()) {
+ *   if (event.event === 'review') expect(event.data.score).toBeGreaterThan(0)
+ * }
+ *
+ * // Or the raw body, for assertions the typed accessors don't cover
+ * expect((await closed).statusCode).toBe(200)
+ * ```
+ *
+ * @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)
+ * expect(error.message).toBe('segment must not be empty')
+ * ```
+ */
+export declare function injectApiSSE<const Contract extends ApiContract>(app: AnyFastifyInstance, contract: Contract, params: InjectApiSSEParams<Contract>): InjectApiSSEResult<Contract>;

package/dist/lib/testing/apiSseInjectHelpers.js

@@ -0,0 +1,212 @@
+import { getSseSchemaByEventName, resolveResponseEntry, } from '@lokalise/api-contracts';
+import { injectByApiContract } from '@lokalise/fastify-api-contracts';
+import { parseSSEEvents } from "../sse/sseParser.js";
+import { truncateBody } from "./sseInjectShared.js";
+const SSE_CONTENT_TYPE = 'text/event-stream';
+/** Read a response header that light-my-request may expose as an array. */
+function readHeader(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+/** Strip `; charset=…` style parameters from a media type. */
+function mediaTypeOf(contentType) {
+    return contentType?.split(';')[0]?.trim().toLowerCase();
+}
+const STATUS_RANGE_KEYS = ['1xx', '2xx', '3xx', '4xx', '5xx'];
+/**
+ * The `responsesByStatusCode` key that serves a status, following the same
+ * exact → range → `'default'` precedence as `resolveResponseEntry`.
+ *
+ * Diagnostics only. `resolveResponseEntry` collapses "no entry for this status" and "an entry
+ * exists but none of its content-map descriptors matched the response's content-type" into a
+ * single `null`; this tells the two apart so the error names the actual problem.
+ */
+function findResponseKeyForStatus(responsesByStatusCode, statusCode) {
+    if (responsesByStatusCode[statusCode]) {
+        return String(statusCode);
+    }
+    const rangeKey = STATUS_RANGE_KEYS[Math.floor(statusCode / 100) - 1];
+    if (rangeKey && responsesByStatusCode[rangeKey]) {
+        return rangeKey;
+    }
+    return responsesByStatusCode.default ? 'default' : undefined;
+}
+/**
+ * The JSON schema the contract declares for the status a response actually carries, or a
+ * thrown error naming why there isn't one.
+ *
+ * Resolution follows the same exact → range → `'default'` precedence (and content-type
+ * matching) the contract client uses, so a stream on one status and JSON bodies on the others
+ * resolve independently.
+ */
+function resolveJsonSchemaForStatus(responsesByStatusCode, statusCode, res) {
+    const contentType = readHeader(res.headers['content-type']);
+    // Non-strict resolution: a response without a content-type still resolves to the entry's
+    // declared kind, which keeps hand-rolled test handlers working.
+    const resolved = resolveResponseEntry(responsesByStatusCode, statusCode, contentType, false);
+    if (!resolved) {
+        const declaredKey = findResponseKeyForStatus(responsesByStatusCode, statusCode);
+        throw new Error(declaredKey === undefined
+            ? `bodyForStatus(${statusCode}) — no response declared for status ${statusCode} in contract.responsesByStatusCode`
+            : `bodyForStatus(${statusCode}) — the '${declaredKey}' entry of contract.responsesByStatusCode declares no body for content-type '${mediaTypeOf(contentType) ?? 'absent'}'; body: ${truncateBody(res.body)}`);
+    }
+    if (resolved.kind !== 'json') {
+        // A dual-mode status lands here: `injectApiSSE` asks for the stream, so that is what the
+        // status resolved to. The type layer rules this out, so reaching it means a cast.
+        const hint = resolved.kind === 'sse'
+            ? ` — injectApiSSE requests '${SSE_CONTENT_TYPE}', so a status declaring a stream always answers with it; read it with events()`
+            : '';
+        throw new Error(`bodyForStatus(${statusCode}) — the contract declares a '${resolved.kind}' response for status ${statusCode}, not a JSON body${hint}`);
+    }
+    return resolved.schema;
+}
+/** JSON-parse and schema-validate a response body, reporting either failure in context. */
+function parseJsonBody(schema, statusCode, body) {
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(body);
+    }
+    catch (err) {
+        throw new Error(`bodyForStatus(${statusCode}) — body is not valid JSON: ${err.message}; body: ${truncateBody(body)}`);
+    }
+    const parsed = schema.safeParse(parsedJson);
+    if (!parsed.success) {
+        throw new Error(`bodyForStatus(${statusCode}) — body does not match the declared schema: ${parsed.error.message}; body: ${truncateBody(body)}`);
+    }
+    return parsed.data;
+}
+/**
+ * Build a `bodyForStatus` accessor bound to one `injectApiSSE` call.
+ *
+ * @internal Exported only for unit testing — not part of the public API
+ * (the testing barrel re-exports `injectApiSSE` by name).
+ */
+export function bindApiBodyForStatus(contract, closed) {
+    // A generic arrow function can't be assigned directly to the generic method signature,
+    // so the whole closure is cast once. Keep in sync with `InjectApiSSEResult['bodyForStatus']`.
+    return (async (statusCode) => {
+        const res = await closed;
+        const expected = statusCode;
+        if (res.statusCode !== expected) {
+            throw new Error(`bodyForStatus(${expected}) — actual status ${res.statusCode}, body: ${truncateBody(res.body)}`);
+        }
+        const schema = resolveJsonSchemaForStatus(contract.responsesByStatusCode, expected, res);
+        return parseJsonBody(schema, expected, res.body);
+    });
+}
+/**
+ * Build an `events` accessor bound to one `injectApiSSE` call: parses the SSE body and
+ * validates every event against the contract's `sseBody` schemas.
+ *
+ * @internal Exported only for unit testing — not part of the public API.
+ */
+export function bindApiEvents(contract, closed) {
+    return async () => {
+        const res = await closed;
+        // Merges the SSE schemas of every declared status, not just the successful ones.
+        const schemaByEventName = getSseSchemaByEventName(contract);
+        if (!schemaByEventName) {
+            throw new Error('events() — the contract declares no SSE response');
+        }
+        const contentType = mediaTypeOf(readHeader(res.headers['content-type']));
+        if (contentType !== SSE_CONTENT_TYPE) {
+            throw new Error(`events() — response is not an SSE stream (status ${res.statusCode}, content-type ${contentType ?? 'absent'}); use bodyForStatus(${res.statusCode}) for declared error responses. Body: ${truncateBody(res.body)}`);
+        }
+        return parseSSEEvents(res.body).map((event) => {
+            // 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(`events() — the contract declares no schema for event "${name}"`);
+            }
+            let parsedJson;
+            try {
+                parsedJson = JSON.parse(event.data);
+            }
+            catch (err) {
+                throw new Error(`events() — 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(`events() — 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,
+            };
+        });
+    };
+}
+/**
+ * Inject an SSE request using a contract built with `defineApiContract` + `sseResponse` /
+ * `sseBody` (the newer `@lokalise/api-contracts` API).
+ *
+ * The `defineApiContract` counterpart of `injectSSE` / `injectPayloadSSE`, which are typed
+ * against the legacy `SSEContractDefinition`. One function covers every method: the HTTP verb
+ * comes from the contract, and `params` (`pathParams` / `queryParams` / `headers` / `body` /
+ * `pathPrefix`) is the same shape `injectByApiContract` takes, so a body is required exactly
+ * when the contract declares `requestBodySchema`.
+ *
+ * The request always carries `accept: text/event-stream` (a caller-supplied `accept` still
+ * wins), so a status declaring a stream answers with it — dual-mode statuses included. Those
+ * 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.
+ *
+ * @param app - Fastify instance
+ * @param contract - Contract built with `defineApiContract`
+ * @param params - Request params derived from the contract
+ *
+ * @example
+ * ```typescript
+ * const { closed, bodyForStatus, events } = injectApiSSE(app, lqaTextSegmentContract, {
+ *   body: { segment: 'hello' },
+ * })
+ *
+ * // Typed events, validated against the contract's sseResponse schemas
+ * for (const event of await events()) {
+ *   if (event.event === 'review') expect(event.data.score).toBeGreaterThan(0)
+ * }
+ *
+ * // Or the raw body, for assertions the typed accessors don't cover
+ * expect((await closed).statusCode).toBe(200)
+ * ```
+ *
+ * @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)
+ * expect(error.message).toBe('segment must not be empty')
+ * ```
+ */
+export function injectApiSSE(app, contract, params) {
+    // biome-ignore lint/suspicious/noExplicitAny: params shape depends on the contract
+    const requestParams = params;
+    const closed = injectByApiContract(app, contract, {
+        ...requestParams,
+        // `accept` first so an explicit caller header still wins; headers may be a factory,
+        // which `injectByApiContract` resolves for us — resolve the caller's here too.
+        headers: async () => ({
+            accept: SSE_CONTENT_TYPE,
+            ...(typeof requestParams.headers === 'function'
+                ? await requestParams.headers()
+                : requestParams.headers),
+        }),
+    }).then((res) => ({
+        statusCode: res.statusCode,
+        headers: res.headers,
+        body: res.body,
+    }));
+    return {
+        closed,
+        bodyForStatus: bindApiBodyForStatus(contract, closed),
+        // `events` is typed `never` for contracts that declare no SSE response, which no concrete
+        // function satisfies — the binder returns the callable form and it is narrowed here.
+        events: bindApiEvents(contract, closed),
+    };
+}
+//# sourceMappingURL=apiSseInjectHelpers.js.map

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

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