@lokalise/api-contracts 6.5.1 → 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/rest/restContractBuilder.js

@@ -1,12 +1,8 @@
 // Implementation
 export function buildRestContract(config) {
-    const method = config.method;
-    const hasBody = 'requestBodySchema' in config && config.requestBodySchema !== undefined;
-    // Determine default for isEmptyResponseExpected based on route type
-    const isDeleteRoute = method === 'delete';
-    const defaultIsEmptyResponseExpected = isDeleteRoute;
+    const { method } = config;
     const baseFields = {
-        isEmptyResponseExpected: config.isEmptyResponseExpected ?? defaultIsEmptyResponseExpected,
+        isEmptyResponseExpected: config.isEmptyResponseExpected ?? method === 'delete',
         isNonJSONResponseExpected: config.isNonJSONResponseExpected ?? false,
         pathResolver: config.pathResolver,
         requestHeaderSchema: config.requestHeaderSchema,
@@ -20,26 +16,17 @@ export function buildRestContract(config) {
         metadata: config.metadata,
         tags: config.tags,
     };
-    if (hasBody) {
-        // Payload route (POST/PUT/PATCH)
+    if (method === 'post' || method === 'put' || method === 'patch') {
         return {
             ...baseFields,
-            method: method,
+            method,
             // biome-ignore lint/suspicious/noExplicitAny: Type assertion needed for config union
             requestBodySchema: config.requestBodySchema,
         };
     }
-    if (isDeleteRoute) {
-        // DELETE route
-        return {
-            ...baseFields,
-            method: 'delete',
-        };
-    }
-    // GET route
     return {
         ...baseFields,
-        method: 'get',
+        method,
     };
 }
 //# sourceMappingURL=restContractBuilder.js.map

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,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;IAC5B,MAAM,OAAO,GAAG,mBAAmB,IAAI,MAAM,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,CAAA;IAEvF,oEAAoE;IACpE,MAAM,aAAa,GAAG,MAAM,KAAK,QAAQ,CAAA;IACzC,MAAM,8BAA8B,GAAG,aAAa,CAAA;IAEpD,MAAM,UAAU,GAAG;QACjB,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,IAAI,8BAA8B;QACzF,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,OAAO,EAAE,CAAC;QACZ,iCAAiC;QACjC,OAAO;YACL,GAAG,UAAU;YACb,MAAM,EAAE,MAAkC;YAC1C,qFAAqF;YACrF,iBAAiB,EAAG,MAAqC,CAAC,iBAAiB;SAC5E,CAAA;IACH,CAAC;IAED,IAAI,aAAa,EAAE,CAAC;QAClB,eAAe;QACf,OAAO;YACL,GAAG,UAAU;YACb,MAAM,EAAE,QAAiB;SAC1B,CAAA;IACH,CAAC;IAED,YAAY;IACZ,OAAO;QACL,GAAG,UAAU;QACb,MAAM,EAAE,KAAc;KACvB,CAAA;AACH,CAAC"}
+{"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"}

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.1",
+    "version": "6.5.3",
     "files": [
         "dist"
     ],