@lokalise/api-contracts 5.3.0 → 6.0.0

package/README.md

@@ -18,6 +18,7 @@ const getContract = buildGetRoute({
     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'] },
@@ -63,3 +64,130 @@ Note that in order to make contract-based requests, you need to use a compatible
 (`@lokalise/frontend-http-client` or `@lokalise/backend-http-client`)
 
 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.
+
+## Header Schemas
+
+### Request Headers (`requestHeaderSchema`)
+
+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.
+
+```ts
+import { buildGetRoute } from '@lokalise/api-contracts'
+import { z } from 'zod'
+
+const contract = buildGetRoute({
+    successResponseBodySchema: DATA_SCHEMA,
+    requestHeaderSchema: z.object({
+        'authorization': z.string(),
+        'x-api-key': z.string(),
+        'accept-language': z.string().optional(),
+    }),
+    pathResolver: () => '/api/data',
+})
+```
+
+### Response Headers (`responseHeaderSchema`)
+
+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
+
+```ts
+import { buildGetRoute } from '@lokalise/api-contracts'
+import { z } from 'zod'
+
+const contract = buildGetRoute({
+    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',
+})
+```
+
+Both header schemas can be used together in a single contract:
+
+```ts
+const contract = buildGetRoute({
+    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',
+})
+```
+
+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
+
+## Utility Functions
+
+### `mapRouteToPath`
+
+Converts a route definition to its corresponding path pattern with parameter placeholders.
+
+```ts
+import { mapRouteToPath, buildGetRoute } from '@lokalise/api-contracts'
+
+const userContract = buildGetRoute({
+    requestPathParamsSchema: z.object({ userId: z.string() }),
+    successResponseBodySchema: USER_SCHEMA,
+    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
+})
+
+const pathPattern = mapRouteToPath(userContract)
+// Returns: "/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
+
+The function replaces actual path parameters with placeholder syntax (`:paramName`), making it compatible with Express-style route patterns.
+
+### `describeContract`
+
+Generates a human-readable description of a route contract, combining the HTTP method with the route path.
+
+```ts
+import { describeContract, buildGetRoute, buildPayloadRoute } from '@lokalise/api-contracts'
+
+const getContract = buildGetRoute({
+    requestPathParamsSchema: z.object({ userId: z.string() }),
+    successResponseBodySchema: USER_SCHEMA,
+    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
+})
+
+const postContract = buildPayloadRoute({
+    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}`,
+})
+
+console.log(describeContract(getContract))  // "GET /users/:userId"
+console.log(describeContract(postContract)) // "POST /orgs/:orgId/users/:userId"
+```
+
+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

package/dist/apiContracts.d.ts

@@ -1,18 +1,46 @@
 import type { ZodSchema, z } from 'zod/v4';
 import type { HttpStatusCode } from './HttpStatusCodes.ts';
-export type { HttpStatusCode };
 export type InferSchemaInput<T extends ZodSchema | undefined> = T extends ZodSchema ? z.input<T> : T extends undefined ? undefined : never;
 export type InferSchemaOutput<T extends ZodSchema | undefined> = T extends ZodSchema ? z.infer<T> : T extends undefined ? undefined : never;
 export type RoutePathResolver<PathParams> = (pathParams: PathParams) => string;
 export interface CommonRouteDefinitionMetadata extends Record<string, unknown> {
 }
-export type CommonRouteDefinition<ResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined> = {
+export type CommonRouteDefinition<ResponseBodySchema 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> = {
     isNonJSONResponseExpected?: IsNonJSONResponseExpected;
     isEmptyResponseExpected?: IsEmptyResponseExpected;
     successResponseBodySchema: ResponseBodySchema;
     requestPathParamsSchema?: PathParamsSchema;
     requestQuerySchema?: RequestQuerySchema;
+    /**
+     * Schema for validating request headers.
+     * Used to define and validate headers that the client must send with the request.
+     *
+     * @example
+     * ```ts
+     * requestHeaderSchema: z.object({
+     *   'authorization': z.string(),
+     *   'x-api-key': z.string()
+     * })
+     * ```
+     */
     requestHeaderSchema?: RequestHeaderSchema;
+    /**
+     * Schema for validating response headers.
+     * Used to define and validate headers that the server will send in the response.
+     * This is useful for documenting expected response headers (e.g., rate limit headers,
+     * pagination headers, cache control headers) and can be used by clients to validate
+     * the response they receive.
+     *
+     * @example
+     * ```ts
+     * responseHeaderSchema: z.object({
+     *   'x-ratelimit-limit': z.string(),
+     *   'x-ratelimit-remaining': z.string(),
+     *   'x-ratelimit-reset': z.string()
+     * })
+     * ```
+     */
+    responseHeaderSchema?: ResponseHeaderSchema;
     pathResolver: RoutePathResolver<InferSchemaOutput<PathParamsSchema>>;
     responseSchemasByStatusCode?: ResponseSchemasByStatusCode;
     metadata?: CommonRouteDefinitionMetadata;
@@ -20,21 +48,21 @@ export type CommonRouteDefinition<ResponseBodySchema extends z.Schema | undefine
     summary?: string;
     tags?: readonly string[];
 };
-export type PayloadRouteDefinition<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, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined> = CommonRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode> & {
+export type PayloadRouteDefinition<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> = CommonRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode> & {
     method: 'post' | 'put' | 'patch';
     requestBodySchema: RequestBodySchema;
 };
-export type GetRouteDefinition<SuccessResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined> = CommonRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode> & {
+export type GetRouteDefinition<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> = CommonRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode> & {
     method: 'get';
 };
-export type DeleteRouteDefinition<SuccessResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = true, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined> = CommonRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode> & {
+export type DeleteRouteDefinition<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> = CommonRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, ResponseHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode> & {
     method: 'delete';
 };
-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, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined>(params: PayloadRouteDefinition<RequestBodySchema, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>): PayloadRouteDefinition<RequestBodySchema, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>;
-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, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined>(params: Omit<GetRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>, 'method'>): GetRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>;
-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, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = true, ResponseSchemasByStatusCode extends Partial<Record<HttpStatusCode, z.Schema>> | undefined = undefined>(params: Omit<DeleteRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>, 'method'>): DeleteRouteDefinition<SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected, ResponseSchemasByStatusCode>;
+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>;
+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>;
+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'
  */
-export declare function mapRouteToPath(routeDefinition: CommonRouteDefinition<any, any, any, any, any, any, any>): string;
-export declare function describeContract(contract: PayloadRouteDefinition<any, any, any, any, any, any, any, any> | GetRouteDefinition<any, any, any, any, any, any, any> | DeleteRouteDefinition<any, any, any, any, any, any, any>): string;
+export declare function mapRouteToPath(routeDefinition: CommonRouteDefinition<any, any, any, any, any, any, any, any>): string;
+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

@@ -7,6 +7,7 @@ export function buildPayloadRoute(params) {
         pathResolver: params.pathResolver,
         requestBodySchema: params.requestBodySchema,
         requestHeaderSchema: params.requestHeaderSchema,
+        responseHeaderSchema: params.responseHeaderSchema,
         requestPathParamsSchema: params.requestPathParamsSchema,
         requestQuerySchema: params.requestQuerySchema,
         successResponseBodySchema: params.successResponseBodySchema,
@@ -24,6 +25,7 @@ export function buildGetRoute(params) {
         method: 'get',
         pathResolver: params.pathResolver,
         requestHeaderSchema: params.requestHeaderSchema,
+        responseHeaderSchema: params.responseHeaderSchema,
         requestPathParamsSchema: params.requestPathParamsSchema,
         requestQuerySchema: params.requestQuerySchema,
         successResponseBodySchema: params.successResponseBodySchema,
@@ -41,6 +43,7 @@ export function buildDeleteRoute(params) {
         method: 'delete',
         pathResolver: params.pathResolver,
         requestHeaderSchema: params.requestHeaderSchema,
+        responseHeaderSchema: params.responseHeaderSchema,
         requestPathParamsSchema: params.requestPathParamsSchema,
         requestQuerySchema: params.requestQuerySchema,
         successResponseBodySchema: params.successResponseBodySchema,

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/index.d.ts

@@ -0,0 +1,3 @@
+export * from './apiContracts.ts';
+export * from './HttpStatusCodes.ts';
+export * from './pathUtils.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./apiContracts.js";
+export * from "./HttpStatusCodes.js";
+export * from "./pathUtils.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,gBAAgB,CAAA"}

package/dist/pathUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Builds a request path by combining a base path with an optional path prefix.
+ * Ensures proper slash handling to avoid double slashes or missing slashes.
+ *
+ * @param path - The base path for the request
+ * @param pathPrefix - Optional prefix to prepend to the path
+ * @returns The combined path with proper slash formatting
+ *
+ * @example
+ * ```typescript
+ * buildRequestPath('/api/users') // '/api/users'
+ * buildRequestPath('api/users') // '/api/users'
+ * buildRequestPath('/api/users', 'v1') // '/v1/api/users'
+ * buildRequestPath('/api/users', '/v1/') // '/v1/api/users'
+ * buildRequestPath('api/users', 'v1') // '/v1/api/users'
+ * ```
+ */
+export declare function buildRequestPath(path: string, pathPrefix?: string): string;

package/dist/pathUtils.js

@@ -0,0 +1,30 @@
+/**
+ * Builds a request path by combining a base path with an optional path prefix.
+ * Ensures proper slash handling to avoid double slashes or missing slashes.
+ *
+ * @param path - The base path for the request
+ * @param pathPrefix - Optional prefix to prepend to the path
+ * @returns The combined path with proper slash formatting
+ *
+ * @example
+ * ```typescript
+ * buildRequestPath('/api/users') // '/api/users'
+ * buildRequestPath('api/users') // '/api/users'
+ * buildRequestPath('/api/users', 'v1') // '/v1/api/users'
+ * buildRequestPath('/api/users', '/v1/') // '/v1/api/users'
+ * buildRequestPath('api/users', 'v1') // '/v1/api/users'
+ * ```
+ */
+export function buildRequestPath(path, pathPrefix) {
+    if (!pathPrefix) {
+        return ensureStartsWithSlash(path);
+    }
+    // Remove trailing slash from pathPrefix and leading slash from path
+    const cleanPrefix = pathPrefix.endsWith('/') ? pathPrefix.slice(0, -1) : pathPrefix;
+    const cleanPath = path.startsWith('/') ? path.slice(1) : path;
+    return ensureStartsWithSlash(`${cleanPrefix}/${cleanPath}`);
+}
+function ensureStartsWithSlash(str) {
+    return str.startsWith('/') ? str : `/${str}`;
+}
+//# sourceMappingURL=pathUtils.js.map

package/dist/pathUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathUtils.js","sourceRoot":"","sources":["../src/pathUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,UAAmB;IAChE,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC;IAED,oEAAoE;IACpE,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAA;IACnF,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAE7D,OAAO,qBAAqB,CAAC,GAAG,WAAW,IAAI,SAAS,EAAE,CAAC,CAAA;AAC7D,CAAC;AAED,SAAS,qBAAqB,CAAC,GAAW;IACxC,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAA;AAC9C,CAAC"}

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "@lokalise/api-contracts",
-    "version": "5.3.0",
+    "version": "6.0.0",
     "files": [
         "dist"
     ],
     "license": "Apache-2.0",
     "type": "module",
-    "main": "./dist/apiContracts.js",
+    "main": "./dist/index.js",
     "enableTransparentWorkspaces": "false",
     "homepage": "https://github.com/lokalise/shared-ts-libs",
     "repository": {
@@ -14,7 +14,7 @@
         "url": "git://github.com/lokalise/shared-ts-libs.git"
     },
     "exports": {
-        ".": "./dist/apiContracts.js",
+        ".": "./dist/index.js",
         "./package.json": "./package.json"
     },
     "private": false,
@@ -45,13 +45,13 @@
         "zod": ">=3.25.56"
     },
     "devDependencies": {
-        "@biomejs/biome": "^2.1.4",
+        "@biomejs/biome": "^2.3.2",
         "@lokalise/biome-config": "^3.1.0",
         "@lokalise/tsconfig": "^1.3.0",
-        "@vitest/coverage-v8": "^3.2.2",
+        "@vitest/coverage-v8": "^3.2.4",
         "rimraf": "^6.0.1",
-        "typescript": "5.9.2",
-        "vitest": "^3.2.2",
+        "typescript": "5.9.3",
+        "vitest": "^3.2.4",
         "zod": "^4.0.17"
     },
     "dependencies": {}