opinionated-machine 6.3.0 → 6.4.0

package/README.md

@@ -398,7 +398,7 @@ await app.register(FastifySSEPlugin)
 
 ### Defining SSE Contracts
 
-Use `buildContract` to define SSE routes. The contract type is automatically determined based on the presence of `body` and `syncResponse` fields. 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'
@@ -429,14 +429,14 @@ export const notificationsContract = buildContract({
   },
 })
 
-// POST-based SSE stream (e.g., AI chat completions) - has body = POST/PUT/PATCH
+// 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),
   }),
@@ -502,7 +502,7 @@ export class NotificationsSSEController extends AbstractSSEController<Contracts>
         handlers: this.handleStream,
         options: {
           onConnect: (conn) => this.onConnect(conn),
-          onDisconnect: (conn) => this.onDisconnect(conn),
+          onClose: (conn, reason) => this.onClose(conn, reason),
         },
       },
     }
@@ -541,10 +541,10 @@ export class NotificationsSSEController extends AbstractSSEController<Contracts>
     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)
   }
 }
 ```
@@ -736,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
@@ -753,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
 
@@ -779,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
@@ -795,7 +847,7 @@ public buildSSERoutes() {
       options: {
         logger: this.logger, // pino-compatible logger
         onConnect: (conn) => { /* may throw */ },
-        onDisconnect: (conn) => { /* may throw */ },
+        onClose: (conn, reason) => { /* may throw */ },
       },
     },
   }
@@ -1142,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()
   })
 })
 
@@ -1360,21 +1412,21 @@ Dual-mode contracts define endpoints that can return **either** a complete JSON
 - 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 `syncResponse` schema in your `buildContract` call:
-- Has `syncResponse` but no `body` → GET dual-mode route
-- Has both `syncResponse` and `body` → POST/PUT/PATCH dual-mode route
+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 { buildContract } from 'opinionated-machine'
 
-// GET dual-mode route (polling or streaming job status) - has syncResponse, no body
+// 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() }),
   requestHeaders: z.object({}),
-  syncResponse: z.object({
+  jsonResponse: z.object({
     status: z.enum(['pending', 'running', 'completed', 'failed']),
     progress: z.number(),
     result: z.string().optional(),
@@ -1385,15 +1437,15 @@ export const jobStatusContract = buildContract({
   },
 })
 
-// POST dual-mode route (OpenAI-style chat completion) - has both syncResponse and body
+// 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() }),
-  syncResponse: z.object({
+  requestBody: z.object({ message: z.string() }),
+  jsonResponse: z.object({
     reply: z.string(),
     usage: z.object({ tokens: z.number() }),
   }),
@@ -1417,8 +1469,8 @@ export const rateLimitedContract = buildContract({
   params: z.object({}),
   query: z.object({}),
   requestHeaders: z.object({}),
-  body: z.object({ data: z.string() }),
-  syncResponse: z.object({ result: z.string() }),
+  requestBody: z.object({ data: z.string() }),
+  jsonResponse: z.object({ result: z.string() }),
   // Define expected response headers
   responseHeaders: z.object({
     'x-ratelimit-limit': z.string(),
@@ -1447,6 +1499,73 @@ handlers: {
 
 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 `buildHandler` to define both JSON and SSE handlers:
@@ -1514,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),
         },
       },
     }
@@ -1529,7 +1648,7 @@ export class ChatDualModeController extends AbstractDualModeController<Contracts
 | `json` | `(request, reply) => Response` |
 | `sse` | `(request, connection) => Either<Error, SSEHandlerResult>` |
 
-The `json` handler must return a value matching `syncResponse` schema. The `sse` handler uses `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
 
@@ -1612,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/lib/contracts/contractBuilders.d.ts

@@ -1,10 +1,10 @@
 import type { z } from 'zod';
-import type { DualModeContractDefinition, PathResolver } from '../dualmode/dualModeContracts.ts';
+import type { MultiFormatResponses, PathResolver, SimplifiedDualModeContractDefinition, VerboseDualModeContractDefinition } from '../dualmode/dualModeContracts.ts';
 import type { SSEContractDefinition, SSEPathResolver } from '../sse/sseContracts.ts';
 import type { SSEEventSchemas } from '../sse/sseTypes.ts';
 /**
  * Configuration for building a GET SSE route.
- * Forbids body for GET variants.
+ * Forbids requestBody for GET variants.
  */
 export type SSEGetContractConfig<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Events extends SSEEventSchemas> = {
     pathResolver: SSEPathResolver<z.infer<Params>>;
@@ -12,12 +12,13 @@ export type SSEGetContractConfig<Params extends z.ZodTypeAny, Query extends z.Zo
     query: Query;
     requestHeaders: RequestHeaders;
     events: Events;
-    body?: never;
-    syncResponse?: never;
+    requestBody?: never;
+    jsonResponse?: never;
+    multiFormatResponses?: never;
 };
 /**
- * Configuration for building a POST/PUT/PATCH SSE route with request body.
- * Requires body for payload variants.
+ * Configuration for building a POST/PUT/PATCH SSE route with request requestBody.
+ * Requires requestBody for payload variants.
  */
 export type SSEPayloadContractConfig<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, Events extends SSEEventSchemas> = {
     method?: 'POST' | 'PUT' | 'PATCH';
@@ -25,20 +26,23 @@ export type SSEPayloadContractConfig<Params extends z.ZodTypeAny, Query extends
     params: Params;
     query: Query;
     requestHeaders: RequestHeaders;
-    body: Body;
+    requestBody: Body;
     events: Events;
-    syncResponse?: never;
+    jsonResponse?: never;
+    multiFormatResponses?: never;
 };
 /**
- * Configuration for building a GET dual-mode route.
- * Has syncResponse, forbids body.
+ * Configuration for building a GET dual-mode route (simplified - single JSON format).
+ * Requires jsonResponse, forbids requestBody.
  */
-export type DualModeGetContractConfig<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, SyncResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined> = {
+export type DualModeGetContractConfig<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, JsonResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined> = {
     pathResolver: PathResolver<z.infer<Params>>;
     params: Params;
     query: Query;
     requestHeaders: RequestHeaders;
-    syncResponse: SyncResponse;
+    /** Single JSON response schema */
+    jsonResponse: JsonResponse;
+    multiFormatResponses?: never;
     /**
      * Schema for validating response headers (JSON mode only).
      * Used to define and validate headers that the server will send in the response.
@@ -53,20 +57,22 @@ export type DualModeGetContractConfig<Params extends z.ZodTypeAny, Query extends
      */
     responseHeaders?: ResponseHeaders;
     events: Events;
-    body?: never;
+    requestBody?: never;
 };
 /**
- * Configuration for building a POST/PUT/PATCH dual-mode route with request body.
- * Has both body and syncResponse.
+ * Configuration for building a POST/PUT/PATCH dual-mode route with request requestBody (simplified).
+ * Requires both requestBody and jsonResponse.
  */
-export type DualModePayloadContractConfig<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, SyncResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined> = {
+export type DualModePayloadContractConfig<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, JsonResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined> = {
     method?: 'POST' | 'PUT' | 'PATCH';
     pathResolver: PathResolver<z.infer<Params>>;
     params: Params;
     query: Query;
     requestHeaders: RequestHeaders;
-    body: Body;
-    syncResponse: SyncResponse;
+    requestBody: Body;
+    /** Single JSON response schema */
+    jsonResponse: JsonResponse;
+    multiFormatResponses?: never;
     /**
      * Schema for validating response headers (JSON mode only).
      * Used to define and validate headers that the server will send in the response.
@@ -83,80 +89,41 @@ export type DualModePayloadContractConfig<Params extends z.ZodTypeAny, Query ext
     events: Events;
 };
 /**
- * Unified contract builder with 4 overloads.
- *
- * Automatically determines the contract type based on the presence of `body` and `syncResponse`:
- *
- * | syncResponse | body | Result |
- * |--------------|------|--------|
- * | ❌ absent | ❌ absent | SSE GET |
- * | ❌ absent | ✅ present | SSE POST/PUT/PATCH |
- * | ✅ present | ❌ absent | Dual-mode GET |
- * | ✅ present | ✅ present | Dual-mode POST/PUT/PATCH |
- *
- * @example
- * ```typescript
- * // SSE GET - no body, no syncResponse
- * const notificationsStream = buildContract({
- *   pathResolver: () => '/api/notifications/stream',
- *   params: z.object({}),
- *   query: z.object({ userId: z.string().optional() }),
- *   requestHeaders: z.object({}),
- *   events: {
- *     notification: z.object({ id: z.string(), message: z.string() }),
- *   },
- * })
- *
- * // SSE POST - has body, no syncResponse
- * const chatCompletionStream = buildContract({
- *   method: 'POST',
- *   pathResolver: () => '/api/chat/completions',
- *   params: z.object({}),
- *   query: z.object({}),
- *   requestHeaders: z.object({}),
- *   body: z.object({ message: z.string(), stream: z.literal(true) }),
- *   events: {
- *     chunk: z.object({ content: z.string() }),
- *     done: z.object({ totalTokens: z.number() }),
- *   },
- * })
- *
- * // Dual-mode GET - has syncResponse, no body
- * const jobStatus = buildContract({
- *   pathResolver: (params) => `/api/jobs/${params.jobId}/status`,
- *   params: z.object({ jobId: z.string().uuid() }),
- *   query: z.object({}),
- *   requestHeaders: z.object({}),
- *   syncResponse: z.object({
- *     status: z.enum(['pending', 'running', 'completed']),
- *     progress: z.number(),
- *   }),
- *   events: {
- *     progress: z.object({ percent: z.number() }),
- *     done: z.object({ result: z.string() }),
- *   },
- * })
- *
- * // Dual-mode POST - has both body and syncResponse
- * const chatCompletion = buildContract({
- *   method: 'POST',
- *   pathResolver: () => '/api/chat/completions',
- *   params: z.object({}),
- *   query: z.object({}),
- *   requestHeaders: z.object({ authorization: z.string() }),
- *   body: z.object({ message: z.string() }),
- *   syncResponse: z.object({
- *     reply: z.string(),
- *     usage: z.object({ tokens: z.number() }),
- *   }),
- *   events: {
- *     chunk: z.object({ delta: z.string() }),
- *     done: z.object({ usage: z.object({ total: z.number() }) }),
- *   },
- * })
- * ```
+ * Configuration for building a GET dual-mode route with multi-format responses.
+ * Has multiFormatResponses, forbids requestBody and jsonResponse.
  */
-export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, SyncResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined>(config: DualModePayloadContractConfig<Params, Query, RequestHeaders, Body, SyncResponse, Events, ResponseHeaders>): DualModeContractDefinition<'POST' | 'PUT' | 'PATCH', Params, Query, RequestHeaders, Body, SyncResponse, Events, ResponseHeaders>;
-export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, SyncResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined>(config: DualModeGetContractConfig<Params, Query, RequestHeaders, SyncResponse, Events, ResponseHeaders>): DualModeContractDefinition<'GET', Params, Query, RequestHeaders, undefined, SyncResponse, Events, ResponseHeaders>;
+export type MultiFormatGetContractConfig<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Formats extends MultiFormatResponses, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined> = {
+    pathResolver: PathResolver<z.infer<Params>>;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    jsonResponse?: never;
+    /** Multi-format response schemas */
+    multiFormatResponses: Formats;
+    responseHeaders?: ResponseHeaders;
+    events: Events;
+    requestBody?: never;
+};
+/**
+ * Configuration for building a POST/PUT/PATCH dual-mode route with multi-format responses.
+ * Has both requestBody and multiFormatResponses.
+ */
+export type MultiFormatPayloadContractConfig<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, Formats extends MultiFormatResponses, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined> = {
+    method?: 'POST' | 'PUT' | 'PATCH';
+    pathResolver: PathResolver<z.infer<Params>>;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    requestBody: Body;
+    jsonResponse?: never;
+    /** Multi-format response schemas */
+    multiFormatResponses: Formats;
+    responseHeaders?: ResponseHeaders;
+    events: Events;
+};
+export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, Formats extends MultiFormatResponses, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined>(config: MultiFormatPayloadContractConfig<Params, Query, RequestHeaders, Body, Formats, Events, ResponseHeaders>): VerboseDualModeContractDefinition<'POST' | 'PUT' | 'PATCH', Params, Query, RequestHeaders, Body, Formats, Events, ResponseHeaders>;
+export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Formats extends MultiFormatResponses, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined>(config: MultiFormatGetContractConfig<Params, Query, RequestHeaders, Formats, Events, ResponseHeaders>): VerboseDualModeContractDefinition<'GET', Params, Query, RequestHeaders, undefined, Formats, Events, ResponseHeaders>;
+export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, JsonResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined>(config: DualModePayloadContractConfig<Params, Query, RequestHeaders, Body, JsonResponse, Events, ResponseHeaders>): SimplifiedDualModeContractDefinition<'POST' | 'PUT' | 'PATCH', Params, Query, RequestHeaders, Body, JsonResponse, Events, ResponseHeaders>;
+export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, JsonResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined>(config: DualModeGetContractConfig<Params, Query, RequestHeaders, JsonResponse, Events, ResponseHeaders>): SimplifiedDualModeContractDefinition<'GET', Params, Query, RequestHeaders, undefined, JsonResponse, Events, ResponseHeaders>;
 export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, Events extends SSEEventSchemas>(config: SSEPayloadContractConfig<Params, Query, RequestHeaders, Body, Events>): SSEContractDefinition<'POST' | 'PUT' | 'PATCH', Params, Query, RequestHeaders, Body, Events>;
 export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Events extends SSEEventSchemas>(config: SSEGetContractConfig<Params, Query, RequestHeaders, Events>): SSEContractDefinition<'GET', Params, Query, RequestHeaders, undefined, Events>;

package/dist/lib/contracts/contractBuilders.js

@@ -1,29 +1,105 @@
+/**
+ * Unified contract builder with overloads for SSE-only, simplified dual-mode, and verbose dual-mode contracts.
+ *
+ * Automatically determines the contract type based on the presence of `requestBody`, `jsonResponse`, and `multiFormatResponses`:
+ *
+ * | Response Config | requestBody | Result |
+ * |-----------------|------|--------|
+ * | none | ❌ | SSE GET |
+ * | none | ✅ | SSE POST/PUT/PATCH |
+ * | jsonResponse | ❌ | Simplified Dual-mode GET |
+ * | jsonResponse | ✅ | Simplified Dual-mode POST/PUT/PATCH |
+ * | multiFormatResponses | ❌ | Verbose Dual-mode GET |
+ * | multiFormatResponses | ✅ | Verbose Dual-mode POST/PUT/PATCH |
+ *
+ * @example
+ * ```typescript
+ * // SSE GET - no requestBody, no jsonResponse/multiFormatResponses
+ * const notificationsStream = buildContract({
+ *   pathResolver: () => '/api/notifications/stream',
+ *   params: z.object({}),
+ *   query: z.object({ userId: z.string().optional() }),
+ *   requestHeaders: z.object({}),
+ *   events: { notification: z.object({ id: z.string(), message: z.string() }) },
+ * })
+ *
+ * // Simplified dual-mode POST (recommended) - single JSON format
+ * const chatCompletion = buildContract({
+ *   method: 'POST',
+ *   pathResolver: () => '/api/chat/completions',
+ *   params: z.object({}),
+ *   query: z.object({}),
+ *   requestHeaders: z.object({}),
+ *   requestBody: z.object({ message: z.string() }),
+ *   jsonResponse: z.object({ reply: z.string(), usage: z.object({ tokens: z.number() }) }),
+ *   events: { chunk: z.object({ delta: z.string() }), done: z.object({ usage: z.object({ total: z.number() }) }) },
+ * })
+ *
+ * // Verbose dual-mode POST - multiple format support
+ * const exportData = buildContract({
+ *   method: 'POST',
+ *   pathResolver: () => '/api/export',
+ *   params: z.object({}),
+ *   query: z.object({}),
+ *   requestHeaders: z.object({}),
+ *   requestBody: z.object({ format: z.string() }),
+ *   multiFormatResponses: {
+ *     'application/json': z.object({ data: z.array(z.unknown()) }),
+ *     'text/csv': z.string(),
+ *     'text/plain': z.string(),
+ *   },
+ *   events: { progress: z.object({ percent: z.number() }), done: z.object({ rowCount: z.number() }) },
+ * })
+ * ```
+ */
+// Helper to build base contract fields
+// biome-ignore lint/suspicious/noExplicitAny: Config union type
+function buildBaseFields(config, hasBody) {
+    return {
+        pathResolver: config.pathResolver,
+        params: config.params,
+        query: config.query,
+        requestHeaders: config.requestHeaders,
+        requestBody: hasBody ? config.requestBody : undefined,
+        events: config.events,
+    };
+}
+// Helper to determine method
+function determineMethod(config, hasBody, defaultMethod) {
+    return hasBody ? (config.method ?? defaultMethod) : 'GET';
+}
 // Implementation
 export function buildContract(config) {
-    const hasDualMode = 'syncResponse' in config && config.syncResponse !== undefined;
-    const hasBody = 'body' in config && config.body !== undefined;
-    if (hasDualMode) {
+    const hasMultiFormat = 'multiFormatResponses' in config && config.multiFormatResponses !== undefined;
+    const hasJsonResponse = 'jsonResponse' in config && config.jsonResponse !== undefined;
+    const hasBody = 'requestBody' in config && config.requestBody !== undefined;
+    const base = buildBaseFields(config, hasBody);
+    if (hasMultiFormat) {
+        // Verbose multi-format contract
         return {
-            method: hasBody ? (config.method ?? 'POST') : 'GET',
-            pathResolver: config.pathResolver,
-            params: config.params,
-            query: config.query,
-            requestHeaders: config.requestHeaders,
-            body: hasBody ? config.body : undefined,
-            syncResponse: config.syncResponse,
+            ...base,
+            method: determineMethod(config, hasBody, 'POST'),
+            multiFormatResponses: config.multiFormatResponses,
             responseHeaders: config.responseHeaders,
-            events: config.events,
             isDualMode: true,
+            isVerbose: true,
         };
     }
+    if (hasJsonResponse) {
+        // Simplified single-JSON-format contract
+        return {
+            ...base,
+            method: determineMethod(config, hasBody, 'POST'),
+            jsonResponse: config.jsonResponse,
+            responseHeaders: config.responseHeaders,
+            isDualMode: true,
+            isSimplified: true,
+        };
+    }
+    // SSE-only contract
     return {
-        method: hasBody ? (config.method ?? 'POST') : 'GET',
-        pathResolver: config.pathResolver,
-        params: config.params,
-        query: config.query,
-        requestHeaders: config.requestHeaders,
-        body: hasBody ? config.body : undefined,
-        events: config.events,
+        ...base,
+        method: determineMethod(config, hasBody, 'POST'),
         isSSE: true,
     };
 }

package/dist/lib/contracts/contractBuilders.js.map

@@ -1 +1 @@
-{"version":3,"file":"contractBuilders.js","sourceRoot":"","sources":["../../../lib/contracts/contractBuilders.ts"],"names":[],"mappings":"AAgRA,iBAAiB;AACjB,MAAM,UAAU,aAAa,CAC3B,MAO4C;IAG5C,MAAM,WAAW,GAAG,cAAc,IAAI,MAAM,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,CAAA;IACjF,MAAM,OAAO,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,CAAA;IAE7D,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO;YACL,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAE,MAAsC,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK;YACpF,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAE,MAA4B,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;YAC9D,YAAY,EAAG,MAAoC,CAAC,YAAY;YAChE,eAAe,EAAG,MAAwC,CAAC,eAAe;YAC1E,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,UAAU,EAAE,IAAI;SACjB,CAAA;IACH,CAAC;IAED,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAE,MAAiC,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK;QAC/E,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAE,MAA4B,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QAC9D,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,IAAI;KACZ,CAAA;AACH,CAAC"}
+{"version":3,"file":"contractBuilders.js","sourceRoot":"","sources":["../../../lib/contracts/contractBuilders.ts"],"names":[],"mappings":"AAgLA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,uCAAuC;AACvC,gEAAgE;AAChE,SAAS,eAAe,CAAC,MAAW,EAAE,OAAgB;IACpD,OAAO;QACL,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;QACrD,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAA;AACH,CAAC;AAED,6BAA6B;AAC7B,SAAS,eAAe,CAAC,MAA2B,EAAE,OAAgB,EAAE,aAAqB;IAC3F,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,aAAa,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAC3D,CAAC;AA2ID,iBAAiB;AACjB,MAAM,UAAU,aAAa,CAC3B,MAW4C;IAG5C,MAAM,cAAc,GAClB,sBAAsB,IAAI,MAAM,IAAI,MAAM,CAAC,oBAAoB,KAAK,SAAS,CAAA;IAC/E,MAAM,eAAe,GAAG,cAAc,IAAI,MAAM,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,CAAA;IACrF,MAAM,OAAO,GAAG,aAAa,IAAI,MAAM,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,CAAA;IAC3E,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAE7C,IAAI,cAAc,EAAE,CAAC;QACnB,gCAAgC;QAChC,OAAO;YACL,GAAG,IAAI;YACP,MAAM,EAAE,eAAe,CAAC,MAA6B,EAAE,OAAO,EAAE,MAAM,CAAC;YACvE,oBAAoB,EAAG,MAA4C,CAAC,oBAAoB;YACxF,eAAe,EAAG,MAAwC,CAAC,eAAe;YAC1E,UAAU,EAAE,IAAI;YAChB,SAAS,EAAE,IAAI;SAChB,CAAA;IACH,CAAC;IAED,IAAI,eAAe,EAAE,CAAC;QACpB,yCAAyC;QACzC,OAAO;YACL,GAAG,IAAI;YACP,MAAM,EAAE,eAAe,CAAC,MAA6B,EAAE,OAAO,EAAE,MAAM,CAAC;YACvE,YAAY,EAAG,MAAoC,CAAC,YAAY;YAChE,eAAe,EAAG,MAAwC,CAAC,eAAe;YAC1E,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;SACnB,CAAA;IACH,CAAC;IAED,oBAAoB;IACpB,OAAO;QACL,GAAG,IAAI;QACP,MAAM,EAAE,eAAe,CAAC,MAA6B,EAAE,OAAO,EAAE,MAAM,CAAC;QACvE,KAAK,EAAE,IAAI;KACZ,CAAA;AACH,CAAC"}