opinionated-machine 10.0.0 → 10.3.0

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

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

@@ -0,0 +1,202 @@
+import type { ApiContract, ClientErrorHttpStatusCode, ExpandStatusRangeKey, HttpStatusCode, HttpStatusCodeRange, InformationalHttpStatusCode, RedirectionHttpStatusCode, ServerErrorHttpStatusCode, SuccessfulHttpStatusCode } from '@lokalise/api-contracts';
+import type { InjectByApiContractParams } from '@lokalise/fastify-api-contracts';
+import type { z } from 'zod';
+import type { SSEResponse } from './sseTestTypes.ts';
+/**
+ * Request params for {@link injectApiSSE}, derived from a `defineApiContract` contract.
+ *
+ * Identical to the params of `injectByApiContract` from
+ * `@lokalise/fastify-api-contracts` — `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 InjectApiSSEParams<Contract extends ApiContract> = InjectByApiContractParams<Contract>;
+/** The `responsesByStatusCode` map of a contract. */
+type Responses<Contract extends ApiContract> = Contract['responsesByStatusCode'];
+/** The concrete status codes a contract declares exactly (non-wildcard keys). */
+type ExactStatusCodes<Contract extends ApiContract> = keyof Responses<Contract> & HttpStatusCode;
+/** Status codes covered by any range key (e.g. `'2xx'`, `'4xx'`) the contract declares. */
+type RangeStatusCodes<Contract extends ApiContract> = {
+    [Key in keyof Responses<Contract> & HttpStatusCodeRange]: ExpandStatusRangeKey<Key>;
+}[keyof Responses<Contract> & HttpStatusCodeRange];
+/**
+ * Maps a `responsesByStatusCode` key to the statuses it covers, mirroring the runtime
+ * lookup precedence (exact → range → `'default'`): a concrete key stays as-is; a range key
+ * expands to its status class minus the exactly-declared codes; `'default'` expands to every
+ * status not covered by an exact or range key.
+ */
+type StatusesForKey<Contract extends ApiContract, Key> = Key extends 'default' ? Exclude<HttpStatusCode, ExactStatusCodes<Contract> | RangeStatusCodes<Contract>> : Key extends HttpStatusCodeRange ? Exclude<ExpandStatusRangeKey<Key>, ExactStatusCodes<Contract>> : Key;
+/** The range key a concrete status code falls into. */
+type RangeKeyOf<Status extends HttpStatusCode> = Status extends InformationalHttpStatusCode ? '1xx' : Status extends SuccessfulHttpStatusCode ? '2xx' : Status extends RedirectionHttpStatusCode ? '3xx' : Status extends ClientErrorHttpStatusCode ? '4xx' : Status extends ServerErrorHttpStatusCode ? '5xx' : never;
+/** The media type `injectApiSSE` always asks for — see {@link StreamSchemasOfEntry}. */
+type SSEMediaType = 'text/event-stream';
+/**
+ * The `event name -> schema` map of an SSE body descriptor, or `never` for any other
+ * descriptor (a bare Zod schema is JSON, `blobBody()` is opaque bytes).
+ */
+type SseSchemasOfDescriptor<Descriptor> = Descriptor extends {
+    _tag: 'SseBody';
+    schemaByEventName: infer Schemas;
+} ? Schemas : never;
+/**
+ * Every SSE schema map a response entry declares, across all of its media types — the
+ * type-level counterpart of the maps `getSseSchemaByEventName` collects at runtime.
+ */
+type SseSchemasOfEntry<Entry> = Entry extends {
+    content: infer Content;
+} ? SseSchemasOfDescriptor<Content[keyof Content]> : never;
+/**
+ * The SSE schema map an entry declares under `text/event-stream` specifically.
+ *
+ * `injectApiSSE` always sends `accept: text/event-stream`, so this is the descriptor a
+ * status resolves to whenever it declares one — even on a dual-mode content map that also
+ * carries a JSON schema.
+ */
+type StreamSchemasOfEntry<Entry> = Entry extends {
+    content: infer Content;
+} ? SseSchemasOfDescriptor<Content[SSEMediaType & keyof Content]> : never;
+/**
+ * The JSON Zod schema of a single response entry, or `never` when this helper can't reach a
+ * JSON body there. A bare schema is JSON; a content-map entry contributes the schemas of its
+ * non-blob, non-SSE descriptors.
+ *
+ * An entry that declares a `text/event-stream` body has no reachable JSON side: the request
+ * asks for the stream, so a dual-mode status answers with SSE and `bodyForStatus` would throw.
+ * Read those with `events()` instead.
+ */
+type JsonSchemaOfEntry<Entry> = [StreamSchemasOfEntry<Entry>] extends [never] ? Entry extends z.ZodType ? Entry : Entry extends {
+    content: infer Content;
+} ? Extract<Content[keyof Content], z.ZodType> : never : never;
+/** Indexes a responses map with a key that may not exist on it (yielding `never` if it doesn't). */
+type EntryAt<Contract extends ApiContract, Key> = NonNullable<Responses<Contract>[Key & keyof Responses<Contract>]>;
+/** The response entry that serves a concrete status, following exact → range → `'default'`. */
+type EntryForStatus<Contract extends ApiContract, Status extends HttpStatusCode> = [
+    EntryAt<Contract, Status>
+] extends [never] ? [EntryAt<Contract, RangeKeyOf<Status>>] extends [never] ? EntryAt<Contract, 'default'> : EntryAt<Contract, RangeKeyOf<Status>> : EntryAt<Contract, Status>;
+/**
+ * Status codes for which the contract declares a JSON response body.
+ *
+ * Resolves to `never` for contracts that declare none, so `bodyForStatus` is uncallable there.
+ * Range and `'default'` keys expand to the concrete statuses they serve, so a contract
+ * declaring only `4xx` still allows `bodyForStatus(404)`.
+ */
+export type ApiDeclaredResponseStatus<Contract extends ApiContract> = {
+    [Key in keyof Responses<Contract>]: [JsonSchemaOfEntry<EntryAt<Contract, Key>>] extends [never] ? never : StatusesForKey<Contract, Key>;
+}[keyof Responses<Contract>] & HttpStatusCode;
+/** Infers a schema's output type, or `never` when there is no schema. */
+type InferJsonBody<Schema> = Schema extends z.ZodType ? z.output<Schema> : never;
+/** The parsed JSON response body a contract declares for a concrete status. */
+export type ApiDeclaredResponseBody<Contract extends ApiContract, Status extends HttpStatusCode> = InferJsonBody<JsonSchemaOfEntry<EntryForStatus<Contract, Status>>>;
+/**
+ * Union of the SSE schema maps a contract declares, over *every* status key.
+ *
+ * Deliberately not `InferSseSuccessResponses`, which only looks at success / `'2xx'` /
+ * `'default'` keys: the runtime `getSseSchemaByEventName` merges the maps of every entry in
+ * `responsesByStatusCode`, so a stream declared under e.g. `'4xx'` produces validated events
+ * too and has to be visible here.
+ */
+type ApiSSEEventSchemas<Contract extends ApiContract> = SseSchemasOfEntry<NonNullable<Responses<Contract>[keyof Responses<Contract>]>>;
+/**
+ * The event names of a union of schema maps.
+ *
+ * `keyof` a union yields only the keys shared by every member, which collapses to `never` as
+ * soon as two statuses declare different events — so distribute first and union the keys,
+ * mirroring the runtime merge.
+ */
+type SseEventNamesOf<Schemas> = Schemas extends unknown ? keyof Schemas & string : never;
+/**
+ * The schema(s) a union of maps declares for one event name. Maps that don't declare it drop
+ * out; two maps declaring it with different schemas yield a union, since the runtime merge
+ * keeps only one of them and the reader can't tell which.
+ */
+type SseSchemaForEventName<Schemas, Name extends string> = Schemas extends Record<Name, infer Schema> ? Schema : never;
+/** Builds the event union for an already-resolved set of schema maps. */
+type ApiSSEEventOf<Schemas> = {
+    [Name in SseEventNamesOf<Schemas>]: {
+        /** Event ID, when the server sent an `id:` field. */
+        id?: string;
+        /** Event name, as sent in the `event:` field (defaults to `message`). */
+        event: Name;
+        /** Reconnection hint in milliseconds, when the server sent a `retry:` field. */
+        retry?: number;
+        /** `data:` payload, JSON-parsed and validated against the contract's schema. */
+        data: InferJsonBody<SseSchemaForEventName<Schemas, Name>>;
+    };
+}[SseEventNamesOf<Schemas>];
+/**
+ * Discriminated union of the SSE events a contract declares, with `data` parsed and typed
+ * per event name. `never` for a contract that declares no SSE response at all.
+ */
+export type ApiSSEEvent<Contract extends ApiContract> = ApiSSEEventOf<ApiSSEEventSchemas<Contract>>;
+/** Whether a contract declares an SSE response on any status. */
+type HasApiSSEResponse<Contract extends ApiContract> = [ApiSSEEventSchemas<Contract>] extends [
+    never
+] ? false : true;
+/**
+ * The callable form of {@link InjectApiSSEResult.events}.
+ *
+ * Always a function, so the internal binder has a type to return regardless of what the
+ * contract declares; the result type below hides it behind {@link HasApiSSEResponse}.
+ */
+export type ApiSSEEventReader<Contract extends ApiContract> = () => Promise<ApiSSEEvent<Contract>[]>;
+/**
+ * Result of an {@link injectApiSSE} call.
+ *
+ * The `defineApiContract` counterpart of `InjectSSEResult`: same `closed` promise and
+ * `bodyForStatus` accessor, plus `events()` for reading the stream typed against the
+ * contract's `sseResponse` / `sseBody` schemas.
+ */
+export type InjectApiSSEResult<Contract extends ApiContract> = {
+    /**
+     * Resolves when the response completes with the full SSE body.
+     * Parse the body with `parseSSEEvents()` — or use `events()` for typed events.
+     */
+    closed: Promise<SSEResponse>;
+    /**
+     * Awaits the response, asserts the status code matches, parses the body against the
+     * contract's JSON schema for that status, and returns the parsed object. Useful for
+     * asserting on the documented error responses a handler emits before streaming starts.
+     *
+     * Throws (with the offending status and a truncated body snippet) if:
+     * - the actual status code doesn't match the expected one;
+     * - the contract declares no JSON body for that status;
+     * - the body isn't valid JSON;
+     * - the body doesn't match the declared Zod schema.
+     *
+     * At the type level, `statusCode` is constrained to the statuses the contract declares a
+     * JSON body for. Contracts without any can't call this method (`statusCode: never`).
+     *
+     * @example
+     * ```typescript
+     * const { bodyForStatus } = injectApiSSE(app, contract, { body })
+     * const error = await bodyForStatus(400)  // typed as z.output<400-schema>
+     * expect(error.message).toBe('Bad request')
+     * ```
+     */
+    bodyForStatus<Status extends ApiDeclaredResponseStatus<Contract>>(statusCode: Status): Promise<ApiDeclaredResponseBody<Contract, Status>>;
+    /**
+     * Awaits the response, parses the SSE body, and validates every event against the
+     * contract's SSE schemas, returning them as a discriminated union on `event`.
+     *
+     * Events are typed from the SSE schemas of *every* status the contract declares, merged
+     * exactly as the runtime merges them — a contract streaming different events on two
+     * statuses yields the union of both.
+     *
+     * Throws if the response isn't an SSE stream (use `bodyForStatus` for the documented
+     * error statuses), if an event name isn't declared by the contract, or if an event payload
+     * doesn't match its schema.
+     *
+     * A contract that declares no SSE response at all types this as `never`, so calling it is
+     * a compile error rather than a guaranteed throw — reach for `injectByApiContract` there.
+     *
+     * @example
+     * ```typescript
+     * const events = await injectApiSSE(app, contract, { body }).events()
+     * const review = events.find((event) => event.event === 'review')
+     * expect(review?.data.score).toBe(42)  // `data` typed by the `review` schema
+     * ```
+     */
+    events: HasApiSSEResponse<Contract> extends true ? ApiSSEEventReader<Contract> : never;
+};
+export {};

package/dist/lib/testing/apiSseTestTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=apiSseTestTypes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"apiSseTestTypes.js","sourceRoot":"","sources":["../../../lib/testing/apiSseTestTypes.ts"],"names":[],"mappings":""}

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

@@ -1,5 +1,8 @@
-export { type HasSessionSpy, SSEHttpClient, type SSEHttpConnectOptions, type SSEHttpConnectResult, type SSEHttpConnectWithSpyOptions, } from './sseHttpClient.js';
+export { injectApiSSE } from './apiSseInjectHelpers.js';
+export type { ApiDeclaredResponseBody, ApiDeclaredResponseStatus, ApiSSEEvent, ApiSSEEventReader, InjectApiSSEParams, InjectApiSSEResult, } from './apiSseTestTypes.js';
+export { type HasSessionSpy, SSEHttpClient, type SSEHttpConnectOptions, type SSEHttpConnectResult, type SSEHttpConnectWithSessionSpyOptions, type SSEHttpConnectWithSpyOptions, type SSEHttpMethod, } from './sseHttpClient.js';
 export { SSEInjectClient, SSEInjectConnection } from './sseInjectClient.js';
 export { injectPayloadSSE, injectSSE } from './sseInjectHelpers.js';
+export { type CreateSSESessionSpyResult, createSSESessionSpy, type SSESessionSpyHooks, type SSESessionSpyRouteOptions, } from './sseSessionSpyFactory.js';
 export { SSETestServer } from './sseTestServer.js';
-export type { InjectPayloadSSEOptions, InjectSSEOptions, InjectSSEResult, SSEConnectOptions, SSEResponse, SSETestConnection, } from './sseTestTypes.js';
+export type { InjectPayloadSSEOptions, InjectSSEOptions, InjectSSEResult, SSEConnectOptions, SSEInjectMethod, SSEResponse, SSETestConnection, } from './sseTestTypes.js';

package/dist/lib/testing/index.js

@@ -1,5 +1,7 @@
+export { injectApiSSE } from './apiSseInjectHelpers.js';
 export { SSEHttpClient, } from './sseHttpClient.js';
 export { SSEInjectClient, SSEInjectConnection } from './sseInjectClient.js';
 export { injectPayloadSSE, injectSSE } from './sseInjectHelpers.js';
+export { createSSESessionSpy, } from './sseSessionSpyFactory.js';
 export { SSETestServer } from './sseTestServer.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,GAId,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AASvD,OAAO,EAEL,aAAa,GAMd,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACnE,OAAO,EAEL,mBAAmB,GAGpB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}

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

@@ -1,5 +1,5 @@
 import type { SSESession } from '../routes/fastifyRouteTypes.ts';
-import type { SSESessionSpy } from '../sse/SSESessionSpy.ts';
+import type { SpiedSSESession, SSESessionSpy } from '../sse/SSESessionSpy.ts';
 import { type ParsedSSEEvent } from '../sse/sseParser.ts';
 /**
  * Interface for objects that have a sessionSpy (e.g., SSE controllers in test mode).
@@ -7,6 +7,16 @@ import { type ParsedSSEEvent } from '../sse/sseParser.ts';
 export type HasSessionSpy = {
     connectionSpy: SSESessionSpy;
 };
+/** Canonical, on-the-wire spelling of a supported method. */
+type NormalizedSSEHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH';
+/**
+ * HTTP methods supported when connecting to an SSE endpoint.
+ *
+ * Both spellings are accepted and normalized internally, so the lowercase form
+ * used by route contracts (`buildContract({ method: 'post' })`) can be handed
+ * over as-is.
+ */
+export type SSEHttpMethod = NormalizedSSEHttpMethod | Lowercase<NormalizedSSEHttpMethod>;
 /**
  * Options for connecting to an SSE endpoint via HTTP.
  */
@@ -15,9 +25,28 @@ export type SSEHttpConnectOptions = {
     query?: Record<string, string | undefined>;
     /** Additional headers to send with the request */
     headers?: Record<string, string>;
+    /** HTTP method to use, upper- or lowercase (default: 'GET') */
+    method?: SSEHttpMethod;
+    /**
+     * Request body.
+     *
+     * Values `fetch()` can send natively - strings, `URLSearchParams`, `FormData`,
+     * `Blob`/`File`, `ArrayBuffer`, typed arrays (`Buffer`, `Uint8Array`, ...) and
+     * `ReadableStream` - are passed through untouched. Anything else is
+     * JSON-stringified.
+     *
+     * `content-type: application/json` is defaulted for JSON-stringified and string
+     * bodies, unless `headers` already provides a content type. Bodies that describe
+     * their own encoding (`URLSearchParams`, `FormData`, `Blob`) are left for
+     * `fetch()` to label, so their content type is never overwritten with a wrong one.
+     *
+     * Requires a non-GET `method`.
+     */
+    body?: unknown;
 };
 /**
- * Options for connecting with automatic server-side connection waiting.
+ * Options for connecting with automatic server-side connection waiting,
+ * driven by a controller's built-in `connectionSpy`.
  */
 export type SSEHttpConnectWithSpyOptions = SSEHttpConnectOptions & {
     /**
@@ -32,12 +61,32 @@ export type SSEHttpConnectWithSpyOptions = SSEHttpConnectOptions & {
         timeout?: number;
     };
 };
+/**
+ * Options for connecting with automatic server-side connection waiting,
+ * driven by a standalone spy from `createSSESessionSpy()`.
+ *
+ * Use this for routes built with `buildApiRoute`, which have no controller to
+ * read a `connectionSpy` off of.
+ */
+export type SSEHttpConnectWithSessionSpyOptions<TSession extends SpiedSSESession> = SSEHttpConnectOptions & {
+    /**
+     * Wait for server-side connection registration after HTTP headers are received.
+     * This eliminates the race condition between `connect()` returning and the
+     * server-side handler completing connection registration.
+     */
+    awaitServerConnection: {
+        /** A standalone spy, wired to the route via `createSSESessionSpy()`'s `routeOptions` */
+        spy: SSESessionSpy<TSession>;
+        /** Timeout in milliseconds (default: 5000) */
+        timeout?: number;
+    };
+};
 /**
  * Result when connecting with awaitServerConnection option.
  */
-export type SSEHttpConnectResult = {
+export type SSEHttpConnectResult<TSession extends SpiedSSESession = SSESession> = {
     client: SSEHttpClient;
-    serverConnection: SSESession;
+    serverConnection: TSession;
 };
 /**
  * SSE client for testing long-lived connections using real HTTP.
@@ -49,6 +98,13 @@ export type SSEHttpConnectResult = {
  * - **Long-lived connections** that stay open indefinitely
  * - **Real-time notifications** where events arrive over time
  * - **Push-based streaming** where the client waits for server-initiated events
+ * - **Assertions on the wire while the handler is still running** - `connect()`
+ *   resolves as soon as headers arrive, so `response.status` / `response.headers`
+ *   can be checked before the handler produces its first event
+ *
+ * GET, POST, PUT and PATCH are all supported (see `method` / `body` in
+ * {@link SSEHttpConnectOptions}), so POST SSE endpoints that take a request
+ * body can be tested over real HTTP too.
  *
  * **When to use SSEHttpClient vs SSEInjectClient:**
  *
@@ -92,14 +148,33 @@ export type SSEHttpConnectResult = {
  * ```
  */
 export declare class SSEHttpClient {
-    /** The fetch Response object. Available immediately after connect() returns. */
+    /**
+     * The fetch Response object. Available immediately after connect() returns,
+     * before any event is consumed, so status and headers can be asserted while
+     * the handler is still running.
+     *
+     * The response body is only locked once events are first consumed, so
+     * `response.json()` / `response.text()` still work for endpoints that
+     * answered with a regular HTTP response instead of a stream (for example an
+     * error raised before `sse.start()`). Read that body *before* calling
+     * `close()` - `close()` aborts the request, which rejects any pending or
+     * subsequent body read with an `AbortError`.
+     */
     readonly response: Response;
     private readonly abortController;
-    private readonly reader;
+    private readonly responseBody;
+    private streamReader;
     private readonly decoder;
     private buffer;
     private closed;
     private constructor();
+    /**
+     * Lazily acquire the stream reader, locking the response body on first use.
+     *
+     * A missing body is reported here rather than from the constructor, so a
+     * bodiless response (e.g. `204`) can still be inspected via `response`.
+     */
+    private get reader();
     /**
      * Connect to an SSE endpoint.
      *
@@ -109,7 +184,7 @@ export declare class SSEHttpClient {
      *
      * @param baseUrl - Base URL of the server (e.g., 'http://localhost:3000')
      * @param path - SSE endpoint path (e.g., '/api/notifications')
-     * @param options - Connection options (query params, headers)
+     * @param options - Connection options (method, body, query params, headers)
      * @returns Connected SSE client ready to receive events
      *
      * @example
@@ -121,6 +196,16 @@ export declare class SSEHttpClient {
      *   { query: { userId: '123' }, headers: { authorization: 'Bearer token' } }
      * )
      *
+     * // POST with a JSON body (content-type defaults to application/json)
+     * const client = await SSEHttpClient.connect(
+     *   'http://localhost:3000',
+     *   '/api/chat/completions',
+     *   { method: 'POST', body: { message: 'Hello', stream: true } }
+     * )
+     * // Headers are on the wire before the handler finished its slow work
+     * expect(client.response.status).toBe(200)
+     * expect(client.response.headers.get('content-type')).toContain('text/event-stream')
+     *
      * // With awaitServerConnection (waits for server-side registration)
      * const { client, serverConnection } = await SSEHttpClient.connect(
      *   'http://localhost:3000',
@@ -129,9 +214,20 @@ export declare class SSEHttpClient {
      * )
      * // serverConnection is ready to use immediately
      * await controller.sendEvent(serverConnection.id, { event: 'test', data: {} })
+     *
+     * // Same, for a `buildApiRoute` route with no controller: wire a standalone
+     * // spy into the route's hooks with createSSESessionSpy()
+     * const { spy, routeOptions } = createSSESessionSpy()
+     * const { client, serverConnection } = await SSEHttpClient.connect(
+     *   'http://localhost:3000',
+     *   '/api/stream',
+     *   { awaitServerConnection: { spy } }
+     * )
+     * await serverConnection.send('test', {})
      * ```
      */
     static connect(baseUrl: string, path: string, options: SSEHttpConnectWithSpyOptions): Promise<SSEHttpConnectResult>;
+    static connect<TSession extends SpiedSSESession>(baseUrl: string, path: string, options: SSEHttpConnectWithSessionSpyOptions<TSession>): Promise<SSEHttpConnectResult<TSession>>;
     static connect(baseUrl: string, path: string, options?: SSEHttpConnectOptions): Promise<SSEHttpClient>;
     /**
      * Async generator that yields parsed SSE events as they arrive.
@@ -198,6 +294,11 @@ export declare class SSEHttpClient {
      *
      * This aborts the underlying fetch request. Call this when done
      * consuming events to clean up resources.
+     *
+     * Aborting also discards any unread response body, so for a non-stream
+     * response (an error raised before `sse.start()`, say) read
+     * `response.json()` / `response.text()` before calling this.
      */
     close(): void;
 }
+export {};