opinionated-machine 10.0.0 → 10.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # opinionated-machine
 
+## 10.2.0
+
+### Minor Changes
+
+- 9a9a89d: Add `injectApiSSE`, a contract-typed SSE inject helper for contracts built with `defineApiContract` + `sseResponse`/`sseBody`. The existing `injectSSE`/`injectPayloadSSE` are typed against the legacy `SSEContractDefinition` and reject the newer contract shape. `injectApiSSE` covers every HTTP method from the contract, takes the same params as `injectByApiContract`, resolves `bodyForStatus` schemas from `responsesByStatusCode` (exact → range → `default` precedence), and adds `events()` for events parsed and validated against the contract's SSE schemas, merged across every declared status. The request always asks for `text/event-stream`, so statuses that declare a stream — dual-mode ones included — are excluded from `bodyForStatus`, and `events` is typed `never` for contracts that declare no SSE response.
+
+## 10.1.0
+
+### Minor Changes
+
+- 45dd012: Add `createSSESessionSpy()` testing factory so `buildApiRoute` routes can use `SSEHttpClient`'s `awaitServerConnection`. It returns a standalone `SSESessionSpy`, `{ onConnect, onClose }` route options to spread into a route with no lifecycle hooks of its own, and a `withSpy()` helper that merges the spy into a route's existing options by chaining rather than replacing its `onConnect` / `onClose`. `awaitServerConnection` now accepts `{ spy }` alongside `{ controller }`, and `SSESessionSpy` is generic over the observed session type, defaulting to the previous one.
+
+### Patch Changes
+
+- 45dd012: Fix `SSEHttpClient.connect()` leaking the open SSE response when `awaitServerConnection` times out. The caller never received a client handle, so a keep-alive stream stayed open and hung the test's `app.close()`, hiding the original timeout behind a suite-level timeout. A `waitForConnection` timeout now also explains itself when matching connections were registered but had already closed, which is what an `autoClose` session looks like to the spy.
+
 ## 10.0.0
 
 ### Major Changes

package/README.md

@@ -1559,7 +1559,7 @@ describe('NotificationsSSEController', () => {
 
 #### Testing autoClose SSE (request-response streaming)
 
-Use `SSEInjectClient` or the contract-aware `injectSSE`/`injectPayloadSSE` helpers. No real HTTP server needed - all events are available immediately after the handler completes:
+Use `SSEInjectClient` or the contract-aware `injectSSE`/`injectPayloadSSE` helpers (`injectApiSSE` for `defineApiContract` contracts). No real HTTP server needed - all events are available immediately after the handler completes:
 
 ```ts
 import { SSEInjectClient } from 'opinionated-machine'
@@ -1613,6 +1613,49 @@ it('returns the documented 401 body when unauthenticated', async () => {
 
 `bodyForStatus(status)` awaits the response, asserts the actual status matches, JSON-parses the body, and runs it through the Zod schema declared for that status. It throws — with the offending status and a truncated body snippet — if the status doesn't match, the contract declares no schema for that status, the body isn't valid JSON, or Zod parsing fails. The raw `closed` promise is still exposed for callers that want to read `body: string` directly.
 
+#### Contracts built with `defineApiContract`: `injectApiSSE`
+
+`injectSSE` / `injectPayloadSSE` are typed against the legacy `SSEContractDefinition` from `buildSseContract`. For contracts built with the newer `defineApiContract` + `sseResponse` / `sseBody` API, use `injectApiSSE` instead — one function for every method, with `params` in the same shape `injectByApiContract` takes:
+
+```ts
+import { defineApiContract, sseResponse } from '@lokalise/api-contracts'
+import { z } from 'zod/v4'
+import { injectApiSSE } from 'opinionated-machine'
+
+const lqaSegmentContract = defineApiContract({
+  visibility: 'internal',
+  method: 'post',
+  summary: 'Perform LQA on a text segment',
+  pathResolver: () => '/v1/content/actions/lqa-text-segment',
+  requestBodySchema: z.object({ segment: z.string() }),
+  responsesByStatusCode: {
+    200: sseResponse({ review: z.object({ score: z.number() }) }),
+    400: z.object({ message: z.string() }),
+  },
+})
+
+it('streams the review', async () => {
+  const { events } = injectApiSSE(app, lqaSegmentContract, { body: { segment: 'hello' } })
+
+  // Events are validated against the contract and typed as a union on `event`.
+  for (const event of await events()) {
+    if (event.event === 'review') expect(event.data.score).toBeGreaterThan(0)
+  }
+})
+
+it('returns the documented 400 body for an empty segment', async () => {
+  const { bodyForStatus } = injectApiSSE(app, lqaSegmentContract, { body: { segment: '' } })
+
+  // `body` is typed as `{ message: string }` — the contract's 400 schema.
+  const body = await bodyForStatus(400)
+  expect(body.message).toBe('segment must not be empty')
+})
+```
+
+`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.
+
+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
 
 The `connectionSpy` is available when `isTestMode: true` is passed to `asSSEControllerClass`:
@@ -1642,6 +1685,77 @@ controller.connectionSpy.clear()
 
 **Note**: `waitForConnection` tracks "claimed" sessions internally. Each call returns a unique unclaimed session, allowing sequential waits for the same URL path without returning the same session twice. This is used internally by `SSEHttpClient.connect()` with `awaitServerConnection`.
 
+#### Standalone spy for `buildApiRoute` routes
+
+`connectionSpy` only exists on `AbstractSSEController`. For routes built with `buildApiRoute` there is no controller to read it off, so `createSSESessionSpy()` returns a spy plus the `onConnect` / `onClose` route hooks that drive it:
+
+```ts
+import { createSSESessionSpy, SSEHttpClient } from 'opinionated-machine'
+
+const { spy, routeOptions } = createSSESessionSpy()
+
+// in the app under test — `routeOptions` is just `{ onConnect, onClose }`
+app.route(buildApiRoute(streamContract, handler, { ...routeOptions }))
+
+// in the test — same race-free connect as with a controller
+const { client, serverConnection } = await SSEHttpClient.connect(baseUrl, '/api/stream', {
+  awaitServerConnection: { spy },
+})
+await serverConnection.send('ping', { seq: 1 })
+```
+
+`awaitServerConnection` accepts either `{ controller }` or `{ spy }`; both wait for the server-side handler to finish registering the session before `connect()` resolves.
+
+**The hooks have to reach the `buildApiRoute()` call itself.** `buildApiRoute` captures `onConnect` / `onClose` when it builds the handler, so assigning them to the `RouteOptions` object it returns does nothing — the connect would just time out:
+
+```ts
+// Does NOT work: the route was already built without the hooks
+const route = controller.routes.streamUpdates
+Object.assign(route, routeOptions) // no-op as far as SSE lifecycle hooks go
+```
+
+A route owned by a controller therefore has to accept SSE route options for a test to be able to spy on it. Take them as a dependency and pass them through:
+
+```ts
+export class StreamController extends AbstractApiController<typeof StreamController.contracts> {
+  static contracts = { streamUpdates: streamUpdatesContract } as const
+
+  readonly routes: Record<keyof typeof StreamController.contracts, RouteOptions>
+
+  constructor({ sseRouteOptions }: StreamControllerDependencies) {
+    super()
+    this.routes = {
+      streamUpdates: buildApiRoute(
+        StreamController.contracts.streamUpdates,
+        this.streamUpdates,
+        sseRouteOptions,
+      ),
+    }
+  }
+}
+
+// production wiring registers no hooks; the test registers the spy's
+const { spy, routeOptions } = createSSESessionSpy()
+const controller = new StreamController({ sseRouteOptions: routeOptions })
+```
+
+If the route already declares lifecycle hooks of its own, use `withSpy()` rather than spreading `routeOptions` over them — spreading silently drops one side or the other, depending on the order. `withSpy()` keeps the route's hook (it runs first, and the spy is notified once it settles) and passes every other option through:
+
+```ts
+const { spy, withSpy } = createSSESessionSpy()
+
+app.route(
+  buildApiRoute(streamContract, handler, withSpy({
+    heartbeat: false,
+    onConnect: (connection) => subscriptions.add(connection.id),
+  })),
+)
+```
+
+**`keepAlive` sessions only.** An `autoClose` route closes its session as the handler returns, and `waitForConnection` only hands back sessions that are still open, since a closed one can no longer be sent events. Awaiting such a connection races and usually times out (with an error that says as much) — omit `awaitServerConnection` for `autoClose` routes and assert on the events the client received instead.
+
+The spy is typed for the `SSESession` of `@lokalise/fastify-api-contracts`, which is what `buildApiRoute` passes to its hooks. To wire the same spy into a `buildFastifyRoute`-built route, parameterize it with this package's session type: `createSSESessionSpy<SSESession>()`.
+
 ### Session Monitoring
 
 Controllers have access to utility methods for monitoring sessions:
@@ -2127,7 +2241,7 @@ The library provides utilities for testing SSE endpoints.
 | `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 |
 
-`SSEInjectClient` and `injectSSE`/`injectPayloadSSE` do the same thing (Fastify inject), but `injectSSE`/`injectPayloadSSE` provide type safety via contracts while `SSEInjectClient` works with raw URLs.
+`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`.
 
 #### Detailed Comparison
 
@@ -2240,6 +2354,9 @@ Omit `awaitServerConnection` only in these cases:
 - Testing against external SSE endpoints (not your own controller)
 - When `isTestMode: false` (connectionSpy not available)
 - Simple smoke tests that only verify response headers/status without sending server events
+- Routes whose handler starts an `autoClose` session: it closes as the handler returns, so there is no live session left to wait for — assert on the received events instead
+
+For `keepAlive` routes built with `buildApiRoute` (no controller, so no `connectionSpy`), pass a standalone spy instead of dropping the option: `awaitServerConnection: { spy }`, with the spy from [`createSSESessionSpy()`](#standalone-spy-for-buildapiroute-routes).
 
 **Consequence**: Without `awaitServerConnection`, `connect()` resolves as soon as HTTP headers are received. Server-side connection registration may not have completed yet, so you cannot reliably send events from the server immediately after `connect()` returns.
 

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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"}