@lokalise/api-contracts 6.5.2 → 6.5.3

package/README.md

@@ -12,8 +12,8 @@ type-safe way).
 
 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:
 
-| `sseEvents` | Contract Type |
-|-------------|---------------|
+| `serverSentEventSchemas` | Contract Type |
+|--------------------------|---------------|
 | ❌ | REST contract (GET, POST, PUT, PATCH, DELETE) |
 | ✅ | SSE or Dual-mode contract |
 
@@ -44,11 +44,9 @@ const deleteUser = buildContract({
 
 // SSE-only streaming endpoint
 const notifications = buildContract({
+    method: 'get',
     pathResolver: () => '/api/notifications/stream',
-    params: z.object({}),
-    query: z.object({}),
-    requestHeaders: z.object({}),
-    sseEvents: {
+    serverSentEventSchemas: {
         notification: z.object({ id: z.string(), message: z.string() }),
     },
 })
@@ -57,12 +55,9 @@ const notifications = buildContract({
 const chatCompletion = buildContract({
     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() }),
-    sseEvents: {
+    requestBodySchema: z.object({ message: z.string() }),
+    successResponseBodySchema: z.object({ reply: z.string() }),
+    serverSentEventSchemas: {
         chunk: z.object({ delta: z.string() }),
         done: z.object({ usage: z.object({ tokens: z.number() }) }),
     },
@@ -302,12 +297,12 @@ 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',
-    params: z.object({}),
-    query: z.object({ userId: z.string().optional() }),
-    requestHeaders: z.object({}),
-    sseEvents: {
+    requestQuerySchema: z.object({ userId: z.string().optional() }),
+    serverSentEventSchemas: {
         notification: z.object({ id: z.string(), message: z.string() }),
     },
 })
@@ -317,11 +312,8 @@ const notificationsStream = buildSseContract({
 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: {
+    requestBodySchema: z.object({ fileId: z.string() }),
+    serverSentEventSchemas: {
         progress: z.object({ percent: z.number() }),
         done: z.object({ result: z.string() }),
     },
@@ -330,15 +322,15 @@ const processStream = buildSseContract({
 
 // SSE endpoint with error schemas (for errors before streaming starts)
 const channelStream = buildSseContract({
+    method: 'get',
     pathResolver: (params) => `/api/channels/${params.channelId}/stream`,
-    params: z.object({ channelId: z.string() }),
-    query: z.object({}),
-    requestHeaders: z.object({ authorization: z.string() }),
-    sseEvents: {
+    requestPathParamsSchema: z.object({ channelId: z.string() }),
+    requestHeaderSchema: z.object({ authorization: z.string() }),
+    serverSentEventSchemas: {
         message: z.object({ text: z.string() }),
     },
     // Errors returned before streaming begins
-    responseSchemasByStatusCode: {
+    responseBodySchemasByStatusCode: {
         401: z.object({ error: z.literal('Unauthorized') }),
         404: z.object({ error: z.literal('Channel not found') }),
     },
@@ -363,16 +355,13 @@ import { z } from 'zod'
 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({
+    requestBodySchema: z.object({ message: z.string() }),
+    // Adding successResponseBodySchema makes it dual-mode
+    successResponseBodySchema: z.object({
         reply: z.string(),
         usage: z.object({ tokens: z.number() }),
     }),
-    sseEvents: {
+    serverSentEventSchemas: {
         chunk: z.object({ delta: z.string() }),
         done: z.object({ usage: z.object({ totalTokens: z.number() }) }),
     },
@@ -381,15 +370,15 @@ const chatCompletion = buildSseContract({
 
 // GET dual-mode endpoint for job status (poll or stream)
 const jobStatus = buildSseContract({
+    method: 'get',
     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({
+    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(),
     }),
-    sseEvents: {
+    serverSentEventSchemas: {
         progress: z.object({ percent: z.number() }),
         done: z.object({ result: z.string() }),
     },
@@ -399,21 +388,19 @@ const jobStatus = buildSseContract({
 
 ### 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):
+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):
 
 ```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: {
+    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() }),
     },
-    responseSchemasByStatusCode: {
+    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() }),
@@ -423,10 +410,10 @@ const chatCompletion = buildSseContract({
 
 ### Contract Type Detection
 
-`buildSseContract` automatically determines the contract type based on the presence of `syncResponseBody`:
+`buildSseContract` automatically determines the contract type based on the presence of `successResponseBodySchema`:
 
-| `syncResponseBody` | `requestBody` | Result |
-|-------------------|---------------|--------|
+| `successResponseBodySchema` | `requestBodySchema` | Result |
+|----------------------------|---------------------|--------|
 | ❌ | ❌ | SSE-only GET |
 | ❌ | ✅ | SSE-only POST/PUT/PATCH |
 | ✅ | ❌ | Dual-mode GET |

package/dist/sse/dualModeContracts.d.ts

@@ -20,9 +20,9 @@ import type { SSEEventSchemas } from './sseTypes.ts';
 export type DualModeContractDefinition<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>>;
-    requestPathParamsSchema: Params;
-    requestQuerySchema: Query;
-    requestHeaderSchema: RequestHeaders;
+    requestPathParamsSchema?: Params;
+    requestQuerySchema?: Query;
+    requestHeaderSchema?: RequestHeaders;
     requestBodySchema: Body;
     /** Sync response schema - use with `sync` handler */
     successResponseBodySchema: SyncResponse;
@@ -50,9 +50,9 @@ export type DualModeContractDefinition<Method extends SSEMethod = SSEMethod, Par
 export type AnyDualModeContractDefinition = {
     method: SSEMethod;
     pathResolver: RoutePathResolver<any>;
-    requestPathParamsSchema: z.ZodTypeAny;
-    requestQuerySchema: z.ZodTypeAny;
-    requestHeaderSchema: z.ZodTypeAny;
+    requestPathParamsSchema?: z.ZodTypeAny;
+    requestQuerySchema?: z.ZodTypeAny;
+    requestHeaderSchema?: z.ZodTypeAny;
     requestBodySchema: z.ZodTypeAny | undefined;
     /** Sync response schema - use with `sync` handler */
     successResponseBodySchema: z.ZodTypeAny;

package/dist/sse/sseContractBuilders.d.ts

@@ -11,9 +11,9 @@ import type { SSEEventSchemas } from './sseTypes.ts';
 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> = {
     method: 'get';
     pathResolver: RoutePathResolver<z.infer<Params>>;
-    requestPathParamsSchema: Params;
-    requestQuerySchema: Query;
-    requestHeaderSchema: RequestHeaders;
+    requestPathParamsSchema?: Params;
+    requestQuerySchema?: Query;
+    requestHeaderSchema?: RequestHeaders;
     serverSentEventSchemas: Events;
     /**
      * Error response schemas by HTTP status code.
@@ -39,9 +39,9 @@ export type SSEGetContractConfig<Params extends z.ZodTypeAny, Query extends z.Zo
 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>>;
-    requestPathParamsSchema: Params;
-    requestQuerySchema: Query;
-    requestHeaderSchema: RequestHeaders;
+    requestPathParamsSchema?: Params;
+    requestQuerySchema?: Query;
+    requestHeaderSchema?: RequestHeaders;
     requestBodySchema: Body;
     serverSentEventSchemas: Events;
     /**
@@ -67,9 +67,9 @@ export type SSEPayloadContractConfig<Params extends z.ZodTypeAny, Query extends
 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> = {
     method: 'get';
     pathResolver: RoutePathResolver<z.infer<Params>>;
-    requestPathParamsSchema: Params;
-    requestQuerySchema: Query;
-    requestHeaderSchema: RequestHeaders;
+    requestPathParamsSchema?: Params;
+    requestQuerySchema?: Query;
+    requestHeaderSchema?: RequestHeaders;
     /** Single sync response schema */
     successResponseBodySchema: JsonResponse;
     /**
@@ -108,9 +108,9 @@ export type DualModeGetContractConfig<Params extends z.ZodTypeAny, Query extends
 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>>;
-    requestPathParamsSchema: Params;
-    requestQuerySchema: Query;
-    requestHeaderSchema: RequestHeaders;
+    requestPathParamsSchema?: Params;
+    requestQuerySchema?: Query;
+    requestHeaderSchema?: RequestHeaders;
     requestBodySchema: Body;
     /** Single sync response schema */
     successResponseBodySchema: JsonResponse;

package/dist/sse/sseContracts.d.ts

@@ -26,9 +26,9 @@ export type SSEContractDefinition<Method extends SSEMethod = SSEMethod, Params e
      * Receives typed params and returns the URL path string.
      */
     pathResolver: RoutePathResolver<z.infer<Params>>;
-    requestPathParamsSchema: Params;
-    requestQuerySchema: Query;
-    requestHeaderSchema: RequestHeaders;
+    requestPathParamsSchema?: Params;
+    requestQuerySchema?: Query;
+    requestHeaderSchema?: RequestHeaders;
     requestBodySchema: Body;
     serverSentEventSchemas: Events;
     /**
@@ -54,9 +54,9 @@ export type SSEContractDefinition<Method extends SSEMethod = SSEMethod, Params e
 export type AnySSEContractDefinition = {
     method: SSEMethod;
     pathResolver: RoutePathResolver<any>;
-    requestPathParamsSchema: z.ZodTypeAny;
-    requestQuerySchema: z.ZodTypeAny;
-    requestHeaderSchema: z.ZodTypeAny;
+    requestPathParamsSchema?: z.ZodTypeAny;
+    requestQuerySchema?: z.ZodTypeAny;
+    requestHeaderSchema?: z.ZodTypeAny;
     requestBodySchema: z.ZodTypeAny | undefined;
     serverSentEventSchemas: SSEEventSchemas;
     responseBodySchemasByStatusCode?: Partial<Record<HttpStatusCode, z.ZodTypeAny>>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lokalise/api-contracts",
-    "version": "6.5.2",
+    "version": "6.5.3",
     "files": [
         "dist"
     ],