@lokalise/api-contracts 4.1.0

package/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright 2024 Lokalise, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,63 @@
+# 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.
+
+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).
+
+Usage examples:
+
+```ts
+import { buildGetRoute, buildDeleteRoute, buildPayloadRoute } from '@lokalise/api-contracts'
+
+const getContract = buildGetRoute({
+    successResponseBodySchema: RESPONSE_BODY_SCHEMA,
+    requestPathParamsSchema: REQUEST_PATH_PARAMS_SCHEMA,
+    requestQuerySchema: REQUEST_QUERY_SCHEMA,
+    requestHeaderSchema: REQUEST_HEADER_SCHEMA,
+    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
+    metadata: { allowedRoles: ['admin'] },
+})
+
+const postContract = buildPayloadRoute({
+    method: 'post', // can also be 'patch' or 'post'
+    successResponseBodySchema: RESPONSE_BODY_SCHEMA,
+    requestBodySchema: REQUEST_BODY_SCHEMA,
+    pathResolver: () => '/',
+    metadata: { allowedPermission: ['edit'] },
+})
+
+const deleteContract = buildDeleteRoute({
+    successResponseBodySchema: RESPONSE_BODY_SCHEMA,
+    requestPathParamsSchema: REQUEST_PATH_PARAMS_SCHEMA,
+    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
+})
+```
+
+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.
+
+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/apiContracts';
+
+// Augment the module to extend the interface with specific properties
+declare module '@lokalise/api-contracts/apiContracts' {
+    interface CommonRouteDefinitionMetadata {
+        myTestProp?: string[];
+        mySecondTestProp?: number;
+    }
+}
+```
+
+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`)
+
+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.

package/dist/HttpStatusCodes.d.ts

@@ -0,0 +1 @@
+export type HttpStatusCode = 100 | 101 | 102 | 103 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511;

package/dist/HttpStatusCodes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=HttpStatusCodes.js.map

package/dist/HttpStatusCodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpStatusCodes.js","sourceRoot":"","sources":["../src/HttpStatusCodes.ts"],"names":[],"mappings":""}

package/dist/apiContracts.d.ts

@@ -0,0 +1,36 @@
+import type { ZodSchema, z } from 'zod';
+import type { HttpStatusCode } from './HttpStatusCodes.js';
+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<PathParams, ResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema<PathParams> | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false> = {
+    isNonJSONResponseExpected?: IsNonJSONResponseExpected;
+    isEmptyResponseExpected?: IsEmptyResponseExpected;
+    successResponseBodySchema: ResponseBodySchema;
+    requestPathParamsSchema?: PathParamsSchema;
+    requestQuerySchema?: RequestQuerySchema;
+    requestHeaderSchema?: RequestHeaderSchema;
+    pathResolver: RoutePathResolver<InferSchemaOutput<PathParamsSchema>>;
+    responseSchemasByStatusCode?: Partial<Record<HttpStatusCode, z.Schema>>;
+    description?: string;
+    metadata?: CommonRouteDefinitionMetadata;
+};
+export type PayloadRouteDefinition<PathParams, RequestBodySchema extends z.Schema | undefined = undefined, SuccessResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema<PathParams> | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false> = CommonRouteDefinition<PathParams, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected> & {
+    method: 'post' | 'put' | 'patch';
+    requestBodySchema: RequestBodySchema;
+};
+export type GetRouteDefinition<PathParams, SuccessResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema<PathParams> | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = false> = CommonRouteDefinition<PathParams, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected> & {
+    method: 'get';
+};
+export type DeleteRouteDefinition<PathParams, SuccessResponseBodySchema extends z.Schema | undefined = undefined, PathParamsSchema extends z.Schema<PathParams> | undefined = undefined, RequestQuerySchema extends z.Schema | undefined = undefined, RequestHeaderSchema extends z.Schema | undefined = undefined, IsNonJSONResponseExpected extends boolean = false, IsEmptyResponseExpected extends boolean = true> = CommonRouteDefinition<PathParams, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected> & {
+    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, PathParams = PathParamsSchema extends z.Schema<infer T> ? T : never>(params: PayloadRouteDefinition<PathParams, RequestBodySchema, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected>): PayloadRouteDefinition<PathParams, RequestBodySchema, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected>;
+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, PathParams = PathParamsSchema extends z.Schema<infer T> ? T : never>(params: Omit<GetRouteDefinition<PathParams, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected>, 'method'>): GetRouteDefinition<PathParams, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected>;
+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, PathParams = PathParamsSchema extends z.Schema<infer T> ? T : never>(params: Omit<DeleteRouteDefinition<PathParams, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected>, 'method'>): DeleteRouteDefinition<PathParams, SuccessResponseBodySchema, PathParamsSchema, RequestQuerySchema, RequestHeaderSchema, IsNonJSONResponseExpected, IsEmptyResponseExpected>;
+/**
+ * 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;

package/dist/apiContracts.js

@@ -0,0 +1,64 @@
+const EMPTY_PARAMS = {};
+export function buildPayloadRoute(params) {
+    return {
+        isEmptyResponseExpected: params.isEmptyResponseExpected ?? false,
+        isNonJSONResponseExpected: params.isNonJSONResponseExpected ?? false,
+        method: params.method,
+        pathResolver: params.pathResolver,
+        requestBodySchema: params.requestBodySchema,
+        requestHeaderSchema: params.requestHeaderSchema,
+        requestPathParamsSchema: params.requestPathParamsSchema,
+        requestQuerySchema: params.requestQuerySchema,
+        successResponseBodySchema: params.successResponseBodySchema,
+        description: params.description,
+        responseSchemasByStatusCode: params.responseSchemasByStatusCode,
+        metadata: params.metadata,
+    };
+}
+export function buildGetRoute(params) {
+    return {
+        isEmptyResponseExpected: params.isEmptyResponseExpected ?? false,
+        isNonJSONResponseExpected: params.isNonJSONResponseExpected ?? false,
+        method: 'get',
+        pathResolver: params.pathResolver,
+        requestHeaderSchema: params.requestHeaderSchema,
+        requestPathParamsSchema: params.requestPathParamsSchema,
+        requestQuerySchema: params.requestQuerySchema,
+        successResponseBodySchema: params.successResponseBodySchema,
+        description: params.description,
+        responseSchemasByStatusCode: params.responseSchemasByStatusCode,
+        metadata: params.metadata,
+    };
+}
+export function buildDeleteRoute(params) {
+    return {
+        isEmptyResponseExpected: params.isEmptyResponseExpected ?? true,
+        isNonJSONResponseExpected: params.isNonJSONResponseExpected ?? false,
+        method: 'delete',
+        pathResolver: params.pathResolver,
+        requestHeaderSchema: params.requestHeaderSchema,
+        requestPathParamsSchema: params.requestPathParamsSchema,
+        requestQuerySchema: params.requestQuerySchema,
+        successResponseBodySchema: params.successResponseBodySchema,
+        description: params.description,
+        responseSchemasByStatusCode: params.responseSchemasByStatusCode,
+        metadata: params.metadata,
+    };
+}
+/**
+ * This method maps given route definition to a 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
+routeDefinition) {
+    if (!routeDefinition.requestPathParamsSchema) {
+        return routeDefinition.pathResolver(EMPTY_PARAMS);
+    }
+    const shape = routeDefinition.requestPathParamsSchema.shape;
+    const resolverParams = {};
+    for (const key of Object.keys(shape)) {
+        resolverParams[key] = `:${key}`;
+    }
+    return routeDefinition.pathResolver(resolverParams);
+}
+//# sourceMappingURL=apiContracts.js.map

package/dist/apiContracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.js","sourceRoot":"","sources":["../src/apiContracts.ts"],"names":[],"mappings":"AAGA,MAAM,YAAY,GAAG,EAAE,CAAA;AAqGvB,MAAM,UAAU,iBAAiB,CAU/B,MASC;IAWD,OAAO;QACL,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,IAAK,KAAiC;QAC7F,yBAAyB,EACvB,MAAM,CAAC,yBAAyB,IAAK,KAAmC;QAC1E,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,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,2BAA2B,EAAE,MAAM,CAAC,2BAA2B;QAC/D,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAA;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAS3B,MAWC;IAUD,OAAO;QACL,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,IAAK,KAAiC;QAC7F,yBAAyB,EACvB,MAAM,CAAC,yBAAyB,IAAK,KAAmC;QAC1E,MAAM,EAAE,KAAK;QACb,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,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,2BAA2B,EAAE,MAAM,CAAC,2BAA2B;QAC/D,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAA;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAS9B,MAWC;IAUD,OAAO;QACL,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,IAAK,IAAgC;QAC5F,yBAAyB,EACvB,MAAM,CAAC,yBAAyB,IAAK,KAAmC;QAC1E,MAAM,EAAE,QAAQ;QAChB,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,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,2BAA2B,EAAE,MAAM,CAAC,2BAA2B;QAC/D,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;AAC5B,sGAAsG;AACtG,eAAyE;IAEzE,IAAI,CAAC,eAAe,CAAC,uBAAuB,EAAE,CAAC;QAC7C,OAAO,eAAe,CAAC,YAAY,CAAC,YAAY,CAAC,CAAA;IACnD,CAAC;IACD,MAAM,KAAK,GAAG,eAAe,CAAC,uBAAuB,CAAC,KAAK,CAAA;IAC3D,MAAM,cAAc,GAA2B,EAAE,CAAA;IACjD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,cAAc,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,CAAA;IACjC,CAAC;IAED,OAAO,eAAe,CAAC,YAAY,CAAC,cAAc,CAAC,CAAA;AACrD,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@lokalise/api-contracts",
+    "version": "4.1.0",
+    "files": ["dist"],
+    "license": "Apache-2.0",
+    "type": "module",
+    "main": "./dist/apiContracts.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/apiContracts.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:ci": "vitest run --coverage",
+        "prepublishOnly": "npm run build",
+        "package-version": "echo $npm_package_version",
+        "postversion": "biome check --write package.json"
+    },
+    "peerDependencies": {
+        "zod": "^3.24.2"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^1.9.4",
+        "@lokalise/biome-config": "^1.5.0",
+        "@lokalise/tsconfig": "~1.0.2",
+        "@vitest/coverage-v8": "^3.0.9",
+        "rimraf": "^6.0.1",
+        "typescript": "5.8.2",
+        "vitest": "^3.0.9"
+    },
+    "dependencies": {}
+}