@flusys/nestjs-storage 1.0.0-rc → 1.0.0

package/README.md

@@ -9,8 +9,10 @@ This comprehensive guide covers the storage package - flexible file storage with
 
 - [Overview](#overview)
 - [Installation](#installation)
+- [Constants](#constants)
 - [Package Architecture](#package-architecture)
 - [Module Setup](#module-setup)
+- [Entities](#entities)
 - [Storage Providers](#storage-providers)
 - [Storage Configuration](#storage-configuration)
 - [File Manager](#file-manager)
@@ -62,6 +64,19 @@ npm install ssh2-sftp-client                                    # For SFTP
 
 ---
 
+## Constants
+
+```typescript
+// Injection Token
+export const STORAGE_MODULE_OPTIONS = 'STORAGE_MODULE_OPTIONS';
+
+// Default Configuration
+export const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
+export const DEFAULT_ALLOWED_FILE_TYPES = ['*/*']; // All file types
+```
+
+---
+
 ## Package Architecture
 
 ```
@@ -259,6 +274,34 @@ This ensures the API documentation accurately reflects the available fields base
 
 ---
 
+## Entities
+
+### Entity Groups
+
+```typescript
+// Core entities (no company feature)
+export const StorageCoreEntities = [FileManager, Folder, StorageConfig];
+
+// Company-specific entities
+export const StorageCompanyEntities = [
+  FileManagerWithCompany,
+  FolderWithCompany,
+  StorageConfigWithCompany,
+];
+
+// Helper function
+export function getStorageEntitiesByConfig(enableCompanyFeature: boolean): any[] {
+  return enableCompanyFeature ? StorageCompanyEntities : StorageCoreEntities;
+}
+
+// Base type aliases for backwards compatibility
+export { FileManager as FileManagerBase } from './file-manager.entity';
+export { Folder as FolderBase } from './folder.entity';
+export { StorageConfig as StorageConfigBase } from './storage-config.entity';
+```
+
+---
+
 ## Storage Providers
 
 ### Provider Types
@@ -1397,4 +1440,4 @@ The `@flusys/nestjs-storage` package provides:
 
 ---
 
-**Last Updated:** 2026-02-18
+**Last Updated:** 2026-02-21

package/cjs/config/index.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", {
     value: true
 });
 _export_star(require("./storage.constants"), exports);
-_export_star(require("./storage-config.service"), exports);
 function _export_star(from, to) {
     Object.keys(from).forEach(function(k) {
         if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {

package/cjs/config/storage.constants.js

@@ -17,9 +17,6 @@ _export(exports, {
     get DEFAULT_MAX_FILE_SIZE () {
         return DEFAULT_MAX_FILE_SIZE;
     },
-    get FILE_VALIDATION_MESSAGES () {
-        return FILE_VALIDATION_MESSAGES;
-    },
     get STORAGE_MODULE_OPTIONS () {
         return STORAGE_MODULE_OPTIONS;
     }
@@ -29,9 +26,3 @@ const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
 const DEFAULT_ALLOWED_FILE_TYPES = [
     '*/*'
 ]; // All file types
-const FILE_VALIDATION_MESSAGES = {
-    FILE_TOO_LARGE: 'File size exceeds the maximum allowed size',
-    INVALID_FILE_TYPE: 'File type is not allowed',
-    NO_FILE_PROVIDED: 'No file was provided',
-    UPLOAD_FAILED: 'File upload failed'
-};

package/cjs/controllers/upload.controller.js

@@ -44,35 +44,30 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 let UploadController = class UploadController {
+    toFileUploadResponse(file) {
+        return {
+            size: this.uploadService.bytesToKb(file.size),
+            name: file.name,
+            key: file.key,
+            contentType: file.contentType,
+            location: file.location || 'local',
+            storageConfigId: file.storageConfigId || ''
+        };
+    }
     async uploadSingleFile(file, options, user) {
         const result = await this.uploadService.uploadSingleFile(file, options, user);
         return {
             success: true,
             message: 'File uploaded successfully',
-            data: {
-                size: this.uploadService.bytesToKb(result.size),
-                name: result.name,
-                key: result.key,
-                contentType: result.contentType,
-                location: result.location || 'local',
-                storageConfigId: result.storageConfigId || ''
-            }
+            data: this.toFileUploadResponse(result)
         };
     }
     async uploadMultipleFiles(files, options, user) {
         const uploadResponses = await this.uploadService.uploadMultipleFiles(files, options, user);
-        const responseData = uploadResponses.map((file)=>({
-                size: this.uploadService.bytesToKb(file.size),
-                name: file.name,
-                key: file.key,
-                contentType: file.contentType,
-                location: file.location || 'local',
-                storageConfigId: file.storageConfigId || ''
-            }));
         return {
             success: true,
             message: 'Files uploaded successfully',
-            data: responseData
+            data: uploadResponses.map((file)=>this.toFileUploadResponse(file))
         };
     }
     async deleteSingleFile(dto, user) {

package/cjs/docs/storage-swagger.config.js

@@ -8,7 +8,7 @@ Object.defineProperty(exports, "storageSwaggerConfig", {
         return storageSwaggerConfig;
     }
 });
-/** Schema properties to exclude when company feature is disabled */ const COMPANY_SCHEMA_EXCLUSIONS = [
+const COMPANY_SCHEMA_EXCLUSIONS = [
     {
         schemaName: 'FileManagerResponseDto',
         properties: [
@@ -28,120 +28,18 @@ Object.defineProperty(exports, "storageSwaggerConfig", {
         ]
     }
 ];
-function storageSwaggerConfig(bootstrapConfig) {
-    const enableCompanyFeature = bootstrapConfig?.enableCompanyFeature ?? true;
-    return {
-        title: 'Storage API',
-        description: enableCompanyFeature ? `
-# Storage Management API
-
-Complete file storage and management system with multi-tenant support.
-
-## Features
-
-### 📁 File Management
-- Upload single or multiple files
-- Download files with presigned URLs
-- Delete files (single or batch)
-- File metadata management
-- Automatic compression and optimization
-- **Company isolation**
-
-### 🗂️ Folder Company
-- Create folder hierarchies
-- Organize files by folders
-- **Company-level permissions**
-- Automatic context filtering
-
-### ⚙️ Storage Configuration
-- Multiple storage providers (AWS S3, Azure, SFTP, Local)
-- Provider-specific configurations
-- Default storage settings
-- Dynamic provider switching
-
-### 🔒 Security
-- JWT authentication required
-- **Company isolation**
-- File access control
-- Presigned URL generation
-
-## Storage Providers
-
-### AWS S3
-- Scalable cloud storage
-- Automatic redundancy
-- Global CDN integration
-
-### Azure Blob Storage
-- Microsoft Azure integration
-- Geo-redundant storage
-- Advanced security features
-
-### SFTP
-- Secure file transfer
-- Legacy system integration
-- Custom server support
-
-### Local Storage
-- Same-server storage
-- Fast access
-- No external dependencies
-
+function buildDescription(enableCompanyFeature) {
+    const companyIsolation = enableCompanyFeature ? '\n- **Company isolation**' : '';
+    const companyPermissions = enableCompanyFeature ? '\n- **Company-level permissions**' : '';
+    const multiTenantSection = enableCompanyFeature ? `
 ## Multi-Tenant Support
 
 Files are automatically isolated by:
 - **Company ID**: Company-level storage
 
 All queries automatically filter by current user's company context.
-
-## File Validation
-
-### Size Limits
-Configure maximum file size per upload (default: 10MB)
-
-### File Types
-Restrict allowed file types (default: images, PDFs)
-
-### Image Compression
-- Automatic image optimization
-- Format conversion (JPEG, PNG, WebP, AVIF)
-- Resize to maximum dimensions
-- Quality control
-
-## Response Format
-
-All endpoints return standardized responses with success status, data, message, and timestamp.
-
-## Error Handling
-
-Errors return structured responses with success false, error message, error code, and timestamp.
-
-## Common Error Codes
-
-- **400 Bad Request**: Invalid input data
-- **401 Unauthorized**: Missing or invalid authentication
-- **403 Forbidden**: Insufficient permissions
-- **404 Not Found**: Resource not found
-- **413 Payload Too Large**: File exceeds size limit
-- **415 Unsupported Media Type**: File type not allowed
-- **500 Internal Server Error**: Server error
-
-## Getting Started
-
-1. **Authenticate**: Obtain JWT token from /auth/login
-2. **Configure Storage**: Create storage configuration via /storage/storage-config/insert
-3. **Create Folders**: Organize files with /storage/folder/insert
-4. **Upload Files**: Upload files via /storage/upload/single-file
-5. **Manage Files**: Track uploads in /storage/file-manager
-
-## API Endpoints
-
-All storage endpoints are prefixed with \`/storage\`:
-- \`/storage/file-manager/*\` - File metadata management
-- \`/storage/folder/*\` - Folder organization
-- \`/storage/storage-config/*\` - Storage configuration
-- \`/storage/upload/*\` - File upload/download
-
+` : '';
+    const examplesSection = enableCompanyFeature ? `
 ## Examples
 
 ### Upload a File
@@ -155,27 +53,11 @@ POST /storage/file-manager/get-all with JSON body containing page and pageSize p
 ### Create Folder
 
 POST /storage/folder/insert with JSON body containing folder name
-
-## Best Practices
-
-1. **Always authenticate**: Include JWT token in Authorization header
-2. **Use folders**: Organize files hierarchically
-3. **Check file size**: Validate before upload
-4. **Handle errors**: Implement proper error handling
-5. **Clean up**: Delete unused files regularly
-6. **Use presigned URLs**: Generate temporary URLs for file access
-7. **Compress images**: Enable compression for faster loading
-
-## Rate Limiting
-
-All endpoints are rate-limited to prevent abuse. Default limits:
-- **Upload**: 100 requests per hour
-- **Download**: 1000 requests per hour
-- **Delete**: 50 requests per hour
-      ` : `
+` : '';
+    return `
 # Storage Management API
 
-Complete file storage and management system.
+Complete file storage and management system${enableCompanyFeature ? ' with multi-tenant support' : ''}.
 
 ## Features
 
@@ -184,12 +66,12 @@ Complete file storage and management system.
 - Download files with presigned URLs
 - Delete files (single or batch)
 - File metadata management
-- Automatic compression and optimization
+- Automatic compression and optimization${companyIsolation}
 
-### 🗂️ Folder Company
+### 🗂️ Folder Organization
 - Create folder hierarchies
-- Organize files by folders
-- Folder-level company
+- Organize files by folders${companyPermissions}
+- Automatic context filtering
 
 ### ⚙️ Storage Configuration
 - Multiple storage providers (AWS S3, Azure, SFTP, Local)
@@ -198,7 +80,7 @@ Complete file storage and management system.
 - Dynamic provider switching
 
 ### 🔒 Security
-- JWT authentication required
+- JWT authentication required${companyIsolation}
 - File access control
 - Presigned URL generation
 
@@ -223,7 +105,7 @@ Complete file storage and management system.
 - Same-server storage
 - Fast access
 - No external dependencies
-
+${multiTenantSection}
 ## File Validation
 
 ### Size Limits
@@ -271,7 +153,7 @@ All storage endpoints are prefixed with \`/storage\`:
 - \`/storage/folder/*\` - Folder organization
 - \`/storage/storage-config/*\` - Storage configuration
 - \`/storage/upload/*\` - File upload/download
-
+${examplesSection}
 ## Best Practices
 
 1. **Always authenticate**: Include JWT token in Authorization header
@@ -288,7 +170,13 @@ All endpoints are rate-limited to prevent abuse. Default limits:
 - **Upload**: 100 requests per hour
 - **Download**: 1000 requests per hour
 - **Delete**: 50 requests per hour
-      `,
+`;
+}
+function storageSwaggerConfig(bootstrapConfig) {
+    const enableCompanyFeature = bootstrapConfig?.enableCompanyFeature ?? true;
+    return {
+        title: 'Storage API',
+        description: buildDescription(enableCompanyFeature),
         version: '1.0',
         path: 'api/docs/storage',
         bearerAuth: true,

package/cjs/dtos/file-manager.dto.js

@@ -82,7 +82,7 @@ _ts_decorate([
 ], CreateFileManagerDto.prototype, "key", void 0);
 _ts_decorate([
     (0, _swagger.ApiProperty)({
-        description: 'Size of the FileManager item',
+        description: 'Size of the file in bytes',
         example: '1024'
     }),
     (0, _classvalidator.IsNotEmpty)(),
@@ -91,7 +91,7 @@ _ts_decorate([
 ], CreateFileManagerDto.prototype, "size", void 0);
 _ts_decorate([
     (0, _swagger.ApiProperty)({
-        description: 'mime type of file',
+        description: 'MIME type of file',
         example: 'image/jpeg'
     }),
     (0, _classvalidator.IsNotEmpty)(),
@@ -100,7 +100,7 @@ _ts_decorate([
 ], CreateFileManagerDto.prototype, "contentType", void 0);
 _ts_decorate([
     (0, _swagger.ApiProperty)({
-        description: 'Indicates if the FileManager item is private',
+        description: 'Indicates if the file is private',
         example: true
     }),
     (0, _classvalidator.IsNotEmpty)(),
@@ -108,21 +108,21 @@ _ts_decorate([
     _ts_metadata("design:type", Boolean)
 ], CreateFileManagerDto.prototype, "isPrivate", void 0);
 _ts_decorate([
-    (0, _swagger.ApiProperty)({
+    (0, _swagger.ApiPropertyOptional)({
         description: 'Folder ID (UUID)',
         example: 'f2e9c8d0-7a2a-11eb-9439-0242ac130002'
     }),
     (0, _classvalidator.IsOptional)(),
-    (0, _classvalidator.IsString)(),
+    (0, _classvalidator.IsUUID)(),
     _ts_metadata("design:type", String)
 ], CreateFileManagerDto.prototype, "folderId", void 0);
 _ts_decorate([
     (0, _swagger.ApiPropertyOptional)({
-        description: 'Storage configuration ID - if not provided, uses default',
+        description: 'Storage configuration ID',
         example: '123e4567-e89b-12d3-a456-426614174000'
     }),
     (0, _classvalidator.IsOptional)(),
-    (0, _classvalidator.IsString)(),
+    (0, _classvalidator.IsUUID)(),
     _ts_metadata("design:type", String)
 ], CreateFileManagerDto.prototype, "storageConfigId", void 0);
 _ts_decorate([
@@ -133,7 +133,7 @@ _ts_decorate([
     }),
     (0, _classvalidator.IsOptional)(),
     (0, _classvalidator.IsEnum)(_enums.FileLocationEnum),
-    _ts_metadata("design:type", typeof _enums.FileLocationEnum === "undefined" ? Object : _enums.FileLocationEnum)
+    _ts_metadata("design:type", String)
 ], CreateFileManagerDto.prototype, "location", void 0);
 let UpdateFileManagerDto = class UpdateFileManagerDto extends (0, _swagger.PartialType)(CreateFileManagerDto) {
     constructor(...args){
@@ -145,19 +145,63 @@ _ts_decorate([
         description: 'Unique identifier of the file',
         example: 'f2e9c8d0-7a2a-11eb-9439-0242ac130002'
     }),
+    (0, _classvalidator.IsUUID)(),
     (0, _classvalidator.IsNotEmpty)(),
-    (0, _classvalidator.IsString)(),
     _ts_metadata("design:type", String)
 ], UpdateFileManagerDto.prototype, "id", void 0);
-let FileManagerResponseDto = class FileManagerResponseDto extends UpdateFileManagerDto {
-    constructor(...args){
-        super(...args), _define_property(this, "providerName", void 0);
+let FileManagerResponseDto = class FileManagerResponseDto {
+    constructor(){
+        _define_property(this, "id", void 0);
+        _define_property(this, "name", void 0);
+        _define_property(this, "key", void 0);
+        _define_property(this, "size", void 0);
+        _define_property(this, "contentType", void 0);
+        _define_property(this, "isPrivate", void 0);
+        _define_property(this, "folderId", void 0);
+        _define_property(this, "storageConfigId", void 0);
+        _define_property(this, "location", void 0);
+        _define_property(this, "providerName", void 0);
     }
 };
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", String)
+], FileManagerResponseDto.prototype, "id", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", String)
+], FileManagerResponseDto.prototype, "name", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", String)
+], FileManagerResponseDto.prototype, "key", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", String)
+], FileManagerResponseDto.prototype, "size", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", String)
+], FileManagerResponseDto.prototype, "contentType", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", Boolean)
+], FileManagerResponseDto.prototype, "isPrivate", void 0);
+_ts_decorate([
+    (0, _swagger.ApiPropertyOptional)(),
+    _ts_metadata("design:type", String)
+], FileManagerResponseDto.prototype, "folderId", void 0);
+_ts_decorate([
+    (0, _swagger.ApiPropertyOptional)(),
+    _ts_metadata("design:type", String)
+], FileManagerResponseDto.prototype, "storageConfigId", void 0);
+_ts_decorate([
+    (0, _swagger.ApiPropertyOptional)(),
+    _ts_metadata("design:type", String)
+], FileManagerResponseDto.prototype, "location", void 0);
 _ts_decorate([
     (0, _swagger.ApiPropertyOptional)({
-        example: 'My S3 Storage',
-        description: 'Name of the storage configuration/provider'
+        description: 'Name of the storage provider'
     }),
     _ts_metadata("design:type", String)
 ], FileManagerResponseDto.prototype, "providerName", void 0);
@@ -170,8 +214,8 @@ _ts_decorate([
     (0, _swagger.ApiProperty)({
         example: 'f2e9c8d0-7a2a-11eb-9439-0242ac130002'
     }),
+    (0, _classvalidator.IsUUID)(),
     (0, _classvalidator.IsNotEmpty)(),
-    (0, _classvalidator.IsString)(),
     _ts_metadata("design:type", String)
 ], GetFilesRequestDto.prototype, "id", void 0);
 let FilesResponseDto = class FilesResponseDto {
@@ -186,47 +230,36 @@ let FilesResponseDto = class FilesResponseDto {
     }
 };
 _ts_decorate([
-    (0, _swagger.ApiProperty)({
-        example: 'file123.jpg'
-    }),
+    (0, _swagger.ApiProperty)(),
     _ts_metadata("design:type", String)
 ], FilesResponseDto.prototype, "id", void 0);
 _ts_decorate([
-    (0, _swagger.ApiProperty)({
-        example: 'file123.jpg'
-    }),
+    (0, _swagger.ApiProperty)(),
     _ts_metadata("design:type", String)
 ], FilesResponseDto.prototype, "name", void 0);
 _ts_decorate([
-    (0, _swagger.ApiProperty)({
-        example: 'image/jpeg'
-    }),
+    (0, _swagger.ApiProperty)(),
     _ts_metadata("design:type", String)
 ], FilesResponseDto.prototype, "contentType", void 0);
 _ts_decorate([
-    (0, _swagger.ApiProperty)({
-        example: 'https://example.com/file123.jpg'
-    }),
+    (0, _swagger.ApiProperty)(),
     _ts_metadata("design:type", String)
 ], FilesResponseDto.prototype, "url", void 0);
 _ts_decorate([
     (0, _swagger.ApiPropertyOptional)({
-        example: 'local',
-        description: 'Storage provider type (local, aws, azure, sftp)'
+        description: 'Storage provider type'
     }),
     _ts_metadata("design:type", String)
 ], FilesResponseDto.prototype, "location", void 0);
 _ts_decorate([
     (0, _swagger.ApiPropertyOptional)({
-        example: '123e4567-e89b-12d3-a456-426614174000',
         description: 'Storage configuration ID'
     }),
     _ts_metadata("design:type", String)
 ], FilesResponseDto.prototype, "storageConfigId", void 0);
 _ts_decorate([
     (0, _swagger.ApiPropertyOptional)({
-        example: 'My S3 Storage',
-        description: 'Name of the storage configuration/provider'
+        description: 'Name of the storage provider'
     }),
     _ts_metadata("design:type", String)
 ], FilesResponseDto.prototype, "providerName", void 0);

package/cjs/dtos/folder.dto.js

@@ -67,20 +67,26 @@ _ts_decorate([
         description: 'Unique identifier of the folder',
         example: 'f2e9c8d0-7a2a-11eb-9439-0242ac130002'
     }),
+    (0, _classvalidator.IsUUID)(),
     (0, _classvalidator.IsNotEmpty)(),
     _ts_metadata("design:type", String)
 ], UpdateFolderDto.prototype, "id", void 0);
-let FolderResponseDto = class FolderResponseDto extends UpdateFolderDto {
-    constructor(...args){
-        super(...args), _define_property(this, "slug", void 0);
+let FolderResponseDto = class FolderResponseDto {
+    constructor(){
+        _define_property(this, "id", void 0);
+        _define_property(this, "name", void 0);
+        _define_property(this, "slug", void 0);
     }
 };
 _ts_decorate([
-    (0, _swagger.ApiProperty)({
-        description: 'Name of the folder',
-        example: 'Invoices'
-    }),
-    (0, _classvalidator.IsNotEmpty)(),
-    (0, _classvalidator.IsString)(),
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", String)
+], FolderResponseDto.prototype, "id", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
+    _ts_metadata("design:type", String)
+], FolderResponseDto.prototype, "name", void 0);
+_ts_decorate([
+    (0, _swagger.ApiProperty)(),
     _ts_metadata("design:type", String)
 ], FolderResponseDto.prototype, "slug", void 0);