npm - servcraft - Versions diffs - 0.1.0 - Mend

servcraft 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (106) hide show

package/.dockerignore +45 -0
package/.env.example +46 -0
package/.husky/commit-msg +1 -0
package/.husky/pre-commit +1 -0
package/.prettierignore +4 -0
package/.prettierrc +11 -0
package/Dockerfile +76 -0
package/Dockerfile.dev +31 -0
package/README.md +232 -0
package/commitlint.config.js +24 -0
package/dist/cli/index.cjs +3968 -0
package/dist/cli/index.cjs.map +1 -0
package/dist/cli/index.d.cts +1 -0
package/dist/cli/index.d.ts +1 -0
package/dist/cli/index.js +3945 -0
package/dist/cli/index.js.map +1 -0
package/dist/index.cjs +2458 -0
package/dist/index.cjs.map +1 -0
package/dist/index.d.cts +828 -0
package/dist/index.d.ts +828 -0
package/dist/index.js +2332 -0
package/dist/index.js.map +1 -0
package/docker-compose.prod.yml +118 -0
package/docker-compose.yml +147 -0
package/eslint.config.js +27 -0
package/npm-cache/_cacache/content-v2/sha512/1c/d0/03440d500a0487621aad1d6402978340698976602046db8e24fa03c01ee6c022c69b0582f969042d9442ee876ac35c038e960dd427d1e622fa24b8eb7dba +0 -0
package/npm-cache/_cacache/content-v2/sha512/42/55/28b493ca491833e5aab0e9c3108d29ab3f36c248ca88f45d4630674fce9130959e56ae308797ac2b6328fa7f09a610b9550ed09cb971d039876d293fc69d +0 -0
package/npm-cache/_cacache/content-v2/sha512/e0/12/f360dc9315ee5f17844a0c8c233ee6bf7c30837c4a02ea0d56c61c7f7ab21c0e958e50ed2c57c59f983c762b93056778c9009b2398ffc26def0183999b13 +0 -0
package/npm-cache/_cacache/content-v2/sha512/ed/b0/fae1161902898f4c913c67d7f6cdf6be0665aec3b389b9c4f4f0a101ca1da59badf1b59c4e0030f5223023b8d63cfe501c46a32c20c895d4fb3f11ca2232 +0 -0
package/npm-cache/_cacache/index-v5/58/94/c2cba79e0f16b4c10e95a87e32255741149e8222cc314a476aab67c39cc0 +5 -0
package/npm-cache/_update-notifier-last-checked +0 -0
package/package.json +112 -0
package/prisma/schema.prisma +157 -0
package/src/cli/commands/add-module.ts +422 -0
package/src/cli/commands/db.ts +137 -0
package/src/cli/commands/docs.ts +16 -0
package/src/cli/commands/generate.ts +459 -0
package/src/cli/commands/init.ts +640 -0
package/src/cli/index.ts +32 -0
package/src/cli/templates/controller.ts +67 -0
package/src/cli/templates/dynamic-prisma.ts +89 -0
package/src/cli/templates/dynamic-schemas.ts +232 -0
package/src/cli/templates/dynamic-types.ts +60 -0
package/src/cli/templates/module-index.ts +33 -0
package/src/cli/templates/prisma-model.ts +17 -0
package/src/cli/templates/repository.ts +104 -0
package/src/cli/templates/routes.ts +70 -0
package/src/cli/templates/schemas.ts +26 -0
package/src/cli/templates/service.ts +58 -0
package/src/cli/templates/types.ts +27 -0
package/src/cli/utils/docs-generator.ts +47 -0
package/src/cli/utils/field-parser.ts +315 -0
package/src/cli/utils/helpers.ts +89 -0
package/src/config/env.ts +80 -0
package/src/config/index.ts +97 -0
package/src/core/index.ts +5 -0
package/src/core/logger.ts +43 -0
package/src/core/server.ts +132 -0
package/src/database/index.ts +7 -0
package/src/database/prisma.ts +54 -0
package/src/database/seed.ts +59 -0
package/src/index.ts +63 -0
package/src/middleware/error-handler.ts +73 -0
package/src/middleware/index.ts +3 -0
package/src/middleware/security.ts +116 -0
package/src/modules/audit/audit.service.ts +192 -0
package/src/modules/audit/index.ts +2 -0
package/src/modules/audit/types.ts +37 -0
package/src/modules/auth/auth.controller.ts +182 -0
package/src/modules/auth/auth.middleware.ts +87 -0
package/src/modules/auth/auth.routes.ts +123 -0
package/src/modules/auth/auth.service.ts +142 -0
package/src/modules/auth/index.ts +49 -0
package/src/modules/auth/schemas.ts +52 -0
package/src/modules/auth/types.ts +69 -0
package/src/modules/email/email.service.ts +212 -0
package/src/modules/email/index.ts +10 -0
package/src/modules/email/templates.ts +213 -0
package/src/modules/email/types.ts +57 -0
package/src/modules/swagger/index.ts +3 -0
package/src/modules/swagger/schema-builder.ts +263 -0
package/src/modules/swagger/swagger.service.ts +169 -0
package/src/modules/swagger/types.ts +68 -0
package/src/modules/user/index.ts +30 -0
package/src/modules/user/schemas.ts +49 -0
package/src/modules/user/types.ts +78 -0
package/src/modules/user/user.controller.ts +139 -0
package/src/modules/user/user.repository.ts +156 -0
package/src/modules/user/user.routes.ts +199 -0
package/src/modules/user/user.service.ts +145 -0
package/src/modules/validation/index.ts +18 -0
package/src/modules/validation/validator.ts +104 -0
package/src/types/common.ts +61 -0
package/src/types/index.ts +10 -0
package/src/utils/errors.ts +66 -0
package/src/utils/index.ts +33 -0
package/src/utils/pagination.ts +38 -0
package/src/utils/response.ts +63 -0
package/tests/integration/auth.test.ts +59 -0
package/tests/setup.ts +17 -0
package/tests/unit/modules/validation.test.ts +88 -0
package/tests/unit/utils/errors.test.ts +113 -0
package/tests/unit/utils/pagination.test.ts +82 -0
package/tsconfig.json +33 -0
package/tsup.config.ts +14 -0
package/vitest.config.ts +34 -0

package/src/modules/email/templates.ts ADDED Viewed

@@ -0,0 +1,213 @@
+import Handlebars from 'handlebars';
+// Base layout template
+const baseLayout = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{{subject}}</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+      line-height: 1.6;
+      color: #333;
+      max-width: 600px;
+      margin: 0 auto;
+      padding: 20px;
+      background-color: #f5f5f5;
+    }
+    .container {
+      background-color: #ffffff;
+      border-radius: 8px;
+      padding: 40px;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+    }
+    .header {
+      text-align: center;
+      margin-bottom: 30px;
+    }
+    .logo {
+      font-size: 24px;
+      font-weight: bold;
+      color: #2563eb;
+    }
+    .content {
+      margin-bottom: 30px;
+    }
+    .button {
+      display: inline-block;
+      padding: 12px 24px;
+      background-color: #2563eb;
+      color: #ffffff !important;
+      text-decoration: none;
+      border-radius: 6px;
+      font-weight: 500;
+    }
+    .button:hover {
+      background-color: #1d4ed8;
+    }
+    .footer {
+      text-align: center;
+      font-size: 12px;
+      color: #666;
+      margin-top: 30px;
+      padding-top: 20px;
+      border-top: 1px solid #eee;
+    }
+    .warning {
+      background-color: #fef3c7;
+      border: 1px solid #f59e0b;
+      border-radius: 6px;
+      padding: 12px;
+      margin: 20px 0;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="header">
+      <div class="logo">{{appName}}</div>
+    </div>
+    <div class="content">
+      {{{body}}}
+    </div>
+    <div class="footer">
+      <p>&copy; {{year}} {{appName}}. All rights reserved.</p>
+      <p>This email was sent to {{userEmail}}</p>
+    </div>
+  </div>
+</body>
+</html>
+`;
+// Individual templates
+const templates: Record<string, string> = {
+  welcome: `
+    <h2>Welcome to {{appName}}!</h2>
+    <p>Hi {{userName}},</p>
+    <p>Thank you for joining {{appName}}. We're excited to have you on board!</p>
+    <p>To get started, please verify your email address by clicking the button below:</p>
+    <p style="text-align: center; margin: 30px 0;">
+      <a href="{{actionUrl}}" class="button">Verify Email</a>
+    </p>
+    <p>If you didn't create an account with us, you can safely ignore this email.</p>
+  `,
+  'verify-email': `
+    <h2>Verify Your Email</h2>
+    <p>Hi {{userName}},</p>
+    <p>Please verify your email address by clicking the button below:</p>
+    <p style="text-align: center; margin: 30px 0;">
+      <a href="{{actionUrl}}" class="button">Verify Email</a>
+    </p>
+    <p>This link will expire in {{expiresIn}}.</p>
+    <p>If you didn't request this verification, you can safely ignore this email.</p>
+  `,
+  'password-reset': `
+    <h2>Reset Your Password</h2>
+    <p>Hi {{userName}},</p>
+    <p>We received a request to reset your password. Click the button below to create a new password:</p>
+    <p style="text-align: center; margin: 30px 0;">
+      <a href="{{actionUrl}}" class="button">Reset Password</a>
+    </p>
+    <p>This link will expire in {{expiresIn}}.</p>
+    <div class="warning">
+      <strong>Security Notice:</strong> If you didn't request this password reset, please ignore this email and your password will remain unchanged.
+    </div>
+  `,
+  'password-changed': `
+    <h2>Password Changed</h2>
+    <p>Hi {{userName}},</p>
+    <p>Your password has been successfully changed.</p>
+    <p>If you didn't make this change, please contact our support team immediately and secure your account.</p>
+    <div class="warning">
+      <strong>Details:</strong><br>
+      Time: {{timestamp}}<br>
+      IP Address: {{ipAddress}}<br>
+      Device: {{userAgent}}
+    </div>
+  `,
+  'login-alert': `
+    <h2>New Login Detected</h2>
+    <p>Hi {{userName}},</p>
+    <p>We detected a new login to your account.</p>
+    <div class="warning">
+      <strong>Login Details:</strong><br>
+      Time: {{timestamp}}<br>
+      IP Address: {{ipAddress}}<br>
+      Device: {{userAgent}}<br>
+      Location: {{location}}
+    </div>
+    <p>If this was you, you can safely ignore this email.</p>
+    <p>If you didn't log in, please change your password immediately and contact support.</p>
+  `,
+  'account-suspended': `
+    <h2>Account Suspended</h2>
+    <p>Hi {{userName}},</p>
+    <p>Your account has been suspended due to: {{reason}}</p>
+    <p>If you believe this is a mistake, please contact our support team.</p>
+  `,
+};
+// Compile templates
+const compiledLayout = Handlebars.compile(baseLayout);
+const compiledTemplates: Record<string, HandlebarsTemplateDelegate> = {};
+for (const [name, template] of Object.entries(templates)) {
+  compiledTemplates[name] = Handlebars.compile(template);
+}
+export function renderTemplate(
+  templateName: string,
+  data: Record<string, unknown>
+): string {
+  const template = compiledTemplates[templateName];
+  if (!template) {
+    throw new Error(`Template "${templateName}" not found`);
+  }
+  const body = template(data);
+  return compiledLayout({
+    ...data,
+    body,
+    year: new Date().getFullYear(),
+    appName: data.appName || 'Servcraft',
+  });
+}
+export function renderCustomTemplate(
+  htmlTemplate: string,
+  data: Record<string, unknown>
+): string {
+  const template = Handlebars.compile(htmlTemplate);
+  const body = template(data);
+  return compiledLayout({
+    ...data,
+    body,
+    year: new Date().getFullYear(),
+    appName: data.appName || 'Servcraft',
+  });
+}
+// Register Handlebars helpers
+Handlebars.registerHelper('formatDate', (date: Date) => {
+  return new Date(date).toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+});
+Handlebars.registerHelper('eq', (a, b) => a === b);
+Handlebars.registerHelper('ne', (a, b) => a !== b);

package/src/modules/email/types.ts ADDED Viewed

@@ -0,0 +1,57 @@
+export interface EmailConfig {
+  host: string;
+  port: number;
+  secure?: boolean;
+  auth: {
+    user: string;
+    pass: string;
+  };
+  from: string;
+}
+export interface EmailOptions {
+  to: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  template?: string;
+  data?: Record<string, unknown>;
+  attachments?: EmailAttachment[];
+  replyTo?: string;
+  cc?: string | string[];
+  bcc?: string | string[];
+}
+export interface EmailAttachment {
+  filename: string;
+  content?: string | Buffer;
+  path?: string;
+  contentType?: string;
+}
+export interface EmailResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+}
+export type EmailTemplate =
+  | 'welcome'
+  | 'verify-email'
+  | 'password-reset'
+  | 'password-changed'
+  | 'login-alert'
+  | 'account-suspended'
+  | 'custom';
+export interface TemplateData {
+  appName?: string;
+  userName?: string;
+  userEmail?: string;
+  actionUrl?: string;
+  token?: string;
+  expiresIn?: string;
+  ipAddress?: string;
+  userAgent?: string;
+  [key: string]: unknown;
+}

package/src/modules/swagger/index.ts ADDED Viewed

@@ -0,0 +1,3 @@
+export { registerSwagger, commonResponses, paginationQuery, idParam } from './swagger.service.js';
+export { buildOpenApiSchema, generateRouteSchema } from './schema-builder.js';
+export type { SwaggerConfig, SwaggerTag, SwaggerServer, RouteSchema, EndpointDoc } from './types.js';

package/src/modules/swagger/schema-builder.ts ADDED Viewed

@@ -0,0 +1,263 @@
+import type { FieldDefinition } from '../../cli/utils/field-parser.js';
+/**
+ * Build OpenAPI schema from field definitions
+ */
+export function buildOpenApiSchema(
+  fields: FieldDefinition[],
+  options: { includeId?: boolean; includeTimestamps?: boolean } = {}
+): Record<string, unknown> {
+  const { includeId = false, includeTimestamps = false } = options;
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  if (includeId) {
+    properties.id = { type: 'string', format: 'uuid', description: 'Unique identifier' };
+  }
+  for (const field of fields) {
+    properties[field.name] = fieldToOpenApi(field);
+    if (!field.isOptional) {
+      required.push(field.name);
+    }
+  }
+  if (includeTimestamps) {
+    properties.createdAt = { type: 'string', format: 'date-time', description: 'Creation timestamp' };
+    properties.updatedAt = { type: 'string', format: 'date-time', description: 'Last update timestamp' };
+  }
+  return {
+    type: 'object',
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+  };
+}
+/**
+ * Convert field definition to OpenAPI property schema
+ */
+function fieldToOpenApi(field: FieldDefinition): Record<string, unknown> {
+  const typeMap: Record<string, Record<string, unknown>> = {
+    string: { type: 'string' },
+    number: { type: 'number' },
+    int: { type: 'integer' },
+    float: { type: 'number', format: 'float' },
+    decimal: { type: 'number', format: 'double' },
+    boolean: { type: 'boolean' },
+    date: { type: 'string', format: 'date' },
+    datetime: { type: 'string', format: 'date-time' },
+    text: { type: 'string', maxLength: 65535 },
+    email: { type: 'string', format: 'email' },
+    url: { type: 'string', format: 'uri' },
+    uuid: { type: 'string', format: 'uuid' },
+    json: { type: 'object', additionalProperties: true },
+    enum: { type: 'string' },
+  };
+  let schema = typeMap[field.type] || { type: 'string' };
+  if (field.isArray) {
+    schema = {
+      type: 'array',
+      items: schema,
+    };
+  }
+  return schema;
+}
+/**
+ * Generate route schema for Fastify with OpenAPI annotations
+ */
+export function generateRouteSchema(
+  modelName: string,
+  fields: FieldDefinition[],
+  operation: 'list' | 'get' | 'create' | 'update' | 'delete'
+): Record<string, unknown> {
+  const tag = modelName + 's';
+  switch (operation) {
+    case 'list':
+      return {
+        schema: {
+          summary: `List all ${modelName}s`,
+          description: `Retrieve a paginated list of ${modelName}s`,
+          tags: [tag],
+          querystring: {
+            type: 'object',
+            properties: {
+              page: { type: 'integer', minimum: 1, default: 1 },
+              limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+              sortBy: { type: 'string' },
+              sortOrder: { type: 'string', enum: ['asc', 'desc'] },
+              search: { type: 'string' },
+            },
+          },
+          response: {
+            200: {
+              description: 'Successful response',
+              type: 'object',
+              properties: {
+                success: { type: 'boolean' },
+                data: {
+                  type: 'object',
+                  properties: {
+                    data: {
+                      type: 'array',
+                      items: buildOpenApiSchema(fields, { includeId: true, includeTimestamps: true }),
+                    },
+                    meta: {
+                      type: 'object',
+                      properties: {
+                        total: { type: 'integer' },
+                        page: { type: 'integer' },
+                        limit: { type: 'integer' },
+                        totalPages: { type: 'integer' },
+                        hasNextPage: { type: 'boolean' },
+                        hasPrevPage: { type: 'boolean' },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      };
+    case 'get':
+      return {
+        schema: {
+          summary: `Get ${modelName} by ID`,
+          description: `Retrieve a single ${modelName} by its ID`,
+          tags: [tag],
+          params: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', format: 'uuid' },
+            },
+            required: ['id'],
+          },
+          response: {
+            200: {
+              description: 'Successful response',
+              type: 'object',
+              properties: {
+                success: { type: 'boolean' },
+                data: buildOpenApiSchema(fields, { includeId: true, includeTimestamps: true }),
+              },
+            },
+            404: {
+              description: 'Not found',
+              type: 'object',
+              properties: {
+                success: { type: 'boolean', example: false },
+                message: { type: 'string', example: `${modelName} not found` },
+              },
+            },
+          },
+        },
+      };
+    case 'create':
+      return {
+        schema: {
+          summary: `Create ${modelName}`,
+          description: `Create a new ${modelName}`,
+          tags: [tag],
+          body: buildOpenApiSchema(fields),
+          response: {
+            201: {
+              description: 'Created successfully',
+              type: 'object',
+              properties: {
+                success: { type: 'boolean' },
+                data: buildOpenApiSchema(fields, { includeId: true, includeTimestamps: true }),
+              },
+            },
+            400: {
+              description: 'Validation error',
+              type: 'object',
+              properties: {
+                success: { type: 'boolean', example: false },
+                message: { type: 'string' },
+                errors: { type: 'object' },
+              },
+            },
+          },
+        },
+      };
+    case 'update':
+      // Make all fields optional for update
+      const optionalFields = fields.map((f) => ({ ...f, isOptional: true }));
+      return {
+        schema: {
+          summary: `Update ${modelName}`,
+          description: `Update an existing ${modelName}`,
+          tags: [tag],
+          params: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', format: 'uuid' },
+            },
+            required: ['id'],
+          },
+          body: buildOpenApiSchema(optionalFields),
+          response: {
+            200: {
+              description: 'Updated successfully',
+              type: 'object',
+              properties: {
+                success: { type: 'boolean' },
+                data: buildOpenApiSchema(fields, { includeId: true, includeTimestamps: true }),
+              },
+            },
+            404: {
+              description: 'Not found',
+              type: 'object',
+              properties: {
+                success: { type: 'boolean', example: false },
+                message: { type: 'string' },
+              },
+            },
+          },
+        },
+      };
+    case 'delete':
+      return {
+        schema: {
+          summary: `Delete ${modelName}`,
+          description: `Delete a ${modelName} by ID`,
+          tags: [tag],
+          params: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', format: 'uuid' },
+            },
+            required: ['id'],
+          },
+          response: {
+            204: {
+              description: 'Deleted successfully',
+              type: 'null',
+            },
+            404: {
+              description: 'Not found',
+              type: 'object',
+              properties: {
+                success: { type: 'boolean', example: false },
+                message: { type: 'string' },
+              },
+            },
+          },
+        },
+      };
+    default:
+      return {};
+  }
+}

package/src/modules/swagger/swagger.service.ts ADDED Viewed

@@ -0,0 +1,169 @@
+import type { FastifyInstance } from 'fastify';
+import swagger from '@fastify/swagger';
+import swaggerUi from '@fastify/swagger-ui';
+import { config } from '../../config/index.js';
+import { logger } from '../../core/logger.js';
+import type { SwaggerConfig } from './types.js';
+const defaultConfig: SwaggerConfig = {
+  enabled: true,
+  route: '/docs',
+  title: 'Servcraft API',
+  description: 'API documentation generated by Servcraft',
+  version: '1.0.0',
+  tags: [
+    { name: 'Auth', description: 'Authentication endpoints' },
+    { name: 'Users', description: 'User management endpoints' },
+    { name: 'Health', description: 'Health check endpoints' },
+  ],
+};
+export async function registerSwagger(
+  app: FastifyInstance,
+  customConfig?: Partial<SwaggerConfig>
+): Promise<void> {
+  const swaggerConfig = { ...defaultConfig, ...customConfig };
+  if (swaggerConfig.enabled === false) {
+    logger.info('Swagger documentation disabled');
+    return;
+  }
+  await app.register(swagger, {
+    openapi: {
+      openapi: '3.0.3',
+      info: {
+        title: swaggerConfig.title,
+        description: swaggerConfig.description,
+        version: swaggerConfig.version,
+        contact: swaggerConfig.contact,
+        license: swaggerConfig.license,
+      },
+      servers: swaggerConfig.servers || [
+        {
+          url: `http://localhost:${config.server.port}`,
+          description: 'Development server',
+        },
+      ],
+      tags: swaggerConfig.tags,
+      components: {
+        securitySchemes: {
+          bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT',
+            description: 'Enter your JWT token',
+          },
+        },
+      },
+    },
+  });
+  await app.register(swaggerUi, {
+    routePrefix: swaggerConfig.route || '/docs',
+    uiConfig: {
+      docExpansion: 'list',
+      deepLinking: true,
+      displayRequestDuration: true,
+      filter: true,
+      showExtensions: true,
+      showCommonExtensions: true,
+    },
+    staticCSP: true,
+    transformStaticCSP: (header) => header,
+  });
+  logger.info('Swagger documentation registered at /docs');
+}
+// Helper to generate schema from Zod
+export function zodToJsonSchema(zodSchema: unknown): Record<string, unknown> {
+  // This is a simplified version - for full support use zod-to-json-schema package
+  return {
+    type: 'object',
+    properties: {},
+  };
+}
+// Common response schemas
+export const commonResponses = {
+  success: {
+    type: 'object',
+    properties: {
+      success: { type: 'boolean', example: true },
+      data: { type: 'object' },
+    },
+  },
+  error: {
+    type: 'object',
+    properties: {
+      success: { type: 'boolean', example: false },
+      message: { type: 'string' },
+      errors: {
+        type: 'object',
+        additionalProperties: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+      },
+    },
+  },
+  unauthorized: {
+    type: 'object',
+    properties: {
+      success: { type: 'boolean', example: false },
+      message: { type: 'string', example: 'Unauthorized' },
+    },
+  },
+  notFound: {
+    type: 'object',
+    properties: {
+      success: { type: 'boolean', example: false },
+      message: { type: 'string', example: 'Resource not found' },
+    },
+  },
+  paginated: {
+    type: 'object',
+    properties: {
+      success: { type: 'boolean', example: true },
+      data: {
+        type: 'object',
+        properties: {
+          data: { type: 'array', items: { type: 'object' } },
+          meta: {
+            type: 'object',
+            properties: {
+              total: { type: 'number' },
+              page: { type: 'number' },
+              limit: { type: 'number' },
+              totalPages: { type: 'number' },
+              hasNextPage: { type: 'boolean' },
+              hasPrevPage: { type: 'boolean' },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+// Query parameters for pagination
+export const paginationQuery = {
+  type: 'object',
+  properties: {
+    page: { type: 'integer', minimum: 1, default: 1, description: 'Page number' },
+    limit: { type: 'integer', minimum: 1, maximum: 100, default: 20, description: 'Items per page' },
+    sortBy: { type: 'string', description: 'Field to sort by' },
+    sortOrder: { type: 'string', enum: ['asc', 'desc'], default: 'asc', description: 'Sort order' },
+    search: { type: 'string', description: 'Search query' },
+  },
+};
+// ID parameter
+export const idParam = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', format: 'uuid', description: 'Resource ID' },
+  },
+  required: ['id'],
+};