opinionated-machine 6.2.1 → 6.4.0

package/README.md

@@ -30,7 +30,7 @@ Very opinionated DI framework for fastify, built on top of awilix
   - [Prerequisites](#prerequisites)
   - [Defining SSE Contracts](#defining-sse-contracts)
   - [Creating SSE Controllers](#creating-sse-controllers)
-  - [Type-Safe SSE Handlers with buildSSEHandler](#type-safe-sse-handlers-with-buildssehandler)
+  - [Type-Safe SSE Handlers with buildHandler](#type-safe-sse-handlers-with-buildhandler)
   - [SSE Controllers Without Dependencies](#sse-controllers-without-dependencies)
   - [Registering SSE Controllers](#registering-sse-controllers)
   - [Registering SSE Routes](#registering-sse-routes)
@@ -398,14 +398,14 @@ await app.register(FastifySSEPlugin)
 
 ### Defining SSE Contracts
 
-Use `buildSSEContract` for GET-based SSE streams or `buildPayloadSSEContract` for POST/PUT/PATCH streams. Paths are defined using `pathResolver`, a type-safe function that receives typed params and returns the URL path:
+Use `buildContract` to define SSE routes. The contract type is automatically determined based on the presence of `requestBody` and `jsonResponse` fields. Paths are defined using `pathResolver`, a type-safe function that receives typed params and returns the URL path:
 
 ```ts
 import { z } from 'zod'
-import { buildSSEContract, buildPayloadSSEContract } from 'opinionated-machine'
+import { buildContract } from 'opinionated-machine'
 
-// GET-based SSE stream with path params
-export const channelStreamContract = buildSSEContract({
+// GET-based SSE stream with path params (no body = GET)
+export const channelStreamContract = buildContract({
   pathResolver: (params) => `/api/channels/${params.channelId}/stream`,
   params: z.object({ channelId: z.string() }),
   query: z.object({}),
@@ -416,7 +416,7 @@ export const channelStreamContract = buildSSEContract({
 })
 
 // GET-based SSE stream without path params
-export const notificationsContract = buildSSEContract({
+export const notificationsContract = buildContract({
   pathResolver: () => '/api/notifications/stream',
   params: z.object({}),
   query: z.object({ userId: z.string().optional() }),
@@ -429,14 +429,14 @@ export const notificationsContract = buildSSEContract({
   },
 })
 
-// POST-based SSE stream (e.g., AI chat completions)
-export const chatCompletionContract = buildPayloadSSEContract({
+// POST-based SSE stream (e.g., AI chat completions) - has requestBody = POST/PUT/PATCH
+export const chatCompletionContract = buildContract({
   method: 'POST',
   pathResolver: () => '/api/chat/completions',
   params: z.object({}),
   query: z.object({}),
   requestHeaders: z.object({}),
-  body: z.object({
+  requestBody: z.object({
     message: z.string(),
     stream: z.literal(true),
   }),
@@ -463,12 +463,13 @@ const streamingEvents = {
 
 ### Creating SSE Controllers
 
-SSE controllers extend `AbstractSSEController` and must implement a two-parameter constructor. Use `buildSSEHandler` for automatic type inference of request parameters:
+SSE controllers extend `AbstractSSEController` and must implement a two-parameter constructor. Use `buildHandler` for automatic type inference of request parameters:
 
 ```ts
 import {
   AbstractSSEController,
-  buildSSEHandler,
+  buildHandler,
+  success,
   type SSEControllerConfig,
   type SSEConnection
 } from 'opinionated-machine'
@@ -498,10 +499,10 @@ export class NotificationsSSEController extends AbstractSSEController<Contracts>
     return {
       notificationsStream: {
         contract: NotificationsSSEController.contracts.notificationsStream,
-        handler: this.handleStream,
+        handlers: this.handleStream,
         options: {
           onConnect: (conn) => this.onConnect(conn),
-          onDisconnect: (conn) => this.onDisconnect(conn),
+          onClose: (conn, reason) => this.onClose(conn, reason),
         },
       },
     }
@@ -509,9 +510,8 @@ export class NotificationsSSEController extends AbstractSSEController<Contracts>
 
   // Handler with automatic type inference from contract
   // connection.send provides type-safe event sending
-  private handleStream = buildSSEHandler(
-    notificationsContract,
-    async (request, connection) => {
+  private handleStream = buildHandler(notificationsContract, {
+    sse: async (request, connection) => {
       // request.query is typed from contract: { userId?: string }
       const userId = request.query.userId ?? 'anonymous'
       connection.context = { userId }
@@ -531,29 +531,32 @@ export class NotificationsSSEController extends AbstractSSEController<Contracts>
       // For direct sending within the handler, use the connection's send method.
       // It provides stricter per-route typing (only events from this specific contract).
       await connection.send('notification', { id: 'welcome', message: 'Connected!' })
+
+      // Keep connection open for subscription events (client closes when done)
+      return success('maintain_connection')
     },
-  )
+  })
 
   private onConnect = (connection: SSEConnection) => {
     console.log('Client connected:', connection.id)
   }
 
-  private onDisconnect = (connection: SSEConnection) => {
+  private onClose = (connection: SSEConnection, reason: SSECloseReason) => {
     const userId = connection.context?.userId as string
     this.notificationService.unsubscribe(userId)
-    console.log('Client disconnected:', connection.id)
+    console.log(`Client disconnected (${reason}):`, connection.id)
   }
 }
 ```
 
-### Type-Safe SSE Handlers with `buildSSEHandler`
+### Type-Safe SSE Handlers with `buildHandler`
 
-For automatic type inference of request parameters (similar to `buildFastifyPayloadRoute` for regular controllers), use `buildSSEHandler`:
+For automatic type inference of request parameters (similar to `buildFastifyPayloadRoute` for regular controllers), use `buildHandler`:
 
 ```ts
 import {
   AbstractSSEController,
-  buildSSEHandler,
+  buildHandler,
   type SSEControllerConfig,
   type SSEConnection
 } from 'opinionated-machine'
@@ -569,9 +572,8 @@ class ChatSSEController extends AbstractSSEController<Contracts> {
 
   // Handler with automatic type inference from contract
   // connection.send is fully typed per-route
-  private handleChatCompletion = buildSSEHandler(
-    chatCompletionContract,
-    async (request, connection) => {
+  private handleChatCompletion = buildHandler(chatCompletionContract, {
+    sse: async (request, connection) => {
       // request.body is typed as { message: string; stream: true }
       // request.query, request.params, request.headers all typed from contract
       const words = request.body.message.split(' ')
@@ -582,15 +584,15 @@ class ChatSSEController extends AbstractSSEController<Contracts> {
       }
 
       // Gracefully end the stream - all sent data is flushed before connection closes
-      this.closeConnection(connection.id)
+      return success('disconnect')
     },
-  )
+  })
 
   public buildSSERoutes() {
     return {
       chatCompletion: {
         contract: ChatSSEController.contracts.chatCompletion,
-        handler: this.handleChatCompletion,
+        handlers: this.handleChatCompletion,
       },
     }
   }
@@ -725,7 +727,7 @@ public buildSSERoutes() {
   return {
     adminStream: {
       contract: AdminSSEController.contracts.adminStream,
-      handler: this.handleAdminStream,
+      handlers: this.handleAdminStream,
       options: {
         // Route-specific authentication
         preHandler: (request, reply) => {
@@ -734,7 +736,7 @@ public buildSSERoutes() {
           }
         },
         onConnect: (conn) => console.log('Admin connected'),
-        onDisconnect: (conn) => console.log('Admin disconnected'),
+        onClose: (conn, reason) => console.log(`Admin disconnected (${reason})`),
         // Handle client reconnection with Last-Event-ID
         onReconnect: async (conn, lastEventId) => {
           // Return events to replay, or handle manually
@@ -751,12 +753,64 @@ public buildSSERoutes() {
 **Available route options:**
 
 | Option | Description |
-|--------|-------------|
+| -------- | ------------- |
 | `preHandler` | Authentication/authorization hook that runs before SSE connection |
 | `onConnect` | Called after client connects (SSE handshake complete) |
-| `onDisconnect` | Called when client disconnects |
+| `onClose` | Called when connection closes (client disconnect, network failure, or server close). Receives `(connection, reason)` where reason is `'server'` or `'client'` |
 | `onReconnect` | Handle Last-Event-ID reconnection, return events to replay |
 | `logger` | Optional `SSELogger` for error handling (compatible with pino and `@lokalise/node-core`). If not provided, errors in lifecycle hooks are silently ignored |
+| `serializer` | Custom serializer for SSE data (e.g., for custom JSON encoding) |
+| `heartbeatInterval` | Interval in ms for heartbeat keep-alive messages |
+
+**onClose reason parameter:**
+- `'server'`: Server explicitly closed the connection (via `closeConnection()` or `success('disconnect')`)
+- `'client'`: Client closed the connection (EventSource.close(), navigation, network failure)
+
+```ts
+options: {
+  onConnect: (conn) => console.log('Client connected'),
+  onClose: (conn, reason) => {
+    console.log(`Connection closed (${reason}):`, conn.id)
+    // reason is 'server' or 'client'
+  },
+  serializer: (data) => JSON.stringify(data, null, 2), // Pretty-print JSON
+  heartbeatInterval: 30000, // Send heartbeat every 30 seconds
+}
+```
+
+### SSE Connection Methods
+
+The `connection` object in SSE handlers provides several useful methods:
+
+```ts
+private handleStream = buildHandler(streamContract, {
+  sse: async (request, connection) => {
+    // Check if connection is still active
+    if (connection.isConnected()) {
+      await connection.send('status', { connected: true })
+    }
+
+    // Get raw writable stream for advanced use cases (e.g., pipeline)
+    const stream = connection.getStream()
+
+    // Stream messages from an async iterable with automatic validation
+    async function* generateMessages() {
+      yield { event: 'message' as const, data: { text: 'Hello' } }
+      yield { event: 'message' as const, data: { text: 'World' } }
+    }
+    await connection.sendStream(generateMessages())
+
+    return success('disconnect')
+  },
+})
+```
+
+| Method | Description |
+| -------- | ------------- |
+| `send(event, data, options?)` | Send a typed event (validates against contract schema) |
+| `isConnected()` | Check if the connection is still active |
+| `getStream()` | Get the underlying `WritableStream` for advanced use cases |
+| `sendStream(messages)` | Stream messages from an `AsyncIterable` with validation |
 
 ### Graceful Shutdown
 
@@ -777,7 +831,7 @@ if (!sent) {
 }
 ```
 
-**Lifecycle hook errors** (`onConnect`, `onReconnect`, `onDisconnect`):
+**Lifecycle hook errors** (`onConnect`, `onReconnect`, `onClose`):
 - All lifecycle hooks are wrapped in try/catch to prevent crashes
 - If a `logger` is provided in route options, errors are logged with context
 - If no logger is provided, errors are silently ignored
@@ -789,11 +843,11 @@ public buildSSERoutes() {
   return {
     stream: {
       contract: streamContract,
-      handler: this.handleStream,
+      handlers: this.handleStream,
       options: {
         logger: this.logger, // pino-compatible logger
         onConnect: (conn) => { /* may throw */ },
-        onDisconnect: (conn) => { /* may throw */ },
+        onClose: (conn, reason) => { /* may throw */ },
       },
     },
   }
@@ -802,43 +856,87 @@ public buildSSERoutes() {
 
 ### Long-lived Connections vs Request-Response Streaming
 
+SSE handlers must return an `Either<Error, SSEHandlerResult>` to explicitly indicate connection management.
+
+The `Either` type along with the `success` and `failure` helper functions are re-exported from `@lokalise/node-core` for convenience, so you don't need to add `@lokalise/node-core` as a direct dependency:
+
+```ts
+import { type Either, success, failure } from 'opinionated-machine'
+
+// Return success('disconnect') - close connection after handler completes
+// Return success('maintain_connection') - keep connection open for external events
+// Return failure(error) - handle error and close connection
+```
+
 **Long-lived connections** (notifications, live updates):
-- Handler sets up subscriptions and returns
-- Connection stays open until client disconnects
-- Use `sendEventInternal()` for external triggers (typed with union of all contract events)
+- Handler sets up subscriptions and returns `success('maintain_connection')`
+- Connection stays open indefinitely after handler returns
+- Events are sent later via callbacks using `sendEventInternal()`
+- **Client closes connection** when done (e.g., `eventSource.close()` or navigating away)
+- Server cleans up via `onConnectionClosed()` hook
 
 ```ts
-private handleStream = buildSSEHandler(streamContract, async (request, connection) => {
-  // External callbacks (subscriptions, timers) can't access `connection` - it's only in this scope.
-  // Use sendEventInternal instead - it's a controller method accessible from any callback.
-  this.service.subscribe(connection.id, (data) => {
-    this.sendEventInternal(connection.id, { event: 'update', data })
-  })
-  // Handler returns, connection stays open
+import { success } from 'opinionated-machine'
+
+private handleStream = buildHandler(streamContract, {
+  sse: async (request, connection) => {
+    // Set up subscription - events sent via callback AFTER handler returns
+    this.service.subscribe(connection.id, (data) => {
+      this.sendEventInternal(connection.id, { event: 'update', data })
+    })
+    // Keep connection open until CLIENT disconnects
+    return success('maintain_connection')
+  },
 })
+
+// Clean up when client disconnects
+protected onConnectionClosed(connection: SSEConnection): void {
+  this.service.unsubscribe(connection.id)
+}
 ```
 
 **Request-response streaming** (AI completions):
-- Handler sends all events and closes connection
-- Use `connection.send` for type-safe event sending
+- Handler sends all events synchronously, then returns `success('disconnect')`
+- Use `connection.send()` for type-safe event sending within the handler
+- Connection automatically closes when handler returns with `'disconnect'`
 
 ```ts
-private handleChatCompletion = buildSSEHandler(chatCompletionContract, async (request, connection) => {
-  // request.body is typed from contract
-  const words = request.body.message.split(' ')
+import { success } from 'opinionated-machine'
 
-  for (const word of words) {
-    // connection.send() provides compile-time type checking for event names and data
-    await connection.send('chunk', { content: word })
-  }
+private handleChatCompletion = buildHandler(chatCompletionContract, {
+  sse: async (request, connection) => {
+    const words = request.body.message.split(' ')
 
-  await connection.send('done', { totalTokens: words.length })
+    for (const word of words) {
+      await connection.send('chunk', { content: word })
+    }
+    await connection.send('done', { totalTokens: words.length })
 
-  // Gracefully end the stream - all sent data is flushed before connection closes
-  this.closeConnection(connection.id)
+    // Signal that streaming is complete and connection should close
+    return success('disconnect')
+  },
 })
 ```
 
+**Error handling:**
+
+Return `failure(error)` to signal an error occurred. The framework will send an error event and close the connection:
+
+```ts
+import { success, failure } from 'opinionated-machine'
+
+private handleStream = buildHandler(streamContract, {
+  sse: async (request, connection) => {
+    try {
+      const data = await this.service.getData(request.params.id)
+      await connection.send('data', data)
+      return success('disconnect')
+    } catch (err) {
+      return failure(err instanceof Error ? err : new Error(String(err)))
+    }
+  },
+})
+
 ### SSE Parsing Utilities
 
 The library provides production-ready utilities for parsing SSE (Server-Sent Events) streams:
@@ -1096,7 +1194,7 @@ import { SSETestServer, SSEHttpClient } from 'opinionated-machine'
 const server = await SSETestServer.create(async (app) => {
   app.get('/api/events', async (request, reply) => {
     reply.sse({ event: 'message', data: { hello: 'world' } })
-    reply.sseClose()
+    reply.sse.close()
   })
 })
 
@@ -1308,14 +1406,22 @@ Dual-mode controllers extend `AbstractDualModeController` which inherits from `A
 
 ### Defining Dual-Mode Contracts
 
-Use `buildDualModeContract` for GET routes or `buildPayloadDualModeContract` for POST/PUT/PATCH routes. The key difference from SSE contracts is the addition of `jsonResponse` schema:
+Dual-mode contracts define endpoints that can return **either** a complete JSON response **or** stream SSE events, based on the client's `Accept` header. Use dual-mode when:
+
+- Clients may want immediate results (JSON) or real-time updates (SSE)
+- You're building OpenAI-style APIs where `stream: true` triggers SSE
+- You need polling fallback for clients that don't support SSE
+
+To create a dual-mode contract, include a `jsonResponse` schema in your `buildContract` call:
+- Has `jsonResponse` but no `requestBody` → GET dual-mode route
+- Has both `jsonResponse` and `requestBody` → POST/PUT/PATCH dual-mode route
 
 ```ts
 import { z } from 'zod'
-import { buildDualModeContract, buildPayloadDualModeContract } from 'opinionated-machine'
+import { buildContract } from 'opinionated-machine'
 
-// GET dual-mode route (polling or streaming job status)
-export const jobStatusContract = buildDualModeContract({
+// GET dual-mode route (polling or streaming job status) - has jsonResponse, no requestBody
+export const jobStatusContract = buildContract({
   pathResolver: (params) => `/api/jobs/${params.jobId}/status`,
   params: z.object({ jobId: z.string().uuid() }),
   query: z.object({ verbose: z.string().optional() }),
@@ -1331,14 +1437,14 @@ export const jobStatusContract = buildDualModeContract({
   },
 })
 
-// POST dual-mode route (OpenAI-style chat completion)
-export const chatCompletionContract = buildPayloadDualModeContract({
+// POST dual-mode route (OpenAI-style chat completion) - has both jsonResponse and requestBody
+export const chatCompletionContract = buildContract({
   method: 'POST',
   pathResolver: (params) => `/api/chats/${params.chatId}/completions`,
   params: z.object({ chatId: z.string().uuid() }),
   query: z.object({}),
   requestHeaders: z.object({ authorization: z.string() }),
-  body: z.object({ message: z.string() }),
+  requestBody: z.object({ message: z.string() }),
   jsonResponse: z.object({
     reply: z.string(),
     usage: z.object({ tokens: z.number() }),
@@ -1352,14 +1458,122 @@ export const chatCompletionContract = buildPayloadDualModeContract({
 
 **Note**: Dual-mode contracts use `pathResolver` instead of static `path` for type-safe path construction. The `pathResolver` function receives typed params and returns the URL path.
 
+### Response Headers (JSON Mode)
+
+Dual-mode contracts support an optional `responseHeaders` schema to define and validate headers sent with JSON responses. This is useful for documenting expected headers (rate limits, pagination, cache control) and validating that your handlers set them correctly:
+
+```ts
+export const rateLimitedContract = buildContract({
+  method: 'POST',
+  pathResolver: () => '/api/rate-limited',
+  params: z.object({}),
+  query: z.object({}),
+  requestHeaders: z.object({}),
+  requestBody: z.object({ data: z.string() }),
+  jsonResponse: z.object({ result: z.string() }),
+  // Define expected response headers
+  responseHeaders: z.object({
+    'x-ratelimit-limit': z.string(),
+    'x-ratelimit-remaining': z.string(),
+    'x-ratelimit-reset': z.string(),
+  }),
+  events: {
+    result: z.object({ success: z.boolean() }),
+  },
+})
+```
+
+In your handler, set headers using `reply.header()`:
+
+```ts
+handlers: {
+  json: async (request, reply) => {
+    reply.header('x-ratelimit-limit', '100')
+    reply.header('x-ratelimit-remaining', '99')
+    reply.header('x-ratelimit-reset', '1640000000')
+    return { result: 'success' }
+  },
+  sse: async (request, connection) => { /* ... */ },
+}
+```
+
+If the handler doesn't set the required headers, validation will fail with a `RESPONSE_HEADERS_VALIDATION_FAILED` error.
+
+### Multi-Format Responses (Verbose Mode)
+
+For endpoints that need to return multiple response formats (JSON, plain text, CSV, etc.), use `multiFormatResponses` instead of `jsonResponse`. This enables content negotiation based on the `Accept` header:
+
+```ts
+import { z } from 'zod'
+import { buildContract } from 'opinionated-machine'
+
+// Multi-format export endpoint
+export const exportContract = buildContract({
+  method: 'POST',
+  pathResolver: () => '/api/export',
+  params: z.object({}),
+  query: z.object({}),
+  requestHeaders: z.object({}),
+  requestBody: z.object({
+    data: z.array(z.object({ name: z.string(), value: z.number() })),
+  }),
+  // Define multiple response formats
+  multiFormatResponses: {
+    'application/json': z.object({
+      items: z.array(z.object({ name: z.string(), value: z.number() })),
+      count: z.number(),
+    }),
+    'text/plain': z.string(),
+    'text/csv': z.string(),
+  },
+  events: {
+    progress: z.object({ percent: z.number() }),
+    done: z.object({ format: z.string() }),
+  },
+})
+```
+
+The handler structure changes to `sync` with per-format handlers:
+
+```ts
+handlers: buildHandler(exportContract, {
+  sync: {
+    'application/json': (request) => ({
+      items: request.body.data,
+      count: request.body.data.length,
+    }),
+    'text/plain': (request) =>
+      request.body.data.map((item) => `${item.name}: ${item.value}`).join('\n'),
+    'text/csv': (request) =>
+      `name,value\n${request.body.data.map((item) => `${item.name},${item.value}`).join('\n')}`,
+  },
+  sse: async (request, connection) => {
+    // SSE streaming handler
+    await connection.send('done', { totalItems: request.body.data.length })
+    return success('disconnect')
+  },
+})
+```
+
+**Contract styles comparison:**
+
+| Style | Contract Field | Handler Key | Use Case |
+|-------|---------------|-------------|----------|
+| Simplified | `jsonResponse` | `json` | Single JSON format (recommended) |
+| Verbose | `multiFormatResponses` | `sync` | Multiple formats (JSON, text, CSV, etc.) |
+
+TypeScript enforces the correct handler structure based on your contract:
+- `jsonResponse` contracts must use `json` handler
+- `multiFormatResponses` contracts must use `sync` handlers for all declared formats
+
 ### Implementing Dual-Mode Controllers
 
-Dual-mode controllers use `buildDualModeHandler` to define both JSON and SSE handlers:
+Dual-mode controllers use `buildHandler` to define both JSON and SSE handlers:
 
 ```ts
 import {
   AbstractDualModeController,
-  buildDualModeHandler,
+  buildHandler,
   type BuildFastifyDualModeRoutesReturnType,
   type DualModeControllerConfig,
 } from 'opinionated-machine'
@@ -1388,24 +1602,24 @@ export class ChatDualModeController extends AbstractDualModeController<Contracts
     return {
       chatCompletion: {
         contract: ChatDualModeController.contracts.chatCompletion,
-        handlers: buildDualModeHandler(chatCompletionContract, {
+        handlers: buildHandler(chatCompletionContract, {
           // JSON mode - return complete response
-          json: async (ctx) => {
-            const result = await this.aiService.complete(ctx.request.body.message)
+          json: async (request, _reply) => {
+            const result = await this.aiService.complete(request.body.message)
             return {
               reply: result.text,
               usage: { tokens: result.tokenCount },
             }
           },
           // SSE mode - stream response chunks
-          sse: async (ctx) => {
+          sse: async (request, connection) => {
             let totalTokens = 0
-            for await (const chunk of this.aiService.stream(ctx.request.body.message)) {
-              await ctx.connection.send('chunk', { delta: chunk.text })
+            for await (const chunk of this.aiService.stream(request.body.message)) {
+              await connection.send('chunk', { delta: chunk.text })
               totalTokens += chunk.tokenCount ?? 0
             }
-            await ctx.connection.send('done', { usage: { total: totalTokens } })
-            this.closeConnection(ctx.connection.id)
+            await connection.send('done', { usage: { total: totalTokens } })
+            return success('disconnect')
           },
         }),
         options: {
@@ -1419,7 +1633,7 @@ export class ChatDualModeController extends AbstractDualModeController<Contracts
           },
           // Optional: SSE lifecycle hooks
           onConnect: (conn) => console.log('Client connected:', conn.id),
-          onDisconnect: (conn) => console.log('Client disconnected:', conn.id),
+          onClose: (conn, reason) => console.log(`Client disconnected (${reason}):`, conn.id),
         },
       },
     }
@@ -1427,14 +1641,14 @@ export class ChatDualModeController extends AbstractDualModeController<Contracts
 }
 ```
 
-**Handler Context:**
+**Handler Signatures:**
 
-| Mode | Context Properties |
-| ---- | ------------------ |
-| `json` | `ctx.mode`, `ctx.request`, `ctx.reply` |
-| `sse` | `ctx.mode`, `ctx.connection`, `ctx.request` |
+| Mode | Signature |
+| ---- | --------- |
+| `json` | `(request, reply) => Response` |
+| `sse` | `(request, connection) => Either<Error, SSEHandlerResult>` |
 
-The `json` handler must return a value matching `jsonResponse` schema. The `sse` handler uses `ctx.connection.send()` for type-safe event streaming.
+The `json` handler must return a value matching `jsonResponse` schema. The `sse` handler uses `connection.send()` for type-safe event streaming.
 
 ### Registering Dual-Mode Controllers
 
@@ -1517,6 +1731,21 @@ curl -H "Accept: text/event-stream;q=0.5, application/json;q=1.0" ...
 curl -H "Accept: application/json;q=0.5, text/event-stream;q=1.0" ...
 ```
 
+**Subtype wildcards** are supported for flexible content negotiation:
+
+```bash
+# Accept any text format (matches text/plain, text/csv, etc.)
+curl -H "Accept: text/*" ...
+
+# Accept any application format (matches application/json, application/xml, etc.)
+curl -H "Accept: application/*" ...
+
+# Combine with quality values
+curl -H "Accept: text/event-stream;q=0.9, application/*;q=0.5" ...
+```
+
+The matching priority is: `text/event-stream` (SSE) > exact matches > subtype wildcards > `*/*` > fallback.
+
 ### Testing Dual-Mode Controllers
 
 Test both JSON and SSE modes:

package/dist/index.d.ts

@@ -2,9 +2,11 @@ export { AbstractController, type BuildRoutesReturnType } from './lib/AbstractCo
 export { AbstractModule, type MandatoryNameAndRegistrationPair, type UnionToIntersection, } from './lib/AbstractModule.js';
 export { AbstractTestContextFactory, type CreateTestContextParams, } from './lib/AbstractTestContextFactory.js';
 export type { NestedPartial } from './lib/configUtils.js';
+export * from './lib/contracts/index.js';
 export { type DependencyInjectionOptions, DIContext, type RegisterDependenciesParams, } from './lib/DIContext.js';
 export { ENABLE_ALL, isAnyMessageQueueConsumerEnabled, isEnqueuedJobWorkersEnabled, isJobQueueEnabled, isMessageQueueConsumerEnabled, isPeriodicJobEnabled, resolveJobQueuesEnabled, } from './lib/diConfigUtils.js';
 export * from './lib/dualmode/index.js';
 export * from './lib/resolverFunctions.js';
+export * from './lib/routes/index.js';
 export * from './lib/sse/index.js';
 export * from './lib/testing/index.js';

package/dist/index.js

@@ -1,11 +1,15 @@
 export { AbstractController } from './lib/AbstractController.js';
 export { AbstractModule, } from './lib/AbstractModule.js';
 export { AbstractTestContextFactory, } from './lib/AbstractTestContextFactory.js';
+// Contracts (unified builder)
+export * from './lib/contracts/index.js';
 export { DIContext, } from './lib/DIContext.js';
 export { ENABLE_ALL, isAnyMessageQueueConsumerEnabled, isEnqueuedJobWorkersEnabled, isJobQueueEnabled, isMessageQueueConsumerEnabled, isPeriodicJobEnabled, resolveJobQueuesEnabled, } from './lib/diConfigUtils.js';
 // Dual-mode (SSE + JSON)
 export * from './lib/dualmode/index.js';
 export * from './lib/resolverFunctions.js';
+// Routes (unified route builder)
+export * from './lib/routes/index.js';
 // SSE
 export * from './lib/sse/index.js';
 // SSE testing utilities