@lenne.tech/nest-server 11.21.3 → 11.22.1

package/migration-guides/11.7.x-to-11.8.x.md

@@ -0,0 +1,318 @@
+# Migration Guide: 11.7.x → 11.8.x
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | 1 (File download endpoint) |
+| **New Features** | 2 (TUS Module, CoreFileController) |
+| **Bugfixes** | None |
+| **Migration Effort** | ~10 minutes |
+
+---
+
+## Prerequisites
+
+### Node.js Version
+
+**Node.js >= 20.19.0 is required** for `@tus/server` support.
+
+```bash
+# Check your version
+node --version
+
+# Should output v20.19.0 or higher
+```
+
+### New Dependencies
+
+The following packages are automatically installed with nest-server 11.8.x:
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `@tus/server` | 2.3.0 | TUS protocol server implementation |
+| `@tus/file-store` | 2.0.0 | File storage backend for TUS uploads |
+
+These are production dependencies and will be installed automatically when updating nest-server.
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+npm install @lenne.tech/nest-server@11.8.x
+
+# Install new TUS dependencies (automatically included)
+npm install
+
+# Verify build
+npm run build
+
+# Run tests
+npm test
+```
+
+**Important:** If your project uses file downloads, see [Breaking Changes](#breaking-changes) below.
+
+---
+
+## What's New in 11.8.x
+
+### 1. TUS Module (Resumable Uploads)
+
+TUS is **enabled by default** - no configuration required! The module provides resumable file uploads using the [tus.io](https://tus.io) protocol.
+
+**Endpoints (automatically available):**
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| OPTIONS | `/tus` | Get server capabilities |
+| POST | `/tus` | Create new upload |
+| HEAD | `/tus/:id` | Get upload status |
+| PATCH | `/tus/:id` | Continue upload |
+| DELETE | `/tus/:id` | Terminate upload |
+
+**Default Configuration:**
+```typescript
+{
+  enabled: true,
+  path: '/tus',
+  maxSize: 50 * 1024 * 1024 * 1024, // 50 GB
+  expiration: { expiresIn: '24h' },
+}
+```
+
+> **Note:** `@tus/server` already includes all TUS protocol headers (Authorization, Content-Type, Tus-Resumable, Upload-Length, Upload-Metadata, Upload-Offset, etc.). The `allowedHeaders` option is only for project-specific custom headers.
+
+**Add custom headers (if needed):**
+```typescript
+// config.env.ts
+tus: {
+  allowedHeaders: ['X-Custom-Header'], // Only additional project-specific headers
+}
+```
+
+**Disable TUS (if needed):**
+```typescript
+// server.module.ts
+TusModule.forRoot({ config: false })
+```
+
+**Client Usage:**
+```typescript
+import { Upload } from 'tus-js-client';
+
+const upload = new Upload(file, {
+  endpoint: 'http://localhost:3000/tus',
+  metadata: { filename: file.name, filetype: file.type },
+  onSuccess: () => console.log('Upload complete!'),
+});
+upload.start();
+```
+
+### 2. CoreFileController (Public Download Endpoints)
+
+New abstract controller providing public file download endpoints:
+
+| Endpoint | Description | Permission |
+|----------|-------------|------------|
+| `GET /files/id/:id` | Download by ID | S_EVERYONE |
+| `GET /files/:filename` | Download by filename | S_EVERYONE |
+
+Projects extending `CoreFileController` automatically get these endpoints.
+
+---
+
+## Breaking Changes
+
+### Change 1: File Download Endpoint Pattern
+
+The file download by ID endpoint has changed from `/files/:id` to `/files/id/:id`.
+
+**Before (11.7.x):**
+```typescript
+// FileController with custom download endpoint
+@Get(':id')
+@Roles(RoleEnum.ADMIN)
+async getFile(@Param('id') id: string, @Res() res: Response) { }
+
+// Client usage
+GET /files/abc123  → Downloads file by ID (admin only)
+```
+
+**After (11.8.x):**
+```typescript
+// FileController extends CoreFileController
+export class FileController extends CoreFileController {
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
+  // Inherited: GET /files/id/:id (public)
+  // Inherited: GET /files/:filename (public)
+}
+
+// Client usage
+GET /files/id/abc123  → Downloads file by ID (public)
+GET /files/example.pdf  → Downloads file by filename (public)
+```
+
+**Migration Steps:**
+
+1. **Update FileController** to extend `CoreFileController`:
+
+```typescript
+// src/server/modules/file/file.controller.ts
+import { Controller, Delete, Get, Param, Post, UploadedFile, UseInterceptors } from '@nestjs/common';
+import { CoreFileController, Roles, RoleEnum } from '@lenne.tech/nest-server';
+import { FileService } from './file.service';
+
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController extends CoreFileController {
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
+
+  // Keep your admin-only endpoints (upload, info, delete)
+  @Post('upload')
+  @Roles(RoleEnum.ADMIN)
+  @UseInterceptors(FileInterceptor('file'))
+  async uploadFile(@UploadedFile() file: Express.Multer.File) { /* ... */ }
+
+  @Get('info/:id')
+  @Roles(RoleEnum.ADMIN)
+  async getFileInfo(@Param('id') id: string) { /* ... */ }
+
+  @Delete(':id')
+  @Roles(RoleEnum.ADMIN)
+  async deleteFile(@Param('id') id: string) { /* ... */ }
+
+  // REMOVE your old getFile() method - CoreFileController handles downloads
+}
+```
+
+2. **Update client-side download URLs:**
+
+```typescript
+// Before
+const downloadUrl = `/files/${fileId}`;
+
+// After
+const downloadUrl = `/files/id/${fileId}`;
+// Or by filename:
+const downloadUrl = `/files/${filename}`;
+```
+
+3. **Optional: Restrict download access** (if you need authentication):
+
+```typescript
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController extends CoreFileController {
+  // Override to require authentication
+  @Get('id/:id')
+  @Roles(RoleEnum.S_USER)  // Require logged-in user
+  override async getFileById(@Param('id') id: string, @Res() res: Response) {
+    return super.getFileById(id, res);
+  }
+
+  @Get(':filename')
+  @Roles(RoleEnum.S_USER)
+  override async getFile(@Param('filename') filename: string, @Res() res: Response) {
+    return super.getFile(filename, res);
+  }
+}
+```
+
+---
+
+## Compatibility Notes
+
+### Pattern: Custom FileController without CoreFileController
+
+If you want to keep the old behavior exactly:
+
+```typescript
+// This still works - don't extend CoreFileController
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController {
+  constructor(private readonly fileService: FileService) {}
+
+  @Get(':id')
+  @Roles(RoleEnum.ADMIN)
+  async getFile(@Param('id') id: string, @Res() res: Response) {
+    // Your existing implementation
+  }
+}
+```
+
+### Pattern: TUS with Authentication
+
+By default, TUS allows everyone to upload. To require authentication:
+
+```typescript
+// src/server/modules/tus/tus.controller.ts
+import { Controller } from '@nestjs/common';
+import { CoreTusController, Roles, RoleEnum } from '@lenne.tech/nest-server';
+
+@Controller('tus')
+@Roles(RoleEnum.S_USER)  // Require logged-in user
+export class TusController extends CoreTusController {}
+
+// server.module.ts
+TusModule.forRoot({ controller: TusController })
+```
+
+---
+
+## Troubleshooting
+
+### Download returns 404 after migration
+
+**Cause:** Using old endpoint pattern `/files/:id` instead of `/files/id/:id`
+
+**Solution:** Update client to use `/files/id/:id` or `/files/:filename`
+
+### TUS uploads not working
+
+**Cause:** TUS might be disabled in config
+
+**Solution:** Check that `tus: false` is not set in your config. TUS is enabled by default.
+
+### TypeScript error: "must have an 'override' modifier"
+
+**Cause:** `fileService` in constructor needs `override` when extending CoreFileController
+
+**Solution:**
+```typescript
+// Add 'override' keyword
+constructor(protected override readonly fileService: FileService) {
+  super(fileService);
+}
+```
+
+---
+
+## Module Documentation
+
+### TUS Module
+
+- **README:** [src/core/modules/tus/README.md](../src/core/modules/tus/README.md)
+- **Integration Checklist:** [src/core/modules/tus/INTEGRATION-CHECKLIST.md](../src/core/modules/tus/INTEGRATION-CHECKLIST.md)
+- **Reference Implementation:** `src/server/server.module.ts`
+
+### File Module
+
+- **README:** [src/core/modules/file/README.md](../src/core/modules/file/README.md)
+- **Reference Implementation:** `src/server/modules/file/file.controller.ts`
+
+---
+
+## References
+
+- [TUS Protocol](https://tus.io/protocols/resumable-upload)
+- [tus-js-client](https://github.com/tus/tus-js-client)
+- [@tus/server](https://github.com/tus/tus-node-server)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

package/migration-guides/11.8.x-to-11.9.x.md

@@ -0,0 +1,322 @@
+# Migration Guide: 11.8.x → 11.9.x
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | ErrorCodeModule for centralized error handling with i18n translations |
+| **Bugfixes** | None |
+| **Migration Effort** | Minimal (~5 minutes for basic update, optional feature adoption) |
+
+---
+
+## Quick Migration (No Breaking Changes)
+
+```bash
+# Update package
+npm install @lenne.tech/nest-server@11.9.x
+
+# Verify build
+npm run build
+
+# Run tests
+npm test
+```
+
+**That's it!** The ErrorCodeModule is automatically registered and provides error translations at `/api/i18n/errors/:locale`.
+
+---
+
+## What's New in 11.9.x
+
+### 1. ErrorCodeModule - Centralized Error Handling with i18n
+
+The new ErrorCodeModule provides a centralized system for error codes with internationalization support.
+
+#### Features
+
+- **REST API** for error translations (Nuxt i18n compatible)
+- **Type-safe error codes** with `ErrorCode` constant
+- **Extensible** for project-specific error codes
+- **Auto-registered** in CoreModule by default
+
+#### New REST Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/i18n/errors/de` | GET | German error translations |
+| `/api/i18n/errors/en` | GET | English error translations |
+
+#### Response Format (Nuxt i18n compatible)
+
+```json
+{
+  "errors": {
+    "LTNS_0001": "Benutzer wurde nicht gefunden.",
+    "LTNS_0002": "Das eingegebene Passwort ist ungültig.",
+    "LTNS_0100": "Sie sind nicht angemeldet.",
+    "LTNS_0101": "Zugriff verweigert - Unzureichende Berechtigungen."
+  }
+}
+```
+
+> **Note:** The translations returned by the i18n API are user-friendly messages intended for end users. They may differ from the technical error messages used in exceptions (e.g., `#LTNS_0100: Unauthorized - User is not logged in`).
+
+#### Error Code Ranges
+
+| Range | Category |
+|-------|----------|
+| LTNS_0001-0099 | Authentication errors |
+| LTNS_0100-0199 | Authorization errors |
+| LTNS_0200-0299 | User errors |
+| LTNS_0300-0399 | Validation errors |
+| LTNS_0400-0499 | Resource errors |
+| LTNS_0500-0599 | File errors |
+| LTNS_0900-0999 | Internal errors |
+
+---
+
+## Using Error Codes in Your Code
+
+### Basic Usage
+
+```typescript
+import { UnauthorizedException, BadRequestException } from '@nestjs/common';
+import { ErrorCode } from '@lenne.tech/nest-server';
+
+// Throw with standardized error code
+throw new UnauthorizedException(ErrorCode.UNAUTHORIZED);
+// Response: { statusCode: 401, message: "#LTNS_0100: Unauthorized - User is not logged in" }
+
+throw new BadRequestException(ErrorCode.VALIDATION_FAILED);
+// Response: { statusCode: 400, message: "#LTNS_0300: Validation failed" }
+```
+
+### Available Error Codes
+
+```typescript
+ErrorCode.USER_NOT_FOUND          // #LTNS_0001: User not found
+ErrorCode.INVALID_PASSWORD        // #LTNS_0002: Invalid password
+ErrorCode.INVALID_TOKEN           // #LTNS_0003: Invalid or malformed token
+ErrorCode.TOKEN_EXPIRED           // #LTNS_0004: Token has expired
+ErrorCode.REFRESH_TOKEN_REQUIRED  // #LTNS_0005: Refresh token required
+ErrorCode.USER_NOT_VERIFIED       // #LTNS_0006: User email not verified
+ErrorCode.UNAUTHORIZED            // #LTNS_0100: Unauthorized - User is not logged in
+ErrorCode.ACCESS_DENIED           // #LTNS_0101: Access denied - Insufficient permissions
+ErrorCode.RESOURCE_FORBIDDEN      // #LTNS_0102: Resource access forbidden
+ErrorCode.EMAIL_ALREADY_EXISTS    // #LTNS_0200: Email already registered
+ErrorCode.USERNAME_ALREADY_EXISTS // #LTNS_0201: Username already taken
+ErrorCode.VALIDATION_FAILED       // #LTNS_0300: Validation failed
+ErrorCode.REQUIRED_FIELD_MISSING  // #LTNS_0301: Required field missing
+ErrorCode.INVALID_FIELD_FORMAT    // #LTNS_0302: Invalid field format
+ErrorCode.RESOURCE_NOT_FOUND      // #LTNS_0400: Resource not found
+ErrorCode.RESOURCE_ALREADY_EXISTS // #LTNS_0401: Resource already exists
+ErrorCode.FILE_NOT_FOUND          // #LTNS_0500: File not found
+ErrorCode.FILE_UPLOAD_FAILED      // #LTNS_0501: File upload failed
+ErrorCode.FILE_TYPE_NOT_ALLOWED   // #LTNS_0502: File type not allowed
+ErrorCode.INTERNAL_ERROR          // #LTNS_0900: Internal server error
+ErrorCode.SERVICE_UNAVAILABLE     // #LTNS_0901: Service temporarily unavailable
+ErrorCode.LEGACY_AUTH_DISABLED    // #LTNS_0902: Legacy authentication is disabled
+```
+
+---
+
+## Adding Project-Specific Error Codes (Optional)
+
+### Scenario A: Simple Addition via Config (Recommended)
+
+The easiest way to add project-specific error codes.
+
+**1. Create error codes file:**
+
+```typescript
+// src/server/common/errors/project-errors.ts
+import { IErrorRegistry, mergeErrorCodes } from '@lenne.tech/nest-server';
+
+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 usage
+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 Additional Locales)
+
+Use this when you need additional locales beyond German and English.
+
+See [INTEGRATION-CHECKLIST.md](../src/core/modules/error-code/INTEGRATION-CHECKLIST.md) for detailed instructions.
+
+### Scenario C: Custom Controller (For Custom Routes)
+
+Use this when you need custom endpoints like `/codes` listing.
+
+See [INTEGRATION-CHECKLIST.md](../src/core/modules/error-code/INTEGRATION-CHECKLIST.md) for detailed instructions.
+
+---
+
+## Configuration Reference
+
+### New Config Option: errorCode
+
+```typescript
+// config.env.ts
+const config: IServerOptions = {
+  // ... other config ...
+
+  /**
+   * ErrorCodeModule configuration (new in 11.9.0)
+   */
+  errorCode: {
+    /**
+     * Additional error registry to merge with core LTNS_* errors
+     * @optional
+     */
+    additionalErrorRegistry: ProjectErrors,
+
+    /**
+     * Auto-register ErrorCodeModule in CoreModule
+     * Set to false to provide your own module with custom controller/service
+     * @default true
+     */
+    autoRegister: true,
+  },
+};
+```
+
+---
+
+## Compatibility Notes
+
+### Existing Projects
+
+- **No changes required** - ErrorCodeModule is auto-registered and provides translations immediately
+- **Existing error handling** continues to work unchanged
+- **New error codes** are opt-in and can be adopted gradually
+
+### Custom Auth Implementations
+
+If your project extends CoreAuthService or CoreAuthResolver, you can now use standardized error codes:
+
+```typescript
+// Before (still works)
+throw new UnauthorizedException('Invalid password');
+
+// After (recommended)
+import { ErrorCode } from '@lenne.tech/nest-server';
+throw new UnauthorizedException(ErrorCode.INVALID_PASSWORD);
+```
+
+---
+
+## Troubleshooting
+
+### Error translations not loading
+
+**Symptom:** `/api/i18n/errors/de` returns 404
+
+**Solution:** Ensure you're on version 11.9.x and the server has been restarted:
+
+```bash
+npm install @lenne.tech/nest-server@11.9.x
+npm run build
+npm run start:dev
+```
+
+### Custom errors not appearing
+
+**Symptom:** Project-specific errors not in translation response
+
+**Solution:** Verify your config.env.ts includes the additionalErrorRegistry:
+
+```typescript
+import { ProjectErrors } from './server/common/errors/project-errors';
+
+errorCode: {
+  additionalErrorRegistry: ProjectErrors,
+}
+```
+
+### Route conflict with custom controller
+
+**Symptom:** `/codes` endpoint returns locale error
+
+**Solution:** Use a standalone controller (not extending CoreErrorCodeController). See the INTEGRATION-CHECKLIST.md for details.
+
+---
+
+## Module Documentation
+
+### ErrorCodeModule
+
+- **Integration Checklist:** [src/core/modules/error-code/INTEGRATION-CHECKLIST.md](../src/core/modules/error-code/INTEGRATION-CHECKLIST.md)
+- **Reference Implementation:** `src/server/modules/error-code/`
+- **Key Files:**
+  - `error-codes.ts` - Core error definitions and ErrorCode constant
+  - `core-error-code.service.ts` - Service for translation handling
+  - `core-error-code.controller.ts` - REST controller
+  - `interfaces/error-code.interfaces.ts` - Type definitions
+
+---
+
+## New Exports
+
+The following are now exported from `@lenne.tech/nest-server`:
+
+```typescript
+// Error Code types and constants
+export { ErrorCode } from './core/modules/error-code/error-codes';
+export { LtnsErrors } from './core/modules/error-code/error-codes';
+export { IErrorDefinition, IErrorRegistry, ErrorCodeKey, ErrorCodeType, RawErrorCode } from './core/modules/error-code/error-codes';
+export { getAllErrorDefinitions, mergeErrorCodes } from './core/modules/error-code/error-codes';
+
+// Module and services
+export { ErrorCodeModule } from './core/modules/error-code/error-code.module';
+export { CoreErrorCodeService } from './core/modules/error-code/core-error-code.service';
+export { CoreErrorCodeController } from './core/modules/error-code/core-error-code.controller';
+
+// Interfaces
+export { IErrorCodeModuleConfig, IErrorTranslationResponse, SupportedLocale } from './core/modules/error-code/interfaces/error-code.interfaces';
+
+// Config interface
+export { IErrorCode } from './core/common/interfaces/server-options.interface';
+```
+
+---
+
+## References
+
+- [ErrorCodeModule Integration Checklist](../src/core/modules/error-code/INTEGRATION-CHECKLIST.md)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+- [Error Code Documentation](../docs/error-codes.md) (if available)