@dakkitor/api-contracts 1.1.3 → 1.1.5

package/dist/clients/clients.contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clients.contract.d.ts","sourceRoot":"","sources":["../../contracts/clients/clients.contract.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBvB,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;EAI7B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4B5B,CAAC;AAEJ,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;EAK7B,CAAC;AAEH,eAAO,MAAM,gCAAgC;;;;;;;;;EAG3C,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;EAElC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EACS,CAAC;AAI9C,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,gCAAgC,CACxC,CAAC;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAC1E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE1E,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4FjB,CAAC;AAIX,eAAO,MAAM,eAAe,EACD,OAAO,qBAAqB,CAAC"}
+{"version":3,"file":"clients.contract.d.ts","sourceRoot":"","sources":["../../contracts/clients/clients.contract.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0BxB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAK3B,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmBM,CAAC;AAEhC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;EAUM,CAAC;AAEtC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4B5B,CAAC;AAEJ,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwB7B,CAAC;AAEH,eAAO,MAAM,gCAAgC;;;;;;;;;EAKF,CAAC;AAE5C,eAAO,MAAM,uBAAuB;;;;;;;;;EAYM,CAAC;AAE3C,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAIa,CAAC;AAElD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAChE,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,gCAAgC,CACxC,CAAC;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAC1E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAI1E,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8EjC,CAAC"}

package/dist/clients/clients.contract.js

@@ -1,22 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.clientsContract = exports.PaginatedResponseSchema = exports.AutocompleteQuerySchema = exports.ClientAutocompleteResponseSchema = exports.FilterClientSchema = exports.UpdateClientSchema = exports.CreateClientSchema = exports.ClientSchema = void 0;
+exports.clientsContractRouter = exports.PaginatedResponseSchema = exports.AutocompleteQuerySchema = exports.ClientAutocompleteResponseSchema = exports.FilterClientSchema = exports.UpdateClientSchema = exports.CreateClientSchema = exports.ClientSchema = exports.ClientUserSchema = void 0;
+const zod_openapi_1 = require("@anatine/zod-openapi");
 const core_1 = require("@ts-rest/core");
 const zod_1 = require("zod");
 const error_schemas_1 = require("../common/error-schemas");
 const pagination_schema_1 = require("../common/pagination.schema");
+(0, zod_openapi_1.extendZodWithOpenApi)(zod_1.z);
 const ClientStatusSchema = zod_1.z.enum([
     'APPROVED',
     'PENDING_VERIFICATION',
     'BLACKLISTED',
 ]);
-const UserSchema = zod_1.z.object({
+const SortOrderSchema = zod_1.z.enum(['ASC', 'DESC']);
+const ClientSortableFieldsSchema = zod_1.z.enum([
+    'name',
+    'director',
+    'createdAt',
+    'updatedAt',
+]);
+const DateRangeSchema = zod_1.z.object({
+    from: zod_1.z.string().datetime().optional(),
+    to: zod_1.z.string().datetime().optional(),
+});
+exports.ClientUserSchema = zod_1.z.object({
     id: zod_1.z.string().uuid(),
     firstName: zod_1.z.string(),
     lastName: zod_1.z.string(),
     email: zod_1.z.string().email(),
 });
-exports.ClientSchema = zod_1.z.object({
+exports.ClientSchema = zod_1.z
+    .object({
     id: zod_1.z.string().uuid().describe('Client ID'),
     name: zod_1.z.string().describe('Client Name'),
     crn: zod_1.z.string().describe('Company Registration Number'),
@@ -28,17 +42,24 @@ exports.ClientSchema = zod_1.z.object({
         .nullable()
         .optional()
         .describe('Reason for Blacklisting'),
-    lastUpdatedBy: UserSchema.describe('Last Updated By'),
+    lastUpdatedBy: exports.ClientUserSchema.describe('Last Updated By'),
     createdAt: zod_1.z.string().datetime().describe('Creation Date'),
     updatedAt: zod_1.z.string().datetime().describe('Last Update Date'),
     version: zod_1.z.number().describe('Version Number'),
     agentClientLinks: zod_1.z.object({ agentId: zod_1.z.string() }).describe('Agent Link'),
-});
-exports.CreateClientSchema = zod_1.z.object({
+})
+    .openapi({ title: 'Client' });
+exports.CreateClientSchema = zod_1.z
+    .object({
     name: zod_1.z.string().max(255).describe('Client Name'),
-    govLink: zod_1.z.string().url().max(2048).describe('Government Registration Link'),
+    govLink: zod_1.z
+        .string()
+        .url()
+        .max(2048)
+        .describe('Government Registration Link'),
     director: zod_1.z.string().max(255).describe('Director Name'),
-});
+})
+    .openapi({ title: 'CreateClient' });
 exports.UpdateClientSchema = zod_1.z
     .object({
     name: zod_1.z.string().max(255).optional().describe('Client Name'),
@@ -66,31 +87,54 @@ exports.UpdateClientSchema = zod_1.z
     path: ['blacklistReason'],
 });
 exports.FilterClientSchema = zod_1.z.object({
-    limit: zod_1.z.coerce.number().default(50).describe('Results per page'),
-    page: zod_1.z.coerce.number().default(1).describe('Page number'),
-    search: zod_1.z.string().optional().describe('Search by name'),
-    status: ClientStatusSchema.optional().describe('Filter by Status'),
+    limit: zod_1.z.coerce
+        .number()
+        .default(50)
+        .describe('The number of items to return per page.'),
+    page: zod_1.z.coerce.number().default(1).describe('The page number to retrieve.'),
+    name: zod_1.z
+        .string()
+        .optional()
+        .describe('Filter by client name (case-insensitive contains match)'),
+    status: ClientStatusSchema.optional().describe('Filter by client status'),
+    director: zod_1.z
+        .string()
+        .optional()
+        .describe('Filter by director name (case-insensitive contains match)'),
+    createdAt: DateRangeSchema.optional().describe('Filter by created date range.'),
+    sortBy: ClientSortableFieldsSchema.optional().describe('The field to sort the results by.'),
+    sortOrder: SortOrderSchema.optional().describe('The order to sort the results by.'),
 });
-exports.ClientAutocompleteResponseSchema = zod_1.z.object({
+exports.ClientAutocompleteResponseSchema = zod_1.z
+    .object({
     id: zod_1.z.string().uuid().describe('Client ID'),
     name: zod_1.z.string().describe('Client Name'),
-});
-exports.AutocompleteQuerySchema = zod_1.z.object({
-    search: zod_1.z.string().optional().describe('Search...'),
-});
-exports.PaginatedResponseSchema = (0, pagination_schema_1.createPaginatedResponseSchema)(exports.ClientSchema);
+})
+    .openapi({ title: 'ClientAutocomplete' });
+exports.AutocompleteQuerySchema = zod_1.z
+    .object({
+    query: zod_1.z
+        .string()
+        .optional()
+        .describe('Search query string to filter results'),
+    id: zod_1.z
+        .string()
+        .uuid()
+        .optional()
+        .describe('Specific record ID to include in results'),
+})
+    .openapi({ title: 'AutocompleteQuery' });
+exports.PaginatedResponseSchema = (0, pagination_schema_1.createPaginatedResponseSchema)(exports.ClientSchema)
+    .describe('Resources retrieved successfully.')
+    .openapi({ title: 'ClientsPaginatedResponse' });
 const c = (0, core_1.initContract)();
-const clientsContractConfig = {
+exports.clientsContractRouter = c.router({
     create: {
         method: 'POST',
         path: '/v2/clients',
         responses: {
             201: exports.ClientSchema,
-            400: error_schemas_1.ErrorResponseSchema,
-            401: error_schemas_1.ErrorResponseSchema,
-            403: error_schemas_1.ErrorResponseSchema,
             409: error_schemas_1.ErrorResponseSchema,
-            500: error_schemas_1.ErrorResponseSchema,
         },
         body: exports.CreateClientSchema,
         summary: 'Create a new client',
@@ -100,10 +144,6 @@ const clientsContractConfig = {
         path: '/v2/clients',
         responses: {
             200: exports.PaginatedResponseSchema,
-            400: error_schemas_1.ErrorResponseSchema,
-            401: error_schemas_1.ErrorResponseSchema,
-            403: error_schemas_1.ErrorResponseSchema,
-            500: error_schemas_1.ErrorResponseSchema,
         },
         query: exports.FilterClientSchema,
         summary: 'Get all clients',
@@ -113,10 +153,6 @@ const clientsContractConfig = {
         path: '/v2/clients/autocomplete',
         responses: {
             200: zod_1.z.array(exports.ClientAutocompleteResponseSchema),
-            400: error_schemas_1.ErrorResponseSchema,
-            401: error_schemas_1.ErrorResponseSchema,
-            403: error_schemas_1.ErrorResponseSchema,
-            500: error_schemas_1.ErrorResponseSchema,
         },
         query: exports.AutocompleteQuerySchema,
         summary: 'Get clients for autocomplete',
@@ -126,14 +162,10 @@ const clientsContractConfig = {
         path: '/v2/clients/:id',
         responses: {
             200: exports.ClientSchema,
-            400: error_schemas_1.ErrorResponseSchema,
-            401: error_schemas_1.ErrorResponseSchema,
-            403: error_schemas_1.ErrorResponseSchema,
             404: error_schemas_1.ErrorResponseSchema,
-            500: error_schemas_1.ErrorResponseSchema,
         },
         pathParams: zod_1.z.object({
-            id: zod_1.z.string().uuid(),
+            id: zod_1.z.string().uuid().describe('Client ID'),
         }),
         summary: 'Get a client by ID',
     },
@@ -142,15 +174,11 @@ const clientsContractConfig = {
         path: '/v2/clients/:id',
         responses: {
             200: exports.ClientSchema,
-            400: error_schemas_1.ErrorResponseSchema,
-            401: error_schemas_1.ErrorResponseSchema,
-            403: error_schemas_1.ErrorResponseSchema,
             404: error_schemas_1.ErrorResponseSchema,
             409: error_schemas_1.ErrorResponseSchema,
-            500: error_schemas_1.ErrorResponseSchema,
         },
         pathParams: zod_1.z.object({
-            id: zod_1.z.string().uuid(),
+            id: zod_1.z.string().uuid().describe('Client ID'),
         }),
         body: exports.UpdateClientSchema,
         summary: 'Update a client',
@@ -159,19 +187,20 @@ const clientsContractConfig = {
         method: 'DELETE',
         path: '/v2/clients/:id',
         responses: {
-            204: zod_1.z.null(),
-            400: error_schemas_1.ErrorResponseSchema,
-            401: error_schemas_1.ErrorResponseSchema,
-            403: error_schemas_1.ErrorResponseSchema,
+            204: zod_1.z.undefined(),
             404: error_schemas_1.ErrorResponseSchema,
-            500: error_schemas_1.ErrorResponseSchema,
         },
         pathParams: zod_1.z.object({
-            id: zod_1.z.string().uuid(),
+            id: zod_1.z.string().uuid().describe('Client ID'),
         }),
-        body: zod_1.z.undefined(),
+        body: c.noBody(),
         summary: 'Delete a client',
     },
-};
-const clientsContractRouter = c.router(clientsContractConfig);
-exports.clientsContract = clientsContractRouter;
+}, {
+    commonResponses: {
+        400: error_schemas_1.ErrorResponseSchema,
+        401: error_schemas_1.ErrorResponseSchema,
+        403: error_schemas_1.ErrorResponseSchema,
+        500: error_schemas_1.ErrorResponseSchema,
+    },
+});

package/dist/common/api-responses.d.ts

@@ -0,0 +1,105 @@
+export declare const CommonErrorResponses: {
+    readonly 400: {
+        readonly description: "Bad Request. The request could not be understood by the server due to malformed syntax or invalid data.";
+        readonly content: {
+            readonly 'application/json': {
+                readonly schema: {
+                    readonly $ref: "#/components/schemas/ErrorResponse";
+                };
+                readonly example: {
+                    readonly statusCode: 400;
+                    readonly message: "Input validation failed or request is malformed.";
+                    readonly code: "VALIDATION_ERROR";
+                    readonly timestamp: "2024-01-01T12:00:00.000Z";
+                    readonly path: "/v1/example-endpoint";
+                };
+            };
+        };
+    };
+    readonly 401: {
+        readonly description: "Unauthorized. The user is not authenticated or token is missing/invalid.";
+        readonly content: {
+            readonly 'application/json': {
+                readonly schema: {
+                    readonly $ref: "#/components/schemas/ErrorResponse";
+                };
+                readonly example: {
+                    readonly statusCode: 401;
+                    readonly message: "Authentication required or token is invalid.";
+                    readonly code: "UNAUTHORIZED";
+                    readonly timestamp: "2024-01-01T12:00:00.000Z";
+                    readonly path: "/v1/example-endpoint";
+                };
+            };
+        };
+    };
+    readonly 403: {
+        readonly description: "Forbidden. The user does not have the necessary permissions for this resource.";
+        readonly content: {
+            readonly 'application/json': {
+                readonly schema: {
+                    readonly $ref: "#/components/schemas/ErrorResponse";
+                };
+                readonly example: {
+                    readonly statusCode: 403;
+                    readonly message: "Access to this resource is forbidden.";
+                    readonly code: "FORBIDDEN";
+                    readonly timestamp: "2024-01-01T12:00:00.000Z";
+                    readonly path: "/v1/example-endpoint";
+                };
+            };
+        };
+    };
+    readonly 404: {
+        readonly description: "Not Found. The requested resource could not be found.";
+        readonly content: {
+            readonly 'application/json': {
+                readonly schema: {
+                    readonly $ref: "#/components/schemas/ErrorResponse";
+                };
+                readonly example: {
+                    readonly statusCode: 404;
+                    readonly message: "The requested resource could not be found.";
+                    readonly code: "RESOURCE_NOT_FOUND";
+                    readonly timestamp: "2024-01-01T12:00:00.000Z";
+                    readonly path: "/v1/example-endpoint";
+                };
+            };
+        };
+    };
+    readonly 409: {
+        readonly description: "Conflict. The resource already exists.";
+        readonly content: {
+            readonly 'application/json': {
+                readonly schema: {
+                    readonly $ref: "#/components/schemas/ErrorResponse";
+                };
+                readonly example: {
+                    readonly statusCode: 409;
+                    readonly message: "A conflict occurred with the current state of the resource.";
+                    readonly code: "RESOURCE_CONFLICT";
+                    readonly timestamp: "2024-01-01T12:00:00.000Z";
+                    readonly path: "/v1/example-endpoint";
+                };
+            };
+        };
+    };
+    readonly 500: {
+        readonly description: "Internal Server Error. An unexpected error occurred on the server.";
+        readonly content: {
+            readonly 'application/json': {
+                readonly schema: {
+                    readonly $ref: "#/components/schemas/ErrorResponse";
+                };
+                readonly example: {
+                    readonly statusCode: 500;
+                    readonly message: "An unexpected error occurred on the server.";
+                    readonly code: "INTERNAL_SERVER_ERROR";
+                    readonly timestamp: "2024-01-01T12:00:00.000Z";
+                    readonly path: "/v1/example-endpoint";
+                };
+            };
+        };
+    };
+};
+//# sourceMappingURL=api-responses.d.ts.map

package/dist/common/api-responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-responses.d.ts","sourceRoot":"","sources":["../../contracts/common/api-responses.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4GvB,CAAC"}

package/dist/common/api-responses.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommonErrorResponses = void 0;
+exports.CommonErrorResponses = {
+    400: {
+        description: 'Bad Request. The request could not be understood by the server due to malformed syntax or invalid data.',
+        content: {
+            'application/json': {
+                schema: {
+                    $ref: '#/components/schemas/ErrorResponse',
+                },
+                example: {
+                    statusCode: 400,
+                    message: 'Input validation failed or request is malformed.',
+                    code: 'VALIDATION_ERROR',
+                    timestamp: '2024-01-01T12:00:00.000Z',
+                    path: '/v1/example-endpoint',
+                },
+            },
+        },
+    },
+    401: {
+        description: 'Unauthorized. The user is not authenticated or token is missing/invalid.',
+        content: {
+            'application/json': {
+                schema: {
+                    $ref: '#/components/schemas/ErrorResponse',
+                },
+                example: {
+                    statusCode: 401,
+                    message: 'Authentication required or token is invalid.',
+                    code: 'UNAUTHORIZED',
+                    timestamp: '2024-01-01T12:00:00.000Z',
+                    path: '/v1/example-endpoint',
+                },
+            },
+        },
+    },
+    403: {
+        description: 'Forbidden. The user does not have the necessary permissions for this resource.',
+        content: {
+            'application/json': {
+                schema: {
+                    $ref: '#/components/schemas/ErrorResponse',
+                },
+                example: {
+                    statusCode: 403,
+                    message: 'Access to this resource is forbidden.',
+                    code: 'FORBIDDEN',
+                    timestamp: '2024-01-01T12:00:00.000Z',
+                    path: '/v1/example-endpoint',
+                },
+            },
+        },
+    },
+    404: {
+        description: 'Not Found. The requested resource could not be found.',
+        content: {
+            'application/json': {
+                schema: {
+                    $ref: '#/components/schemas/ErrorResponse',
+                },
+                example: {
+                    statusCode: 404,
+                    message: 'The requested resource could not be found.',
+                    code: 'RESOURCE_NOT_FOUND',
+                    timestamp: '2024-01-01T12:00:00.000Z',
+                    path: '/v1/example-endpoint',
+                },
+            },
+        },
+    },
+    409: {
+        description: 'Conflict. The resource already exists.',
+        content: {
+            'application/json': {
+                schema: {
+                    $ref: '#/components/schemas/ErrorResponse',
+                },
+                example: {
+                    statusCode: 409,
+                    message: 'A conflict occurred with the current state of the resource.',
+                    code: 'RESOURCE_CONFLICT',
+                    timestamp: '2024-01-01T12:00:00.000Z',
+                    path: '/v1/example-endpoint',
+                },
+            },
+        },
+    },
+    500: {
+        description: 'Internal Server Error. An unexpected error occurred on the server.',
+        content: {
+            'application/json': {
+                schema: {
+                    $ref: '#/components/schemas/ErrorResponse',
+                },
+                example: {
+                    statusCode: 500,
+                    message: 'An unexpected error occurred on the server.',
+                    code: 'INTERNAL_SERVER_ERROR',
+                    timestamp: '2024-01-01T12:00:00.000Z',
+                    path: '/v1/example-endpoint',
+                },
+            },
+        },
+    },
+};

package/dist/common/error-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-schemas.d.ts","sourceRoot":"","sources":["../../contracts/common/error-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;EAQ9B,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
+{"version":3,"file":"error-schemas.d.ts","sourceRoot":"","sources":["../../contracts/common/error-schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;EAUM,CAAC;AAEvC,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/common/error-schemas.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorResponseSchema = void 0;
+const zod_openapi_1 = require("@anatine/zod-openapi");
 const zod_1 = require("zod");
+(0, zod_openapi_1.extendZodWithOpenApi)(zod_1.z);
 /**
  * Shared error response schema matching IErrorResponse interface.
  * This ensures type consistency between backend error handling and contract definitions.
  */
-exports.ErrorResponseSchema = zod_1.z.object({
+exports.ErrorResponseSchema = zod_1.z
+    .object({
     statusCode: zod_1.z.number().describe('HTTP Status Code'),
     message: zod_1.z.string().describe('Human-readable error message'),
     code: zod_1.z.string().describe('Machine-readable error code'),
@@ -14,4 +17,5 @@ exports.ErrorResponseSchema = zod_1.z.object({
     timestamp: zod_1.z.string().describe('Error timestamp'),
     path: zod_1.z.string().describe('Request path'),
     correlationId: zod_1.z.string().optional().describe('Request correlation ID'),
-});
+})
+    .openapi({ title: 'ErrorResponse' });

package/dist/common/openapi-metadata.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Project: Internal Recruitment Platform API
+ * File: openapi-metadata.ts
+ *
+ * Description: TypeScript types for OpenAPI metadata that can be attached to ts-rest routes.
+ * This metadata structure matches the patterns from api-responses.decorator.ts and will be
+ * used to post-process the generated OpenAPI spec.
+ */
+/**
+ * Metadata for a single response status code.
+ */
+export interface ResponseMetadata {
+    /**
+     * Description of the response.
+     */
+    description?: string;
+    /**
+     * Example response data.
+     */
+    example?: Record<string, unknown>;
+}
+/**
+ * Metadata for OpenAPI documentation that can be attached to ts-rest routes.
+ */
+export interface OpenApiMetadata {
+    /**
+     * Tags for grouping endpoints in Swagger UI.
+     */
+    tags?: string[];
+    /**
+     * Custom response metadata for each status code.
+     * Keys are status codes (e.g., '200', '201', '400', '401', etc.)
+     */
+    responses?: Record<string, ResponseMetadata>;
+}
+/**
+ * Standard error response examples and descriptions
+ */
+export declare const STANDARD_ERROR_RESPONSES: Record<number, ResponseMetadata>;
+/**
+ * Helper to create metadata for standard CRUD operations
+ */
+export declare const createStandardMetadata: {
+    /**
+     * Metadata for CREATE operations (201)
+     */
+    create: (customResponses?: Record<string, ResponseMetadata>) => OpenApiMetadata;
+    /**
+     * Metadata for FIND ONE operations (200)
+     */
+    findOne: (customResponses?: Record<string, ResponseMetadata>) => OpenApiMetadata;
+    /**
+     * Metadata for FIND ALL operations (200)
+     */
+    findAll: (customResponses?: Record<string, ResponseMetadata>) => OpenApiMetadata;
+    /**
+     * Metadata for UPDATE operations (200)
+     */
+    update: (customResponses?: Record<string, ResponseMetadata>) => OpenApiMetadata;
+    /**
+     * Metadata for DELETE operations (204)
+     */
+    delete: (customResponses?: Record<string, ResponseMetadata>) => OpenApiMetadata;
+};
+//# sourceMappingURL=openapi-metadata.d.ts.map

package/dist/common/openapi-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-metadata.d.ts","sourceRoot":"","sources":["../../contracts/common/openapi-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAiErE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB;IACjC;;OAEG;+BAEiB,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KACjD,eAAe;IAWlB;;OAEG;gCAEiB,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KACjD,eAAe;IAWlB;;OAEG;gCAEiB,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KACjD,eAAe;IAUlB;;OAEG;+BAEiB,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KACjD,eAAe;IAuBlB;;OAEG;+BAEiB,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KACjD,eAAe;CAUnB,CAAC"}