@flusys/nestjs-storage 4.1.0 → 5.0.0

package/README.md

@@ -1,78 +1,9 @@
 # @flusys/nestjs-storage
 
-> Multi-provider file storage for NestJS — Local disk, AWS S3, Azure Blob, and SFTP with folder management, image compression, presigned URL generation, and multi-tenant support.
+Multi-provider file storage for NestJS — Local disk, AWS S3, Azure Blob, and SFTP with folder management, image compression, and multi-tenant support.
 
 [![npm version](https://img.shields.io/npm/v/@flusys/nestjs-storage.svg)](https://www.npmjs.com/package/@flusys/nestjs-storage)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Module Registration](#module-registration)
-  - [forRoot (Sync)](#forroot-sync)
-  - [forRootAsync (Factory)](#forrootasync-factory)
-- [Configuration Reference](#configuration-reference)
-- [Feature Toggles](#feature-toggles)
-- [Storage Providers](#storage-providers)
-  - [Local](#local-provider)
-  - [AWS S3](#aws-s3)
-  - [Azure Blob Storage](#azure-blob-storage)
-  - [SFTP](#sftp)
-  - [Custom Provider](#custom-provider)
-- [API Endpoints](#api-endpoints)
-- [Entities](#entities)
-- [File Serving (Local)](#file-serving-local)
-- [Image Compression](#image-compression)
-- [File Validation](#file-validation)
-- [Exported Services](#exported-services)
-- [Programmatic Usage](#programmatic-usage)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
----
-
-## Overview
-
-`@flusys/nestjs-storage` provides a unified API for managing files across multiple storage backends. Provider configurations are stored in the database — switch providers without code changes. Cloud providers (S3, Azure, SFTP) are dynamically imported so you only pay the install cost for what you use.
-
----
-
-## Features
-
-- **4 storage backends** — Local disk, AWS S3, Azure Blob Storage, SFTP
-- **Pluggable providers** — Register custom providers via `StorageProviderRegistry`
-- **Folder hierarchy** — Organize files in folders with parent-child relationships
-- **Image compression** — Automatic optimization via `sharp` (JPEG, PNG, WebP, AVIF, TIFF, GIF)
-- **Presigned URLs** — Time-limited signed URLs for S3 and Azure with TTL caching
-- **File validation** — Magic-byte validation prevents file-type spoofing
-- **Path traversal protection** — All file paths sanitized before disk access
-- **Company scoping** — Optional `companyId` filtering on all queries
-- **Multi-tenant** — Per-tenant DataSource isolation
-
----
-
-## Compatibility
-
-| Package | Version |
-|---------|---------|
-| `@flusys/nestjs-core` | `^4.0.0` |
-| `@flusys/nestjs-shared` | `^4.0.0` |
-| `sharp` | `^0.33.0` |
-| `uuid` | `^9.0.0` |
-| `mime-types` | `^2.0.0` |
-| `@aws-sdk/client-s3` | `^3.0.0` *(optional)* |
-| `@azure/storage-blob` | `^12.0.0` *(optional)* |
-| `ssh2-sftp-client` | `^9.0.0` *(optional)* |
-| Node.js | `>= 18.x` |
 
 ---
 
@@ -82,28 +13,21 @@
 npm install @flusys/nestjs-storage @flusys/nestjs-shared @flusys/nestjs-core sharp uuid mime-types
 ```
 
-Optional cloud provider SDKs (install only what you need):
+Optional cloud SDKs — install only what you need:
 
 ```bash
-# AWS S3
-npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
-
-# Azure Blob Storage
-npm install @azure/storage-blob
-
-# SFTP
-npm install ssh2-sftp-client
-npm install -D @types/ssh2-sftp-client
+npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner  # S3
+npm install @azure/storage-blob                                                    # Azure
+npm install ssh2-sftp-client                                                       # SFTP
 ```
 
----
+## 1. Register the Module
 
-## Quick Start
+### Synchronous
 
-### Local Storage (Minimal Setup)
+#### Mode 1: Single Database
 
 ```typescript
-import { Module } from '@nestjs/common';
 import { StorageModule } from '@flusys/nestjs-storage';
 
 @Module({
@@ -117,17 +41,17 @@ import { StorageModule } from '@flusys/nestjs-storage';
       },
       config: {
         defaultDatabaseConfig: {
-          type: 'postgres',
+          type: 'mysql',
           host: process.env.DB_HOST,
-          port: Number(process.env.DB_PORT ?? 5432),
+          port: Number(process.env.DB_PORT ?? 3306),
           username: process.env.DB_USER,
           password: process.env.DB_PASSWORD,
           database: process.env.DB_NAME,
         },
-        maxFileSize: 10 * 1024 * 1024,             // 10 MB
-        allowedFileTypes: ['image/*', 'application/pdf'],
+        maxFileSize: 10 * 1024 * 1024, // 10 MB (default: 100 MB)
+        allowedFileTypes: ['image/*', 'application/pdf'], // default: ['*/*']
         localStoragePath: './uploads',
-        appUrl: process.env.APP_URL ?? 'http://localhost:2002',
+        appUrl: process.env.APP_URL,
       },
     }),
   ],
@@ -135,49 +59,43 @@ import { StorageModule } from '@flusys/nestjs-storage';
 export class AppModule {}
 ```
 
-### Register Local File Serving Middleware
-
-```typescript
-import { FileServeMiddleware } from '@flusys/nestjs-storage';
-
-@Module({})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    // Serves GET /storage/upload/file/* from local disk
-    consumer.apply(FileServeMiddleware).forRoutes('storage/upload/file');
-  }
-}
-```
-
----
-
-## Module Registration
-
-### forRoot (Sync)
+#### Mode 2: Multi-Tenant
 
 ```typescript
 StorageModule.forRoot({
-  global?: boolean;
-  includeController?: boolean;
+  global: true,
+  includeController: true,
   bootstrapAppConfig: {
-    databaseMode: 'single' | 'multi-tenant';
-    enableCompanyFeature: boolean;
-  };
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
+  },
   config: {
-    defaultDatabaseConfig: IDatabaseConfig;
-    maxFileSize?: number;          // bytes, default: 100MB
-    allowedFileTypes?: string[];   // MIME types/patterns, default: ['*/*']
-    localStoragePath?: string;     // default: './uploads'
-    appUrl?: string;               // Base URL for local file links
-  };
-})
+    tenantDefaultDatabaseConfig: {
+      type: 'mysql',
+      host: process.env.TENANT_DB_HOST,
+      port: Number(process.env.TENANT_DB_PORT ?? 3306),
+      username: process.env.TENANT_DB_USER,
+      password: process.env.TENANT_DB_PASSWORD,
+      database: process.env.TENANT_DB_NAME,
+    },
+    tenants: [
+      { id: 'tenant-a', database: 'tenant_a_db' },
+      { id: 'tenant-b', database: 'tenant_b_db' },
+    ],
+    maxFileSize: 10 * 1024 * 1024,
+    localStoragePath: './uploads',
+    appUrl: process.env.APP_URL,
+  },
+});
 ```
 
-### forRootAsync (Factory)
+### Asynchronous (with ConfigService)
 
 ```typescript
-import { ConfigService } from '@nestjs/config';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { StorageModule, ITenantDatabaseConfig } from '@flusys/nestjs-storage';
 
+// Single database
 StorageModule.forRootAsync({
   global: true,
   includeController: true,
@@ -188,7 +106,7 @@ StorageModule.forRootAsync({
   imports: [ConfigModule],
   useFactory: (configService: ConfigService) => ({
     defaultDatabaseConfig: {
-      type: 'postgres',
+      type: 'mysql',
       host: configService.get('DB_HOST'),
       port: configService.get<number>('DB_PORT'),
       username: configService.get('DB_USER'),
@@ -200,378 +118,48 @@ StorageModule.forRootAsync({
     localStoragePath: configService.get('UPLOAD_PATH', './uploads'),
   }),
   inject: [ConfigService],
-})
-```
-
----
-
-## Configuration Reference
-
-```typescript
-interface IStorageModuleConfig extends IDataSourceServiceOptions {
-  /** Maximum file size in bytes (default: 100MB) */
-  maxFileSize?: number;
-
-  /** Allowed MIME types. Use '*/*' for all. (default: ['*/*']) */
-  allowedFileTypes?: string[];
-
-  /** Local storage base directory (default: './uploads') */
-  localStoragePath?: string;
-
-  /** Application base URL for building file URLs (local provider) */
-  appUrl?: string;
-}
-```
-
----
+});
 
-## Feature Toggles
-
-| Feature | Config | Default | Effect |
-|---------|--------|---------|--------|
-| Company scoping | `enableCompanyFeature: true` | `false` | Uses `*WithCompany` entity variants; filters all queries by `companyId` |
-| Local file serving | Built-in | Always on | Register `FileServeMiddleware` to serve uploaded files from disk |
-| Cloud providers | Install SDK + register | Disabled | S3/Azure/SFTP only activate after provider registration |
-
----
-
-## Storage Providers
-
-### Local Provider
-
-Built-in, no extra SDK required. Files stored on the server filesystem.
-
-Create a `StorageConfig` record:
-
-```json
-POST /storage/storage-config/insert
-{
-  "name": "Local Storage",
-  "storage": "local",
-  "config": {},
-  "isActive": true,
-  "isDefault": true
-}
-```
-
-File URLs format: `{appUrl}/storage/upload/file/{path}`
-
-### AWS S3
-
-**1. Install the SDK:**
-```bash
-npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
-```
-
-**2. Register the provider at startup (before module init):**
-```typescript
-import { StorageProviderRegistry, FileLocationEnum } from '@flusys/nestjs-storage';
-import { S3Provider } from '@flusys/nestjs-storage/providers/s3-provider.optional';
-
-StorageProviderRegistry.register(FileLocationEnum.AWS, S3Provider);
-```
-
-**3. Create a StorageConfig:**
-```json
-POST /storage/storage-config/insert
-{
-  "name": "Production S3",
-  "storage": "aws",
-  "config": {
-    "region": "us-east-1",
-    "bucket": "my-app-files",
-    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
-    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
-  },
-  "isDefault": true
-}
-```
-
-### Azure Blob Storage
-
-**1. Install the SDK:**
-```bash
-npm install @azure/storage-blob
-```
-
-**2. Register:**
-```typescript
-import { AzureProvider } from '@flusys/nestjs-storage/providers/azure-provider.optional';
-StorageProviderRegistry.register(FileLocationEnum.AZURE, AzureProvider);
-```
-
-**3. Create a StorageConfig:**
-```json
-POST /storage/storage-config/insert
-{
-  "name": "Azure Blob",
-  "storage": "azure",
-  "config": {
-    "connectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net",
-    "containerName": "my-files"
+// Multi-tenant
+StorageModule.forRootAsync({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
   },
-  "isDefault": true
-}
-```
-
-### SFTP
-
-**1. Install the SDK:**
-```bash
-npm install ssh2-sftp-client
-```
-
-**2. Register:**
-```typescript
-import { SFTPProvider } from '@flusys/nestjs-storage/providers/sftp-provider.optional';
-StorageProviderRegistry.register(FileLocationEnum.SFTP, SFTPProvider);
-```
-
-**3. Create a StorageConfig:**
-```json
-POST /storage/storage-config/insert
-{
-  "name": "Legacy SFTP",
-  "storage": "sftp",
-  "config": {
-    "host": "sftp.example.com",
-    "port": 22,
-    "username": "sftpuser",
-    "password": "secret",
-    "remotePath": "/uploads"
-  }
-}
-```
-
-### Custom Provider
-
-```typescript
-import { IStorageProvider, StorageProviderRegistry } from '@flusys/nestjs-storage';
-
-class MyCloudProvider implements IStorageProvider {
-  async upload(file: IFileUploadOptions): Promise<IUploadedFile> { /* ... */ }
-  async delete(path: string): Promise<void> { /* ... */ }
-  async getUrl(path: string, ttl?: number): Promise<string> { /* ... */ }
-}
-
-StorageProviderRegistry.register('my-cloud', MyCloudProvider);
-```
-
----
-
-## API Endpoints
-
-All endpoints use **POST** and require JWT authentication.
-
-### Storage Config — `POST /storage/storage-config/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /storage/storage-config/insert` | `storage-config.create` | Add provider config |
-| `POST /storage/storage-config/get-all` | `storage-config.read` | List configs |
-| `POST /storage/storage-config/get/:id` | `storage-config.read` | Get config by ID |
-| `POST /storage/storage-config/update` | `storage-config.update` | Update config |
-| `POST /storage/storage-config/delete` | `storage-config.delete` | Delete config |
-| `POST /storage/storage-config/set-default` | `storage-config.update` | Set as default provider |
-
-### Folders — `POST /storage/folder/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /storage/folder/insert` | `folder.create` | Create folder |
-| `POST /storage/folder/get-all` | `folder.read` | List folders |
-| `POST /storage/folder/get/:id` | `folder.read` | Get folder by ID |
-| `POST /storage/folder/get-tree` | `folder.read` | Get hierarchical folder tree |
-| `POST /storage/folder/update` | `folder.update` | Update folder |
-| `POST /storage/folder/delete` | `folder.delete` | Delete folder (must be empty) |
-
-### Files — `POST /storage/file/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /storage/file/upload` | `file.create` | Upload a file (multipart/form-data) |
-| `POST /storage/file/get-all` | `file.read` | List files with pagination |
-| `POST /storage/file/get/:id` | `file.read` | Get file metadata by ID |
-| `POST /storage/file/get-url/:id` | `file.read` | Get presigned or direct file URL |
-| `POST /storage/file/update` | `file.update` | Update file metadata |
-| `POST /storage/file/delete` | `file.delete` | Delete file (from storage + DB) |
-| `POST /storage/file/move` | `file.update` | Move file to a different folder |
-
-### File Serving (Local)
-
-```
-GET /storage/upload/file/{path}
+  imports: [ConfigModule],
+  useFactory: (configService: ConfigService) => ({
+    tenantDefaultDatabaseConfig: {
+      type: 'mysql',
+      host: configService.get('TENANT_DB_HOST'),
+      port: configService.get<number>('TENANT_DB_PORT'),
+      username: configService.get('TENANT_DB_USER'),
+      password: configService.get('TENANT_DB_PASSWORD'),
+      database: configService.get('TENANT_DB_NAME'),
+    },
+    tenants: configService.get<ITenantDatabaseConfig[]>('TENANTS'),
+    maxFileSize: configService.get<number>('MAX_FILE_SIZE', 10 * 1024 * 1024),
+    appUrl: configService.get('APP_URL'),
+    localStoragePath: configService.get('UPLOAD_PATH', './uploads'),
+  }),
+  inject: [ConfigService],
+});
 ```
 
-Served directly by `FileServeMiddleware`. No authentication (public file access). Register the middleware in your `AppModule`.
-
----
-
-## Entities
-
-### Core Entities (always registered)
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `StorageConfig` | `storage_config` | Provider configuration (credentials, bucket, etc.) |
-| `Folder` | `storage_folder` | Folder hierarchy with `parentId` |
-| `FileManager` | `storage_file` | File metadata (name, path, size, MIME type, provider) |
-
-### Company Feature Entities (`enableCompanyFeature: true`)
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `StorageConfigWithCompany` | `storage_config` | Same + `companyId` |
-| `FolderWithCompany` | `storage_folder` | Same + `companyId` |
-| `FileManagerWithCompany` | `storage_file` | Same + `companyId` |
+## 2. Register Entities in TypeORM
 
 ```typescript
-import { StorageModule } from '@flusys/nestjs-storage';
+import { getStorageEntitiesByConfig } from '@flusys/nestjs-storage/entities';
 
 TypeOrmModule.forRoot({
   entities: [
-    ...StorageModule.getEntities({ enableCompanyFeature: true }),
+    ...getStorageEntitiesByConfig(true), // match enableCompanyFeature in bootstrapAppConfig
   ],
-})
-```
-
----
-
-## File Serving (Local)
-
-Register `FileServeMiddleware` to serve uploaded local files over HTTP:
-
-```typescript
-import { FileServeMiddleware } from '@flusys/nestjs-storage';
-
-// In AppModule
-configure(consumer: MiddlewareConsumer) {
-  consumer.apply(FileServeMiddleware).forRoutes('storage/upload/file');
-}
-```
-
-Files are served from the `localStoragePath` directory. The middleware validates paths to prevent directory traversal attacks.
-
----
-
-## Image Compression
-
-Automatic compression is applied on upload for supported image types:
-
-| Format | Compression applied |
-|--------|---------------------|
-| JPEG | Quality 80%, progressive |
-| PNG | Compression level 6 |
-| WebP | Quality 80% |
-| AVIF | Quality 75% |
-| TIFF | Deflate compression |
-| GIF | Passthrough |
-
-Custom compression options:
-
-```json
-POST /storage/file/upload
-Content-Type: multipart/form-data
-
-{
-  "file": <binary>,
-  "folderId": "uuid",
-  "compress": true,
-  "maxWidth": 1920,
-  "maxHeight": 1080,
-  "quality": 75
-}
-```
-
----
-
-## File Validation
-
-Files are validated using **magic bytes** (file header inspection), not just the file extension or MIME type header. This prevents users from uploading malicious files with forged extensions.
-
-Allowed types are configured via `allowedFileTypes`:
-```typescript
-allowedFileTypes: ['image/*', 'application/pdf', 'text/plain']
+});
 ```
 
-Wildcard patterns like `image/*` match any subtype (e.g., `image/jpeg`, `image/png`, `image/webp`).
-
----
-
-## Exported Services
-
-| Service | Description |
-|---------|-------------|
-| `FileManagerService` | File upload, retrieval, deletion, move |
-| `FolderService` | Folder CRUD and tree queries |
-| `StorageConfigService` | Provider config CRUD |
-| `StorageDataSourceProvider` | Dynamic DataSource per request |
-
----
-
-## Programmatic Usage
-
-```typescript
-import { FileManagerService } from '@flusys/nestjs-storage';
-
-@Injectable()
-export class ProfileService {
-  constructor(
-    @Inject(FileManagerService) private readonly fileManager: FileManagerService,
-  ) {}
-
-  async uploadAvatar(userId: string, fileBuffer: Buffer, filename: string): Promise<string> {
-    const result = await this.fileManager.uploadFile({
-      buffer: fileBuffer,
-      originalName: filename,
-      mimeType: 'image/jpeg',
-      folderId: 'avatars-folder-id',
-    });
-    return result.id; // Store file ID on user profile
-  }
-
-  async getAvatarUrl(fileId: string): Promise<string> {
-    return this.fileManager.getFileUrl(fileId);
-  }
-}
-```
-
----
-
-## Troubleshooting
-
-**`Provider not registered` error**
-
-You created a StorageConfig with `storage: 'aws'` but forgot to register the S3 provider. Call `StorageProviderRegistry.register()` before the module initializes.
-
----
-
-**Local files return 404**
-
-Ensure `FileServeMiddleware` is registered and that `localStoragePath` points to an existing directory. The path must be accessible by the Node.js process.
-
----
-
-**`File type not allowed` for a valid file**
-
-Magic-byte validation is strict. If your file is being rejected incorrectly, check `allowedFileTypes` in your config and ensure the actual file header matches the declared MIME type.
-
----
-
-**Presigned URL expired immediately**
-
-S3 and Azure presigned URLs have a TTL. The default TTL is cached per file. Pass a custom TTL in the get-url request body:
-```json
-POST /storage/file/get-url/:id
-{ "ttl": 3600 }
-```
-
----
 
 ## License
 
-MIT © FLUSYS
-
----
-
-> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.
+MIT © FLUSYS