@lenne.tech/nest-server 11.8.0 → 11.10.0

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/modules/user/interfaces/core-user-service-options.interface.ts

@@ -1,4 +1,4 @@
-import { BetterAuthUserMapper } from '../../better-auth/better-auth-user.mapper';
+import { CoreBetterAuthUserMapper } from '../../better-auth/core-better-auth-user.mapper';
 
 /**
  * Optional configuration for CoreUserService
@@ -8,8 +8,8 @@ import { BetterAuthUserMapper } from '../../better-auth/better-auth-user.mapper'
  */
 export interface CoreUserServiceOptions {
   /**
-   * Optional BetterAuthUserMapper for syncing between Legacy and IAM auth systems.
+   * Optional CoreBetterAuthUserMapper for syncing between Legacy and IAM auth systems.
    * When provided, email changes and user deletions are automatically synced.
    */
-  betterAuthUserMapper?: BetterAuthUserMapper;
+  betterAuthUserMapper?: CoreBetterAuthUserMapper;
 }

package/src/core.module.ts

@@ -19,9 +19,10 @@ import { EmailService } from './core/common/services/email.service';
 import { MailjetService } from './core/common/services/mailjet.service';
 import { ModelDocService } from './core/common/services/model-doc.service';
 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 { CoreBetterAuthUserMapper } from './core/modules/better-auth/core-better-auth-user.mapper';
+import { CoreBetterAuthModule } from './core/modules/better-auth/core-better-auth.module';
+import { CoreBetterAuthService } from './core/modules/better-auth/core-better-auth.service';
+import { ErrorCodeModule } from './core/modules/error-code/error-code.module';
 import { CoreHealthCheckModule } from './core/modules/health-check/core-health-check.module';
 
 /**
@@ -85,8 +86,8 @@ export class CoreModule implements NestModule {
    *
    * **Requirements:**
    * - Configure `betterAuth` in your config (enabled by default)
-   * - Create BetterAuthModule, Resolver, and Controller in your project
-   * - Inject BetterAuthUserMapper in UserService
+   * - Create CoreBetterAuthModule, Resolver, and Controller in your project
+   * - Inject CoreBetterAuthUserMapper in UserService
    *
    * ### Legacy + IAM Signature (For existing projects)
    *
@@ -226,12 +227,27 @@ 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);
     }
 
-    // Add BetterAuthModule based on mode
-    // IAM-only mode: Always register BetterAuthModule (required for subscription auth)
+    // Add CoreBetterAuthModule based on mode
+    // IAM-only mode: Always register CoreBetterAuthModule (required for subscription auth)
     // Legacy mode: Only register if autoRegister is explicitly true
     // betterAuth can be: boolean | IBetterAuth | undefined
     const betterAuthConfig = config.betterAuth;
@@ -242,7 +258,7 @@ export class CoreModule implements NestModule {
     if (isBetterAuthEnabled) {
       if (isIamOnlyMode || isAutoRegister) {
         imports.push(
-          BetterAuthModule.forRoot({
+          CoreBetterAuthModule.forRoot({
             config: betterAuthConfig === true ? {} : betterAuthConfig || {},
             // Pass JWT secrets for backwards compatibility fallback
             fallbackSecrets: [config.jwt?.secret, config.jwt?.refresh?.secret],
@@ -273,14 +289,14 @@ export class CoreModule implements NestModule {
   /**
    * Build GraphQL driver configuration for IAM-only mode
    *
-   * Uses BetterAuthService for subscription authentication via JWT tokens.
+   * Uses CoreBetterAuthService for subscription authentication via JWT tokens.
    * This is the recommended mode for new projects.
    */
   private static buildIamOnlyGraphQlDriver(cors: object, options: Partial<IServerOptions>) {
     return {
-      imports: [BetterAuthModule],
-      inject: [BetterAuthService, BetterAuthUserMapper],
-      useFactory: async (betterAuthService: BetterAuthService, userMapper: BetterAuthUserMapper) =>
+      imports: [CoreBetterAuthModule],
+      inject: [CoreBetterAuthService, CoreBetterAuthUserMapper],
+      useFactory: async (betterAuthService: CoreBetterAuthService, userMapper: CoreBetterAuthUserMapper) =>
         Object.assign(
           {
             autoSchemaFile: 'schema.gql',

package/src/index.ts

@@ -36,6 +36,7 @@ export * from './core/common/helpers/filter.helper';
 export * from './core/common/helpers/graphql.helper';
 export * from './core/common/helpers/gridfs.helper';
 export * from './core/common/helpers/input.helper';
+export * from './core/common/helpers/logging.helper';
 export * from './core/common/helpers/model.helper';
 export * from './core/common/helpers/register-enum.helper';
 export * from './core/common/helpers/scim.helper';
@@ -131,6 +132,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
 // =====================================================================================================================

package/src/server/modules/better-auth/better-auth.controller.ts

@@ -3,9 +3,9 @@ import { Controller } from '@nestjs/common';
 import { Roles } from '../../../core/common/decorators/roles.decorator';
 import { RoleEnum } from '../../../core/common/enums/role.enum';
 import { ConfigService } from '../../../core/common/services/config.service';
-import { BetterAuthUserMapper } from '../../../core/modules/better-auth/better-auth-user.mapper';
-import { BetterAuthService } from '../../../core/modules/better-auth/better-auth.service';
+import { CoreBetterAuthUserMapper } from '../../../core/modules/better-auth/core-better-auth-user.mapper';
 import { CoreBetterAuthController } from '../../../core/modules/better-auth/core-better-auth.controller';
+import { CoreBetterAuthService } from '../../../core/modules/better-auth/core-better-auth.service';
 
 /**
  * Server BetterAuth REST Controller
@@ -32,8 +32,8 @@ import { CoreBetterAuthController } from '../../../core/modules/better-auth/core
 @Roles(RoleEnum.ADMIN)
 export class BetterAuthController extends CoreBetterAuthController {
   constructor(
-    protected override readonly betterAuthService: BetterAuthService,
-    protected override readonly userMapper: BetterAuthUserMapper,
+    protected override readonly betterAuthService: CoreBetterAuthService,
+    protected override readonly userMapper: CoreBetterAuthUserMapper,
     protected override readonly configService: ConfigService,
   ) {
     super(betterAuthService, userMapper, configService);

package/src/server/modules/better-auth/better-auth.module.ts

@@ -1,7 +1,7 @@
 import { DynamicModule, Module } from '@nestjs/common';
 
 import { IBetterAuth } from '../../../core/common/interfaces/server-options.interface';
-import { BetterAuthModule as CoreBetterAuthModule } from '../../../core/modules/better-auth/better-auth.module';
+import { CoreBetterAuthModule } from '../../../core/modules/better-auth/core-better-auth.module';
 import { BetterAuthController } from './better-auth.controller';
 import { BetterAuthResolver } from './better-auth.resolver';