@lenne.tech/nest-server 11.8.0 → 11.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.8.0",
+  "version": "11.9.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -21,7 +21,7 @@
     "build:pack": "npm pack && echo 'use file:/ROOT_PATH_TO_TGZ_FILE to integrate the package'",
     "build:dev": "npm run build && yalc push --private",
     "docs": "npm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",
-    "docs:bootstrap": "node extras/update-spectaql-version.mjs && npx -y spectaql ./spectaql.yml",
+    "docs:bootstrap": "node extras/update-spectaql-version.mjs && node scripts/run-spectaql.mjs",
     "docs:ci": "ts-node ./scripts/init-server.ts && npm run docs:bootstrap && compodoc -p tsconfig.json",
     "format": "prettier --write 'src/**/*.ts'",
     "format:staged": "pretty-quick --staged",

package/src/config.env.ts

@@ -262,6 +262,10 @@ const config: { [env: string]: IServerOptions } = {
       verificationLink: 'http://localhost:4200/user/verification',
     },
     env: 'local',
+    // Disable auto-registration to allow Server ErrorCodeModule with SRV_* codes
+    errorCode: {
+      autoRegister: false,
+    },
     execAfterInit: 'npm run docs:bootstrap',
     filter: {
       maxLimit: null,

package/src/core/common/interfaces/server-options.interface.ts

@@ -589,6 +589,70 @@ export interface IBetterAuthUserField {
   type: BetterAuthFieldType;
 }
 
+/**
+ * Interface for Error Code module configuration
+ *
+ * Controls how the ErrorCodeModule is registered and configured.
+ *
+ * @since 11.9.0
+ */
+export interface IErrorCode {
+  /**
+   * Additional error registry to merge with core LTNS_* errors
+   *
+   * Use this to add project-specific error codes with a custom prefix.
+   *
+   * @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;
+   *
+   * errorCode: {
+   *   additionalErrorRegistry: ProjectErrors,
+   * }
+   * ```
+   */
+  additionalErrorRegistry?: Record<
+    string,
+    {
+      code: string;
+      message: string;
+      translations: { [locale: string]: string; de: string; en: string };
+    }
+  >;
+
+  /**
+   * Automatically register the ErrorCodeModule in CoreModule
+   *
+   * Set to `false` to disable auto-registration and provide your own
+   * ErrorCodeModule with custom controller and/or service.
+   *
+   * @default true
+   *
+   * @example
+   * ```typescript
+   * // In config.env.ts - disable auto-registration
+   * errorCode: {
+   *   autoRegister: false,
+   * }
+   *
+   * // In server.module.ts - import your custom module
+   * @Module({
+   *   imports: [
+   *     CoreModule.forRoot(...),
+   *     ErrorCodeModule.forRoot(), // Your custom module
+   *   ],
+   * })
+   * ```
+   */
+  autoRegister?: boolean;
+}
+
 /**
  * Interface for JWT configuration (main and refresh)
  */
@@ -766,6 +830,31 @@ export interface IServerOptions {
    */
   env?: string;
 
+  /**
+   * Configuration for the error code module
+   *
+   * Controls how error codes and translations are handled.
+   *
+   * @since 11.9.0
+   *
+   * @example
+   * ```typescript
+   * // Default: auto-register with core errors only
+   * errorCode: undefined
+   *
+   * // Add project-specific error codes
+   * errorCode: {
+   *   additionalErrorRegistry: ProjectErrors,
+   * }
+   *
+   * // Disable auto-registration to provide your own module
+   * errorCode: {
+   *   autoRegister: false,
+   * }
+   * ```
+   */
+  errorCode?: IErrorCode;
+
   /**
    * Exec a command after server is initialized
    * e.g. 'npm run docs:bootstrap'

package/src/core/modules/auth/guards/roles.guard.ts

@@ -1,4 +1,4 @@
-import { ExecutionContext, Injectable, Logger, Optional, UnauthorizedException } from '@nestjs/common';
+import { ExecutionContext, ForbiddenException, Injectable, Logger, Optional, UnauthorizedException } from '@nestjs/common';
 import { ModuleRef, Reflector } from '@nestjs/core';
 import { GqlExecutionContext } from '@nestjs/graphql';
 import { getConnectionToken } from '@nestjs/mongoose';
@@ -7,6 +7,7 @@ import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
 import { BetterAuthService } from '../../better-auth/better-auth.service';
+import { ErrorCode } from '../../error-code';
 import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
 import { ExpiredTokenException } from '../exceptions/expired-token.exception';
 import { InvalidTokenException } from '../exceptions/invalid-token.exception';
@@ -331,7 +332,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
 
     // Check if locked
     if (roles && roles.includes(RoleEnum.S_NO_ONE)) {
-      throw new UnauthorizedException('No access');
+      throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
     }
 
     // Check roles
@@ -354,11 +355,11 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
         if (info?.name === 'TokenExpiredError') {
           throw new ExpiredTokenException();
         }
-        throw new UnauthorizedException('Unauthorized');
+        throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
       }
 
       // Requester is not authorized
-      throw new UnauthorizedException('Missing role');
+      throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
     // Everything is ok

package/src/core/modules/auth/services/core-auth.service.ts

@@ -17,6 +17,7 @@ import { ServiceOptions } from '../../../common/interfaces/service-options.inter
 import { ConfigService } from '../../../common/services/config.service';
 import { BetterAuthUserMapper } from '../../better-auth/better-auth-user.mapper';
 import { BetterAuthService } from '../../better-auth/better-auth.service';
+import { ErrorCode } from '../../error-code';
 import { CoreAuthModel } from '../core-auth.model';
 import { CoreAuthSignInInput } from '../inputs/core-auth-sign-in.input';
 import { CoreAuthSignUpInput } from '../inputs/core-auth-sign-up.input';
@@ -83,13 +84,13 @@ export class CoreAuthService {
     // Check authentication
     const user = serviceOptions.currentUser;
     if (!user || !tokenOrRefreshToken) {
-      throw new UnauthorizedException('Invalid token');
+      throw new UnauthorizedException(ErrorCode.INVALID_TOKEN);
     }
 
     // Check authorization
     const deviceId = this.decodeJwt(tokenOrRefreshToken)?.deviceId;
     if (!deviceId || !user.refreshTokens[deviceId]) {
-      throw new UnauthorizedException('Invalid token');
+      throw new UnauthorizedException(ErrorCode.INVALID_TOKEN);
     }
 
     // Logout from all devices
@@ -374,7 +375,7 @@ export class CoreAuthService {
     if (currentRefreshToken) {
       deviceId = this.decodeJwt(currentRefreshToken)?.deviceId;
       if (!deviceId || !user.refreshTokens?.[deviceId]) {
-        throw new UnauthorizedException('Invalid token');
+        throw new UnauthorizedException(ErrorCode.INVALID_TOKEN);
       }
       if (!this.configService.getFastButReadOnly('jwt.refresh.renewal')) {
         // Return currentToken
@@ -398,7 +399,7 @@ export class CoreAuthService {
     // Set new token
     const payload = this.decodeJwt(newRefreshToken);
     if (!payload) {
-      throw new UnauthorizedException('Invalid token');
+      throw new UnauthorizedException(ErrorCode.INVALID_TOKEN);
     }
     if (!deviceId) {
       deviceId = payload.deviceId;

package/src/core/modules/error-code/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,288 @@
+# ErrorCode Integration Checklist
+
+**For integrating custom error codes into projects using `@lenne.tech/nest-server`.**
+
+> **Estimated time:** 5-10 minutes
+
+---
+
+## Choose Your Scenario
+
+| Scenario | Use When | Configuration | Complexity |
+|----------|----------|---------------|------------|
+| **A. additionalErrorRegistry** | Simple error code addition | Config in `config.env.ts` | Minimal |
+| **B. Custom Service** | Need custom locales or logic | Service inheritance | Low |
+| **C. Custom Controller** | Need custom controller/routes | Service + Controller | Medium |
+
+**Recommendation:** Start with **Scenario A**. Only use B or C if you need customization beyond adding error codes.
+
+---
+
+## Reference Implementation
+
+All files are available as reference in the package:
+
+**Local (in your node_modules):**
+```
+node_modules/@lenne.tech/nest-server/src/server/modules/error-code/
+```
+
+**GitHub:**
+https://github.com/lenneTech/nest-server/tree/develop/src/server/modules/error-code
+
+---
+
+## Scenario A: additionalErrorRegistry (Simplest)
+
+Use this when you just want to add project-specific error codes.
+
+### 1. Define Error Codes
+
+**Create:** `src/server/common/errors/project-errors.ts`
+
+```typescript
+import { IErrorRegistry, mergeErrorCodes } from '@lenne.tech/nest-server';
+
+/**
+ * Project-specific error codes
+ *
+ * Format: PREFIX_XXXX (e.g., PROJ_0001, APP_0001)
+ * Use a unique prefix to avoid collisions with LTNS_* core errors.
+ */
+export const ProjectErrors = {
+  ORDER_NOT_FOUND: {
+    code: 'PROJ_0001',
+    message: 'Order not found',
+    translations: {
+      de: 'Bestellung mit ID {orderId} wurde nicht gefunden.',
+      en: 'Order with ID {orderId} was not found.',
+    },
+  },
+  PAYMENT_FAILED: {
+    code: 'PROJ_0002',
+    message: 'Payment processing failed',
+    translations: {
+      de: 'Die Zahlung konnte nicht verarbeitet werden: {reason}',
+      en: 'Payment processing failed: {reason}',
+    },
+  },
+} as const satisfies IErrorRegistry;
+
+// Merged error codes for type-safe factory functions
+export const ErrorCode = mergeErrorCodes(ProjectErrors);
+```
+
+### 2. Add to config.env.ts
+
+```typescript
+import { ProjectErrors } from './server/common/errors/project-errors';
+
+const config = {
+  // ... other config ...
+  errorCode: {
+    additionalErrorRegistry: ProjectErrors,
+  },
+};
+```
+
+**Done!** Your project errors are now available via `/api/i18n/errors/:locale`.
+
+---
+
+## Scenario B: Custom Service (For Custom Locales)
+
+Use this when you need:
+- Additional locales (e.g., French, Spanish)
+- Custom logic in the service
+
+### 1. Define Error Codes
+
+Same as Scenario A, Step 1.
+
+### 2. Create Custom Service
+
+**Create:** `src/server/modules/error-code/error-code.service.ts`
+**Copy from:** `node_modules/@lenne.tech/nest-server/src/server/modules/error-code/error-code.service.ts`
+
+**Optional customization - add locales:**
+```typescript
+@Injectable()
+export class ErrorCodeService extends CoreErrorCodeService {
+  // Override to add more locales
+  protected override supportedLocales = ['de', 'en', 'fr', 'es'] as const;
+
+  constructor() {
+    super();
+    this.registerErrorRegistry(ProjectErrors);
+  }
+}
+```
+
+### 3. Disable Auto-Registration
+
+**Update:** `src/config.env.ts`
+
+```typescript
+const config = {
+  // ... other config ...
+  errorCode: {
+    autoRegister: false, // Required! Prevents CoreModule from registering its own
+  },
+};
+```
+
+**WHY is `autoRegister: false` required?**
+NestJS @Global() modules use "first wins" for provider registration. Without this, CoreModule's ErrorCodeModule loads first and your custom service is ignored.
+
+### 4. Register in ServerModule
+
+**Update:** `src/server/server.module.ts`
+
+```typescript
+import { ErrorCodeModule as CoreErrorCodeModule } from '@lenne.tech/nest-server';
+import { ErrorCodeService } from './modules/error-code/error-code.service';
+
+@Module({
+  imports: [
+    CoreModule.forRoot(...),
+    // Register with custom service
+    CoreErrorCodeModule.forRoot({
+      service: ErrorCodeService,
+    }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
+---
+
+## Scenario C: Custom Controller (For Custom Routes)
+
+Use this when you need:
+- Custom controller endpoints (e.g., `/codes` listing)
+- Different route paths
+- Additional REST endpoints
+
+**No custom module needed!** Use Core `ErrorCodeModule.forRoot()` with your custom controller and service.
+
+### 1. Create Files
+
+**Copy from:** `node_modules/@lenne.tech/nest-server/src/server/modules/error-code/`
+
+Files needed:
+- `error-codes.ts` - Your error definitions
+- `error-code.service.ts` - Service extending CoreErrorCodeService
+- `error-code.controller.ts` - Controller (**standalone**, not extending)
+- `index.ts` - Exports
+
+**No `error-code.module.ts` needed!**
+
+### 2. Disable Auto-Registration
+
+Same as Scenario B, Step 3.
+
+### 3. Register via Core ErrorCodeModule
+
+**Update:** `src/server/server.module.ts`
+
+```typescript
+import { ErrorCodeModule } from '@lenne.tech/nest-server';
+import { ErrorCodeController } from './modules/error-code/error-code.controller';
+import { ErrorCodeService } from './modules/error-code/error-code.service';
+
+@Module({
+  imports: [
+    CoreModule.forRoot(...),
+    // Use Core ErrorCodeModule with custom service and controller
+    ErrorCodeModule.forRoot({
+      controller: ErrorCodeController,
+      service: ErrorCodeService,
+    }),
+    // ... other modules
+  ],
+})
+export class ServerModule {}
+```
+
+**WHY standalone controller instead of extending?**
+NestJS registers routes from parent classes first, regardless of method order in child classes. This causes `:locale` to intercept `/codes`. A standalone controller ensures correct route order: static routes (`/codes`) first, then parameterized routes (`:locale`).
+
+---
+
+## Verification Checklist
+
+After integration, verify:
+
+- [ ] `npm run build` succeeds without errors
+- [ ] `npm test` passes
+- [ ] `GET /api/i18n/errors/de` returns your project error codes
+- [ ] `GET /api/i18n/errors/en` returns English translations
+- [ ] Error codes follow format `PREFIX_XXXX` (e.g., `PROJ_0001`)
+- [ ] Translations include placeholders where needed (`{param}`)
+
+### For Scenario C only:
+- [ ] `GET /api/i18n/errors/codes` returns all error codes (if implemented)
+
+---
+
+## Common Mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Forgot `autoRegister: false` | Project errors not appearing | Add `errorCode: { autoRegister: false }` to config |
+| Wrong error code format | Validation errors | Use `PREFIX_XXXX` format (4 digits) |
+| Missing translations | Runtime errors | Ensure all locales have translations |
+| Controller extends CoreErrorCodeController | `/codes` returns 404 | Use standalone controller |
+| Duplicate error codes | Unpredictable behavior | Ensure unique codes across all registries |
+| Forgot to import module | No error translations | Import ErrorCodeModule in ServerModule |
+
+---
+
+## Using Error Codes in Code
+
+```typescript
+import { ErrorCode, Errors } from '@lenne.tech/nest-server';
+
+// Type-safe error code access
+const code = ErrorCode.userNotFound;  // Returns '#LTNS_0001: User not found'
+
+// Factory functions with parameters
+throw new BadRequestException(Errors.userNotFound({ email: 'test@example.com' }));
+// Throws: '#LTNS_0001: User with email test@example.com was not found.'
+
+// Project-specific errors (after registration)
+import { ErrorCode as ProjectErrorCode } from './common/errors/project-errors';
+
+const orderCode = ProjectErrorCode.ORDER_NOT_FOUND;  // '#PROJ_0001: Order not found'
+```
+
+---
+
+## API Reference
+
+### REST Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/i18n/errors/:locale` | GET | Get translations for locale (de, en, ...) |
+| `/api/i18n/errors/codes` | GET | Get all error codes (Scenario C only) |
+
+### Response Format (Nuxt i18n compatible)
+
+```json
+{
+  "errors": {
+    "LTNS_0001": "Benutzer mit E-Mail {email} wurde nicht gefunden.",
+    "PROJ_0001": "Bestellung mit ID {orderId} wurde nicht gefunden."
+  }
+}
+```
+
+---
+
+## Detailed Documentation
+
+For complete API reference and advanced topics:
+- **Core Error Codes:** `node_modules/@lenne.tech/nest-server/src/core/modules/error-code/error-codes.ts`
+- **Interfaces:** `node_modules/@lenne.tech/nest-server/src/core/modules/error-code/interfaces/error-code.interfaces.ts`

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