@lenne.tech/nest-server 11.8.0 → 11.9.0

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 };
+}

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

@@ -0,0 +1,14 @@
+// Controller
+export * from './core-error-code.controller';
+
+// Service
+export * from './core-error-code.service';
+
+// Module
+export * from './error-code.module';
+
+// Error Codes
+export * from './error-codes';
+
+// Interfaces
+export * from './interfaces/error-code.interfaces';

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

@@ -0,0 +1,99 @@
+import { Type } from '@nestjs/common';
+
+import { CoreErrorCodeService } from '../core-error-code.service';
+import { IErrorRegistry } from '../error-codes';
+
+/**
+ * Configuration for the error code module
+ */
+export interface IErrorCodeModuleConfig {
+  /**
+   * Additional error registry to merge with core errors
+   *
+   * @example
+   * ```typescript
+   * 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 })
+   * ```
+   */
+  additionalErrorRegistry?: IErrorRegistry;
+
+  /**
+   * Custom controller class to use instead of CoreErrorCodeController.
+   *
+   * **Note:** Use a standalone controller (not extending CoreErrorCodeController)
+   * to ensure correct route registration order when adding new routes.
+   * NestJS registers parent routes first, which can cause parameterized routes
+   * to intercept static routes.
+   *
+   * @example
+   * ```typescript
+   * // Standalone controller (RECOMMENDED)
+   * @Controller('api/i18n/errors')
+   * export class ErrorCodeController {
+   *   constructor(protected readonly errorCodeService: ErrorCodeService) {}
+   *
+   *   @Get('codes')  // Must be defined BEFORE :locale
+   *   @Roles(RoleEnum.S_EVERYONE)
+   *   getAllCodes(): string[] {
+   *     return this.errorCodeService.getErrorCodes();
+   *   }
+   *
+   *   @Get(':locale')
+   *   @Roles(RoleEnum.S_EVERYONE)
+   *   getTranslations(@Param('locale') locale: string) { ... }
+   * }
+   *
+   * // In your module
+   * ErrorCodeModule.forRoot({
+   *   controller: ErrorCodeController,
+   *   service: ErrorCodeService,
+   * })
+   * ```
+   */
+  controller?: Type<any>;
+
+  /**
+   * Custom service class to use instead of CoreErrorCodeService.
+   * The class must extend CoreErrorCodeService.
+   *
+   * @example
+   * ```typescript
+   * // Your custom service with additional locales
+   * @Injectable()
+   * export class ErrorCodeService extends CoreErrorCodeService {
+   *   protected override supportedLocales: SupportedLocale[] = ['de', 'en', 'fr', 'es'];
+   *
+   *   constructor() {
+   *     super();
+   *     this.registerErrorRegistry(ProjectErrors);
+   *   }
+   * }
+   *
+   * // In your module
+   * ErrorCodeModule.forRoot({
+   *   service: ErrorCodeService,
+   * })
+   * ```
+   */
+  service?: Type<CoreErrorCodeService>;
+}
+
+/**
+ * Response format for the translation endpoint
+ */
+export interface IErrorTranslationResponse {
+  errors: Record<string, string>;
+}
+
+/**
+ * Supported locales for error translations
+ */
+export type SupportedLocale = 'de' | 'en';

package/src/core.module.ts

@@ -22,6 +22,7 @@ import { TemplateService } from './core/common/services/template.service';
 import { BetterAuthUserMapper } from './core/modules/better-auth/better-auth-user.mapper';
 import { BetterAuthModule } from './core/modules/better-auth/better-auth.module';
 import { BetterAuthService } from './core/modules/better-auth/better-auth.service';
+import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
 
 /**
@@ -226,6 +227,21 @@ export class CoreModule implements NestModule {
         Object.assign({ driver: ApolloDriver }, config.graphQl.driver, config.graphQl.options),
       ),
     ];
+
+    // Add ErrorCodeModule based on configuration
+    // autoRegister defaults to true (backward compatible)
+    const errorCodeConfig = config.errorCode;
+    const isErrorCodeAutoRegister = errorCodeConfig?.autoRegister !== false;
+
+    if (isErrorCodeAutoRegister) {
+      // Always use forRoot() - it registers the controller and handles configuration
+      imports.push(
+        ErrorCodeModule.forRoot({
+          additionalErrorRegistry: errorCodeConfig?.additionalErrorRegistry,
+        }),
+      );
+    }
+
     if (config.healthCheck) {
       imports.push(CoreHealthCheckModule);
     }

package/src/index.ts

@@ -131,6 +131,12 @@ export * from './core/modules/auth/tokens.decorator';
 
 export * from './core/modules/better-auth';
 
+// =====================================================================================================================
+// Core - Modules - ErrorCode
+// =====================================================================================================================
+
+export * from './core/modules/error-code';
+
 // =====================================================================================================================
 // Core - Modules - File
 // =====================================================================================================================