@lokalise/api-contracts 6.1.0 → 6.2.0

package/README.md

@@ -191,3 +191,146 @@ This function is particularly useful for:
 - Generating documentation or route summaries
 - Error messages that need to reference specific endpoints
 - Test descriptions and assertions
+
+## SSE and Dual-Mode Contracts
+
+Use `buildSseContract` for endpoints that support Server-Sent Events (SSE) streaming. This builder supports two contract types:
+
+### SSE-Only Contracts
+
+Pure streaming endpoints that only return SSE events. Use these for real-time notifications, live feeds, or any endpoint that only streams data.
+
+```ts
+import { buildSseContract } from '@lokalise/api-contracts'
+import { z } from 'zod'
+
+// GET SSE endpoint for live notifications
+const notificationsStream = buildSseContract({
+    pathResolver: () => '/api/notifications/stream',
+    params: z.object({}),
+    query: z.object({ userId: z.string().optional() }),
+    requestHeaders: z.object({}),
+    sseEvents: {
+        notification: z.object({ id: z.string(), message: z.string() }),
+    },
+})
+// Result: isSSE: true
+
+// POST SSE endpoint (e.g., streaming file processing)
+const processStream = buildSseContract({
+    method: 'post',
+    pathResolver: () => '/api/process/stream',
+    params: z.object({}),
+    query: z.object({}),
+    requestHeaders: z.object({}),
+    requestBody: z.object({ fileId: z.string() }),
+    sseEvents: {
+        progress: z.object({ percent: z.number() }),
+        done: z.object({ result: z.string() }),
+    },
+})
+// Result: isSSE: true
+
+// SSE endpoint with error schemas (for errors before streaming starts)
+const channelStream = buildSseContract({
+    pathResolver: (params) => `/api/channels/${params.channelId}/stream`,
+    params: z.object({ channelId: z.string() }),
+    query: z.object({}),
+    requestHeaders: z.object({ authorization: z.string() }),
+    sseEvents: {
+        message: z.object({ text: z.string() }),
+    },
+    // Errors returned before streaming begins
+    responseSchemasByStatusCode: {
+        401: z.object({ error: z.literal('Unauthorized') }),
+        404: z.object({ error: z.literal('Channel not found') }),
+    },
+})
+```
+
+### Dual-Mode (Hybrid) Contracts
+
+Hybrid endpoints that support **both** synchronous JSON responses **and** SSE streaming from the same URL. The response mode is determined by the client's `Accept` header:
+- `Accept: application/json` → Synchronous JSON response
+- `Accept: text/event-stream` → SSE streaming
+
+This pattern is ideal for AI/LLM APIs (like OpenAI's Chat Completions API) where clients can choose between getting the full response at once or streaming it token-by-token.
+
+```ts
+import { buildSseContract } from '@lokalise/api-contracts'
+import { z } from 'zod'
+
+// OpenAI-style chat completion endpoint
+// - Accept: application/json → returns { reply, usage } immediately
+// - Accept: text/event-stream → streams chunk events, then done event
+const chatCompletion = buildSseContract({
+    method: 'post',
+    pathResolver: () => '/api/chat/completions',
+    params: z.object({}),
+    query: z.object({}),
+    requestHeaders: z.object({}),
+    requestBody: z.object({ message: z.string() }),
+    // Adding syncResponseBody makes it dual-mode
+    syncResponseBody: z.object({
+        reply: z.string(),
+        usage: z.object({ tokens: z.number() }),
+    }),
+    sseEvents: {
+        chunk: z.object({ delta: z.string() }),
+        done: z.object({ usage: z.object({ totalTokens: z.number() }) }),
+    },
+})
+// Result: isDualMode: true
+
+// GET dual-mode endpoint for job status (poll or stream)
+const jobStatus = buildSseContract({
+    pathResolver: (params) => `/api/jobs/${params.jobId}/status`,
+    params: z.object({ jobId: z.string().uuid() }),
+    query: z.object({ verbose: z.string().optional() }),
+    requestHeaders: z.object({}),
+    syncResponseBody: z.object({
+        status: z.enum(['pending', 'running', 'completed', 'failed']),
+        progress: z.number(),
+    }),
+    sseEvents: {
+        progress: z.object({ percent: z.number() }),
+        done: z.object({ result: z.string() }),
+    },
+})
+// Result: isDualMode: true
+```
+
+### Response Schemas by Status Code
+
+Both SSE-only and dual-mode contracts support `responseSchemasByStatusCode` for defining different response shapes for errors that occur **before streaming starts** (e.g., authentication failures, validation errors, resource not found):
+
+```ts
+const chatCompletion = buildSseContract({
+    method: 'post',
+    pathResolver: () => '/api/chat/completions',
+    params: z.object({}),
+    query: z.object({}),
+    requestHeaders: z.object({ authorization: z.string() }),
+    requestBody: z.object({ message: z.string() }),
+    syncResponseBody: z.object({ reply: z.string() }),
+    sseEvents: {
+        chunk: z.object({ delta: z.string() }),
+    },
+    responseSchemasByStatusCode: {
+        400: z.object({ error: z.string(), details: z.array(z.string()) }),
+        401: z.object({ error: z.literal('Unauthorized') }),
+        429: z.object({ error: z.string(), retryAfter: z.number() }),
+    },
+})
+```
+
+### Contract Type Detection
+
+`buildSseContract` automatically determines the contract type based on the presence of `syncResponseBody`:
+
+| `syncResponseBody` | `requestBody` | Result |
+|-------------------|---------------|--------|
+| ❌ | ❌ | SSE-only GET |
+| ❌ | ✅ | SSE-only POST/PUT/PATCH |
+| ✅ | ❌ | Dual-mode GET |
+| ✅ | ✅ | Dual-mode POST/PUT/PATCH |

package/dist/index.d.ts

@@ -1,3 +1,7 @@
 export * from './apiContracts.ts';
 export * from './HttpStatusCodes.ts';
 export * from './pathUtils.ts';
+export * from './sse/dualModeContracts.ts';
+export * from './sse/sseContractBuilders.ts';
+export * from './sse/sseContracts.ts';
+export * from './sse/sseTypes.ts';

package/dist/index.js

@@ -1,4 +1,11 @@
 export * from "./apiContracts.js";
 export * from "./HttpStatusCodes.js";
 export * from "./pathUtils.js";
+// Dual-mode (hybrid) contracts
+export * from "./sse/dualModeContracts.js";
+// Contract builders
+export * from "./sse/sseContractBuilders.js";
+// SSE contracts
+export * from "./sse/sseContracts.js";
+export * from "./sse/sseTypes.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,gBAAgB,CAAA;AAC9B,+BAA+B;AAC/B,cAAc,4BAA4B,CAAA;AAC1C,oBAAoB;AACpB,cAAc,8BAA8B,CAAA;AAC5C,gBAAgB;AAChB,cAAc,uBAAuB,CAAA;AACrC,cAAc,mBAAmB,CAAA"}

package/dist/sse/dualModeContracts.d.ts

@@ -0,0 +1,63 @@
+import type { z } from 'zod/v4';
+import type { RoutePathResolver } from '../apiContracts.ts';
+import type { HttpStatusCode } from '../HttpStatusCodes.ts';
+import type { SSEMethod } from './sseContracts.ts';
+import type { SSEEventSchemas } from './sseTypes.ts';
+/**
+ * Definition for a dual-mode route.
+ * Use `syncResponseBody` for the non-streaming response schema.
+ *
+ * @template Method - HTTP method (GET, POST, PUT, PATCH)
+ * @template Params - Path parameters schema
+ * @template Query - Query string parameters schema
+ * @template RequestHeaders - Request headers schema
+ * @template Body - Request requestBody schema (for POST/PUT/PATCH)
+ * @template SyncResponse - Sync response schema (for Accept: application/json)
+ * @template Events - SSE event schemas (for Accept: text/event-stream)
+ * @template ResponseHeaders - Response headers schema (for sync mode)
+ * @template ResponseSchemasByStatusCode - Alternative response schemas by HTTP status code
+ */
+export type SimplifiedDualModeContractDefinition<Method extends SSEMethod = SSEMethod, Params extends z.ZodTypeAny = z.ZodTypeAny, Query extends z.ZodTypeAny = z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny = z.ZodTypeAny, Body extends z.ZodTypeAny | undefined = undefined, SyncResponse extends z.ZodTypeAny = z.ZodTypeAny, Events extends SSEEventSchemas = SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined> = {
+    method: Method;
+    pathResolver: RoutePathResolver<z.infer<Params>>;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    requestBody: Body;
+    /** Sync response schema - use with `sync` handler */
+    syncResponseBody: SyncResponse;
+    responseHeaders?: ResponseHeaders;
+    /**
+     * Alternative response schemas by HTTP status code.
+     * Used to define different response shapes for error cases (e.g., 400, 404, 500).
+     *
+     * @example
+     * ```ts
+     * responseSchemasByStatusCode: {
+     *   400: z.object({ error: z.string(), details: z.array(z.string()) }),
+     *   404: z.object({ error: z.string() }),
+     * }
+     * ```
+     */
+    responseSchemasByStatusCode?: ResponseSchemasByStatusCode;
+    sseEvents: Events;
+    isDualMode: true;
+};
+/**
+ * Type representing any dual-mode route definition (for use in generic constraints).
+ * Uses a manually defined type to avoid pathResolver type incompatibilities.
+ */
+export type AnyDualModeContractDefinition = {
+    method: SSEMethod;
+    pathResolver: RoutePathResolver<any>;
+    params: z.ZodTypeAny;
+    query: z.ZodTypeAny;
+    requestHeaders: z.ZodTypeAny;
+    requestBody: z.ZodTypeAny | undefined;
+    /** Sync response schema */
+    syncResponseBody: z.ZodTypeAny;
+    responseHeaders?: z.ZodTypeAny;
+    responseSchemasByStatusCode?: Partial<Record<HttpStatusCode, z.ZodTypeAny>>;
+    sseEvents: SSEEventSchemas;
+    isDualMode: true;
+};

package/dist/sse/dualModeContracts.js

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

package/dist/sse/dualModeContracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dualModeContracts.js","sourceRoot":"","sources":["../../src/sse/dualModeContracts.ts"],"names":[],"mappings":""}

package/dist/sse/sseContractBuilders.d.ts

@@ -0,0 +1,146 @@
+import type { z } from 'zod/v4';
+import type { RoutePathResolver } from '../apiContracts.ts';
+import type { HttpStatusCode } from '../HttpStatusCodes.ts';
+import type { SimplifiedDualModeContractDefinition } from './dualModeContracts.ts';
+import type { SSEContractDefinition } from './sseContracts.ts';
+import type { SSEEventSchemas } from './sseTypes.ts';
+/**
+ * Configuration for building a GET SSE route.
+ * Forbids requestBody for GET variants.
+ */
+export type SSEGetContractConfig<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined> = {
+    pathResolver: RoutePathResolver<z.infer<Params>>;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    sseEvents: Events;
+    /**
+     * Error response schemas by HTTP status code.
+     * Used to define response shapes for errors that occur before streaming starts
+     * (e.g., authentication failures, validation errors, not found).
+     *
+     * @example
+     * ```ts
+     * responseSchemasByStatusCode: {
+     *   401: z.object({ error: z.literal('Unauthorized') }),
+     *   404: z.object({ error: z.string() }),
+     * }
+     * ```
+     */
+    responseSchemasByStatusCode?: ResponseSchemasByStatusCode;
+    requestBody?: never;
+    syncResponseBody?: never;
+};
+/**
+ * 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, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined> = {
+    method?: 'post' | 'put' | 'patch';
+    pathResolver: RoutePathResolver<z.infer<Params>>;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    requestBody: Body;
+    sseEvents: Events;
+    /**
+     * Error response schemas by HTTP status code.
+     * Used to define response shapes for errors that occur before streaming starts
+     * (e.g., authentication failures, validation errors, not found).
+     *
+     * @example
+     * ```ts
+     * responseSchemasByStatusCode: {
+     *   401: z.object({ error: z.literal('Unauthorized') }),
+     *   404: z.object({ error: z.string() }),
+     * }
+     * ```
+     */
+    responseSchemasByStatusCode?: ResponseSchemasByStatusCode;
+    syncResponseBody?: never;
+};
+/**
+ * Configuration for building a GET dual-mode route.
+ * Requires syncResponseBody, forbids requestBody.
+ */
+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, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined> = {
+    pathResolver: RoutePathResolver<z.infer<Params>>;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    /** Single sync response schema */
+    syncResponseBody: JsonResponse;
+    /**
+     * Schema for validating response headers (sync mode only).
+     * Used to define and validate headers that the server will send in the response.
+     *
+     * @example
+     * ```ts
+     * responseHeaders: z.object({
+     *   'x-ratelimit-limit': z.string(),
+     *   'x-ratelimit-remaining': z.string(),
+     * })
+     * ```
+     */
+    responseHeaders?: ResponseHeaders;
+    /**
+     * Alternative response schemas by HTTP status code.
+     * Used to define different response shapes for error cases.
+     *
+     * @example
+     * ```ts
+     * responseSchemasByStatusCode: {
+     *   400: z.object({ error: z.string(), details: z.array(z.string()) }),
+     *   404: z.object({ error: z.string() }),
+     * }
+     * ```
+     */
+    responseSchemasByStatusCode?: ResponseSchemasByStatusCode;
+    sseEvents: Events;
+    requestBody?: never;
+};
+/**
+ * Configuration for building a POST/PUT/PATCH dual-mode route with request requestBody.
+ * Requires both requestBody and syncResponseBody.
+ */
+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, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined> = {
+    method?: 'post' | 'put' | 'patch';
+    pathResolver: RoutePathResolver<z.infer<Params>>;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    requestBody: Body;
+    /** Single sync response schema */
+    syncResponseBody: JsonResponse;
+    /**
+     * Schema for validating response headers (sync mode only).
+     * Used to define and validate headers that the server will send in the response.
+     *
+     * @example
+     * ```ts
+     * responseHeaders: z.object({
+     *   'x-ratelimit-limit': z.string(),
+     *   'x-ratelimit-remaining': z.string(),
+     * })
+     * ```
+     */
+    responseHeaders?: ResponseHeaders;
+    /**
+     * Alternative response schemas by HTTP status code.
+     * Used to define different response shapes for error cases.
+     *
+     * @example
+     * ```ts
+     * responseSchemasByStatusCode: {
+     *   400: z.object({ error: z.string(), details: z.array(z.string()) }),
+     *   404: z.object({ error: z.string() }),
+     * }
+     * ```
+     */
+    responseSchemasByStatusCode?: ResponseSchemasByStatusCode;
+    sseEvents: Events;
+};
+export declare function buildSseContract<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, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined>(config: DualModePayloadContractConfig<Params, Query, RequestHeaders, Body, JsonResponse, Events, ResponseHeaders, ResponseSchemasByStatusCode>): SimplifiedDualModeContractDefinition<'post' | 'put' | 'patch', Params, Query, RequestHeaders, Body, JsonResponse, Events, ResponseHeaders, ResponseSchemasByStatusCode>;
+export declare function buildSseContract<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, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined>(config: DualModeGetContractConfig<Params, Query, RequestHeaders, JsonResponse, Events, ResponseHeaders, ResponseSchemasByStatusCode>): SimplifiedDualModeContractDefinition<'get', Params, Query, RequestHeaders, undefined, JsonResponse, Events, ResponseHeaders, ResponseSchemasByStatusCode>;
+export declare function buildSseContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined>(config: SSEPayloadContractConfig<Params, Query, RequestHeaders, Body, Events, ResponseSchemasByStatusCode>): SSEContractDefinition<'post' | 'put' | 'patch', Params, Query, RequestHeaders, Body, Events, ResponseSchemasByStatusCode>;
+export declare function buildSseContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined>(config: SSEGetContractConfig<Params, Query, RequestHeaders, Events, ResponseSchemasByStatusCode>): SSEContractDefinition<'get', Params, Query, RequestHeaders, undefined, Events, ResponseSchemasByStatusCode>;

package/dist/sse/sseContractBuilders.js

@@ -0,0 +1,97 @@
+/**
+ * Builds SSE (Server-Sent Events) and dual-mode contracts.
+ *
+ * This builder supports two contract types:
+ *
+ * **SSE-only contracts**: Pure streaming endpoints that only return SSE events.
+ * Use these for real-time notifications, live feeds, or any endpoint that only streams data.
+ *
+ * **Dual-mode contracts**: Hybrid endpoints that support both synchronous JSON responses
+ * AND SSE streaming from the same URL. The response mode is determined by the client's
+ * `Accept` header (`application/json` for sync, `text/event-stream` for SSE).
+ * This is ideal for AI/LLM APIs (like OpenAI) where clients can choose between
+ * getting the full response at once or streaming it token-by-token.
+ *
+ * The contract type is automatically determined based on the presence of `syncResponseBody`:
+ *
+ * | `syncResponseBody` | `requestBody` | Result |
+ * |--------------------|---------------|--------|
+ * | ❌ | ❌ | SSE-only GET |
+ * | ❌ | ✅ | SSE-only POST/PUT/PATCH |
+ * | ✅ | ❌ | Dual-mode GET |
+ * | ✅ | ✅ | Dual-mode POST/PUT/PATCH |
+ *
+ * @example
+ * ```typescript
+ * // SSE-only: Pure streaming endpoint (e.g., live notifications)
+ * const notificationsStream = buildSseContract({
+ *   pathResolver: () => '/api/notifications/stream',
+ *   params: z.object({}),
+ *   query: z.object({ userId: z.string().optional() }),
+ *   requestHeaders: z.object({}),
+ *   sseEvents: {
+ *     notification: z.object({ id: z.string(), message: z.string() }),
+ *   },
+ * })
+ *
+ * // Dual-mode: Same endpoint supports both JSON and SSE (e.g., OpenAI-style API)
+ * // - Accept: application/json → returns { reply, usage } immediately
+ * // - Accept: text/event-stream → streams chunk events, then done event
+ * const chatCompletion = buildSseContract({
+ *   method: 'POST',
+ *   pathResolver: () => '/api/chat/completions',
+ *   params: z.object({}),
+ *   query: z.object({}),
+ *   requestHeaders: z.object({}),
+ *   requestBody: z.object({ message: z.string() }),
+ *   syncResponseBody: z.object({ reply: z.string(), usage: z.object({ tokens: z.number() }) }),
+ *   sseEvents: {
+ *     chunk: z.object({ delta: z.string() }),
+ *     done: z.object({ usage: z.object({ total: 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,
+        sseEvents: config.sseEvents,
+    };
+}
+// Helper to determine method
+function determineMethod(config, hasBody, defaultMethod) {
+    return hasBody ? (config.method ?? defaultMethod) : 'get';
+}
+// Implementation
+export function buildSseContract(config) {
+    const hasSyncResponseBody = 'syncResponseBody' in config && config.syncResponseBody !== undefined;
+    const hasBody = 'requestBody' in config && config.requestBody !== undefined;
+    const base = buildBaseFields(config, hasBody);
+    if (hasSyncResponseBody) {
+        // Dual-mode contract
+        return {
+            ...base,
+            method: determineMethod(config, hasBody, 'post'),
+            syncResponseBody: config.syncResponseBody,
+            responseHeaders: config.responseHeaders,
+            responseSchemasByStatusCode: config
+                .responseSchemasByStatusCode,
+            isDualMode: true,
+        };
+    }
+    // SSE-only contract
+    return {
+        ...base,
+        method: determineMethod(config, hasBody, 'post'),
+        responseSchemasByStatusCode: config
+            .responseSchemasByStatusCode,
+        isSSE: true,
+    };
+}
+//# sourceMappingURL=sseContractBuilders.js.map

package/dist/sse/sseContractBuilders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseContractBuilders.js","sourceRoot":"","sources":["../../src/sse/sseContractBuilders.ts"],"names":[],"mappings":"AAyLA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,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;AAwHD,iBAAiB;AACjB,MAAM,UAAU,gBAAgB,CAC9B,MAOiD;IAGjD,MAAM,mBAAmB,GAAG,kBAAkB,IAAI,MAAM,IAAI,MAAM,CAAC,gBAAgB,KAAK,SAAS,CAAA;IACjG,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,mBAAmB,EAAE,CAAC;QACxB,qBAAqB;QACrB,OAAO;YACL,GAAG,IAAI;YACP,MAAM,EAAE,eAAe,CAAC,MAA6B,EAAE,OAAO,EAAE,MAAM,CAAC;YACvE,gBAAgB,EAAG,MAAwC,CAAC,gBAAgB;YAC5E,eAAe,EAAG,MAAwC,CAAC,eAAe;YAC1E,2BAA2B,EAAG,MAAoD;iBAC/E,2BAA2B;YAC9B,UAAU,EAAE,IAAI;SACjB,CAAA;IACH,CAAC;IAED,oBAAoB;IACpB,OAAO;QACL,GAAG,IAAI;QACP,MAAM,EAAE,eAAe,CAAC,MAA6B,EAAE,OAAO,EAAE,MAAM,CAAC;QACvE,2BAA2B,EAAG,MAAoD;aAC/E,2BAA2B;QAC9B,KAAK,EAAE,IAAI;KACZ,CAAA;AACH,CAAC"}

package/dist/sse/sseContracts.d.ts

@@ -0,0 +1,64 @@
+import type { z } from 'zod/v4';
+import type { RoutePathResolver } from '../apiContracts.ts';
+import type { HttpStatusCode } from '../HttpStatusCodes.ts';
+import type { SSEEventSchemas } from './sseTypes.ts';
+/**
+ * Supported HTTP methods for SSE routes.
+ * While traditional SSE uses GET, modern APIs (e.g., OpenAI) use POST
+ * to send request parameters in the body while streaming responses.
+ */
+export type SSEMethod = 'get' | 'post' | 'put' | 'patch';
+/**
+ * Definition for an SSE route with type-safe contracts.
+ *
+ * @template Method - HTTP method (GET, POST, PUT, PATCH)
+ * @template Params - Path parameters schema
+ * @template Query - Query string parameters schema
+ * @template RequestHeaders - Request headers schema
+ * @template Body - Request requestBody schema (for POST/PUT/PATCH)
+ * @template Events - Map of event name to event data schema
+ * @template ResponseSchemasByStatusCode - Error response schemas by HTTP status code
+ */
+export type SSEContractDefinition<Method extends SSEMethod = SSEMethod, Params extends z.ZodTypeAny = z.ZodTypeAny, Query extends z.ZodTypeAny = z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny = z.ZodTypeAny, Body extends z.ZodTypeAny | undefined = undefined, Events extends SSEEventSchemas = SSEEventSchemas, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined> = {
+    method: Method;
+    /**
+     * Type-safe path resolver function.
+     * Receives typed params and returns the URL path string.
+     */
+    pathResolver: RoutePathResolver<z.infer<Params>>;
+    params: Params;
+    query: Query;
+    requestHeaders: RequestHeaders;
+    requestBody: Body;
+    sseEvents: Events;
+    /**
+     * Error response schemas by HTTP status code.
+     * Used to define response shapes for errors that occur before streaming starts
+     * (e.g., authentication failures, validation errors, not found).
+     *
+     * @example
+     * ```ts
+     * responseSchemasByStatusCode: {
+     *   401: z.object({ error: z.literal('Unauthorized') }),
+     *   404: z.object({ error: z.string() }),
+     * }
+     * ```
+     */
+    responseSchemasByStatusCode?: ResponseSchemasByStatusCode;
+    isSSE: true;
+};
+/**
+ * Type representing any SSE route definition (for use in generic constraints).
+ * Uses a manually defined type to avoid pathResolver type incompatibilities.
+ */
+export type AnySSEContractDefinition = {
+    method: SSEMethod;
+    pathResolver: RoutePathResolver<any>;
+    params: z.ZodTypeAny;
+    query: z.ZodTypeAny;
+    requestHeaders: z.ZodTypeAny;
+    requestBody: z.ZodTypeAny | undefined;
+    sseEvents: SSEEventSchemas;
+    responseSchemasByStatusCode?: Partial<Record<HttpStatusCode, z.ZodTypeAny>>;
+    isSSE: true;
+};

package/dist/sse/sseContracts.js

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

package/dist/sse/sseContracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseContracts.js","sourceRoot":"","sources":["../../src/sse/sseContracts.ts"],"names":[],"mappings":""}

package/dist/sse/sseTypes.d.ts

@@ -0,0 +1,34 @@
+import type { z } from 'zod/v4';
+import type { AnySSEContractDefinition } from './sseContracts.ts';
+/**
+ * Type constraint for SSE event schemas.
+ * Maps event names to their Zod schemas for validation.
+ */
+export type SSEEventSchemas = Record<string, z.ZodTypeAny>;
+/**
+ * Extract all event names from all contracts as a union of string literals.
+ *
+ * @example
+ * ```typescript
+ * type Contracts = {
+ *   notifications: { sseEvents: { alert: z.ZodObject<...> } }
+ *   chat: { sseEvents: { message: z.ZodObject<...>, done: z.ZodObject<...> } }
+ * }
+ * // AllContractEventNames<Contracts> = 'alert' | 'message' | 'done'
+ * ```
+ */
+export type AllContractEventNames<Contracts extends Record<string, AnySSEContractDefinition>> = Contracts[keyof Contracts]['sseEvents'] extends infer E ? E extends SSEEventSchemas ? keyof E & string : never : never;
+/**
+ * Extract the schema for a specific event name across all contracts.
+ * Returns the Zod schema for the event, or never if not found.
+ */
+export type ExtractEventSchema<Contracts extends Record<string, AnySSEContractDefinition>, EventName extends string> = {
+    [K in keyof Contracts]: EventName extends keyof Contracts[K]['sseEvents'] ? Contracts[K]['sseEvents'][EventName] : never;
+}[keyof Contracts];
+/**
+ * Flatten all events from all contracts into a single record.
+ * Used for type-safe event sending across all controller routes.
+ */
+export type AllContractEvents<Contracts extends Record<string, AnySSEContractDefinition>> = {
+    [EventName in AllContractEventNames<Contracts>]: ExtractEventSchema<Contracts, EventName>;
+};

package/dist/sse/sseTypes.js

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

package/dist/sse/sseTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseTypes.js","sourceRoot":"","sources":["../../src/sse/sseTypes.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lokalise/api-contracts",
-    "version": "6.1.0",
+    "version": "6.2.0",
     "files": [
         "dist"
     ],
@@ -45,14 +45,14 @@
         "zod": ">=3.25.56"
     },
     "devDependencies": {
-        "@biomejs/biome": "^2.3.6",
+        "@biomejs/biome": "^2.3.7",
         "@lokalise/biome-config": "^3.1.0",
-        "@lokalise/tsconfig": "^1.3.0",
-        "@vitest/coverage-v8": "^3.2.4",
+        "@lokalise/tsconfig": "^3.1.0",
+        "@vitest/coverage-v8": "^4.0.15",
         "rimraf": "^6.0.1",
         "typescript": "5.9.3",
-        "vitest": "^3.2.4",
-        "zod": "^4.0.17"
+        "vitest": "^4.0.15",
+        "zod": "^4.3.6"
     },
     "dependencies": {}
 }