@lenne.tech/nest-server 11.7.3 → 11.9.0

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/file/README.md

@@ -0,0 +1,165 @@
+# File Module
+
+File upload and download functionality with MongoDB GridFS storage.
+
+## Endpoints
+
+### Public Endpoints (via CoreFileController)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/files/id/:id` | Download file by ID |
+| GET | `/files/:filename` | Download file by filename |
+
+**Note:** These endpoints are public (`S_EVERYONE`) by default. Projects can restrict access by extending `CoreFileController`.
+
+### Admin Endpoints (project-specific)
+
+Projects typically add admin-only endpoints like:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/files/upload` | Upload file (multipart/form-data) |
+| GET | `/files/info/:id` | Get file metadata |
+| DELETE | `/files/:id` | Delete file |
+
+---
+
+## Usage in Projects
+
+### Basic Setup (Extend CoreFileController)
+
+```typescript
+// src/server/modules/file/file.controller.ts
+import { Controller } 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);
+  }
+
+  // Add admin-only endpoints here (upload, delete, etc.)
+}
+```
+
+### Restrict Download Access
+
+To require authentication for downloads, override the inherited methods:
+
+```typescript
+@Controller('files')
+@Roles(RoleEnum.ADMIN)
+export class FileController extends CoreFileController {
+  constructor(protected override readonly fileService: FileService) {
+    super(fileService);
+  }
+
+  // Override to require authentication for ID-based download
+  @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);
+  }
+
+  // Override to require authentication for filename-based download
+  @Get(':filename')
+  @Roles(RoleEnum.S_USER)
+  override async getFile(@Param('filename') filename: string, @Res() res: Response) {
+    return super.getFile(filename, res);
+  }
+}
+```
+
+---
+
+## GraphQL Support
+
+File operations are also available via GraphQL through `CoreFileResolver`:
+
+```graphql
+# Query file by ID
+query {
+  file(id: "...") {
+    id
+    filename
+    contentType
+    length
+  }
+}
+
+# Query file by filename
+query {
+  fileByFilename(filename: "...") {
+    id
+    filename
+    contentType
+  }
+}
+
+# Upload file (via GraphQL Upload scalar)
+mutation {
+  uploadFile(file: Upload!) {
+    id
+    filename
+  }
+}
+
+# Delete file
+mutation {
+  deleteFile(filename: "...") {
+    id
+  }
+}
+```
+
+---
+
+## Integration with TUS
+
+Files uploaded via TUS are automatically stored in GridFS and can be accessed through the same endpoints:
+
+```bash
+# After TUS upload completes, download by ID
+GET /files/id/<gridfs-file-id>
+
+# Or by filename (if unique)
+GET /files/<original-filename>
+```
+
+**Recommendation:** Use ID-based downloads for TUS uploads as filenames may not be unique.
+
+---
+
+## GridFS Storage
+
+Files are stored in MongoDB GridFS with the following structure:
+
+**fs.files collection:**
+```json
+{
+  "_id": ObjectId,
+  "filename": "example.pdf",
+  "length": 1048576,
+  "uploadDate": ISODate,
+  "metadata": {
+    "contentType": "application/pdf",
+    "tusUploadId": "...",  // If uploaded via TUS
+    "uploadedAt": ISODate
+  }
+}
+```
+
+**fs.chunks collection:**
+- Binary file data split into 255KB chunks
+- Automatically managed by GridFS
+
+---
+
+## Related Documentation
+
+- [TUS Module](../tus/README.md) - Resumable upload protocol
+- [CoreFileService](./core-file.service.ts) - File service implementation

package/src/core/modules/file/core-file.controller.ts

@@ -17,7 +17,33 @@ export abstract class CoreFileController {
   protected constructor(protected fileService: CoreFileService) {}
 
   /**
-   * Download file
+   * Download file by ID
+   *
+   * More reliable than filename-based download as IDs are unique.
+   * Recommended for TUS uploads and when filename uniqueness cannot be guaranteed.
+   */
+  @Get('id/:id')
+  @Roles(RoleEnum.S_EVERYONE)
+  async getFileById(@Param('id') id: string, @Res() res: Response) {
+    if (!id) {
+      throw new BadRequestException('Missing file ID for download');
+    }
+
+    const file = await this.fileService.getFileInfo(id);
+    if (!file) {
+      throw new NotFoundException('File not found');
+    }
+    const filestream = await this.fileService.getFileStream(id);
+    res.header('Content-Type', file.contentType || 'application/octet-stream');
+    res.header('Content-Disposition', `attachment; filename=${file.filename}`);
+    return filestream.pipe(res);
+  }
+
+  /**
+   * Download file by filename
+   *
+   * Note: If multiple files have the same filename, only the first match is returned.
+   * For unique file access, use GET /files/id/:id instead.
    */
   @Get(':filename')
   @Roles(RoleEnum.S_EVERYONE)

package/src/core/modules/tus/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,176 @@
+# TUS Integration Checklist
+
+**For customizing TUS uploads in projects using `@lenne.tech/nest-server`.**
+
+> **Note:** TUS is **enabled by default** with no configuration needed. This checklist is only for projects that need to customize behavior (e.g., require authentication).
+
+---
+
+## Do You Need This Checklist?
+
+| Scenario | Checklist Needed? |
+|----------|-------------------|
+| Use TUS with defaults (everyone can upload) | No - works automatically |
+| Require authentication for uploads | Yes - Step 1 |
+| Custom upload handling (notifications, etc.) | Yes - Step 2 |
+| Disable TUS completely | No - just use `TusModule.forRoot({ config: false })` |
+
+---
+
+## Reference Implementation
+
+**Local (in your node_modules):**
+```
+node_modules/@lenne.tech/nest-server/src/server/server.module.ts
+```
+
+**GitHub:**
+https://github.com/lenneTech/nest-server/tree/develop/src/server
+
+---
+
+## Step 1: Custom Controller (Require Authentication)
+
+**Create:** `src/server/modules/tus/tus.controller.ts`
+
+```typescript
+import { Controller } from '@nestjs/common';
+import { CoreTusController, Roles, RoleEnum } from '@lenne.tech/nest-server';
+
+@Controller('tus')
+@Roles(RoleEnum.S_USER) // Require authenticated user
+export class TusController extends CoreTusController {
+  // All methods inherit the S_USER requirement
+  // Override methods here for custom logic
+}
+```
+
+**Update ServerModule:**
+
+```typescript
+// src/server/server.module.ts
+import { TusModule } from '@lenne.tech/nest-server';
+import { TusController } from './modules/tus/tus.controller';
+
+@Module({
+  imports: [
+    // ... other imports
+    TusModule.forRoot({
+      controller: TusController, // Use custom controller
+    }),
+  ],
+})
+export class ServerModule {}
+```
+
+---
+
+## Step 2: Custom Service (Custom Upload Handling)
+
+**Create:** `src/server/modules/tus/tus.service.ts`
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { CoreTusService } from '@lenne.tech/nest-server';
+import { Upload } from '@tus/server';
+
+@Injectable()
+export class TusService extends CoreTusService {
+  protected override async onUploadComplete(upload: Upload): Promise<void> {
+    // Call parent to handle GridFS migration
+    await super.onUploadComplete(upload);
+
+    // Add custom logic
+    const metadata = upload.metadata;
+    console.log(`Upload complete: ${metadata.filename}`);
+    // await this.notificationService.sendUploadComplete(...);
+  }
+}
+```
+
+**Note:** To use a custom service, you'll need to create a custom TusModule that provides your service instead of CoreTusService.
+
+---
+
+## Configuration Options
+
+### Default Configuration (No Changes Needed)
+
+```typescript
+// TUS works with these defaults:
+{
+  enabled: true,
+  path: '/tus',
+  maxSize: 50 * 1024 * 1024 * 1024, // 50 GB
+  expiration: { expiresIn: '24h' },
+}
+```
+
+### Custom Configuration
+
+```typescript
+// server.module.ts
+TusModule.forRoot({
+  config: {
+    maxSize: 100 * 1024 * 1024, // 100 MB
+    path: '/uploads',
+    expiration: { expiresIn: '12h' },
+  },
+})
+```
+
+### Disable TUS
+
+```typescript
+TusModule.forRoot({ config: false })
+```
+
+---
+
+## Verification Checklist
+
+- [ ] `npm run build` succeeds
+- [ ] `npm test` passes
+- [ ] `OPTIONS /tus` returns TUS capabilities
+- [ ] Upload via tus-js-client works
+- [ ] File appears in GridFS after upload completion
+- [ ] (If customized) Authentication is required for uploads
+
+---
+
+## Common Mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Forgot to register custom controller | Default S_EVERYONE permissions | Add `controller: TusController` to forRoot() |
+| Custom controller missing @Roles | No authentication required | Add `@Roles(RoleEnum.S_USER)` to controller class |
+| Using wrong endpoint path | 404 on upload | Ensure client uses same path as config |
+
+---
+
+## Client Configuration
+
+```typescript
+import { Upload } from 'tus-js-client';
+
+const upload = new Upload(file, {
+  endpoint: 'http://localhost:3000/tus',
+  headers: {
+    Authorization: `Bearer ${token}`, // If authentication required
+  },
+  metadata: {
+    filename: file.name,
+    filetype: file.type,
+  },
+  onSuccess: () => console.log('Upload complete!'),
+});
+
+upload.start();
+```
+
+---
+
+## Detailed Documentation
+
+- **README.md:** `node_modules/@lenne.tech/nest-server/src/core/modules/tus/README.md`
+- **GitHub:** https://github.com/lenneTech/nest-server/blob/develop/src/core/modules/tus/README.md