opinionated-machine 7.0.0 → 9.0.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# opinionated-machine
+
+## 9.0.0
+
+### Major Changes
+
+- d6da03e: Adopt mandatory contract visibility (`@lokalise/api-contracts` v8):
+  
+  - Raise peer dependency floors to `@lokalise/api-contracts` >= 8.0.0 (visibility is now a required
+    field of every contract builder config) and `@lokalise/fastify-api-contracts` >= 7.0.0.
+  - Derive the fastify-swagger `hide` flag from contract `visibility` in the SSE and dual-mode route
+    builders, failing closed: only `visibility: 'public'` contracts appear in generated OpenAPI docs.
+    Anything else — `'internal'`, or a contract that lacks the field at runtime because it was compiled
+    against a pre-visibility `@lokalise/api-contracts` — sets `schema.hide: true` and is excluded,
+    matching `@lokalise/fastify-api-contracts`. The same builders now also map the contract's
+    `description`, `summary` and `tags` to the route schema; previously these fields were dropped and
+    the routes appeared undocumented.
+  - Remove the unused `visibility` field from the gateway metadata schema. No generator consumed it
+    and it collided with the (unrelated) contract `visibility` — a docs-internal BFF route can still
+    be gateway-public, so the two concepts cannot be derived from each other. If gateway-level
+    exposure classification is needed later, it will be reintroduced under a non-colliding name
+    (e.g. `exposure`). The metadata schema is strict, so passing `visibility` now fails loudly.
+
+## 8.0.0
+
+### Major Changes
+
+- de12db0: Replace the local ApiContract route builder with `buildFastifyApiRoute` from `@lokalise/fastify-api-contracts` (>=6.0.0, now the source of the route-building, handler inference, response validation, and SSE streaming logic). `buildApiRoute` remains as a thin wrapper that only adds the contract-narrowed `gatewayMetadata` option.
+  
+  Breaking changes:
+  
+  - Handlers now use the package's unified `(request, reply, context) => { status, body }` shape for every response mode. SSE streaming is driven via `context.sse.start(...)` (or by returning an `AsyncIterable` body for an SSE status); dual-mode `{ nonSse, sse }` handler objects and `sse.respond()` / `sse.sendHeaders()` are gone — branch on `context.expectedContentType` and return `{ status, body }` for early HTTP responses.
+  - `ApiNonSseHandler`, `ApiSseHandler`, `InferApiRequest`, and `InferApiStatusResponse` are removed; `InferApiHandler`, `InferApiHandlerRequest`, `InferApiHandlerResult`, `ApiHandlerContext`, and `ApiHandlerReply` are re-exported from `@lokalise/fastify-api-contracts` instead.
+  - `buildApiRoute` options: `defaultMode` is removed (use `context.expectedContentType`). `heartbeatInterval` is removed — per-route heartbeat intervals are no longer possible: the package's `heartbeat` option is a boolean that only enables/disables the heartbeat for a route, and the interval itself is configured once for all routes at `@fastify/sse` plugin registration (`heartbeatInterval`, default 30000 ms).
+  - Response body validation is delegated to the `fastify-type-provider-zod` serializer compiler — apps must register `validatorCompiler` / `serializerCompiler`. This applies to every ApiContract route, not just JSON ones: the package emits a Zod response schema for every declared status (including `sseBody()` and `noBodyResponse()`, which previously produced no response schema), so an app missing `setSerializerCompiler` now fails at boot during route registration — even for SSE-only contracts — with `FST_ERR_SCH_SERIALIZATION_BUILD: Failed building the serialization schema … schema is invalid: data/required must be array`. If you hit that error, register the zod compilers. Peer ranges bumped: `@lokalise/fastify-api-contracts` >=6.0.0, `fastify-type-provider-zod` >=7.0.0.
+  - Error handling is delegated to the app's global `fastify.setErrorHandler` (per the `@lokalise/fastify-api-contracts` README), including for SSE routes: the route builder no longer maps the node-core `httpStatusCode` error convention (`PublicNonRecoverableError`, `InternalError`, …) onto responses — such errors now reach the error handler unmapped and default to 500 — and no longer emits a terminal SSE `error` event when a handler throws after `sse.start()`. Note the resulting cross-system split: legacy `buildFastifyRoute` / SSE / dual-mode routes still honor `httpStatusCode` internally, so an app mixing both route families maps the same error to different statuses. Install a global error handler that maps `httpStatusCode` (and, if your clients rely on it, emits the terminal SSE `error` event) before upgrading.
+  - The `SSESession` / `SSEContext` / `SSESessionMode` / `FastifySSERouteOptions` types exported from the package root still resolve to the legacy `lib/routes` types and no longer match what `buildApiRoute` handlers and lifecycle hooks (`onConnect` / `onClose`) actually receive — the package's session has no `rooms` / `eventSchemas`, an optional `context`, adds `close()`, and its context has no `respond()` / `sendHeaders()`. When typing `buildApiRoute` sessions, contexts, or hooks explicitly, import these types from `@lokalise/fastify-api-contracts` directly; the root exports keep typing the legacy `AbstractSSEController` / `AbstractDualModeController` routes.
+
+## 7.0.0
+
+### Major Changes
+
+- e3a05b6: Require `@lokalise/api-contracts` >= 7.0.0. The route builder no longer handles the legacy response entries removed in api-contracts 7 (`anyOfResponses`, `sseResponse`/`blobResponse`/`textResponse` tagged objects, `ContractNoBody` as a response) — declare responses with bare Zod schemas, `noBodyResponse()`, or content maps (`{ content: { 'text/event-stream': sseBody(...) } }`). Handler body types are now also inferred from content-map entries (JSON media types resolve to their Zod output type, blob to `Blob`, `allowNoBody` to `undefined`).
+
+## 6.20.3
+
+### Patch Changes
+
+- 22a290b: Migrate release automation to Changesets.

package/README.md

@@ -475,6 +475,7 @@ const PATH_PARAMS_SCHEMA = z.object({
 })
 
 const contract = buildRestContract({
+  visibility: 'public',
   method: 'delete',
   successResponseBodySchema: BODY_SCHEMA,
   requestPathParamsSchema: PATH_PARAMS_SCHEMA,
@@ -741,6 +742,7 @@ import { buildSseContract } from '@lokalise/api-contracts'
 
 // GET-based SSE stream with path params
 export const channelStreamContract = buildSseContract({
+  visibility: 'public',
   method: 'get',
   pathResolver: (params) => `/api/channels/${params.channelId}/stream`,
   requestPathParamsSchema: z.object({ channelId: z.string() }),
@@ -753,6 +755,7 @@ export const channelStreamContract = buildSseContract({
 
 // GET-based SSE stream without path params
 export const notificationsContract = buildSseContract({
+  visibility: 'public',
   method: 'get',
   pathResolver: () => '/api/notifications/stream',
   requestPathParamsSchema: z.object({}),
@@ -768,6 +771,7 @@ export const notificationsContract = buildSseContract({
 
 // POST-based SSE stream (e.g., AI chat completions)
 export const chatCompletionContract = buildSseContract({
+  visibility: 'public',
   method: 'post',
   pathResolver: () => '/api/chat/completions',
   requestPathParamsSchema: z.object({}),
@@ -1128,6 +1132,7 @@ The mapper can return any of: `config`, `bodyLimit`, `onRequest`, `preParsing`,
 ```ts
 // In the contract definition
 const adminStreamContract = buildSseContract({
+  visibility: 'public',
   method: 'get',
   pathResolver: () => '/api/admin/stream',
   // ...schemas...
@@ -1521,6 +1526,7 @@ import { z } from 'zod'
 import { injectSSE } from 'opinionated-machine'
 
 const streamContract = buildSseContract({
+  visibility: 'public',
   method: 'get',
   pathResolver: () => '/api/stream',
   requestQuerySchema: z.object({}),
@@ -2262,6 +2268,7 @@ import { buildSseContract } from '@lokalise/api-contracts'
 
 // GET dual-mode route (polling or streaming job status)
 export const jobStatusContract = buildSseContract({
+  visibility: 'public',
   method: 'get',
   pathResolver: (params) => `/api/jobs/${params.jobId}/status`,
   requestPathParamsSchema: z.object({ jobId: z.string().uuid() }),
@@ -2280,6 +2287,7 @@ export const jobStatusContract = buildSseContract({
 
 // POST dual-mode route (OpenAI-style chat completion)
 export const chatCompletionContract = buildSseContract({
+  visibility: 'public',
   method: 'post',
   pathResolver: (params) => `/api/chats/${params.chatId}/completions`,
   requestPathParamsSchema: z.object({ chatId: z.string().uuid() }),
@@ -2305,6 +2313,7 @@ Dual-mode contracts support an optional `responseHeaderSchema` to define and val
 
 ```ts
 export const rateLimitedContract = buildSseContract({
+  visibility: 'public',
   method: 'post',
   pathResolver: () => '/api/rate-limited',
   requestPathParamsSchema: z.object({}),
@@ -2350,6 +2359,7 @@ Dual-mode and SSE contracts support `responseBodySchemasByStatusCode` to define
 
 ```ts
 export const resourceContract = buildSseContract({
+  visibility: 'public',
   method: 'post',
   pathResolver: (params) => `/api/resources/${params.id}`,
   requestPathParamsSchema: z.object({ id: z.string() }),
@@ -2876,12 +2886,14 @@ import {
 import { z } from 'zod/v4'
 
 const getUser = buildRestContract({
+  visibility: 'public',
   method: 'get',
   successResponseBodySchema: z.object({ id: z.string() }),
   requestPathParamsSchema: z.object({ userId: z.string() }),
   pathResolver: (p) => `/users/${p.userId}`,
 })
 const createUser = buildRestContract({
+  visibility: 'public',
   method: 'post',
   requestBodySchema: z.object({ name: z.string() }),
   successResponseBodySchema: z.object({ id: z.string() }),
@@ -3031,6 +3043,7 @@ become compile errors before you ever ship a config:
 
 ```ts
 const getUser = buildRestContract({
+  visibility: 'public',
   method: 'get',
   successResponseBodySchema: ResponseBody,
   requestHeaderSchema: z.object({ 'x-trace-id': z.string() }),
@@ -3088,7 +3101,7 @@ time.
 | `rewrite` | `{ stripPrefix: '/v2' }` or `{ replacePrefix: { from: '/v1', to: '/v2' } }` | |
 | `traffic` | `{ weights: [{ upstream: 'a', weight: 80 }, { upstream: 'b', weight: 20 }] }` | Also `shadow: { upstream, percent }` |
 | `headers` | `{ request: { add: { 'x-internal': 'true' }, remove: ['cookie'] }, response: … }` | Free-form keys; typically infra headers not in the contract |
-| `tags`, `visibility` | `tags: ['users']`, `visibility: 'internal'` | Documentation / partitioning |
+| `tags` | `tags: ['users']` | Documentation / partitioning |
 | `extensions` | `{ envoy: { … }, krakend: { … }, kong: { … } }` | Vendor escape hatch; merged onto the generated route last |
 
 ### Generating Gateway Configs

package/dist/lib/api-contracts/AbstractApiController.d.ts

@@ -20,9 +20,12 @@ import type { GatewayMetadataValue } from '../gateway/gatewayMetadata.ts';
  *       status: 200,
  *       body: { id: req.params.id },
  *     })),
- *     streamUpdates: buildApiRoute(UserController.contracts.streamUpdates, async (_req, sse) => {
- *       sse.start('keepAlive')
- *     }),
+ *     streamUpdates: buildApiRoute(
+ *       UserController.contracts.streamUpdates,
+ *       async (_req, _reply, { sse }) => {
+ *         sse.start('keepAlive')
+ *       },
+ *     ),
  *   }
  * }
  * ```

package/dist/lib/api-contracts/AbstractApiController.js

@@ -17,9 +17,12 @@
  *       status: 200,
  *       body: { id: req.params.id },
  *     })),
- *     streamUpdates: buildApiRoute(UserController.contracts.streamUpdates, async (_req, sse) => {
- *       sse.start('keepAlive')
- *     }),
+ *     streamUpdates: buildApiRoute(
+ *       UserController.contracts.streamUpdates,
+ *       async (_req, _reply, { sse }) => {
+ *         sse.start('keepAlive')
+ *       },
+ *     ),
  *   }
  * }
  * ```

package/dist/lib/api-contracts/AbstractApiController.js.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractApiController.js","sourceRoot":"","sources":["../../../lib/api-contracts/AbstractApiController.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAgB,qBAAqB;IAGzC;;;;;;;OAOG;IACa,eAAe,CAAuB;CACvD"}
+{"version":3,"file":"AbstractApiController.js","sourceRoot":"","sources":["../../../lib/api-contracts/AbstractApiController.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAgB,qBAAqB;IAGzC;;;;;;;OAOG;IACa,eAAe,CAAuB;CACvD"}

package/dist/lib/api-contracts/apiRouteBuilder.d.ts

@@ -1,23 +1,65 @@
-import { type ApiContract } from '@lokalise/api-contracts';
+import type { ApiContract } from '@lokalise/api-contracts';
+import { type ApiRouteOptions as FastifyApiRouteOptions, type InferApiHandler } from '@lokalise/fastify-api-contracts';
 import type { RouteOptions } from 'fastify';
-import type { ApiRouteOptions, InferApiHandler } from './apiHandlerTypes.ts';
+import type { GatewayMetadata } from '../gateway/gatewayTypes.ts';
+/**
+ * Options for configuring an ApiContract route.
+ *
+ * All options from `@lokalise/fastify-api-contracts` (any Fastify route field
+ * minus the ones the contract provides, SSE lifecycle hooks, and
+ * `contractMetadataToRouteMapper`) pass through to `buildFastifyApiRoute`
+ * unchanged.
+ *
+ * Generic in `Contract` so `gatewayMetadata.match.headers` / `match.query`
+ * keys are narrowed to the contract's request schemas. The generic is always
+ * inferred from the contract argument at the `buildApiRoute` call site, so
+ * direct references should write `ApiRouteOptions<typeof myContract>` when
+ * gateway metadata typing is needed.
+ */
+export type ApiRouteOptions<Contract extends ApiContract> = FastifyApiRouteOptions & {
+    /**
+     * Per-route gateway metadata. `match.headers` / `match.query` keys are
+     * narrowed to the contract's request schemas; `customHeaders` /
+     * `customQuery` remain the escape hatch for headers and params not
+     * declared on the contract. Validated at runtime against the same Zod
+     * schema used by `withGatewayMetadata` and stamped on the route via the
+     * shared `GATEWAY_METADATA_SYMBOL`.
+     *
+     * Equivalent to wrapping the result with `withGatewayMetadata` — keep
+     * to one form per route. If both are used on the same route, the later
+     * call (typically `withGatewayMetadata`) overwrites the inline value;
+     * there is no merge.
+     *
+     * @example
+     * ```ts
+     * buildApiRoute(MyController.contracts.getItem, this.getItem, {
+     *   gatewayMetadata: {
+     *     cache: { ttl: '60s' },
+     *     match: {
+     *       // narrowed to keys of the contract's requestHeaderSchema:
+     *       headers: { 'x-trace-id': { regex: '^[a-f0-9]+$' } },
+     *       // escape hatch for headers not declared on the contract:
+     *       customHeaders: { 'x-tenant-id': { regex: '^t_' } },
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    gatewayMetadata?: GatewayMetadata<Contract>;
+};
 /**
  * Build a Fastify `RouteOptions` object from an `ApiContract` + handler.
  *
- * The handler shape is inferred from the contract's response mode:
- * - `'non-sse'` — bare async function returning `{ status, body }`
- * - `'sse'`     — bare async function calling `sse.start(...)` / `sse.respond(...)`
- * - `'dual'`    — `{ nonSse, sse }` object branched by the `Accept` header
+ * Thin wrapper around `buildFastifyApiRoute` from
+ * `@lokalise/fastify-api-contracts` — the handler shape, response mode
+ * inference, SSE streaming, and validation semantics are all the package's.
+ * See its docs for the `(request, reply, context) => { status, body }`
+ * handler model and `context.sse` streaming.
  *
- * The optional `options` argument carries:
- * - any Fastify route field (`preHandler`, `onRequest`, `config`, `bodyLimit`, …)
- *   minus the ones the contract provides (`method`, `url`, `schema`, `handler`, `sse`),
- * - SSE lifecycle hooks (`onConnect`, `onClose`, `onReconnect`, `serializer`,
- *   `heartbeatInterval`) — applied for `'sse'` and `'dual'` contracts only,
- * - `defaultMode` for `'dual'` contracts when the `Accept` header is ambiguous,
- * - `gatewayMetadata` — per-route gateway policy with header / query keys
- *   narrowed to the contract; equivalent to wrapping the result with
- *   `withGatewayMetadata`. See `ApiRouteOptions` for full details.
+ * On top of the package builder this adds one option: `gatewayMetadata` —
+ * per-route gateway policy with header / query keys narrowed to the
+ * contract; equivalent to wrapping the result with `withGatewayMetadata`.
+ * See `ApiRouteOptions` for full details.
  *
  * @returns Fastify `RouteOptions` ready to pass to `app.route()`
  */

package/dist/lib/api-contracts/apiRouteBuilder.js

@@ -1,358 +1,25 @@
-import { randomUUID } from 'node:crypto';
-import { ContractNoBody, getSseSchemaByEventName, hasAnySuccessSseResponse, isContentResponseEntry, isSseBody, mapApiContractToPath, resolveContractResponse, SUCCESSFUL_HTTP_STATUS_CODES, } from '@lokalise/api-contracts';
-import { InternalError } from '@lokalise/node-core';
-import { isErrorLike } from "../errorUtils.js";
+import { buildFastifyApiRoute, } from '@lokalise/fastify-api-contracts';
 import { attachGatewayMetadata } from "../gateway/withGatewayMetadata.js";
-import { determineMode, hasHttpStatusCode } from "../routes/fastifyRouteUtils.js";
-function isSuccessResponseDual(value) {
-    if (isContentResponseEntry(value)) {
-        // A content-map entry offers a non-SSE representation when it allows an empty
-        // body or declares any non-SSE media type descriptor.
-        if (value.allowNoBody || !value.content)
-            return true;
-        return Object.values(value.content).some((descriptor) => !isSseBody(descriptor));
-    }
-    // A bare Zod schema is a JSON response, which always has a non-SSE representation.
-    return true;
-}
-function getContractResponseMode(contract) {
-    if (!hasAnySuccessSseResponse(contract))
-        return 'non-sse';
-    for (const code of SUCCESSFUL_HTTP_STATUS_CODES) {
-        const value = contract.responsesByStatusCode[code];
-        if (value && isSuccessResponseDual(value))
-            return 'dual';
-    }
-    return 'sse';
-}
-function buildSSERouteConfig(options) {
-    if (!options?.serializer && options?.heartbeatInterval === undefined)
-        return true;
-    const sseConfig = {};
-    if (options.serializer)
-        sseConfig.serializer = options.serializer;
-    if (options.heartbeatInterval !== undefined)
-        sseConfig.heartbeatInterval = options.heartbeatInterval;
-    return sseConfig;
-}
-// ============================================================================
-// Internal Helpers — Sync Route
-// ============================================================================
-function getSchemaForStatusCode(contract, status) {
-    const entry = contract.responsesByStatusCode[status];
-    if (!entry)
-        return null;
-    // Resolve the JSON representation for this status code, covering both bare Zod
-    // schemas and content-map entries. Non-JSON responses (blob, SSE, no-body) are
-    // not validated here.
-    const resolved = resolveContractResponse(entry, 'application/json', false);
-    return resolved?.kind === 'json' ? resolved.schema : null;
-}
-function validateApiResponseHeaders(contract, reply) {
-    const schema = contract.responseHeaderSchema;
-    if (!schema) {
-        return;
-    }
-    const result = schema.safeParse(reply.getHeaders());
-    if (!result.success) {
-        throw new InternalError({
-            message: 'Internal Server Error',
-            errorCode: 'RESPONSE_HEADERS_VALIDATION_FAILED',
-            details: { validationError: result.error.message },
-        });
-    }
-}
-async function handleApiSyncRoute(contract, 
-// biome-ignore lint/suspicious/noExplicitAny: Handler types are validated by InferApiHandler at the call site
-handler, 
-// biome-ignore lint/suspicious/noExplicitAny: Request types are validated by Fastify schema
-request, reply) {
-    const { status, body } = await handler(request, reply);
-    if (reply.sent) {
-        request.log.warn({
-            msg: 'Sync handler sent response directly, bypassing response validation',
-            tag: 'response_sent_directly',
-            method: request.method,
-            url: request.url,
-        });
-        return;
-    }
-    try {
-        const schema = getSchemaForStatusCode(contract, status);
-        if (schema) {
-            const result = schema.safeParse(body);
-            if (!result.success) {
-                throw new InternalError({
-                    message: 'Internal Server Error',
-                    errorCode: 'RESPONSE_VALIDATION_FAILED',
-                    details: { validationError: result.error.message },
-                });
-            }
-        }
-    }
-    catch (err) {
-        reply.code(500);
-        throw err;
-    }
-    validateApiResponseHeaders(contract, reply);
-    if (!reply.hasHeader('content-type')) {
-        reply.type('application/json');
-    }
-    return reply.code(status).send(body);
-}
-// ============================================================================
-// Internal Helpers — SSE Route (no controller, uses reply.sse directly)
-// ============================================================================
-function buildApiSSEContext(
-// biome-ignore lint/suspicious/noExplicitAny: Request types are validated by Fastify schema
-request, reply, eventSchemas, options) {
-    let started = false;
-    let responseData;
-    const sseReply = reply;
-    const sseContext = {
-        start: (mode, startOptions) => {
-            started = true;
-            if (mode === 'keepAlive') {
-                sseReply.sse.keepAlive();
-            }
-            // sendHeaders() calls writeHead(200) but only queues headers in the buffer.
-            // flushHeaders() forces them onto the wire so the client's fetch() returns.
-            sseReply.sse.sendHeaders();
-            reply.raw.flushHeaders();
-            const connectionId = randomUUID();
-            const send = async (eventName, data, sendOptions) => {
-                const schema = eventSchemas[eventName];
-                if (schema) {
-                    const result = schema.safeParse(data);
-                    if (!result.success) {
-                        throw new InternalError({
-                            message: `SSE event validation failed for event "${eventName}": ${result.error.message}`,
-                            errorCode: 'RESPONSE_VALIDATION_FAILED',
-                        });
-                    }
-                }
-                try {
-                    await sseReply.sse.send({
-                        event: eventName,
-                        data,
-                        id: sendOptions?.id,
-                        retry: sendOptions?.retry,
-                    });
-                    return true;
-                }
-                catch {
-                    return false;
-                }
-            };
-            const session = {
-                id: connectionId,
-                request,
-                reply,
-                context: (startOptions?.context ?? {}),
-                connectedAt: new Date(),
-                // biome-ignore lint/suspicious/noExplicitAny: SSEEventSender generic is satisfied at handler call site
-                send: send,
-                isConnected: () => sseReply.sse.isConnected,
-                getStream: () => sseReply.sse.stream(),
-                sendStream: async (messages) => {
-                    for await (const message of messages) {
-                        await send(message.event, message.data, { id: message.id, retry: message.retry });
-                    }
-                },
-                rooms: { join: () => { }, leave: () => { } },
-                eventSchemas,
-            };
-            if (options?.onConnect) {
-                void Promise.resolve(options.onConnect(session)).catch(() => { });
-            }
-            if (options?.onClose) {
-                const onClose = options.onClose;
-                sseReply.sse.onClose(() => {
-                    void Promise.resolve(onClose(session, 'client')).catch(() => { });
-                });
-            }
-            if (options?.onReconnect && sseReply.sse.lastEventId) {
-                const onReconnect = options.onReconnect;
-                const lastEventId = sseReply.sse.lastEventId;
-                void sseReply.sse.replay(async () => {
-                    const replay = await onReconnect(session, lastEventId);
-                    if (replay) {
-                        for await (const msg of replay) {
-                            await sseReply.sse.send(msg);
-                        }
-                    }
-                });
-            }
-            return session;
-        },
-        respond: ((code, body) => {
-            if (started) {
-                throw new Error('Cannot call sse.respond() after sse.start() — the SSE stream is already open.');
-            }
-            responseData = { code, body };
-            return { _type: 'respond', code, body };
-            // biome-ignore lint/suspicious/noExplicitAny: respond typing is enforced by contract at call site
-        }),
-        sendHeaders: () => {
-            sseReply.sse.sendHeaders();
-        },
-        reply,
-    };
-    return {
-        sseContext,
-        isStarted: () => started,
-        hasResponse: () => responseData !== undefined,
-        getResponseData: () => responseData,
-    };
-}
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Core SSE handler coordinates context, error handling, and lifecycle
-async function handleApiSseRoute(
-// biome-ignore lint/suspicious/noExplicitAny: SSE handler types are validated by InferApiHandler at call site
-sseHandler, eventSchemas, options, 
-// biome-ignore lint/suspicious/noExplicitAny: Request types are validated by Fastify schema
-request, reply) {
-    const { sseContext, isStarted, hasResponse, getResponseData } = buildApiSSEContext(request, reply, eventSchemas, options);
-    try {
-        await sseHandler(request, sseContext);
-        if (!isStarted() && !hasResponse()) {
-            throw new Error('SSE handler must either send a response (sse.respond()) ' +
-                'or start streaming (sse.start()). Handler returned without doing either.');
-        }
-        const responseData = getResponseData();
-        if (responseData) {
-            // Early HTTP response (sse.respond() was called before streaming)
-            reply.removeHeader('cache-control');
-            reply.removeHeader('x-accel-buffering');
-            reply.type('application/json').code(responseData.code).send(responseData.body);
-        }
-        // If started, @fastify/sse manages the rest of the connection lifecycle
-    }
-    catch (err) {
-        if (isStarted()) {
-            // Headers already sent — can't change status code; try to send error event
-            const sseReply = reply;
-            if (sseReply.sse.isConnected) {
-                try {
-                    await sseReply.sse.send({
-                        event: 'error',
-                        data: { message: isErrorLike(err) ? err.message : 'Internal Server Error' },
-                    });
-                }
-                catch {
-                    // Ignore send failures during error handling
-                }
-            }
-            throw err;
-        }
-        // Streaming not started — send HTTP error response
-        const message = isErrorLike(err) ? err.message : 'Internal Server Error';
-        const statusCode = hasHttpStatusCode(err) ? err.httpStatusCode : 500;
-        const statusText = statusCode >= 500 ? 'Internal Server Error' : 'Error';
-        reply.code(statusCode).type('application/json').send({ statusCode, error: statusText, message });
-    }
-}
-// ============================================================================
-// Internal Helpers — Schema
-// ============================================================================
-function buildResponseSchemas(contract) {
-    return Object.keys(contract.responsesByStatusCode).reduce((acc, statusCode) => {
-        const schema = getSchemaForStatusCode(contract, Number(statusCode));
-        if (schema) {
-            acc[Number(statusCode)] = schema;
-        }
-        return acc;
-    }, {});
-}
-function buildBaseSchema(contract) {
-    const schema = {};
-    if (contract.requestPathParamsSchema)
-        schema.params = contract.requestPathParamsSchema;
-    if (contract.requestQuerySchema)
-        schema.querystring = contract.requestQuerySchema;
-    if (contract.requestHeaderSchema)
-        schema.headers = contract.requestHeaderSchema;
-    if (contract.requestBodySchema !== undefined && contract.requestBodySchema !== ContractNoBody) {
-        schema.body = contract.requestBodySchema;
-    }
-    schema.response = buildResponseSchemas(contract);
-    return schema;
-}
-// ============================================================================
-// Public API
-// ============================================================================
 /**
  * Build a Fastify `RouteOptions` object from an `ApiContract` + handler.
  *
- * The handler shape is inferred from the contract's response mode:
- * - `'non-sse'` — bare async function returning `{ status, body }`
- * - `'sse'`     — bare async function calling `sse.start(...)` / `sse.respond(...)`
- * - `'dual'`    — `{ nonSse, sse }` object branched by the `Accept` header
+ * Thin wrapper around `buildFastifyApiRoute` from
+ * `@lokalise/fastify-api-contracts` — the handler shape, response mode
+ * inference, SSE streaming, and validation semantics are all the package's.
+ * See its docs for the `(request, reply, context) => { status, body }`
+ * handler model and `context.sse` streaming.
  *
- * The optional `options` argument carries:
- * - any Fastify route field (`preHandler`, `onRequest`, `config`, `bodyLimit`, …)
- *   minus the ones the contract provides (`method`, `url`, `schema`, `handler`, `sse`),
- * - SSE lifecycle hooks (`onConnect`, `onClose`, `onReconnect`, `serializer`,
- *   `heartbeatInterval`) — applied for `'sse'` and `'dual'` contracts only,
- * - `defaultMode` for `'dual'` contracts when the `Accept` header is ambiguous,
- * - `gatewayMetadata` — per-route gateway policy with header / query keys
- *   narrowed to the contract; equivalent to wrapping the result with
- *   `withGatewayMetadata`. See `ApiRouteOptions` for full details.
+ * On top of the package builder this adds one option: `gatewayMetadata` —
+ * per-route gateway policy with header / query keys narrowed to the
+ * contract; equivalent to wrapping the result with `withGatewayMetadata`.
+ * See `ApiRouteOptions` for full details.
  *
  * @returns Fastify `RouteOptions` ready to pass to `app.route()`
  */
 export function buildApiRoute(contract, handler, options) {
-    // Separate SSE-specific options (not in Fastify RouteOptions) and gateway
-    // metadata (stamped via Symbol, not spread) from passthrough options.
-    const { defaultMode, contractMetadataToRouteMapper, gatewayMetadata, serializer: _serializer, heartbeatInterval: _heartbeatInterval, onConnect: _onConnect, onClose: _onClose, onReconnect: _onReconnect, logger: _logger, ...fastifyOptions } = options ?? {};
-    const url = mapApiContractToPath(contract);
-    const mode = getContractResponseMode(contract);
-    const eventSchemas = getSseSchemaByEventName(contract) ?? {};
-    const baseSchema = buildBaseSchema(contract);
-    const contractMetadata = contractMetadataToRouteMapper?.(contract.metadata) ?? {};
-    const finalize = (route) => gatewayMetadata !== undefined ? attachGatewayMetadata(route, gatewayMetadata) : route;
-    if (mode === 'non-sse') {
-        // biome-ignore lint/suspicious/noExplicitAny: handler shape validated by InferApiHandler at call site
-        const syncHandler = handler;
-        return finalize({
-            ...fastifyOptions,
-            ...contractMetadata,
-            method: contract.method,
-            url,
-            schema: baseSchema,
-            handler: async (request, reply) => handleApiSyncRoute(contract, syncHandler, request, reply),
-        });
-    }
-    if (mode === 'dual') {
-        const resolvedDefaultMode = defaultMode ?? 'json';
-        // biome-ignore lint/suspicious/noExplicitAny: handler shape validated by InferApiHandler at call site
-        const dualHandlers = handler;
-        return finalize({
-            ...fastifyOptions,
-            ...contractMetadata,
-            method: contract.method,
-            url,
-            sse: buildSSERouteConfig(options),
-            schema: baseSchema,
-            handler: (request, reply) => {
-                const responseMode = determineMode(request.headers.accept, resolvedDefaultMode);
-                if (responseMode === 'json') {
-                    return handleApiSyncRoute(contract, dualHandlers.nonSse, request, reply);
-                }
-                return handleApiSseRoute(dualHandlers.sse, eventSchemas, options, request, reply);
-            },
-        });
-    }
-    // SSE-only
-    // biome-ignore lint/suspicious/noExplicitAny: handler shape validated by InferApiHandler at call site
-    const sseHandler = handler;
-    return finalize({
-        ...fastifyOptions,
-        ...contractMetadata,
-        method: contract.method,
-        url,
-        sse: buildSSERouteConfig(options),
-        schema: baseSchema,
-        handler: async (request, reply) => handleApiSseRoute(sseHandler, eventSchemas, options, request, reply),
-    });
+    // Gateway metadata is stamped via Symbol, not spread into Fastify options.
+    const { gatewayMetadata, ...fastifyOptions } = options ?? {};
+    const route = buildFastifyApiRoute(contract, handler, fastifyOptions);
+    return gatewayMetadata !== undefined ? attachGatewayMetadata(route, gatewayMetadata) : route;
 }
 //# sourceMappingURL=apiRouteBuilder.js.map