servcraft 0.1.0 → 0.1.3

package/src/modules/api-versioning/versioning.middleware.ts

@@ -0,0 +1,120 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { VersioningService } from './versioning.service.js';
+import type { VersionMiddlewareOptions } from './types.js';
+
+/**
+ * Request with version info
+ */
+export interface VersionedRequest extends Request {
+  apiVersion?: string;
+  versionInfo?: {
+    version: string;
+    source: string;
+    isValid: boolean;
+    warning?: string;
+  };
+}
+
+/**
+ * Create versioning middleware
+ */
+export function createVersioningMiddleware(
+  versioningService: VersioningService,
+  options: VersionMiddlewareOptions = {}
+): (req: Request, res: Response, next: NextFunction) => void {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const versionedReq = req as VersionedRequest;
+
+    // Detect version
+    const detection = versioningService.detectVersion({
+      url: req.url,
+      headers: req.headers as Record<string, string | string[] | undefined>,
+      query: req.query as Record<string, string | string[] | undefined>,
+    });
+
+    versionedReq.apiVersion = detection.version;
+    versionedReq.versionInfo = detection;
+
+    // Set response headers
+    res.setHeader('X-API-Version', detection.version);
+
+    if (detection.warning) {
+      res.setHeader('X-API-Deprecation-Warning', detection.warning);
+    }
+
+    // Validation
+    if (!detection.isValid) {
+      res.status(400).json({
+        error: 'Invalid API version',
+        version: detection.version,
+        availableVersions: versioningService.getActiveVersions().map((v) => v.version),
+      });
+      return;
+    }
+
+    // Check version requirements
+    if (options.requiredVersion && detection.version !== options.requiredVersion) {
+      res.status(400).json({
+        error: `This endpoint requires API version ${options.requiredVersion}`,
+        currentVersion: detection.version,
+      });
+      return;
+    }
+
+    if (options.minVersion) {
+      if (versioningService.compareVersions(detection.version, options.minVersion) < 0) {
+        res.status(400).json({
+          error: `This endpoint requires at least API version ${options.minVersion}`,
+          currentVersion: detection.version,
+        });
+        return;
+      }
+    }
+
+    if (options.maxVersion) {
+      if (versioningService.compareVersions(detection.version, options.maxVersion) > 0) {
+        res.status(400).json({
+          error: `This endpoint supports up to API version ${options.maxVersion}`,
+          currentVersion: detection.version,
+        });
+        return;
+      }
+    }
+
+    // Check if deprecated versions are allowed
+    const versionInfo = versioningService.getVersion(detection.version);
+    if (versionInfo?.status === 'deprecated' && options.allowDeprecated === false) {
+      res.status(410).json({
+        error: `API version ${detection.version} is deprecated and no longer supported`,
+        sunsetAt: versionInfo.sunsetAt,
+        migrateToVersion: versioningService.getActiveVersions()[0]?.version,
+      });
+      return;
+    }
+
+    next();
+  };
+}
+
+/**
+ * Version-specific route handler
+ */
+export function versionedRoute(
+  versions: Record<string, (req: Request, res: Response) => void | Promise<void>>
+): (req: Request, res: Response) => void | Promise<void> {
+  return (req: Request, res: Response): void | Promise<void> => {
+    const versionedReq = req as VersionedRequest;
+    const version = versionedReq.apiVersion || 'v1';
+
+    const handler = versions[version];
+
+    if (!handler) {
+      res.status(404).json({
+        error: `Endpoint not available in version ${version}`,
+      });
+      return;
+    }
+
+    return handler(req, res);
+  };
+}

package/src/modules/api-versioning/versioning.routes.ts

@@ -0,0 +1,54 @@
+import { Router } from 'express';
+import type { Request, Response } from 'express';
+import type { VersioningService } from './versioning.service.js';
+
+/**
+ * Create versioning routes
+ */
+export function createVersioningRoutes(versioningService: VersioningService): Router {
+  const router = Router();
+
+  /**
+   * Get all API versions
+   * GET /versions
+   */
+  router.get('/versions', (_req: Request, res: Response) => {
+    const versions = versioningService.getAllVersions();
+    res.json({
+      versions,
+      default: versioningService.getAllVersions().find((v) => v.isDefault)?.version,
+    });
+  });
+
+  /**
+   * Get active versions
+   * GET /versions/active
+   */
+  router.get('/versions/active', (_req: Request, res: Response) => {
+    const versions = versioningService.getActiveVersions();
+    res.json({ versions, count: versions.length });
+  });
+
+  /**
+   * Get specific version info
+   * GET /versions/:version
+   */
+  router.get('/versions/:version', (req: Request, res: Response) => {
+    const versionParam = req.params.version;
+    if (!versionParam) {
+      res.status(400).json({ error: 'Version parameter required' });
+      return;
+    }
+
+    const version = versioningService.getVersion(versionParam);
+
+    if (!version) {
+      res.status(404).json({ error: 'Version not found' });
+      return;
+    }
+
+    res.json(version);
+  });
+
+  return router;
+}

package/src/modules/api-versioning/versioning.service.ts

@@ -0,0 +1,189 @@
+import { logger } from '../../core/logger.js';
+import type {
+  VersioningConfig,
+  ApiVersion,
+  VersionDetectionResult,
+  VersionStrategy,
+  VersionMigration,
+} from './types.js';
+
+/**
+ * API Versioning Service
+ * Multiple API versions support
+ */
+export class VersioningService {
+  private config: VersioningConfig;
+  private migrations = new Map<string, VersionMigration>();
+
+  constructor(config: VersioningConfig) {
+    this.config = {
+      headerName: 'X-API-Version',
+      queryParam: 'version',
+      strict: true,
+      deprecationWarnings: true,
+      ...config,
+    };
+
+    logger.info(
+      {
+        strategy: this.config.strategy,
+        defaultVersion: this.config.defaultVersion,
+        versions: this.config.versions.map((v) => v.version),
+      },
+      'API versioning service initialized'
+    );
+  }
+
+  /**
+   * Detect version from request
+   */
+  detectVersion(req: {
+    url?: string;
+    headers?: Record<string, string | string[] | undefined>;
+    query?: Record<string, string | string[] | undefined>;
+  }): VersionDetectionResult {
+    let version: string | null = null;
+    let source: VersionStrategy = this.config.strategy;
+
+    // Try to detect based on strategy
+    switch (this.config.strategy) {
+      case 'url':
+        version = this.detectFromUrl(req.url || '');
+        source = 'url';
+        break;
+
+      case 'header':
+        version = this.detectFromHeader(req.headers || {});
+        source = 'header';
+        break;
+
+      case 'query':
+        version = this.detectFromQuery(req.query || {});
+        source = 'query';
+        break;
+
+      case 'accept-header':
+        version = this.detectFromAcceptHeader(req.headers || {});
+        source = 'accept-header';
+        break;
+    }
+
+    // Fallback to default version
+    if (!version) {
+      version = this.config.defaultVersion;
+      source = this.config.strategy;
+    }
+
+    // Validate version
+    const isValid = this.isVersionValid(version);
+    const versionInfo = this.getVersion(version);
+
+    let warning: string | undefined;
+    if (versionInfo?.status === 'deprecated' && this.config.deprecationWarnings) {
+      warning = `API version ${version} is deprecated`;
+      if (versionInfo.sunsetAt) {
+        warning += ` and will be removed on ${versionInfo.sunsetAt.toISOString().split('T')[0]}`;
+      }
+    }
+
+    return {
+      version,
+      source,
+      isValid,
+      warning,
+    };
+  }
+
+  /**
+   * Get version info
+   */
+  getVersion(version: string): ApiVersion | undefined {
+    return this.config.versions.find((v) => v.version === version);
+  }
+
+  /**
+   * Get all versions
+   */
+  getAllVersions(): ApiVersion[] {
+    return this.config.versions;
+  }
+
+  /**
+   * Get active versions
+   */
+  getActiveVersions(): ApiVersion[] {
+    return this.config.versions.filter((v) => v.status === 'active');
+  }
+
+  /**
+   * Check if version is valid
+   */
+  isVersionValid(version: string): boolean {
+    return this.config.versions.some((v) => v.version === version);
+  }
+
+  /**
+   * Add version migration
+   */
+  addMigration(migration: VersionMigration): void {
+    const key = `${migration.from}-${migration.to}`;
+    this.migrations.set(key, migration);
+    logger.info({ from: migration.from, to: migration.to }, 'Migration added');
+  }
+
+  /**
+   * Get migration
+   */
+  getMigration(from: string, to: string): VersionMigration | undefined {
+    return this.migrations.get(`${from}-${to}`);
+  }
+
+  /**
+   * Compare versions
+   */
+  compareVersions(v1: string, v2: string): number {
+    const num1 = parseInt(v1.replace(/\D/g, ''), 10);
+    const num2 = parseInt(v2.replace(/\D/g, ''), 10);
+    return num1 - num2;
+  }
+
+  /**
+   * Detect version from URL path
+   */
+  private detectFromUrl(url: string): string | null {
+    const match = url.match(/\/(v\d+)\//);
+    return match?.[1] ?? null;
+  }
+
+  /**
+   * Detect version from header
+   */
+  private detectFromHeader(headers: Record<string, string | string[] | undefined>): string | null {
+    const headerValue = headers[this.config.headerName?.toLowerCase() || 'x-api-version'];
+    return Array.isArray(headerValue) ? (headerValue[0] ?? null) : (headerValue ?? null);
+  }
+
+  /**
+   * Detect version from query parameter
+   */
+  private detectFromQuery(query: Record<string, string | string[] | undefined>): string | null {
+    const queryValue = query[this.config.queryParam || 'version'];
+    return Array.isArray(queryValue) ? (queryValue[0] ?? null) : (queryValue ?? null);
+  }
+
+  /**
+   * Detect version from Accept header
+   */
+  private detectFromAcceptHeader(
+    headers: Record<string, string | string[] | undefined>
+  ): string | null {
+    const accept = headers['accept'];
+    const acceptStr = Array.isArray(accept) ? accept[0] : accept;
+
+    if (!acceptStr) return null;
+
+    // Look for version in Accept header like: application/vnd.myapp.v2+json
+    const match = acceptStr.match(/\.v(\d+)\+/);
+    return match ? `v${match[1]}` : null;
+  }
+}

package/src/modules/audit/audit.repository.ts

@@ -0,0 +1,206 @@
+/**
+ * Audit Repository
+ * Prisma-based persistence for audit logs
+ */
+import type { Prisma } from '@prisma/client';
+import type { PrismaClient, AuditLog as PrismaAuditLog } from '@prisma/client';
+import type { AuditLogEntry, AuditLogQuery } from './types.js';
+import type { PaginatedResult, PaginationParams } from '../../types/index.js';
+import { createPaginatedResult, getSkip } from '../../utils/pagination.js';
+
+export interface AuditLogRecord extends AuditLogEntry {
+  id: string;
+  createdAt: Date;
+}
+
+export class AuditRepository {
+  constructor(private prisma: PrismaClient) {}
+
+  /**
+   * Create a new audit log entry
+   */
+  async create(entry: AuditLogEntry): Promise<AuditLogRecord> {
+    const log = await this.prisma.auditLog.create({
+      data: {
+        userId: entry.userId,
+        action: entry.action,
+        resource: entry.resource,
+        resourceId: entry.resourceId,
+        oldValue: entry.oldValue as Prisma.InputJsonValue,
+        newValue: entry.newValue as Prisma.InputJsonValue,
+        ipAddress: entry.ipAddress,
+        userAgent: entry.userAgent,
+        metadata: entry.metadata as Prisma.InputJsonValue,
+      },
+    });
+
+    return this.mapFromPrisma(log);
+  }
+
+  /**
+   * Create multiple audit log entries
+   */
+  async createMany(entries: AuditLogEntry[]): Promise<number> {
+    const result = await this.prisma.auditLog.createMany({
+      data: entries.map((entry) => ({
+        userId: entry.userId,
+        action: entry.action,
+        resource: entry.resource,
+        resourceId: entry.resourceId,
+        oldValue: entry.oldValue as Prisma.InputJsonValue,
+        newValue: entry.newValue as Prisma.InputJsonValue,
+        ipAddress: entry.ipAddress,
+        userAgent: entry.userAgent,
+        metadata: entry.metadata as Prisma.InputJsonValue,
+      })),
+    });
+
+    return result.count;
+  }
+
+  /**
+   * Find audit log by ID
+   */
+  async findById(id: string): Promise<AuditLogRecord | null> {
+    const log = await this.prisma.auditLog.findUnique({
+      where: { id },
+    });
+
+    return log ? this.mapFromPrisma(log) : null;
+  }
+
+  /**
+   * Query audit logs with filters and pagination
+   */
+  async query(params: AuditLogQuery): Promise<PaginatedResult<AuditLogRecord>> {
+    const { page = 1, limit = 20 } = params;
+    const pagination: PaginationParams = { page, limit };
+
+    const where: Prisma.AuditLogWhereInput = {};
+
+    if (params.userId) where.userId = params.userId;
+    if (params.action) where.action = params.action;
+    if (params.resource) where.resource = params.resource;
+    if (params.resourceId) where.resourceId = params.resourceId;
+
+    if (params.startDate || params.endDate) {
+      where.createdAt = {};
+      if (params.startDate) where.createdAt.gte = params.startDate;
+      if (params.endDate) where.createdAt.lte = params.endDate;
+    }
+
+    const [logs, total] = await Promise.all([
+      this.prisma.auditLog.findMany({
+        where,
+        orderBy: { createdAt: 'desc' },
+        skip: getSkip(pagination),
+        take: limit,
+      }),
+      this.prisma.auditLog.count({ where }),
+    ]);
+
+    const data = logs.map((log) => this.mapFromPrisma(log));
+    return createPaginatedResult(data, total, pagination);
+  }
+
+  /**
+   * Find logs by user ID
+   */
+  async findByUser(userId: string, limit = 50): Promise<AuditLogRecord[]> {
+    const logs = await this.prisma.auditLog.findMany({
+      where: { userId },
+      orderBy: { createdAt: 'desc' },
+      take: limit,
+    });
+
+    return logs.map((log) => this.mapFromPrisma(log));
+  }
+
+  /**
+   * Find logs by resource
+   */
+  async findByResource(
+    resource: string,
+    resourceId?: string,
+    limit = 50
+  ): Promise<AuditLogRecord[]> {
+    const where: Prisma.AuditLogWhereInput = { resource };
+    if (resourceId) where.resourceId = resourceId;
+
+    const logs = await this.prisma.auditLog.findMany({
+      where,
+      orderBy: { createdAt: 'desc' },
+      take: limit,
+    });
+
+    return logs.map((log) => this.mapFromPrisma(log));
+  }
+
+  /**
+   * Find logs by action
+   */
+  async findByAction(action: string, limit = 50): Promise<AuditLogRecord[]> {
+    const logs = await this.prisma.auditLog.findMany({
+      where: { action },
+      orderBy: { createdAt: 'desc' },
+      take: limit,
+    });
+
+    return logs.map((log) => this.mapFromPrisma(log));
+  }
+
+  /**
+   * Count logs with optional filters
+   */
+  async count(filters?: Partial<AuditLogQuery>): Promise<number> {
+    const where: Prisma.AuditLogWhereInput = {};
+
+    if (filters?.userId) where.userId = filters.userId;
+    if (filters?.action) where.action = filters.action;
+    if (filters?.resource) where.resource = filters.resource;
+
+    return this.prisma.auditLog.count({ where });
+  }
+
+  /**
+   * Delete old audit logs (for data retention)
+   */
+  async deleteOlderThan(days: number): Promise<number> {
+    const cutoffDate = new Date();
+    cutoffDate.setDate(cutoffDate.getDate() - days);
+
+    const result = await this.prisma.auditLog.deleteMany({
+      where: {
+        createdAt: { lt: cutoffDate },
+      },
+    });
+
+    return result.count;
+  }
+
+  /**
+   * Clear all audit logs (for testing)
+   */
+  async clear(): Promise<void> {
+    await this.prisma.auditLog.deleteMany();
+  }
+
+  /**
+   * Map Prisma model to domain type
+   */
+  private mapFromPrisma(log: PrismaAuditLog): AuditLogRecord {
+    return {
+      id: log.id,
+      userId: log.userId ?? undefined,
+      action: log.action,
+      resource: log.resource,
+      resourceId: log.resourceId ?? undefined,
+      oldValue: log.oldValue as Record<string, unknown> | undefined,
+      newValue: log.newValue as Record<string, unknown> | undefined,
+      ipAddress: log.ipAddress ?? undefined,
+      userAgent: log.userAgent ?? undefined,
+      metadata: log.metadata as Record<string, unknown> | undefined,
+      createdAt: log.createdAt,
+    };
+  }
+}

package/src/modules/audit/audit.service.ts

@@ -1,24 +1,20 @@
-import { randomUUID } from 'crypto';
 import { logger } from '../../core/logger.js';
 import type { AuditLogEntry, AuditLogQuery } from './types.js';
 import type { PaginatedResult } from '../../types/index.js';
-import { createPaginatedResult } from '../../utils/pagination.js';
-
-// In-memory storage (will be replaced by Prisma in production)
-const auditLogs: Map<string, AuditLogEntry & { id: string; createdAt: Date }> = new Map();
+import { AuditRepository, type AuditLogRecord } from './audit.repository.js';
+import { prisma } from '../../database/prisma.js';
 
 export class AuditService {
-  async log(entry: AuditLogEntry): Promise<void> {
-    const id = randomUUID();
-    const auditEntry = {
-      ...entry,
-      id,
-      createdAt: new Date(),
-    };
+  private repository: AuditRepository;
+
+  constructor() {
+    this.repository = new AuditRepository(prisma);
+  }
 
-    auditLogs.set(id, auditEntry);
+  async log(entry: AuditLogEntry): Promise<void> {
+    await this.repository.create(entry);
 
-    // Also log to structured logger
+    // Also log to structured logger for real-time monitoring
     logger.info(
       {
         audit: true,
@@ -32,54 +28,20 @@ export class AuditService {
     );
   }
 
-  async query(
-    params: AuditLogQuery
-  ): Promise<PaginatedResult<AuditLogEntry & { id: string; createdAt: Date }>> {
-    const { page = 1, limit = 20 } = params;
-    let logs = Array.from(auditLogs.values());
-
-    // Apply filters
-    if (params.userId) {
-      logs = logs.filter((log) => log.userId === params.userId);
-    }
-    if (params.action) {
-      logs = logs.filter((log) => log.action === params.action);
-    }
-    if (params.resource) {
-      logs = logs.filter((log) => log.resource === params.resource);
-    }
-    if (params.resourceId) {
-      logs = logs.filter((log) => log.resourceId === params.resourceId);
-    }
-    if (params.startDate) {
-      logs = logs.filter((log) => log.createdAt >= params.startDate!);
-    }
-    if (params.endDate) {
-      logs = logs.filter((log) => log.createdAt <= params.endDate!);
-    }
-
-    // Sort by date descending
-    logs.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
-
-    const total = logs.length;
-    const skip = (page - 1) * limit;
-    const data = logs.slice(skip, skip + limit);
-
-    return createPaginatedResult(data, total, { page, limit });
+  async query(params: AuditLogQuery): Promise<PaginatedResult<AuditLogRecord>> {
+    return this.repository.query(params);
   }
 
-  async findByUser(userId: string, limit = 50): Promise<(AuditLogEntry & { id: string; createdAt: Date })[]> {
-    const result = await this.query({ userId, limit });
-    return result.data;
+  async findByUser(userId: string, limit = 50): Promise<AuditLogRecord[]> {
+    return this.repository.findByUser(userId, limit);
   }
 
   async findByResource(
     resource: string,
     resourceId: string,
     limit = 50
-  ): Promise<(AuditLogEntry & { id: string; createdAt: Date })[]> {
-    const result = await this.query({ resource, resourceId, limit });
-    return result.data;
+  ): Promise<AuditLogRecord[]> {
+    return this.repository.findByResource(resource, resourceId, limit);
   }
 
   // Shortcut methods for common audit events
@@ -136,10 +98,7 @@ export class AuditService {
     });
   }
 
-  async logLogin(
-    userId: string,
-    meta?: { ipAddress?: string; userAgent?: string }
-  ): Promise<void> {
+  async logLogin(userId: string, meta?: { ipAddress?: string; userAgent?: string }): Promise<void> {
     await this.log({
       action: 'login',
       resource: 'auth',
@@ -172,9 +131,18 @@ export class AuditService {
     });
   }
 
+  // Data retention: delete old logs
+  async cleanupOldLogs(retentionDays: number): Promise<number> {
+    const count = await this.repository.deleteOlderThan(retentionDays);
+    if (count > 0) {
+      logger.info({ count, retentionDays }, 'Cleaned up old audit logs');
+    }
+    return count;
+  }
+
   // Clear all logs (for testing)
   async clear(): Promise<void> {
-    auditLogs.clear();
+    await this.repository.clear();
   }
 }