@lokalise/api-contracts
Version:
107 lines (106 loc) • 9.14 kB
TypeScript
import type { z } from 'zod/v4';
import type { DeleteRouteDefinition, GetRouteDefinition, PayloadRouteDefinition } from './apiContracts.ts';
import type { HttpStatusCode } from './HttpStatusCodes.ts';
import { type DeleteContractConfig, type GetContractConfig, type PayloadContractConfig } from './rest/restContractBuilder.ts';
import type { DualModeContractDefinition } from './sse/dualModeContracts.ts';
import { type DualModeGetContractConfig, type DualModePayloadContractConfig, type SSEGetContractConfig, type SSEPayloadContractConfig } from './sse/sseContractBuilders.ts';
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:
* - `buildRestContract` when no `serverSentEventSchemas` is provided
* - `buildSseContract` when `serverSentEventSchemas` is provided
*
* ## Contract Type Detection
*
* | `serverSentEventSchemas` | `successResponseBodySchema` | `requestBodySchema` | Result |
* |--------------------|----------------------------|---------------------|--------|
* | ❌ | - | ❌ | REST GET |
* | ❌ | - | ✅ (method: post/put/patch) | REST Payload |
* | ❌ | - | ❌ (method: delete) | REST DELETE |
* | ✅ | ❌ | ❌ | SSE-only GET |
* | ✅ | ❌ | ✅ | SSE-only POST/PUT/PATCH |
* | ✅ | ✅ | ❌ | Dual-mode GET |
* | ✅ | ✅ | ✅ | Dual-mode POST/PUT/PATCH |
*
* @example
* ```typescript
* // REST GET route
* const getUsers = buildContract({
* method: 'get',
* successResponseBodySchema: z.array(userSchema),
* pathResolver: () => '/api/users',
* })
*
* // REST POST route
* const createUser = buildContract({
* method: 'post',
* requestBodySchema: createUserSchema,
* successResponseBodySchema: userSchema,
* pathResolver: () => '/api/users',
* })
*
* // REST DELETE route
* const deleteUser = buildContract({
* method: 'delete',
* pathResolver: (params) => `/api/users/${params.userId}`,
* requestPathParamsSchema: z.object({ userId: z.string() }),
* })
*
* // SSE-only streaming endpoint
* const notifications = buildContract({
* method: 'get',
* pathResolver: () => '/api/notifications/stream',
* requestPathParamsSchema: z.object({}),
* requestQuerySchema: z.object({}),
* requestHeaderSchema: z.object({}),
* serverSentEventSchemas: {
* 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',
* requestPathParamsSchema: z.object({}),
* requestQuerySchema: z.object({}),
* requestHeaderSchema: z.object({}),
* 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() }) }),
* },
* })
* ```
*/
export declare function buildContract<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>(config: GetContractConfig<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>): GetRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>;
export declare function buildContract<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>(config: DeleteContractConfig<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>): DeleteRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>;
export declare function buildContract<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>(config: PayloadContractConfig<RequestBodySchema, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>): PayloadRouteDefinition<RequestBodySchema, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>;
export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, JsonResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined>(config: DualModeGetContractConfig<Params, Query, RequestHeaders, JsonResponse, Events, ResponseHeaders, ResponseSchemasByStatusCode>): DualModeContractDefinition<'get', Params, Query, RequestHeaders, undefined, JsonResponse, Events, ResponseHeaders, ResponseSchemasByStatusCode>;
export declare function buildContract<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>;
export declare function buildContract<Params extends z.ZodTypeAny, Query extends z.ZodTypeAny, RequestHeaders extends z.ZodTypeAny, Body extends z.ZodTypeAny, JsonResponse extends z.ZodTypeAny, Events extends SSEEventSchemas, ResponseHeaders extends z.ZodTypeAny | undefined = undefined, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.ZodTypeAny>> | undefined = undefined>(config: DualModePayloadContractConfig<Params, Query, RequestHeaders, Body, JsonResponse, Events, ResponseHeaders, ResponseSchemasByStatusCode>): DualModeContractDefinition<'post' | 'put' | 'patch', Params, Query, RequestHeaders, Body, JsonResponse, Events, ResponseHeaders, ResponseSchemasByStatusCode>;
export declare function buildContract<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>;