@lenne.tech/nest-server 11.7.3 → 11.9.0

package/src/core/modules/error-code/core-error-code.controller.ts

@@ -0,0 +1,54 @@
+import { Controller, Get, NotFoundException, Param } from '@nestjs/common';
+
+import { Roles } from '../../common/decorators/roles.decorator';
+import { RoleEnum } from '../../common/enums/role.enum';
+import { CoreErrorCodeService } from './core-error-code.service';
+import { IErrorTranslationResponse, SupportedLocale } from './interfaces/error-code.interfaces';
+
+/**
+ * Core Error Code Controller
+ *
+ * Provides REST endpoints for error translations.
+ * This controller is publicly accessible (no authentication required).
+ *
+ * @example
+ * GET /api/i18n/errors/de - Get German translations
+ * GET /api/i18n/errors/en - Get English translations
+ */
+@Controller('api/i18n/errors')
+export class CoreErrorCodeController {
+  constructor(protected readonly errorCodeService: CoreErrorCodeService) {}
+
+  /**
+   * Get error translations for a specific locale
+   *
+   * Returns all error codes with their translations in Nuxt i18n compatible format.
+   *
+   * @param locale - Locale code (e.g., 'de', 'en')
+   * @returns Translations object
+   * @throws NotFoundException if locale is not supported
+   *
+   * @example
+   * Response:
+   * ```json
+   * {
+   *   "errors": {
+   *     "LTNS_0001": "Benutzer mit E-Mail {email} wurde nicht gefunden.",
+   *     "LTNS_0002": "Das eingegebene Passwort ist ungültig."
+   *   }
+   * }
+   * ```
+   */
+  @Get(':locale')
+  @Roles(RoleEnum.S_EVERYONE)
+  getTranslations(@Param('locale') locale: string): IErrorTranslationResponse {
+    if (!this.errorCodeService.isLocaleSupported(locale)) {
+      throw new NotFoundException(
+        `Locale "${locale}" is not supported. ` +
+          `Supported locales: ${this.errorCodeService.getSupportedLocales().join(', ')}`,
+      );
+    }
+
+    return this.errorCodeService.getTranslations(locale as SupportedLocale);
+  }
+}

package/src/core/modules/error-code/core-error-code.service.ts

@@ -0,0 +1,135 @@
+import { Injectable } from '@nestjs/common';
+
+import { getAllErrorDefinitions, IErrorRegistry } from './error-codes';
+import { SupportedLocale } from './interfaces/error-code.interfaces';
+
+/**
+ * Core Error Code Service
+ *
+ * Serves error code translations from the structured ErrorRegistry.
+ * Translations are defined in error-codes.ts as Single Source of Truth.
+ *
+ * Projects can extend this service to add custom error registries.
+ *
+ * @example
+ * ```typescript
+ * // In consuming project:
+ * import { CoreErrorCodeService, IErrorRegistry } from '@lenne.tech/nest-server';
+ *
+ * const ProjectErrors = {
+ *   ORDER_NOT_FOUND: {
+ *     code: 'PROJ_0001',
+ *     message: 'Order not found',
+ *     translations: { de: 'Bestellung nicht gefunden.', en: 'Order not found.' }
+ *   }
+ * } as const satisfies IErrorRegistry;
+ *
+ * @Injectable()
+ * export class ErrorCodeService extends CoreErrorCodeService {
+ *   constructor() {
+ *     super();
+ *     this.registerErrorRegistry(ProjectErrors);
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export class CoreErrorCodeService {
+  /**
+   * Supported locales
+   */
+  protected supportedLocales: SupportedLocale[] = ['de', 'en'];
+
+  /**
+   * Cached translations per locale
+   */
+  protected translations: Map<SupportedLocale, Record<string, string>> = new Map();
+
+  /**
+   * Registered error registries
+   */
+  protected registries: IErrorRegistry[] = [];
+
+  constructor() {
+    // Initialize with core errors
+    this.registerErrorRegistry(getAllErrorDefinitions());
+  }
+
+  /**
+   * Register an error registry and generate translations
+   *
+   * @param registry - Error registry to register
+   */
+  registerErrorRegistry(registry: IErrorRegistry): void {
+    this.registries.push(registry);
+    this.generateTranslationsFromRegistry(registry);
+  }
+
+  /**
+   * Generate translations from error registry
+   *
+   * @param registry - Error registry to extract translations from
+   */
+  protected generateTranslationsFromRegistry(registry: IErrorRegistry): void {
+    for (const [, definition] of Object.entries(registry)) {
+      const { code, translations: defTranslations } = definition;
+
+      for (const locale of this.supportedLocales) {
+        const translation = defTranslations[locale];
+        if (translation) {
+          const existing = this.translations.get(locale) || {};
+          this.translations.set(locale, { ...existing, [code]: translation });
+        }
+      }
+    }
+  }
+
+  /**
+   * Check if a locale is supported
+   *
+   * @param locale - Locale to check
+   * @returns True if locale is supported
+   */
+  isLocaleSupported(locale: string): locale is SupportedLocale {
+    return this.supportedLocales.includes(locale as SupportedLocale);
+  }
+
+  /**
+   * Get supported locales
+   *
+   * @returns Array of supported locales
+   */
+  getSupportedLocales(): SupportedLocale[] {
+    return [...this.supportedLocales];
+  }
+
+  /**
+   * Get all translations for a locale
+   *
+   * @param locale - Locale code (e.g., 'de', 'en')
+   * @returns Translations object wrapped in { errors: ... } for Nuxt i18n compatibility
+   * @throws Error if locale is not supported
+   */
+  getTranslations(locale: SupportedLocale): { errors: Record<string, string> } {
+    if (!this.isLocaleSupported(locale)) {
+      throw new Error(`Locale "${locale}" is not supported. Supported: ${this.supportedLocales.join(', ')}`);
+    }
+
+    return { errors: this.translations.get(locale) || {} };
+  }
+
+  /**
+   * Get all error codes
+   *
+   * @returns Array of error codes from all registries
+   */
+  getErrorCodes(): string[] {
+    const codes = new Set<string>();
+    for (const translations of this.translations.values()) {
+      for (const code of Object.keys(translations)) {
+        codes.add(code);
+      }
+    }
+    return Array.from(codes).sort();
+  }
+}

package/src/core/modules/error-code/error-code.module.ts

@@ -0,0 +1,119 @@
+import { DynamicModule, Global, Module, Type } from '@nestjs/common';
+
+import { CoreErrorCodeController } from './core-error-code.controller';
+import { CoreErrorCodeService } from './core-error-code.service';
+import { IErrorCodeModuleConfig } from './interfaces/error-code.interfaces';
+
+/**
+ * Error Code Module
+ *
+ * Provides error code translations via REST endpoint.
+ * Translations are defined in the error registry (Single Source of Truth).
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (auto-register in CoreModule)
+ * // No explicit import needed - included in CoreModule
+ *
+ * // Extended usage (with custom error registry - RECOMMENDED)
+ * const ProjectErrors = {
+ *   ORDER_NOT_FOUND: {
+ *     code: 'PROJ_0001',
+ *     message: 'Order not found',
+ *     translations: { de: 'Bestellung nicht gefunden.', en: 'Order not found.' }
+ *   }
+ * } as const satisfies IErrorRegistry;
+ *
+ * ErrorCodeModule.forRoot({ additionalErrorRegistry: ProjectErrors })
+ *
+ * // Extended usage (with custom controller and service)
+ * ErrorCodeModule.forRoot({
+ *   additionalErrorRegistry: ProjectErrors,
+ *   controller: ErrorCodeController,
+ *   service: ErrorCodeService,
+ * })
+ * ```
+ */
+@Global()
+@Module({
+  // IMPORTANT: Controllers are NOT registered here - they are registered via forRoot()
+  // This prevents duplicate controller registration when using custom controllers,
+  // which would cause route conflicts (e.g., :locale intercepting /codes)
+  exports: [CoreErrorCodeService],
+  providers: [CoreErrorCodeService],
+})
+export class ErrorCodeModule {
+  /**
+   * Gets the controller class to use (custom or default)
+   */
+  private static getControllerClass(config?: IErrorCodeModuleConfig): Type<any> {
+    return config?.controller || CoreErrorCodeController;
+  }
+
+  /**
+   * Gets the service class to use (custom or default)
+   */
+  private static getServiceClass(config?: IErrorCodeModuleConfig): Type<CoreErrorCodeService> {
+    return config?.service || CoreErrorCodeService;
+  }
+
+  /**
+   * Register the module with configuration
+   *
+   * Supports the following patterns:
+   * 1. **No config**: Uses CoreErrorCodeService and CoreErrorCodeController with core errors only
+   * 2. **additionalErrorRegistry only**: Adds project errors to core errors
+   * 3. **service only**: Uses custom service class (should register its own errors in constructor)
+   * 4. **controller only**: Uses custom controller class with CoreErrorCodeService
+   * 5. **Full config**: Uses custom service and controller
+   *
+   * @param config - Module configuration
+   * @returns Dynamic module
+   */
+  static forRoot(config?: IErrorCodeModuleConfig): DynamicModule {
+    const ControllerClass = this.getControllerClass(config);
+    const ServiceClass = this.getServiceClass(config);
+
+    // Build providers array
+    const providers: any[] = [];
+
+    if (config?.service) {
+      // If a custom service is provided, register it under both tokens:
+      // 1. Its own class (for direct injection in custom controllers)
+      // 2. CoreErrorCodeService (for backward compatibility)
+      providers.push(ServiceClass);
+      providers.push({
+        provide: CoreErrorCodeService,
+        useExisting: ServiceClass,
+      });
+    } else {
+      // Use factory to register additional errors
+      providers.push({
+        provide: CoreErrorCodeService,
+        useFactory: () => {
+          const service = new CoreErrorCodeService();
+
+          // Add additional error registry
+          if (config?.additionalErrorRegistry) {
+            service.registerErrorRegistry(config.additionalErrorRegistry);
+          }
+
+          return service;
+        },
+      });
+    }
+
+    // Export both the base class and custom service class (if provided)
+    const exports: any[] = [CoreErrorCodeService];
+    if (config?.service && ServiceClass !== CoreErrorCodeService) {
+      exports.push(ServiceClass);
+    }
+
+    return {
+      controllers: [ControllerClass],
+      exports,
+      module: ErrorCodeModule,
+      providers,
+    };
+  }
+}

package/src/core/modules/error-code/error-codes.ts

@@ -0,0 +1,405 @@
+/**
+ * Lenne Tech Nest Server Error Codes - Structured Registry
+ *
+ * Single Source of Truth for all error codes, messages, and translations.
+ * This file serves as the central registry that:
+ * - Defines error codes with human-readable messages
+ * - Provides translations for multiple languages
+ * - Generates the i18n JSON endpoint automatically
+ *
+ * API Response Format: #PREFIX_XXXX: Short technical description
+ * - # = Marker for machine parsing
+ * - PREFIX = LTNS (Lenne Tech Nest Server) or project-specific
+ * - XXXX = Unique number within range
+ * - : = Separator
+ * - Description = English developer-friendly message
+ *
+ * Error code ranges:
+ * - LTNS_0001-LTNS_0099: Authentication errors
+ * - LTNS_0100-LTNS_0199: Authorization errors
+ * - LTNS_0200-LTNS_0299: User errors
+ * - LTNS_0300-LTNS_0399: Validation errors
+ * - LTNS_0400-LTNS_0499: Resource errors
+ * - LTNS_0500-LTNS_0599: File errors
+ * - LTNS_0900-LTNS_0999: Internal errors
+ *
+ * @example
+ * ```typescript
+ * import { UnauthorizedException } from '@nestjs/common';
+ * import { ErrorCode } from '@lenne.tech/nest-server';
+ *
+ * throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+ * // Response: { statusCode: 401, message: "#LTNS_0100: Unauthorized - User is not logged in" }
+ * ```
+ */
+
+// =====================================================
+// Type Definitions
+// =====================================================
+
+/**
+ * Structure for a single error definition
+ */
+export interface IErrorDefinition {
+  /** Unique error code (e.g., LTNS_0100) */
+  code: string;
+  /** English developer message */
+  message: string;
+  /** Translations for end users */
+  translations: {
+    [locale: string]: string;
+    de: string;
+    en: string;
+  };
+}
+
+/**
+ * Registry type for error definitions
+ */
+export type IErrorRegistry = Record<string, IErrorDefinition>;
+
+// =====================================================
+// Core Error Registry (Single Source of Truth)
+// =====================================================
+
+/**
+ * LTNS Error Registry - Contains all core error definitions
+ *
+ * Each entry includes:
+ * - code: The unique identifier
+ * - message: English technical description for developers
+ * - translations: Localized messages for end users
+ *
+ * NOTE: Entries are grouped by error code range for maintainability.
+ * Do not sort alphabetically - the numeric grouping is intentional.
+ */
+/* eslint-disable perfectionist/sort-objects */
+export const LtnsErrors = {
+  // =====================================================
+  // Authentication Errors (LTNS_0001-LTNS_0099)
+  // =====================================================
+
+  USER_NOT_FOUND: {
+    code: 'LTNS_0001',
+    message: 'User not found',
+    translations: {
+      de: 'Benutzer wurde nicht gefunden.',
+      en: 'User not found.',
+    },
+  },
+
+  INVALID_PASSWORD: {
+    code: 'LTNS_0002',
+    message: 'Invalid password',
+    translations: {
+      de: 'Das eingegebene Passwort ist ungültig.',
+      en: 'The provided password is invalid.',
+    },
+  },
+
+  INVALID_TOKEN: {
+    code: 'LTNS_0003',
+    message: 'Invalid or malformed token',
+    translations: {
+      de: 'Der Token ist ungültig oder fehlerhaft.',
+      en: 'The token is invalid or malformed.',
+    },
+  },
+
+  TOKEN_EXPIRED: {
+    code: 'LTNS_0004',
+    message: 'Token has expired',
+    translations: {
+      de: 'Der Token ist abgelaufen. Bitte melden Sie sich erneut an.',
+      en: 'The token has expired. Please sign in again.',
+    },
+  },
+
+  REFRESH_TOKEN_REQUIRED: {
+    code: 'LTNS_0005',
+    message: 'Refresh token required',
+    translations: {
+      de: 'Ein Refresh-Token wird benötigt.',
+      en: 'A refresh token is required.',
+    },
+  },
+
+  USER_NOT_VERIFIED: {
+    code: 'LTNS_0006',
+    message: 'User email not verified',
+    translations: {
+      de: 'Ihre E-Mail-Adresse wurde noch nicht verifiziert.',
+      en: 'Your email address has not been verified yet.',
+    },
+  },
+
+  // =====================================================
+  // Authorization Errors (LTNS_0100-LTNS_0199)
+  // =====================================================
+
+  UNAUTHORIZED: {
+    code: 'LTNS_0100',
+    message: 'Unauthorized - User is not logged in',
+    translations: {
+      de: 'Sie sind nicht angemeldet.',
+      en: 'You are not logged in.',
+    },
+  },
+
+  ACCESS_DENIED: {
+    code: 'LTNS_0101',
+    message: 'Access denied - Insufficient permissions',
+    translations: {
+      de: 'Zugriff verweigert. Sie haben nicht die erforderlichen Berechtigungen.',
+      en: 'Access denied. You do not have the required permissions.',
+    },
+  },
+
+  RESOURCE_FORBIDDEN: {
+    code: 'LTNS_0102',
+    message: 'Resource access forbidden',
+    translations: {
+      de: 'Der Zugriff auf diese Ressource ist nicht erlaubt.',
+      en: 'Access to this resource is forbidden.',
+    },
+  },
+
+  // =====================================================
+  // User Errors (LTNS_0200-LTNS_0299)
+  // =====================================================
+
+  EMAIL_ALREADY_EXISTS: {
+    code: 'LTNS_0200',
+    message: 'Email already registered',
+    translations: {
+      de: 'Diese E-Mail-Adresse ist bereits registriert.',
+      en: 'This email address is already registered.',
+    },
+  },
+
+  USERNAME_ALREADY_EXISTS: {
+    code: 'LTNS_0201',
+    message: 'Username already taken',
+    translations: {
+      de: 'Dieser Benutzername ist bereits vergeben.',
+      en: 'This username is already taken.',
+    },
+  },
+
+  // =====================================================
+  // Validation Errors (LTNS_0300-LTNS_0399)
+  // =====================================================
+
+  VALIDATION_FAILED: {
+    code: 'LTNS_0300',
+    message: 'Validation failed',
+    translations: {
+      de: 'Die Validierung ist fehlgeschlagen.',
+      en: 'Validation failed.',
+    },
+  },
+
+  REQUIRED_FIELD_MISSING: {
+    code: 'LTNS_0301',
+    message: 'Required field missing',
+    translations: {
+      de: 'Ein erforderliches Feld fehlt.',
+      en: 'A required field is missing.',
+    },
+  },
+
+  INVALID_FIELD_FORMAT: {
+    code: 'LTNS_0302',
+    message: 'Invalid field format',
+    translations: {
+      de: 'Das Feldformat ist ungültig.',
+      en: 'The field format is invalid.',
+    },
+  },
+
+  // =====================================================
+  // Resource Errors (LTNS_0400-LTNS_0499)
+  // =====================================================
+
+  RESOURCE_NOT_FOUND: {
+    code: 'LTNS_0400',
+    message: 'Resource not found',
+    translations: {
+      de: 'Die angeforderte Ressource wurde nicht gefunden.',
+      en: 'The requested resource was not found.',
+    },
+  },
+
+  RESOURCE_ALREADY_EXISTS: {
+    code: 'LTNS_0401',
+    message: 'Resource already exists',
+    translations: {
+      de: 'Diese Ressource existiert bereits.',
+      en: 'This resource already exists.',
+    },
+  },
+
+  // =====================================================
+  // File Errors (LTNS_0500-LTNS_0599)
+  // =====================================================
+
+  FILE_NOT_FOUND: {
+    code: 'LTNS_0500',
+    message: 'File not found',
+    translations: {
+      de: 'Die Datei wurde nicht gefunden.',
+      en: 'The file was not found.',
+    },
+  },
+
+  FILE_UPLOAD_FAILED: {
+    code: 'LTNS_0501',
+    message: 'File upload failed',
+    translations: {
+      de: 'Der Datei-Upload ist fehlgeschlagen.',
+      en: 'The file upload failed.',
+    },
+  },
+
+  FILE_TYPE_NOT_ALLOWED: {
+    code: 'LTNS_0502',
+    message: 'File type not allowed',
+    translations: {
+      de: 'Dieser Dateityp ist nicht erlaubt.',
+      en: 'This file type is not allowed.',
+    },
+  },
+
+  // =====================================================
+  // Internal Errors (LTNS_0900-LTNS_0999)
+  // =====================================================
+
+  INTERNAL_ERROR: {
+    code: 'LTNS_0900',
+    message: 'Internal server error',
+    translations: {
+      de: 'Ein interner Serverfehler ist aufgetreten.',
+      en: 'An internal server error occurred.',
+    },
+  },
+
+  SERVICE_UNAVAILABLE: {
+    code: 'LTNS_0901',
+    message: 'Service temporarily unavailable',
+    translations: {
+      de: 'Der Dienst ist vorübergehend nicht verfügbar.',
+      en: 'The service is temporarily unavailable.',
+    },
+  },
+
+  LEGACY_AUTH_DISABLED: {
+    code: 'LTNS_0902',
+    message: 'Legacy authentication is disabled',
+    translations: {
+      de: 'Die Legacy-Authentifizierung ist deaktiviert. Bitte nutzen Sie die neue Authentifizierung.',
+      en: 'Legacy authentication is disabled. Please use the new authentication.',
+    },
+  },
+} as const satisfies IErrorRegistry;
+/* eslint-enable perfectionist/sort-objects */
+
+// =====================================================
+// Generated ErrorCode Object
+// =====================================================
+
+/**
+ * Generate formatted error message from definition
+ * Format: #CODE: Message
+ */
+function formatErrorMessage(def: IErrorDefinition): string {
+  return `#${def.code}: ${def.message}`;
+}
+
+/**
+ * Generate ErrorCode object from registry
+ * Maps each key to its formatted error string
+ */
+function generateErrorCodes<T extends IErrorRegistry>(registry: T): { [K in keyof T]: string } {
+  const result = {} as { [K in keyof T]: string };
+  for (const key of Object.keys(registry) as Array<keyof T>) {
+    result[key] = formatErrorMessage(registry[key]);
+  }
+  return result;
+}
+
+/**
+ * ErrorCode - Use this in your code with NestJS exceptions
+ *
+ * @example
+ * ```typescript
+ * throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+ * // Response: { statusCode: 401, message: "#LTNS_0100: Unauthorized - User is not logged in" }
+ * ```
+ */
+export const ErrorCode = generateErrorCodes(LtnsErrors);
+
+// =====================================================
+// Type Exports
+// =====================================================
+
+/**
+ * Type for error code keys (readable names like USER_NOT_FOUND)
+ */
+export type ErrorCodeKey = keyof typeof ErrorCode;
+
+/**
+ * Type for all error code formatted strings
+ */
+export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+/**
+ * Type for raw error codes (like LTNS_0100)
+ */
+export type RawErrorCode = (typeof LtnsErrors)[keyof typeof LtnsErrors]['code'];
+
+// =====================================================
+// Helper Functions
+// =====================================================
+
+/**
+ * Get all error definitions (for i18n endpoint)
+ *
+ * @returns All error definitions from the registry
+ */
+export function getAllErrorDefinitions(): typeof LtnsErrors {
+  return LtnsErrors;
+}
+
+// =====================================================
+// Extension Support
+// =====================================================
+
+/**
+ * Merge project-specific errors with core errors
+ *
+ * @param projectErrors - Project-specific error registry
+ * @returns Merged error codes object
+ *
+ * @example
+ * ```typescript
+ * // In your project
+ * const ProjectErrors = {
+ *   ORDER_NOT_FOUND: {
+ *     code: 'PROJ_0001',
+ *     message: 'Order not found',
+ *     translations: { de: 'Bestellung nicht gefunden.', en: 'Order not found.' }
+ *   }
+ * } as const satisfies IErrorRegistry;
+ *
+ * export const ErrorCode = mergeErrorCodes(ProjectErrors);
+ * // Contains both LTNS_* and PROJ_* errors
+ * ```
+ */
+export function mergeErrorCodes<T extends IErrorRegistry>(
+  projectErrors: T,
+): { [K in keyof T | keyof typeof LtnsErrors]: string } {
+  return {
+    ...ErrorCode,
+    ...generateErrorCodes(projectErrors),
+  } as { [K in keyof T | keyof typeof LtnsErrors]: string };
+}