opinionated-machine 6.19.1 → 6.20.0

package/README.md

@@ -1511,6 +1511,39 @@ it('streams chat completions', async () => {
 })
 ```
 
+#### Asserting documented error responses with `bodyForStatus`
+
+When a contract declares `responseBodySchemasByStatusCode` for non-2xx responses (the shape the handler emits via `sse.respond(status, body)` before streaming starts), `injectSSE` / `injectPayloadSSE` expose a typed `bodyForStatus(status)` accessor:
+
+```ts
+import { buildSseContract } from '@lokalise/api-contracts'
+import { z } from 'zod'
+import { injectSSE } from 'opinionated-machine'
+
+const streamContract = buildSseContract({
+  method: 'get',
+  pathResolver: () => '/api/stream',
+  requestQuerySchema: z.object({}),
+  requestHeaderSchema: z.object({}),
+  responseBodySchemasByStatusCode: {
+    401: z.object({ message: z.string() }),
+    404: z.object({ resourceId: z.string() }),
+  },
+  serverSentEventSchemas: { message: z.object({ text: z.string() }) },
+})
+
+it('returns the documented 401 body when unauthenticated', async () => {
+  const { bodyForStatus } = injectSSE(app, streamContract, {})
+
+  // `body` is typed as `{ message: string }` — the 401 schema.
+  // TS rejects status codes the contract doesn't declare, e.g. bodyForStatus(500).
+  const body = await bodyForStatus(401)
+  expect(body.message).toBe('Unauthorized')
+})
+```
+
+`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.
+
 ### SSESessionSpy API
 
 The `connectionSpy` is available when `isTestMode: true` is passed to `asSSEControllerClass`:

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

@@ -1,7 +1,19 @@
-import type { SSEContractDefinition } from '@lokalise/api-contracts';
+import type { HttpStatusCode, SSEContractDefinition } from '@lokalise/api-contracts';
 import type { z } from 'zod';
 import type { AnyFastifyInstance } from './AnyFastifyInstance.ts';
-import type { InjectPayloadSSEOptions, InjectSSEOptions, InjectSSEResult } from './sseTestTypes.ts';
+import type { InjectPayloadSSEOptions, InjectSSEOptions, InjectSSEResult, SSEResponse } from './sseTestTypes.ts';
+/**
+ * Build a `bodyForStatus` accessor bound to one inject call. The closure
+ * captures the contract's schemas map so the resulting helper knows which
+ * schemas to parse against; at the type level the caller is constrained to
+ * status codes the contract actually declares.
+ *
+ * @internal Exported only for unit testing — not part of the public API
+ * (the testing barrel re-exports `injectSSE`/`injectPayloadSSE` by name).
+ */
+export declare function bindBodyForStatus<Schemas extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined>(contract: {
+    responseBodySchemasByStatusCode?: Schemas;
+}, closed: Promise<SSEResponse>): InjectSSEResult<Schemas>['bodyForStatus'];
 /**
  * Inject a GET SSE request using a contract definition.
  *
@@ -21,7 +33,7 @@ import type { InjectPayloadSSEOptions, InjectSSEOptions, InjectSSEResult } from
  * const events = parseSSEEvents(result.body)
  * ```
  */
-export declare function injectSSE<Contract extends SSEContractDefinition<'get', z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, undefined, Record<string, z.ZodTypeAny>>>(app: AnyFastifyInstance, contract: Contract, options?: InjectSSEOptions<Contract>): InjectSSEResult;
+export declare function injectSSE<Contract extends SSEContractDefinition<'get', z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, undefined, Record<string, z.ZodTypeAny>, Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined>>(app: AnyFastifyInstance, contract: Contract, options?: InjectSSEOptions<Contract>): InjectSSEResult<Contract['responseBodySchemasByStatusCode']>;
 /**
  * Inject a POST/PUT/PATCH SSE request using a contract definition.
  *
@@ -49,4 +61,4 @@ export declare function injectSSE<Contract extends SSEContractDefinition<'get',
  * )
  * ```
  */
-export declare function injectPayloadSSE<Contract extends SSEContractDefinition<'post' | 'put' | 'patch', z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, Record<string, z.ZodTypeAny>>>(app: AnyFastifyInstance, contract: Contract, options: InjectPayloadSSEOptions<Contract>): InjectSSEResult;
+export declare function injectPayloadSSE<Contract extends SSEContractDefinition<'post' | 'put' | 'patch', z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny, Record<string, z.ZodTypeAny>, Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined>>(app: AnyFastifyInstance, contract: Contract, options: InjectPayloadSSEOptions<Contract>): InjectSSEResult<Contract['responseBodySchemasByStatusCode']>;

package/dist/lib/testing/sseInjectHelpers.js

@@ -1,3 +1,54 @@
+/** Truncate a long body string for error messages. */
+const BODY_TRUNCATE_LIMIT = 500;
+const truncateBody = (body) => {
+    if (body.length <= BODY_TRUNCATE_LIMIT) {
+        return body;
+    }
+    // Step back one unit if the cut would split a surrogate pair, so the
+    // snippet never ends in a lone (invalid) surrogate.
+    const lastCode = body.charCodeAt(BODY_TRUNCATE_LIMIT - 1);
+    const end = lastCode >= 0xd800 && lastCode <= 0xdbff ? BODY_TRUNCATE_LIMIT - 1 : BODY_TRUNCATE_LIMIT;
+    return `${body.slice(0, end)}…`;
+};
+/**
+ * Build a `bodyForStatus` accessor bound to one inject call. The closure
+ * captures the contract's schemas map so the resulting helper knows which
+ * schemas to parse against; at the type level the caller is constrained to
+ * status codes the contract actually declares.
+ *
+ * @internal Exported only for unit testing — not part of the public API
+ * (the testing barrel re-exports `injectSSE`/`injectPayloadSSE` by name).
+ */
+export function bindBodyForStatus(contract, closed) {
+    // A generic arrow function can't be assigned directly to the generic
+    // method signature, so the whole closure is cast once. Keep this
+    // implementation in sync with `InjectSSEResult['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)}`);
+        }
+        // Widen the generic schemas map to a concrete type so it can be indexed.
+        const schemas = contract.responseBodySchemasByStatusCode;
+        const schema = schemas?.[expected];
+        if (!schema) {
+            throw new Error(`bodyForStatus(${expected}) — no response body schema declared for status ${expected} in contract.responseBodySchemasByStatusCode`);
+        }
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(res.body);
+        }
+        catch (err) {
+            throw new Error(`bodyForStatus(${expected}) — body is not valid JSON: ${err.message}; body: ${truncateBody(res.body)}`);
+        }
+        const parsed = schema.safeParse(parsedJson);
+        if (!parsed.success) {
+            throw new Error(`bodyForStatus(${expected}) — body does not match the declared schema: ${parsed.error.message}; body: ${truncateBody(res.body)}`);
+        }
+        return parsed.data;
+    });
+}
 /**
  * Build query string from query params object.
  * @internal
@@ -62,7 +113,7 @@ export function injectSSE(app, contract, options) {
         headers: res.headers,
         body: res.body,
     }));
-    return { closed };
+    return { closed, bodyForStatus: bindBodyForStatus(contract, closed) };
 }
 /**
  * Inject a POST/PUT/PATCH SSE request using a contract definition.
@@ -109,6 +160,6 @@ export function injectPayloadSSE(app, contract, options) {
         headers: res.headers,
         body: res.body,
     }));
-    return { closed };
+    return { closed, bodyForStatus: bindBodyForStatus(contract, closed) };
 }
 //# sourceMappingURL=sseInjectHelpers.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"sseInjectHelpers.js","sourceRoot":"","sources":["../../../lib/testing/sseInjectHelpers.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAA8B;IACtD,MAAM,YAAY,GAAG,IAAI,eAAe,EAAE,CAAA;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAC1C,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QACzC,CAAC;IACH,CAAC;IACD,OAAO,YAAY,CAAC,QAAQ,EAAE,CAAA;AAChC,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CACf,QAAkB,EAClB,MAA+B,EAC/B,KAA+B;IAE/B,IAAI,GAAG,GAAG,QAAQ,CAAC,YAAY,CAAC,MAAM,IAAI,EAAE,CAAC,CAAA;IAE7C,iCAAiC;IACjC,IAAI,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,WAAW,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAA;QAC3C,IAAI,WAAW,EAAE,CAAC;YAChB,GAAG,GAAG,GAAG,GAAG,IAAI,WAAW,EAAE,CAAA;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,SAAS,CAUvB,GAAuB,EACvB,QAAkB,EAClB,OAAoC;IAEpC,MAAM,GAAG,GAAG,QAAQ,CAClB,QAAQ,EACR,OAAO,EAAE,MAA4C,EACrD,OAAO,EAAE,KAA4C,CACtD,CAAA;IAED,mEAAmE;IACnE,MAAM,MAAM,GAAG,GAAG;SACf,MAAM,CAAC;QACN,MAAM,EAAE,KAAK;QACb,GAAG;QACH,OAAO,EAAE;YACP,MAAM,EAAE,mBAAmB;YAC3B,GAAI,OAAO,EAAE,OAA8C;SAC5D;KACF,CAAC;SACD,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACd,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,OAAO,EAAE,GAAG,CAAC,OAAwD;QACrE,IAAI,EAAE,GAAG,CAAC,IAAI;KACf,CAAC,CAAC,CAAA;IAEL,OAAO,EAAE,MAAM,EAAE,CAAA;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,gBAAgB,CAU9B,GAAuB,EACvB,QAAkB,EAClB,OAA0C;IAE1C,MAAM,GAAG,GAAG,QAAQ,CAClB,QAAQ,EACR,OAAO,CAAC,MAA4C,EACpD,OAAO,CAAC,KAA4C,CACrD,CAAA;IAED,MAAM,MAAM,GAAG,GAAG;SACf,MAAM,CAAC;QACN,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,GAAG;QACH,OAAO,EAAE;YACP,MAAM,EAAE,mBAAmB;YAC3B,cAAc,EAAE,kBAAkB;YAClC,GAAI,OAAO,CAAC,OAA8C;SAC3D;QACD,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;KACtC,CAAC;SACD,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACd,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,OAAO,EAAE,GAAG,CAAC,OAAwD;QACrE,IAAI,EAAE,GAAG,CAAC,IAAI;KACf,CAAC,CAAC,CAAA;IAEL,OAAO,EAAE,MAAM,EAAE,CAAA;AACnB,CAAC"}
+{"version":3,"file":"sseInjectHelpers.js","sourceRoot":"","sources":["../../../lib/testing/sseInjectHelpers.ts"],"names":[],"mappings":"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"}

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

@@ -1,8 +1,16 @@
-import type { AnySSEContractDefinition } from '@lokalise/api-contracts';
+import type { AnySSEContractDefinition, HttpStatusCode } from '@lokalise/api-contracts';
 import type { z } from 'zod';
 import type { ParsedSSEEvent } from '../sse/sseParser.ts';
 /** Safely infer the output type of an optional Zod schema property. */
 type InferOptionalSchema<T, Fallback = unknown> = NonNullable<T> extends z.ZodTypeAny ? z.infer<NonNullable<T>> : Fallback;
+/**
+ * Status codes that the given schemas-map declares.
+ * Resolves to `never` when the map is `undefined`, so `bodyForStatus` is
+ * uncallable for contracts that declare no response body schemas at all.
+ */
+export type DeclaredResponseStatus<Schemas extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined> = Schemas extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> ? keyof Schemas & HttpStatusCode : never;
+/** Type of the parsed response body for a declared status. */
+export type DeclaredResponseBody<Schemas extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined, Status extends DeclaredResponseStatus<Schemas>> = Schemas extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> ? Status extends keyof Schemas ? Schemas[Status] extends z.ZodTypeAny ? z.infer<Schemas[Status]> : never : never : never;
 /**
  * Represents an active SSE test connection (inject-based).
  *
@@ -82,12 +90,45 @@ export type SSEResponse = {
  * Note: Fastify's inject() waits for the full response, so these helpers
  * work best for streaming that completes (OpenAI-style). For long-lived
  * SSE connections, use `SSEHttpClient` with a real HTTP server instead.
+ *
+ * When the contract declares `responseBodySchemasByStatusCode`, the result
+ * exposes `bodyForStatus(status)` — a typed accessor that parses the response
+ * body against the contract's schema for that status. TS rejects status codes
+ * the contract doesn't declare.
  */
-export type InjectSSEResult = {
+export type InjectSSEResult<Schemas extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined> = {
     /**
      * Resolves when the response completes with the full SSE body.
      * Parse the body with `parseSSEEvents()` to get individual events.
      */
     closed: Promise<SSEResponse>;
+    /**
+     * Awaits the response, asserts the status code matches, parses the body
+     * against the contract's schema for that status, and returns the parsed
+     * object. Useful for asserting on documented error response shapes.
+     *
+     * Intended for non-streaming responses emitted via `sse.respond(status, body)`
+     * before streaming starts (auth failures, validation errors, not-found).
+     * Calling it for a status served by an actual SSE stream fails at the
+     * JSON-parse step, since a stream body is `text/event-stream`, not JSON.
+     *
+     * 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 schema 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 keys of the
+     * contract's `responseBodySchemasByStatusCode`. Contracts without any
+     * declared schemas can't call this method (`statusCode: never`).
+     *
+     * @example
+     * ```typescript
+     * const { bodyForStatus } = injectSSE(app, contract, { headers })
+     * const error = await bodyForStatus(401)  // typed as z.infer<401-schema>
+     * expect(error.message).toBe('Unauthorized')
+     * ```
+     */
+    bodyForStatus<Status extends DeclaredResponseStatus<Schemas>>(statusCode: Status): Promise<DeclaredResponseBody<Schemas, Status>>;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "opinionated-machine",
-    "version": "6.19.1",
+    "version": "6.20.0",
     "description": "Very opinionated DI framework for fastify, built on top of awilix ",
     "type": "module",
     "license": "MIT",