@lenne.tech/nest-server 11.7.3 → 11.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.7.3",
+  "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",
@@ -93,6 +93,8 @@
     "@nestjs/swagger": "11.2.3",
     "@nestjs/terminus": "11.0.0",
     "@nestjs/websockets": "11.1.9",
+    "@tus/file-store": "2.0.0",
+    "@tus/server": "2.3.0",
     "apollo-server-core": "3.13.0",
     "bcrypt": "6.0.0",
     "better-auth": "1.4.8-beta.4",
@@ -167,6 +169,7 @@
     "ts-morph": "27.0.2",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
+    "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "1.5.9",
     "vite": "7.3.0",

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'
@@ -1132,4 +1221,158 @@ export interface IServerOptions {
      */
     path?: string;
   };
+
+  /**
+   * TUS resumable upload configuration.
+   *
+   * Follows the "Enabled by Default" pattern - tus is automatically enabled
+   * without any configuration. Set `tus: false` to explicitly disable.
+   *
+   * Accepts:
+   * - `true` or `undefined`: Enable with defaults (enabled by default)
+   * - `false`: Disable TUS uploads
+   * - `{ ... }`: Enable with custom configuration
+   *
+   * @example
+   * ```typescript
+   * // Default: TUS enabled with all defaults (no config needed)
+   *
+   * // Disable TUS
+   * tus: false,
+   *
+   * // Custom configuration
+   * tus: {
+   *   maxSize: 100 * 1024 * 1024, // 100 MB
+   *   path: '/uploads',
+   * },
+   * ```
+   *
+   * @since 11.8.0
+   */
+  tus?: boolean | ITusConfig;
+}
+
+/**
+ * TUS Upload Configuration Interface
+ *
+ * Follows the "Enabled by Default" pattern - tus is automatically enabled
+ * without any configuration. Set `tus: false` to explicitly disable.
+ */
+export interface ITusConfig {
+  /**
+   * Additional allowed HTTP headers for TUS requests (beyond @tus/server defaults).
+   *
+   * Note: @tus/server already includes all TUS protocol headers:
+   * Authorization, Content-Type, Location, Tus-Extension, Tus-Max-Size,
+   * Tus-Resumable, Tus-Version, Upload-Concat, Upload-Defer-Length,
+   * Upload-Length, Upload-Metadata, Upload-Offset, X-HTTP-Method-Override,
+   * X-Requested-With, X-Forwarded-Host, X-Forwarded-Proto, Forwarded
+   *
+   * Use this only for project-specific custom headers.
+   *
+   * @default [] (no additional headers needed)
+   */
+  allowedHeaders?: string[];
+
+  /**
+   * Allowed MIME types for uploads.
+   * If undefined, all types are allowed.
+   * @default undefined (all types allowed)
+   */
+  allowedTypes?: string[];
+
+  /**
+   * Checksum extension configuration.
+   * Enables data integrity verification.
+   * @default true
+   */
+  checksum?: boolean;
+
+  /**
+   * Concatenation extension configuration.
+   * Allows parallel uploads that are merged.
+   * @default true
+   */
+  concatenation?: boolean;
+
+  /**
+   * Creation extension configuration.
+   * Allows creating new uploads via POST.
+   * @default true
+   */
+  creation?: boolean | ITusCreationConfig;
+
+  /**
+   * Creation With Upload extension configuration.
+   * Allows sending data in the initial POST request.
+   * @default true
+   */
+  creationWithUpload?: boolean;
+
+  /**
+   * Whether tus uploads are enabled.
+   * @default true (enabled by default)
+   */
+  enabled?: boolean;
+
+  /**
+   * Expiration extension configuration.
+   * Automatically cleans up incomplete uploads.
+   * @default { expiresIn: '24h' }
+   */
+  expiration?: boolean | ITusExpirationConfig;
+
+  /**
+   * Maximum upload size in bytes
+   * @default 50 * 1024 * 1024 * 1024 (50 GB)
+   */
+  maxSize?: number;
+
+  /**
+   * Base path for tus endpoints
+   * @default '/tus'
+   */
+  path?: string;
+
+  /**
+   * Termination extension configuration.
+   * Allows deleting uploads via DELETE.
+   * @default true
+   */
+  termination?: boolean;
+
+  /**
+   * Directory for temporary upload chunks.
+   * @default 'uploads/tus'
+   */
+  uploadDir?: string;
+}
+
+/**
+ * TUS Creation extension configuration
+ */
+export interface ITusCreationConfig {
+  /**
+   * Whether creation is enabled
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/**
+ * TUS Expiration extension configuration
+ */
+export interface ITusExpirationConfig {
+  /**
+   * Whether expiration is enabled
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Time until incomplete uploads expire
+   * Supports formats: '24h', '1d', '12h', etc.
+   * @default '24h'
+   */
+  expiresIn?: string;
 }

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`