@lokalise/api-contracts 6.9.0 → 6.11.0

package/README.md

@@ -1,420 +1,345 @@
 # api-contracts
 
-Key idea behind API contracts: backend owns entire definition for the route, including its path, HTTP method used and
-response structure expectations, and exposes it as a part of its API schemas. Then frontend consumes that definition
-instead of forming full request configuration manually on the client side.
+API contracts are shared definitions that live in a shared package and are consumed by both the client and the backend.
+The contract describes a route — its path, HTTP method, and request/response schemas — and serves as the single source of truth for both sides.
 
-This reduces amount of assumptions FE needs to make about the behaviour of BE, reduces amount of code that needs to be
-written on FE, and makes the code more type-safe (as path parameter setting is handled by logic exposed by BE, in a
-type-safe way).
+The backend implements the route against the contract.
+The client uses the same contract to make type-safe requests without duplicating configuration.
+This eliminates assumptions across the boundary and keeps documentation, validation, and types in sync.
 
-## Universal Contract Builder
+## Defining contracts
 
-Use `buildContract` as a single entry point for creating any type of API contract. It automatically delegates to the appropriate specialized builder based on the configuration:
+### REST routes
 
-| `serverSentEventSchemas` | Contract Type |
-|--------------------------|---------------|
-| ❌ | REST contract (GET, POST, PUT, PATCH, DELETE) |
-| ✅ | SSE or Dual-mode contract |
+```ts
+import { defineApiContract, ContractNoBody } from '@lokalise/api-contracts'
+import { z } from 'zod/v4'
+
+// GET with path params
+const getUser = defineApiContract({
+  method: 'get',
+  requestPathParamsSchema: z.object({ userId: z.uuid() }),
+  pathResolver: ({ userId }) => `/users/${userId}`,
+  responsesByStatusCode: {
+    200: z.object({ id: z.string(), name: z.string() }),
+  },
+})
+
+// POST
+const createUser = defineApiContract({
+  method: 'post',
+  pathResolver: () => '/users',
+  requestBodySchema: z.object({ name: z.string() }),
+  responsesByStatusCode: {
+    201: z.object({ id: z.string(), name: z.string() }),
+  },
+})
+
+// DELETE with no response body
+const deleteUser = defineApiContract({
+  method: 'delete',
+  requestPathParamsSchema: z.object({ userId: z.uuid() }),
+  pathResolver: ({ userId }) => `/users/${userId}`,
+  responsesByStatusCode: {
+    204: ContractNoBody,
+  },
+})
+```
+
+### Non-JSON responses
+
+Use `textResponse` for text-based responses (plain text, CSV, HTML, XML, YAML, etc.):
 
 ```ts
-import { buildContract } from '@lokalise/api-contracts'
-import { z } from 'zod'
+import { defineApiContract, textResponse } from '@lokalise/api-contracts'
 
-// REST GET route
-const getUsers = buildContract({
-    successResponseBodySchema: z.array(userSchema),
-    pathResolver: () => '/api/users',
+const exportCsv = defineApiContract({
+  method: 'get',
+  pathResolver: () => '/export.csv',
+  responsesByStatusCode: { 200: textResponse('text/csv') },
 })
 
-// REST POST route
-const createUser = buildContract({
-    method: 'post',
-    requestBodySchema: createUserSchema,
-    successResponseBodySchema: userSchema,
-    pathResolver: () => '/api/users',
+const getPage = defineApiContract({
+  method: 'get',
+  pathResolver: () => '/page',
+  responsesByStatusCode: { 200: textResponse('text/html') },
 })
 
-// REST DELETE route
-const deleteUser = buildContract({
-    method: 'delete',
-    requestPathParamsSchema: z.object({ userId: z.string() }),
-    pathResolver: (params) => `/api/users/${params.userId}`,
+const getDocument = defineApiContract({
+  method: 'get',
+  pathResolver: () => '/document',
+  responsesByStatusCode: { 200: textResponse('application/xml') },
 })
+```
+
+Use `blobResponse` for binary responses (images, PDFs, etc.):
 
-// SSE-only streaming endpoint
-const notifications = buildContract({
-    method: 'get',
-    pathResolver: () => '/api/notifications/stream',
-    serverSentEventSchemas: {
-        notification: z.object({ id: z.string(), message: z.string() }),
-    },
+```ts
+import { defineApiContract, blobResponse } from '@lokalise/api-contracts'
+
+const downloadPhoto = defineApiContract({
+  method: 'get',
+  pathResolver: () => '/photo.png',
+  responsesByStatusCode: { 200: blobResponse('image/png') },
+})
+```
+
+### SSE and dual-mode routes
+
+Use `sseResponse()` inside `responsesByStatusCode` to define SSE event schemas.
+For endpoints that can respond with either JSON or an SSE stream depending on the `Accept` header, use `anyOfResponses()` to declare both options on the same status code.
+
+```ts
+import { defineApiContract, sseResponse, anyOfResponses } from '@lokalise/api-contracts'
+import { z } from 'zod/v4'
+
+// SSE-only
+const notifications = defineApiContract({
+  method: 'get',
+  pathResolver: () => '/notifications/stream',
+  responsesByStatusCode: {
+    200: sseResponse({
+      notification: z.object({ id: z.string(), message: z.string() }),
+    }),
+  },
 })
 
-// Dual-mode endpoint (supports both JSON and SSE)
-const chatCompletion = buildContract({
-    method: 'post',
-    pathResolver: () => '/api/chat/completions',
-    requestBodySchema: z.object({ message: z.string() }),
-    successResponseBodySchema: z.object({ reply: z.string() }),
-    serverSentEventSchemas: {
+// Dual-mode: JSON response or SSE stream depending on Accept header
+const chatCompletion = defineApiContract({
+  method: 'post',
+  pathResolver: () => '/chat/completions',
+  requestBodySchema: z.object({ message: z.string() }),
+  responsesByStatusCode: {
+    200: anyOfResponses([
+      sseResponse({
         chunk: z.object({ delta: z.string() }),
-        done: z.object({ usage: z.object({ tokens: z.number() }) }),
-    },
+        done: z.object({ finish_reason: z.string() }),
+      }),
+      z.object({ text: z.string() }),
+    ]),
+  },
 })
 ```
 
-You can also use the specialized builders directly (`buildRestContract`, `buildSseContract`) if you prefer explicit control over contract types.
+`getSseSchemaByEventName(contract)` extracts SSE event schemas from a contract:
 
-## REST Contracts
+```ts
+import { getSseSchemaByEventName } from '@lokalise/api-contracts'
 
-Use `buildRestContract` to create REST API contracts. The contract type is automatically determined based on the configuration:
+getSseSchemaByEventName(notifications)
+// { notification: ZodObject<...> }
 
-| `method` | `requestBodySchema` | Result |
-|----------|---------------------|--------|
-| omitted/undefined | ❌ | GET route |
-| `'delete'` | ❌ | DELETE route |
-| `'post'`/`'put'`/`'patch'` | ✅ | Payload route |
+getSseSchemaByEventName(chatCompletion)
+// { chunk: ZodObject<...>, done: ZodObject<...> }
+```
 
-Usage examples:
+### All fields
 
 ```ts
-import { buildRestContract } from '@lokalise/api-contracts'
-
-// GET route - method is inferred automatically
-const getContract = buildRestContract({
-    successResponseBodySchema: RESPONSE_BODY_SCHEMA,
-    requestPathParamsSchema: REQUEST_PATH_PARAMS_SCHEMA,
-    requestQuerySchema: REQUEST_QUERY_SCHEMA,
-    requestHeaderSchema: REQUEST_HEADER_SCHEMA,
-    responseHeaderSchema: RESPONSE_HEADER_SCHEMA,
-    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
-    summary: 'Route summary',
-    metadata: { allowedRoles: ['admin'] },
+defineApiContract({
+  // Required
+  method: 'get' | 'post' | 'put' | 'patch' | 'delete',
+  pathResolver: (pathParams) => string,
+  responsesByStatusCode: {
+    [statusCode]: z.ZodType | ContractNoBody | TypedTextResponse | TypedBlobResponse | TypedSseResponse | AnyOfResponses
+  },
+
+  // Path params — links pathResolver parameter type to the schema
+  requestPathParamsSchema: z.ZodObject,
+
+  // Request
+  requestBodySchema: z.ZodType | ContractNoBody, // required for POST / PUT / PATCH, forbidden otherwise
+  requestQuerySchema: z.ZodObject,
+  requestHeaderSchema: z.ZodObject,
+
+  // Response
+  responseHeaderSchema: z.ZodObject,
+
+  // Documentation
+  summary: string,
+  description: string,
+  tags: readonly string[],
+  metadata: Record<string, unknown>,
 })
+```
 
-// POST route - requires method and requestBodySchema
-const postContract = buildRestContract({
-    method: 'post', // can also be 'put' or 'patch'
-    successResponseBodySchema: RESPONSE_BODY_SCHEMA,
-    requestBodySchema: REQUEST_BODY_SCHEMA,
-    pathResolver: () => '/',
-    summary: 'Route summary',
-    metadata: { allowedPermission: ['edit'] },
-})
+### Header schemas
 
-// DELETE route - method is 'delete', no body, defaults isEmptyResponseExpected to true
-const deleteContract = buildRestContract({
-    method: 'delete',
-    successResponseBodySchema: RESPONSE_BODY_SCHEMA,
-    requestPathParamsSchema: REQUEST_PATH_PARAMS_SCHEMA,
-    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
+```ts
+const contract = defineApiContract({
+  method: 'get',
+  pathResolver: () => '/api/data',
+  requestHeaderSchema: z.object({
+    authorization: z.string(),
+    'x-api-key': z.string(),
+  }),
+  responseHeaderSchema: z.object({
+    'x-ratelimit-remaining': z.string(),
+    'cache-control': z.string(),
+  }),
+  responsesByStatusCode: {
+    200: dataSchema,
+  },
 })
 ```
 
-### Deprecated Builders
+### Type utilities
 
-The individual builders `buildGetRoute`, `buildPayloadRoute`, and `buildDeleteRoute` are deprecated. Use `buildRestContract` instead:
+**`InferNonSseSuccessResponses<T>`** — TypeScript output type of all non-SSE 2xx responses. JSON schemas → `z.output<T>`, `textResponse` → `string`, `blobResponse` → `Blob`, `ContractNoBody` → `undefined`, `sseResponse` → `never` (excluded). `anyOfResponses` entries are unpacked before mapping.
 
 ```ts
-// Before (deprecated):
-import { buildGetRoute, buildPayloadRoute, buildDeleteRoute } from '@lokalise/api-contracts'
-
-const getContract = buildGetRoute({ ... })
-const postContract = buildPayloadRoute({ method: 'post', ... })
-const deleteContract = buildDeleteRoute({ ... })
+import type { InferNonSseSuccessResponses } from '@lokalise/api-contracts'
 
-// After (recommended):
-import { buildRestContract } from '@lokalise/api-contracts'
+type UserResponse = InferNonSseSuccessResponses<typeof getUser['responsesByStatusCode']>
+// { id: string; name: string }
 
-const getContract = buildRestContract({ ... })  // method inferred as 'get'
-const postContract = buildRestContract({ method: 'post', ... })
-const deleteContract = buildRestContract({ method: 'delete', ... })
+type CsvResponse = InferNonSseSuccessResponses<typeof exportCsv['responsesByStatusCode']>
+// string
 ```
 
-In the previous example, the `metadata` property is an optional, free-form field that allows you to store any additional
-information related to the route. If you require more precise type definitions for the `metadata` field, you can utilize
-TypeScript's module augmentation mechanism to enforce stricter typing. This allows for more controlled and type-safe
-usage in your route definitions.
+**`InferJsonSuccessResponses<T>`** — union of Zod schema types for all JSON 2xx entries. Text, Blob, SSE, and `ContractNoBody` entries are excluded.
 
-Here is how you can apply strict typing to the `metadata` property using TypeScript module augmentation:
-```typescript 
-// file -> apiContracts.d.ts
-// Import the existing module to ensure TypeScript recognizes the original definitions
-import '@lokalise/api-contracts';
+**`InferSseSuccessResponses<T>`** — extracts the SSE event schema map type from a `responsesByStatusCode` map. Returns `never` when no SSE schemas are present.
 
-// Augment the module to extend the interface with specific properties
-declare module '@lokalise/api-contracts' {
-    interface CommonRouteDefinitionMetadata {
-        myTestProp?: string[];
-        mySecondTestProp?: number;
-    }
-}
-```
+**`HasAnySseSuccessResponse<T>`** — `true` if any 2xx entry is a `TypedSseResponse` or an `AnyOfResponses` containing one.
 
-Note that in order to make contract-based requests, you need to use a compatible HTTP client
-(`@lokalise/frontend-http-client` or `@lokalise/backend-http-client`)
+**`HasAnyJsonSuccessResponse<T>`** — `true` if any 2xx entry is a JSON Zod schema or an `AnyOfResponses` containing one.
 
-In case you are using fastify on the backend, you can also use `@lokalise/fastify-api-contracts` in order to simplify definition of your fastify routes, utilizing contracts as the single source of truth.
+**`HasAnyNonSseSuccessResponse<T>`** — `true` if any 2xx entry is a non-SSE response (JSON, text, blob, or no-body).
 
-## Header Schemas
+**`IsNoBodySuccessResponse<T>`** — `true` when all 2xx entries are `ContractNoBody` or no 2xx status codes are defined.
 
-### Request Headers (`requestHeaderSchema`)
+**`ContractResponseMode<T>`** — classifies a contract into `'dual'` (SSE + non-SSE), `'sse'` (SSE-only), or `'non-sse'` (JSON/text/blob/no-body).
 
-Use `requestHeaderSchema` to define and validate headers that the client must send with the request. This is useful for authentication headers, API keys, content negotiation, and other request-specific headers.
+**`AvailableResponseModes<T>`** — union of mode literals available for a contract: `'json' | 'sse' | 'blob' | 'text' | 'noContent'`.
+
+**`SseEventOf<S>`** — discriminated union of SSE events inferred from a `schemaByEventName` map. Aligns with the browser `MessageEvent` shape: `{ type, data, lastEventId, retry }`.
 
 ```ts
-import { buildRestContract } from '@lokalise/api-contracts'
-import { z } from 'zod'
-
-const contract = buildRestContract({
-    successResponseBodySchema: DATA_SCHEMA,
-    requestHeaderSchema: z.object({
-        'authorization': z.string(),
-        'x-api-key': z.string(),
-        'accept-language': z.string().optional(),
-    }),
-    pathResolver: () => '/api/data',
-})
+import type { SseEventOf, InferSseSuccessResponses } from '@lokalise/api-contracts'
+
+type NotificationEvents = InferSseSuccessResponses<typeof notifications['responsesByStatusCode']>
+type NotificationEvent = SseEventOf<NotificationEvents>
+// { type: 'notification'; data: { id: string; message: string }; lastEventId: string; retry: number | undefined }
 ```
 
-### Response Headers (`responseHeaderSchema`)
+### Client types
 
-Use `responseHeaderSchema` to define and validate headers that the server will send in the response. This is particularly useful for documenting:
-- Rate limiting headers
-- Pagination headers
-- Cache control headers
-- Custom API metadata headers
+These types are primarily consumed by HTTP client implementations.
 
-```ts
-import { buildRestContract } from '@lokalise/api-contracts'
-import { z } from 'zod'
-
-const contract = buildRestContract({
-    successResponseBodySchema: DATA_SCHEMA,
-    responseHeaderSchema: z.object({
-        'x-ratelimit-limit': z.string(),
-        'x-ratelimit-remaining': z.string(),
-        'x-ratelimit-reset': z.string(),
-        'cache-control': z.string(),
-    }),
-    pathResolver: () => '/api/data',
-})
-```
+**`ClientRequestParams<TApiContract, TIsStreaming>`** — infers the request parameter object for a contract. Includes `pathParams`, `body`, `queryParams`, `headers` (required when the corresponding schema is defined), `pathPrefix` (always optional), and `streaming` (required for dual-mode contracts, forbidden otherwise).
+
+**`InferSseClientResponse<TApiContract>`** — discriminated union of `{ statusCode, headers, body }` for SSE mode. Success status codes yield `AsyncIterable<SseEventOf<...>>`; error codes yield the declared body type.
+
+**`InferNonSseClientResponse<TApiContract>`** — same shape as above for non-SSE mode. Success status codes yield JSON / `string` / `Blob` / `null`; SSE entries are excluded (`never`).
 
-Both header schemas can be used together in a single contract:
+**`DefaultStreaming<T>`** — `true` for SSE-only contracts, `false` for everything else.
 
 ```ts
-const contract = buildRestContract({
-    successResponseBodySchema: DATA_SCHEMA,
-    requestHeaderSchema: z.object({
-        'authorization': z.string(),
-    }),
-    responseHeaderSchema: z.object({
-        'x-ratelimit-limit': z.string(),
-        'x-ratelimit-remaining': z.string(),
-    }),
-    pathResolver: () => '/api/data',
-})
+import type { ClientRequestParams, InferNonSseClientResponse } from '@lokalise/api-contracts'
+
+type GetUserParams = ClientRequestParams<typeof getUser, false>
+// { pathParams: { userId: string }; pathPrefix?: string }
+
+type GetUserResponse = InferNonSseClientResponse<typeof getUser>
+// { statusCode: 200; headers: Record<string, string>; body: { id: string; name: string } }
 ```
 
-These header schemas are primarily used for:
-- OpenAPI/Swagger documentation generation
-- Client-side validation of response headers
-- Type-safe header access in TypeScript
-- Contract testing between frontend and backend
+### Contract type aliases
 
-## Utility Functions
+**`ApiContract`** — union of all contract variants (`GetApiContract | DeleteApiContract | PayloadApiContract`). Use this to type function parameters that accept any contract.
 
-### `mapRouteToPath`
+**`GetApiContract`**, **`DeleteApiContract`**, **`PayloadApiContract`** — individual contract variants if you need to narrow the type.
 
-Converts a route definition to its corresponding path pattern with parameter placeholders.
+**`RequestPathParamsSchema`**, **`RequestQuerySchema`**, **`RequestHeaderSchema`**, **`ResponseHeaderSchema`** — type aliases for `z.ZodObject`. Use these to constrain schema arguments in generic helpers.
 
-```ts
-import { mapRouteToPath, buildRestContract } from '@lokalise/api-contracts'
+### Utility functions
 
-const userContract = buildRestContract({
-    requestPathParamsSchema: z.object({ userId: z.string() }),
-    successResponseBodySchema: USER_SCHEMA,
-    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
-})
+**`mapApiContractToPath`** — Express/Fastify-style path pattern.
+
+```ts
+import { mapApiContractToPath } from '@lokalise/api-contracts'
 
-const pathPattern = mapRouteToPath(userContract)
-// Returns: "/users/:userId"
+mapApiContractToPath(getUser) // "/users/:userId"
 ```
 
-This function is useful when you need to:
-- Generate OpenAPI/Swagger documentation
-- Create route patterns for server-side routing frameworks
-- Display route information in debugging or logging
+**`describeApiContract`** — human-readable `"METHOD /path"` string.
 
-The function replaces actual path parameters with placeholder syntax (`:paramName`), making it compatible with Express-style route patterns.
+```ts
+import { describeApiContract } from '@lokalise/api-contracts'
 
-### `describeContract`
+describeApiContract(getUser) // "GET /users/:userId"
+```
 
-Generates a human-readable description of a route contract, combining the HTTP method with the route path.
+**`getSuccessResponseSchema`** — merged Zod schema from all 2xx JSON entries. `ContractNoBody` and non-JSON entries are excluded. Returns `null` when no schema is present.
 
 ```ts
-import { describeContract, buildRestContract } from '@lokalise/api-contracts'
+import { getSuccessResponseSchema } from '@lokalise/api-contracts'
 
-const getContract = buildRestContract({
-    requestPathParamsSchema: z.object({ userId: z.string() }),
-    successResponseBodySchema: USER_SCHEMA,
-    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
-})
+getSuccessResponseSchema(getUser)    // ZodObject
+getSuccessResponseSchema(deleteUser) // null
+```
 
-const postContract = buildRestContract({
-    method: 'post',
-    requestPathParamsSchema: z.object({
-        orgId: z.string(),
-        userId: z.string()
-    }),
-    requestBodySchema: CREATE_USER_SCHEMA,
-    successResponseBodySchema: USER_SCHEMA,
-    pathResolver: (pathParams) => `/orgs/${pathParams.orgId}/users/${pathParams.userId}`,
-})
+**`getIsEmptyResponseExpected`** — `true` when no Zod schema exists among 2xx entries.
 
-console.log(describeContract(getContract))  // "GET /users/:userId"
-console.log(describeContract(postContract)) // "POST /orgs/:orgId/users/:userId"
-```
+```ts
+import { getIsEmptyResponseExpected } from '@lokalise/api-contracts'
 
-This function is particularly useful for:
-- Logging and debugging API calls
-- Generating documentation or route summaries
-- Error messages that need to reference specific endpoints
-- Test descriptions and assertions
+getIsEmptyResponseExpected(deleteUser) // true
+getIsEmptyResponseExpected(getUser)    // false
+```
 
-## SSE and Dual-Mode Contracts
+**`hasAnySuccessSseResponse`** — `true` when any 2xx entry is an SSE response (including inside `anyOfResponses`).
 
-Use `buildSseContract` for endpoints that support Server-Sent Events (SSE) streaming. This builder supports two contract types:
+```ts
+import { hasAnySuccessSseResponse } from '@lokalise/api-contracts'
 
-### SSE-Only Contracts
+hasAnySuccessSseResponse(notifications)   // true
+hasAnySuccessSseResponse(getUser)         // false
+hasAnySuccessSseResponse(chatCompletion)  // true (dual-mode)
+```
 
-Pure streaming endpoints that only return SSE events. Use these for real-time notifications, live feeds, or any endpoint that only streams data.
+**`getSseSchemaByEventName`** — extracts SSE event schemas from a contract. Returns `null` when no SSE schemas are present.
 
 ```ts
-import { buildSseContract } from '@lokalise/api-contracts'
-import { z } from 'zod'
-
-// GET SSE endpoint for live notifications
-// requestPathParamsSchema, requestQuerySchema, requestHeaderSchema are optional
-const notificationsStream = buildSseContract({
-    method: 'get',
-    pathResolver: () => '/api/notifications/stream',
-    requestQuerySchema: z.object({ userId: z.string().optional() }),
-    serverSentEventSchemas: {
-        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',
-    requestBodySchema: z.object({ fileId: z.string() }),
-    serverSentEventSchemas: {
-        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({
-    method: 'get',
-    pathResolver: (params) => `/api/channels/${params.channelId}/stream`,
-    requestPathParamsSchema: z.object({ channelId: z.string() }),
-    requestHeaderSchema: z.object({ authorization: z.string() }),
-    serverSentEventSchemas: {
-        message: z.object({ text: z.string() }),
-    },
-    // Errors returned before streaming begins
-    responseBodySchemasByStatusCode: {
-        401: z.object({ error: z.literal('Unauthorized') }),
-        404: z.object({ error: z.literal('Channel not found') }),
-    },
-})
+import { getSseSchemaByEventName } from '@lokalise/api-contracts'
+
+getSseSchemaByEventName(notifications) // { notification: ZodObject<...> }
+getSseSchemaByEventName(getUser)       // null
 ```
 
-### Dual-Mode (Hybrid) Contracts
+## Module augmentation
 
-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
+If you require more precise type definitions for the `metadata` field, you can utilize TypeScript's module augmentation mechanism to enforce stricter typing:
 
-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.
+```typescript
+// file -> apiContracts.d.ts
+import '@lokalise/api-contracts';
 
-```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',
-    requestBodySchema: z.object({ message: z.string() }),
-    // Adding successResponseBodySchema makes it dual-mode
-    successResponseBodySchema: z.object({
-        reply: z.string(),
-        usage: z.object({ tokens: z.number() }),
-    }),
-    serverSentEventSchemas: {
-        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({
-    method: 'get',
-    pathResolver: (params) => `/api/jobs/${params.jobId}/status`,
-    requestPathParamsSchema: z.object({ jobId: z.string().uuid() }),
-    requestQuerySchema: z.object({ verbose: z.string().optional() }),
-    successResponseBodySchema: z.object({
-        status: z.enum(['pending', 'running', 'completed', 'failed']),
-        progress: z.number(),
-    }),
-    serverSentEventSchemas: {
-        progress: z.object({ percent: z.number() }),
-        done: z.object({ result: z.string() }),
-    },
-})
-// Result: isDualMode: true
+declare module '@lokalise/api-contracts' {
+  interface CommonRouteDefinitionMetadata {
+    myTestProp?: string[];
+    mySecondTestProp?: number;
+  }
+}
 ```
 
-### Response Schemas by Status Code
+## HTTP clients
 
-Both SSE-only and dual-mode contracts support `responseBodySchemasByStatusCode` for defining different response shapes for errors that occur **before streaming starts** (e.g., authentication failures, validation errors, resource not found):
+To make contract-based requests, use a compatible HTTP client (`@lokalise/frontend-http-client` or `@lokalise/backend-http-client`).
 
-```ts
-const chatCompletion = buildSseContract({
-    method: 'post',
-    pathResolver: () => '/api/chat/completions',
-    requestHeaderSchema: z.object({ authorization: z.string() }),
-    requestBodySchema: z.object({ message: z.string() }),
-    successResponseBodySchema: z.object({ reply: z.string() }),
-    serverSentEventSchemas: {
-        chunk: z.object({ delta: z.string() }),
-    },
-    responseBodySchemasByStatusCode: {
-        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() }),
-    },
-})
-```
+For Fastify backends, use `@lokalise/fastify-api-contracts` to simplify route definition using contracts as the single source of truth.
 
-### Contract Type Detection
+## Future: request body content type
 
-`buildSseContract` automatically determines the contract type based on the presence of `successResponseBodySchema`:
+Currently, HTTP clients default to `application/json` when a request body is present. The planned improvement is a `requestBodyContentType` field on `defineApiContract`:
 
-| `successResponseBodySchema` | `requestBodySchema` | Result |
-|----------------------------|---------------------|--------|
-| ❌ | ❌ | SSE-only GET |
-| ❌ | ✅ | SSE-only POST/PUT/PATCH |
-| ✅ | ❌ | Dual-mode GET |
-| ✅ | ✅ | Dual-mode POST/PUT/PATCH |
+```ts
+defineApiContract({
+  method: 'post',
+  pathResolver: () => '/upload',
+  requestBodySchema: z.object({ file: z.unknown() }),
+  requestBodyContentType: 'multipart/form-data',
+  responsesByStatusCode: { 200: z.object({ url: z.string() }) },
+})
+```

package/dist/apiContracts.d.ts

@@ -59,7 +59,7 @@ export type DeleteRouteDefinition<SuccessResponseBodySchema extends z.Schema | u
     method: 'delete';
 };
 /**
- * @deprecated Use `buildRestContract` instead. This function will be removed in a future version.
+ * @deprecated Use `defineApiContract` instead. This function will be removed in a future version.
  * @example
  * ```typescript
  * // Before (deprecated):
@@ -71,17 +71,17 @@ export type DeleteRouteDefinition<SuccessResponseBodySchema extends z.Schema | u
  * })
  *
  * // After (recommended):
- * const route = buildRestContract({
+ * const route = defineApiContract({
  *   method: 'post',
  *   requestBodySchema: bodySchema,
- *   successResponseBodySchema: responseSchema,
  *   pathResolver: () => '/api/users',
+ *   responsesByStatusCode: { 201: responseSchema },
  * })
  * ```
  */
 export declare function buildPayloadRoute<RequestBodySchema extends z.Schema | undefined = undefined, SuccessResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, ResponseHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined>(params: PayloadRouteDefinition<RequestBodySchema, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>): PayloadRouteDefinition<RequestBodySchema, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>;
 /**
- * @deprecated Use `buildRestContract` instead. This function will be removed in a future version.
+ * @deprecated Use `defineApiContract` instead. This function will be removed in a future version.
  * @example
  * ```typescript
  * // Before (deprecated):
@@ -91,34 +91,40 @@ export declare function buildPayloadRoute<RequestBodySchema extends z.Schema | u
  * })
  *
  * // After (recommended):
- * const route = buildRestContract({
- *   successResponseBodySchema: responseSchema,
+ * const route = defineApiContract({
+ *   method: 'get',
  *   pathResolver: () => '/api/users',
+ *   responsesByStatusCode: { 200: responseSchema },
  * })
  * ```
  */
 export declare function buildGetRoute<SuccessResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, ResponseHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined>(params: Omit<GetRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>, 'method'>): GetRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>;
 /**
- * @deprecated Use `buildRestContract` instead. This function will be removed in a future version.
+ * @deprecated Use `defineApiContract` instead. This function will be removed in a future version.
  * @example
  * ```typescript
  * // Before (deprecated):
  * const route = buildDeleteRoute({
- *   successResponseBodySchema: responseSchema,
- *   pathResolver: () => '/api/users/123',
+ *   requestPathParamsSchema: z.object({ userId: z.string() }),
+ *   pathResolver: (params) => `/api/users/${params.userId}`,
  * })
  *
  * // After (recommended):
- * const route = buildRestContract({
+ * const route = defineApiContract({
  *   method: 'delete',
- *   successResponseBodySchema: responseSchema,
- *   pathResolver: () => '/api/users/123',
+ *   requestPathParamsSchema: z.object({ userId: z.string() }),
+ *   pathResolver: ({ userId }) => `/api/users/${userId}`,
+ *   responsesByStatusCode: { 204: ContractNoBody },
  * })
  * ```
  */
 export declare function buildDeleteRoute<SuccessResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, ResponseHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = true, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined>(params: Omit<DeleteRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>, 'method'>): DeleteRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>;
 /**
- * This method maps given route definition to a string of the format '/static-path-part/:path-param-value'
+ * @deprecated Use `mapApiContractToPath` instead.
+ * Maps a route definition to a path string of the format '/static-path-part/:path-param-value'.
  */
 export declare function mapRouteToPath(routeDefinition: CommonRouteDefinition<any, any, any, any, any, any, any, any>): string;
+/**
+ * @deprecated Use `describeApiContract` instead.
+ */
 export declare function describeContract(contract: PayloadRouteDefinition<any, any, any, any, any, any, any, any, any> | GetRouteDefinition<any, any, any, any, any, any, any, any> | DeleteRouteDefinition<any, any, any, any, any, any, any, any>): string;

package/dist/apiContracts.js

@@ -1,6 +1,6 @@
 const EMPTY_PARAMS = {};
 /**
- * @deprecated Use `buildRestContract` instead. This function will be removed in a future version.
+ * @deprecated Use `defineApiContract` instead. This function will be removed in a future version.
  * @example
  * ```typescript
  * // Before (deprecated):
@@ -12,11 +12,11 @@ const EMPTY_PARAMS = {};
  * })
  *
  * // After (recommended):
- * const route = buildRestContract({
+ * const route = defineApiContract({
  *   method: 'post',
  *   requestBodySchema: bodySchema,
- *   successResponseBodySchema: responseSchema,
  *   pathResolver: () => '/api/users',
+ *   responsesByStatusCode: { 201: responseSchema },
  * })
  * ```
  */
@@ -40,7 +40,7 @@ export function buildPayloadRoute(params) {
     };
 }
 /**
- * @deprecated Use `buildRestContract` instead. This function will be removed in a future version.
+ * @deprecated Use `defineApiContract` instead. This function will be removed in a future version.
  * @example
  * ```typescript
  * // Before (deprecated):
@@ -50,9 +50,10 @@ export function buildPayloadRoute(params) {
  * })
  *
  * // After (recommended):
- * const route = buildRestContract({
- *   successResponseBodySchema: responseSchema,
+ * const route = defineApiContract({
+ *   method: 'get',
  *   pathResolver: () => '/api/users',
+ *   responsesByStatusCode: { 200: responseSchema },
  * })
  * ```
  */
@@ -75,20 +76,21 @@ export function buildGetRoute(params) {
     };
 }
 /**
- * @deprecated Use `buildRestContract` instead. This function will be removed in a future version.
+ * @deprecated Use `defineApiContract` instead. This function will be removed in a future version.
  * @example
  * ```typescript
  * // Before (deprecated):
  * const route = buildDeleteRoute({
- *   successResponseBodySchema: responseSchema,
- *   pathResolver: () => '/api/users/123',
+ *   requestPathParamsSchema: z.object({ userId: z.string() }),
+ *   pathResolver: (params) => `/api/users/${params.userId}`,
  * })
  *
  * // After (recommended):
- * const route = buildRestContract({
+ * const route = defineApiContract({
  *   method: 'delete',
- *   successResponseBodySchema: responseSchema,
- *   pathResolver: () => '/api/users/123',
+ *   requestPathParamsSchema: z.object({ userId: z.string() }),
+ *   pathResolver: ({ userId }) => `/api/users/${userId}`,
+ *   responsesByStatusCode: { 204: ContractNoBody },
  * })
  * ```
  */
@@ -111,7 +113,8 @@ export function buildDeleteRoute(params) {
     };
 }
 /**
- * This method maps given route definition to a string of the format '/static-path-part/:path-param-value'
+ * @deprecated Use `mapApiContractToPath` instead.
+ * Maps a route definition to a path string of the format '/static-path-part/:path-param-value'.
  */
 export function mapRouteToPath(
 // biome-ignore lint/suspicious/noExplicitAny: We don't care about types here, we just need Zod schema
@@ -126,6 +129,9 @@ routeDefinition) {
     }
     return routeDefinition.pathResolver(resolverParams);
 }
+/**
+ * @deprecated Use `describeApiContract` instead.
+ */
 export function describeContract(contract) {
     return `${contract.method.toUpperCase()} ${mapRouteToPath(contract)}`;
 }

package/dist/apiContracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"apiContracts.js","sourceRoot":"","sources":["../src/apiContracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apiContracts.js","sourceRoot":"","sources":["../src/apiContracts.ts"],"names":[],"mappings":"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"}

package/dist/contractBuilder.d.ts

@@ -7,6 +7,26 @@ import { type DualModeGetContractConfig, type DualModePayloadContractConfig, typ
 import type { SSEContractDefinition } from './sse/sseContracts.ts';
 import type { SSEEventSchemas } from './sse/sseTypes.ts';
 /**
+ * @deprecated Use `defineApiContract` instead. This function will be removed in a future version.
+ * @example
+ * ```typescript
+ * // Before (deprecated):
+ * const contract = buildContract({
+ *   method: 'post',
+ *   requestBodySchema: bodySchema,
+ *   successResponseBodySchema: responseSchema,
+ *   pathResolver: () => '/api/resource',
+ * })
+ *
+ * // After (recommended):
+ * const contract = defineApiContract({
+ *   method: 'post',
+ *   requestBodySchema: bodySchema,
+ *   pathResolver: () => '/api/resource',
+ *   responsesByStatusCode: { 201: responseSchema },
+ * })
+ * ```
+ *
  * Universal contract builder that creates either REST or SSE contracts based on configuration.
  *
  * This is a unified entry point that delegates to:

package/dist/contractBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"contractBuilder.js","sourceRoot":"","sources":["../src/contractBuilder.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,iBAAiB,GAIlB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,gBAAgB,GAKjB,MAAM,8BAA8B,CAAA;AAuTrC,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E,MAAM,UAAU,aAAa;AAC3B,wEAAwE;AACxE,MAAW;IAGX,MAAM,YAAY,GAChB,wBAAwB,IAAI,MAAM,IAAI,MAAM,CAAC,sBAAsB,KAAK,SAAS,CAAA;IAEnF,IAAI,YAAY,EAAE,CAAC;QACjB,mCAAmC;QACnC,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAA;IACjC,CAAC;IAED,oCAAoC;IACpC,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAA;AAClC,CAAC"}
+{"version":3,"file":"contractBuilder.js","sourceRoot":"","sources":["../src/contractBuilder.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,iBAAiB,GAIlB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EACL,gBAAgB,GAKjB,MAAM,8BAA8B,CAAA;AA2UrC,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E,MAAM,UAAU,aAAa;AAC3B,wEAAwE;AACxE,MAAW;IAGX,MAAM,YAAY,GAChB,wBAAwB,IAAI,MAAM,IAAI,MAAM,CAAC,sBAAsB,KAAK,SAAS,CAAA;IAEnF,IAAI,YAAY,EAAE,CAAC;QACjB,mCAAmC;QACnC,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAA;IACjC,CAAC;IAED,oCAAoC;IACpC,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAA;AAClC,CAAC"}

package/dist/new/contractResponse.d.ts

@@ -21,6 +21,7 @@ export type TypedSseResponse<T extends SseSchemaByEventName = SseSchemaByEventNa
 export declare const sseResponse: <T extends SseSchemaByEventName>(schemaByEventName: T) => TypedSseResponse<T>;
 export declare const isSseResponse: (value: ApiContractResponse) => value is TypedSseResponse;
 export type TypedJsonResponse = z.ZodType;
+export declare const isJsonResponse: (value: ApiContractResponse) => value is TypedJsonResponse;
 export type TypedApiContractResponse = TypedJsonResponse | TypedTextResponse | TypedBlobResponse | TypedSseResponse;
 export type AnyOfResponses<T extends TypedApiContractResponse = TypedApiContractResponse> = {
     readonly _tag: 'AnyOfResponses';

package/dist/new/contractResponse.js

@@ -14,6 +14,7 @@ export const sseResponse = (schemaByEventName) => ({
     schemaByEventName,
 });
 export const isSseResponse = (value) => typeof value === 'object' && value !== null && '_tag' in value && value._tag === 'SseResponse';
+export const isJsonResponse = (value) => typeof value === 'object' && value !== null && !('_tag' in value);
 export const anyOfResponses = (responses) => ({
     _tag: 'AnyOfResponses',
     responses,

package/dist/new/contractResponse.js.map

@@ -1 +1 @@
-{"version":3,"file":"contractResponse.js","sourceRoot":"","sources":["../../src/new/contractResponse.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAO/C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,WAAmB,EAAqB,EAAE,CAAC,CAAC;IACvE,IAAI,EAAE,cAAc;IACpB,WAAW;CACZ,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAA0B,EAA8B,EAAE,CACvF,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,CAAA;AAOjG,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,WAAmB,EAAqB,EAAE,CAAC,CAAC;IACvE,IAAI,EAAE,cAAc;IACpB,WAAW;CACZ,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAA0B,EAA8B,EAAE,CACvF,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,CAAA;AASjG,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,iBAAoB,EACC,EAAE,CAAC,CAAC;IACzB,IAAI,EAAE,aAAa;IACnB,iBAAiB;CAClB,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAA0B,EAA6B,EAAE,CACrF,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,CAAA;AAehG,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,SAAc,EACK,EAAE,CAAC,CAAC;IACvB,IAAI,EAAE,gBAAgB;IACtB,SAAS;CACV,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAA0B,EAA2B,EAAE,CACtF,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAA;AAanG,MAAM,kBAAkB,GAAG,CACzB,KAA+B,EAC/B,WAAmB,EACE,EAAE;IACvB,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IAC1E,CAAC;IAED,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IAC1E,CAAC;IAED,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,WAAW,CAAC,QAAQ,CAAC,mBAAmB,CAAC;YAC9C,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,EAAE;YAC7D,CAAC,CAAC,IAAI,CAAA;IACV,CAAC;IAED,IAAI,WAAW,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;IACxC,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED,MAAM,aAAa,GAAG,CAAC,KAA+B,EAAgB,EAAE;IACtE,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;IACzB,CAAC;IACD,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;IACzB,CAAC;IACD,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,EAAE,CAAA;IACpE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AACxC,CAAC,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,WAAgC,EAChC,WAA+B,EAC/B,MAAM,GAAG,IAAI,EACQ,EAAE;IACvB,IAAI,WAAW,KAAK,cAAc,EAAE,CAAC;QACnC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAA;IAC9B,CAAC;IAED,IAAI,gBAAgB,CAAC,WAAW,CAAC,EAAE,CAAC;QAClC,+FAA+F;QAC/F,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;YACzC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;YACtD,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,QAAQ,CAAA;YACjB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAA;IACnD,CAAC;IAED,MAAM,OAAO,GAAG,kBAAkB,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;IAE5D,OAAO,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAA;AAChE,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,qBAA4C,EAC5C,UAAkB,EAClB,WAA+B,EAC/B,iBAA0B;IAE1B,MAAM,WAAW,GAAG,qBAAqB,CAAC,UAA4B,CAAC,CAAA;IAEvE,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,uBAAuB,CAAC,WAAW,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAA;AAC7E,CAAC"}
+{"version":3,"file":"contractResponse.js","sourceRoot":"","sources":["../../src/new/contractResponse.ts"],"names":[],"mappings":"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"}

package/dist/rest/restContractBuilder.d.ts

@@ -32,6 +32,26 @@ export type PayloadContractConfig<RequestBodySchema extends z.Schema | undefined
     serverSentEventSchemas?: never;
 };
 /**
+ * @deprecated Use `defineApiContract` instead. This function will be removed in a future version.
+ * @example
+ * ```typescript
+ * // Before (deprecated):
+ * const contract = buildRestContract({
+ *   method: 'get',
+ *   pathResolver: (params) => `/users/${params.userId}`,
+ *   requestPathParamsSchema: z.object({ userId: z.string() }),
+ *   successResponseBodySchema: userSchema,
+ * })
+ *
+ * // After (recommended):
+ * const contract = defineApiContract({
+ *   method: 'get',
+ *   pathResolver: ({ userId }) => `/users/${userId}`,
+ *   requestPathParamsSchema: z.object({ userId: z.string() }),
+ *   responsesByStatusCode: { 200: userSchema },
+ * })
+ * ```
+ *
  * Builds REST API contracts with automatic type inference.
  *
  * This unified builder replaces the individual `buildGetRoute`, `buildPayloadRoute`,

package/dist/rest/restContractBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"restContractBuilder.js","sourceRoot":"","sources":["../../src/rest/restContractBuilder.ts"],"names":[],"mappings":"AAiSA,iBAAiB;AACjB,MAAM,UAAU,iBAAiB,CAC/B,MAKsE;IAGtE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IAEzB,MAAM,UAAU,GAAG;QACjB,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,IAAI,MAAM,KAAK,QAAQ;QAC9E,yBAAyB,EAAE,MAAM,CAAC,yBAAyB,IAAI,KAAK;QACpE,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;QACjD,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;QACvD,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,yBAAyB,EAAE,MAAM,CAAC,yBAAyB;QAC3D,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,2BAA2B,EAAE,MAAM,CAAC,2BAA2B;QAC/D,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAA;IAED,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QAChE,OAAO;YACL,GAAG,UAAU;YACb,MAAM;YACN,qFAAqF;YACrF,iBAAiB,EAAG,MAAqC,CAAC,iBAAiB;SAC5E,CAAA;IACH,CAAC;IAED,OAAO;QACL,GAAG,UAAU;QACb,MAAM;KACP,CAAA;AACH,CAAC"}
+{"version":3,"file":"restContractBuilder.js","sourceRoot":"","sources":["../../src/rest/restContractBuilder.ts"],"names":[],"mappings":"AAqTA,iBAAiB;AACjB,MAAM,UAAU,iBAAiB,CAC/B,MAKsE;IAGtE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IAEzB,MAAM,UAAU,GAAG;QACjB,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,IAAI,MAAM,KAAK,QAAQ;QAC9E,yBAAyB,EAAE,MAAM,CAAC,yBAAyB,IAAI,KAAK;QACpE,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;QACjD,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;QACvD,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,yBAAyB,EAAE,MAAM,CAAC,yBAAyB;QAC3D,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,2BAA2B,EAAE,MAAM,CAAC,2BAA2B;QAC/D,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAA;IAED,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QAChE,OAAO;YACL,GAAG,UAAU;YACb,MAAM;YACN,qFAAqF;YACrF,iBAAiB,EAAG,MAAqC,CAAC,iBAAiB;SAC5E,CAAA;IACH,CAAC;IAED,OAAO;QACL,GAAG,UAAU;QACb,MAAM;KACP,CAAA;AACH,CAAC"}

package/dist/sse/sseContractBuilders.js

@@ -1,4 +1,41 @@
 /**
+ * @deprecated Use `defineApiContract` with `sseResponse()` or `anyOfResponses()` instead. This function will be removed in a future version.
+ * @example
+ * ```typescript
+ * // SSE-only — Before (deprecated):
+ * const contract = buildSseContract({
+ *   method: 'get',
+ *   pathResolver: () => '/stream',
+ *   serverSentEventSchemas: { event: eventSchema },
+ * })
+ *
+ * // SSE-only — After (recommended):
+ * const contract = defineApiContract({
+ *   method: 'get',
+ *   pathResolver: () => '/stream',
+ *   responsesByStatusCode: { 200: sseResponse({ event: eventSchema }) },
+ * })
+ *
+ * // Dual-mode — Before (deprecated):
+ * const contract = buildSseContract({
+ *   method: 'post',
+ *   pathResolver: () => '/stream',
+ *   requestBodySchema: bodySchema,
+ *   successResponseBodySchema: jsonSchema,
+ *   serverSentEventSchemas: { chunk: chunkSchema },
+ * })
+ *
+ * // Dual-mode — After (recommended):
+ * const contract = defineApiContract({
+ *   method: 'post',
+ *   pathResolver: () => '/stream',
+ *   requestBodySchema: bodySchema,
+ *   responsesByStatusCode: {
+ *     200: anyOfResponses([sseResponse({ chunk: chunkSchema }), jsonSchema]),
+ *   },
+ * })
+ * ```
+ *
  * Builds SSE (Server-Sent Events) and dual-mode contracts.
  *
  * This builder supports two contract types:

package/dist/sse/sseContractBuilders.js.map

@@ -1 +1 @@
-{"version":3,"file":"sseContractBuilders.js","sourceRoot":"","sources":["../../src/sse/sseContractBuilders.ts"],"names":[],"mappings":"AA2MA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,uCAAuC;AACvC,gEAAgE;AAChE,SAAS,eAAe,CAAC,MAAW,EAAE,OAAgB;IACpD,OAAO;QACL,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;QACvD,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS;QACjE,sBAAsB,EAAE,MAAM,CAAC,sBAAsB;QACrD,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAA;AACH,CAAC;AAED,6BAA6B;AAC7B,SAAS,eAAe,CAAC,MAA0B;IACjD,OAAO,MAAM,CAAC,MAAM,CAAA;AACtB,CAAC;AAwHD,iBAAiB;AACjB,MAAM,UAAU,gBAAgB,CAC9B,MAOiD;IAGjD,MAAM,mBAAmB,GACvB,2BAA2B,IAAI,MAAM,IAAI,MAAM,CAAC,yBAAyB,KAAK,SAAS,CAAA;IACzF,MAAM,OAAO,GAAG,mBAAmB,IAAI,MAAM,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,CAAA;IACvF,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,MAA4B,CAAC;YACrD,yBAAyB,EAAG,MAAiD;iBAC1E,yBAAyB;YAC5B,oBAAoB,EAAG,MAA6C,CAAC,oBAAoB;YACzF,+BAA+B,EAAG,MAAwD;iBACvF,+BAA+B;YAClC,UAAU,EAAE,IAAI;SACjB,CAAA;IACH,CAAC;IAED,oBAAoB;IACpB,OAAO;QACL,GAAG,IAAI;QACP,MAAM,EAAE,eAAe,CAAC,MAA4B,CAAC;QACrD,+BAA+B,EAAG,MAAwD;aACvF,+BAA+B;QAClC,KAAK,EAAE,IAAI;KACZ,CAAA;AACH,CAAC"}
+{"version":3,"file":"sseContractBuilders.js","sourceRoot":"","sources":["../../src/sse/sseContractBuilders.ts"],"names":[],"mappings":"AA2MA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AAEH,uCAAuC;AACvC,gEAAgE;AAChE,SAAS,eAAe,CAAC,MAAW,EAAE,OAAgB;IACpD,OAAO;QACL,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;QACvD,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,iBAAiB,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS;QACjE,sBAAsB,EAAE,MAAM,CAAC,sBAAsB;QACrD,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAA;AACH,CAAC;AAED,6BAA6B;AAC7B,SAAS,eAAe,CAAC,MAA0B;IACjD,OAAO,MAAM,CAAC,MAAM,CAAA;AACtB,CAAC;AAwHD,iBAAiB;AACjB,MAAM,UAAU,gBAAgB,CAC9B,MAOiD;IAGjD,MAAM,mBAAmB,GACvB,2BAA2B,IAAI,MAAM,IAAI,MAAM,CAAC,yBAAyB,KAAK,SAAS,CAAA;IACzF,MAAM,OAAO,GAAG,mBAAmB,IAAI,MAAM,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,CAAA;IACvF,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,MAA4B,CAAC;YACrD,yBAAyB,EAAG,MAAiD;iBAC1E,yBAAyB;YAC5B,oBAAoB,EAAG,MAA6C,CAAC,oBAAoB;YACzF,+BAA+B,EAAG,MAAwD;iBACvF,+BAA+B;YAClC,UAAU,EAAE,IAAI;SACjB,CAAA;IACH,CAAC;IAED,oBAAoB;IACpB,OAAO;QACL,GAAG,IAAI;QACP,MAAM,EAAE,eAAe,CAAC,MAA4B,CAAC;QACrD,+BAA+B,EAAG,MAAwD;aACvF,+BAA+B;QAClC,KAAK,EAAE,IAAI;KACZ,CAAA;AACH,CAAC"}

package/package.json

@@ -1,58 +1,57 @@
 {
-    "name": "@lokalise/api-contracts",
-    "version": "6.9.0",
-    "files": [
-        "dist"
-    ],
-    "license": "Apache-2.0",
-    "type": "module",
-    "main": "./dist/index.js",
-    "enableTransparentWorkspaces": "false",
-    "homepage": "https://github.com/lokalise/shared-ts-libs",
-    "repository": {
-        "type": "git",
-        "url": "git://github.com/lokalise/shared-ts-libs.git"
-    },
-    "exports": {
-        ".": "./dist/index.js",
-        "./package.json": "./package.json"
-    },
-    "private": false,
-    "publishConfig": {
-        "access": "public"
-    },
-    "keywords": [
-        "api",
-        "contracts",
-        "contract",
-        "frontend",
-        "backend",
-        "single",
-        "source",
-        "truth"
-    ],
-    "scripts": {
-        "build": "rimraf dist && tsc --project tsconfig.build.json",
-        "lint": "biome check . && tsc",
-        "lint:fix": "biome check --write",
-        "test": "vitest run",
-        "test:ci": "vitest run --coverage",
-        "prepublishOnly": "npm run build",
-        "package-version": "echo $npm_package_version",
-        "postversion": "biome check --write package.json"
-    },
-    "peerDependencies": {
-        "zod": ">=3.25.56"
-    },
-    "devDependencies": {
-        "@biomejs/biome": "^2.4.7",
-        "@lokalise/biome-config": "^3.1.0",
-        "@lokalise/tsconfig": "^3.1.0",
-        "@vitest/coverage-v8": "^4.0.18",
-        "rimraf": "^6.1.2",
-        "typescript": "5.9.3",
-        "vitest": "^4.0.18",
-        "zod": "^4.3.6"
-    },
-    "dependencies": {}
-}
+  "name": "@lokalise/api-contracts",
+  "version": "6.11.0",
+  "files": [
+    "dist"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "enableTransparentWorkspaces": "false",
+  "homepage": "https://github.com/lokalise/shared-ts-libs",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/lokalise/shared-ts-libs.git"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "api",
+    "contracts",
+    "contract",
+    "frontend",
+    "backend",
+    "single",
+    "source",
+    "truth"
+  ],
+  "peerDependencies": {
+    "zod": ">=3.25.56"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.7",
+    "@lokalise/biome-config": "^3.1.0",
+    "@lokalise/tsconfig": "^4.0.0",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.18",
+    "rimraf": "^6.1.2",
+    "typescript": "6.0.3",
+    "vitest": "^4.0.18",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc --project tsconfig.build.json",
+    "lint": "biome check . && tsc",
+    "lint:fix": "biome check --write",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage",
+    "package-version": "echo $npm_package_version",
+    "postversion": "biome check --write package.json"
+  }
+}