@dakkitor/api-contracts 1.1.4 → 1.1.6

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;AAUxB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAK3B,CAAC;AAEH,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;AAE9C,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"}
+{"version":3,"file":"clients.contract.d.ts","sourceRoot":"","sources":["../../contracts/clients/clients.contract.ts"],"names":[],"mappings":"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"}

package/dist/clients/clients.contract.js

@@ -1,22 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 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");
-const ClientStatusSchema = zod_1.z.enum([
-    'APPROVED',
-    'PENDING_VERIFICATION',
-    'BLACKLISTED',
-]);
+(0, zod_openapi_1.extendZodWithOpenApi)(zod_1.z);
+const ClientStatusSchema = zod_1.z
+    .enum(['APPROVED', 'PENDING_VERIFICATION', 'BLACKLISTED'])
+    .openapi({ title: 'ClientStatus' });
+const SortOrderSchema = zod_1.z.enum(['ASC', 'DESC']).openapi({ title: 'SortOrder' });
+const ClientSortableFieldsSchema = zod_1.z
+    .enum(['name', 'director', 'createdAt', 'updatedAt'])
+    .openapi({ title: 'ClientSortableFields' });
+const DateRangeSchema = zod_1.z
+    .object({
+    from: zod_1.z.string().datetime().optional(),
+    to: zod_1.z.string().datetime().optional(),
+})
+    .openapi({ title: 'DateRange' });
 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'),
@@ -29,16 +40,29 @@ exports.ClientSchema = zod_1.z.object({
         .optional()
         .describe('Reason for Blacklisting'),
     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'),
+    createdAt: zod_1.z
+        .union([zod_1.z.string().datetime(), zod_1.z.date()])
+        .transform((val) => (val instanceof Date ? val.toISOString() : val))
+        .describe('Creation Date'),
+    updatedAt: zod_1.z
+        .union([zod_1.z.string().datetime(), zod_1.z.date()])
+        .transform((val) => (val instanceof Date ? val.toISOString() : val))
+        .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'),
@@ -64,21 +88,59 @@ exports.UpdateClientSchema = zod_1.z
 }, {
     message: 'blacklistReason is required when status is BLACKLISTED',
     path: ['blacklistReason'],
-});
+})
+    .openapi({ title: 'UpdateClient' });
 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()
+        .nullable()
+        .describe('Filter by client name (case-insensitive contains match)'),
+    status: ClientStatusSchema.optional()
+        .nullable()
+        .describe('Filter by client status'),
+    director: zod_1.z
+        .string()
+        .optional()
+        .nullable()
+        .describe('Filter by director name (case-insensitive contains match)'),
+    createdAt: DateRangeSchema.optional()
+        .nullable()
+        .describe('Filter by created date range.'),
+    sortBy: ClientSortableFieldsSchema.optional()
+        .nullable()
+        .describe('The field to sort the results by.'),
+    sortOrder: SortOrderSchema.optional()
+        .nullable()
+        .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)();
 exports.clientsContractRouter = c.router({
     create: {
@@ -90,6 +152,7 @@ exports.clientsContractRouter = c.router({
         },
         body: exports.CreateClientSchema,
         summary: 'Create a new client',
+        metadata: { tags: ['Clients'], openApi: { operationId: 'createClient' } },
     },
     findAll: {
         method: 'GET',
@@ -99,6 +162,10 @@ exports.clientsContractRouter = c.router({
         },
         query: exports.FilterClientSchema,
         summary: 'Get all clients',
+        metadata: {
+            tags: ['Clients'],
+            openApi: { operationId: 'findAllClients' },
+        },
     },
     autocomplete: {
         method: 'GET',
@@ -108,6 +175,10 @@ exports.clientsContractRouter = c.router({
         },
         query: exports.AutocompleteQuerySchema,
         summary: 'Get clients for autocomplete',
+        metadata: {
+            tags: ['Clients'],
+            openApi: { operationId: 'autocompleteClients' },
+        },
     },
     findOne: {
         method: 'GET',
@@ -117,9 +188,13 @@ exports.clientsContractRouter = c.router({
             404: 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',
+        metadata: {
+            tags: ['Clients'],
+            openApi: { operationId: 'findClientById' },
+        },
     },
     update: {
         method: 'PATCH',
@@ -130,23 +205,25 @@ exports.clientsContractRouter = c.router({
             409: 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',
+        metadata: { tags: ['Clients'], openApi: { operationId: 'updateClient' } },
     },
     remove: {
         method: 'DELETE',
         path: '/v2/clients/:id',
         responses: {
-            204: c.noBody(),
+            224: zod_1.z.undefined(),
             404: 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: c.noBody(),
         summary: 'Delete a client',
+        metadata: { tags: ['Clients'], openApi: { operationId: 'deleteClient' } },
     },
 }, {
     commonResponses: {

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"}