@flusys/ng-storage 1.1.1-beta → 1.2.0-rc.1

package/README.md

@@ -1,657 +1,70 @@
-# Storage Package Guide
+# @flusys/ng-storage
 
-> **Package:** `@flusys/ng-storage`
-> **Type:** File storage management with upload, folder organization, and multi-provider support
+File storage UI for FLUSYS Angular apps — upload, file manager pages, presigned URL fetching, and provider adapter registration for Local, S3, Azure, and SFTP backends.
 
----
-
-## Overview
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-storage.svg)](https://www.npmjs.com/package/@flusys/ng-storage)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-`@flusys/ng-storage` provides complete file storage management:
-
-- **File Upload** - Single and multiple file uploads with image compression
-- **File Manager** - CRUD operations for file metadata with presigned URLs
-- **Folder Management** - Folder organization for files
-- **Storage Configs** - Multi-provider configurations (AWS S3, Azure Blob, SFTP, Local)
-- **Company Scoping** - Automatic company-scoped queries (when enabled)
-- **Lazy Loading** - All page components are lazy-loaded via routes
+---
 
-### Package Hierarchy
+## Installation
 
+```bash
+npm install @flusys/ng-storage @flusys/ng-core @flusys/ng-shared
 ```
-@flusys/ng-core           <- Foundation (BaseApiService, APP_CONFIG)
-        |
-@flusys/ng-shared         <- Shared utilities (ApiResourceService, IBaseEntity)
-        |
-@flusys/ng-layout         <- Layout (LAYOUT_AUTH_STATE for company context)
-        |
-@flusys/ng-storage        <- File storage (THIS PACKAGE)
-```
-
-### Company Context
 
-Storage components use `LAYOUT_AUTH_STATE` from `@flusys/ng-layout` for company context. This follows the Provider Interface Pattern - ng-storage depends on ng-layout's abstraction, not ng-auth directly.
+## 1. Register Providers
 
 ```typescript
-import { LAYOUT_AUTH_STATE } from '@flusys/ng-layout';
-
-private readonly companyContext = inject(LAYOUT_AUTH_STATE);
-
-readonly currentCompanyName = computed(
-  () => this.companyContext.currentCompanyInfo()?.name ?? DEFAULT_APP_NAME,
-);
-```
-
----
-
-## Package Architecture
+// app.config.ts
+import { provideStorageProviders } from '@flusys/ng-storage';
 
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...provideStorageProviders(), // registers FILE_PROVIDER for ng-shared's file picker and FileUrlService
+  ],
+};
 ```
-ng-storage/
-├── enums/
-│   ├── file-location.enum.ts     # FileLocationEnum, ImageFormat
-│   └── public-api.ts
-├── interfaces/
-│   ├── file-manager.interface.ts  # IFileManager, ICreateFileManagerDto, IUpdateFileManagerDto
-│   ├── folder.interface.ts        # IFolder, ICreateFolderDto, IUpdateFolderDto
-│   ├── storage-config.interface.ts # IStorageConfig, provider-specific configs
-│   ├── upload.interface.ts        # IUploadOptionsDto, IUploadedFileInfo
-│   └── public-api.ts
-├── services/
-│   ├── file-manager-api.service.ts   # File metadata CRUD + presigned URLs
-│   ├── folder-api.service.ts         # Folder CRUD
-│   ├── storage-config-api.service.ts # Storage config CRUD
-│   └── upload.service.ts             # File upload/delete operations
-├── pages/
-│   ├── storage-container/
-│   │   └── storage-container.component.ts  # Tab container (Files, Folders, Configs)
-│   ├── file-manager/
-│   │   ├── file-manager-list.component.ts
-│   │   └── file-manager-form.component.ts
-│   ├── folder/
-│   │   ├── folder-list.component.ts
-│   │   └── folder-form.component.ts
-│   └── storage-config/
-│       ├── storage-config-list.component.ts
-│       └── storage-config-form.component.ts
-├── routes/
-│   └── storage.routes.ts
-└── public-api.ts
-```
-
----
 
-## Route Integration
+`FILE_PROVIDER` is consumed by `FileSelectorComponent` and `FileUrlService` in `ng-shared`. Without this, file pickers in other packages (e.g., ng-form-builder, ng-email) will not work.
 
-### Adding Storage Routes
+## 2. Add Storage Routes (Optional)
 
 ```typescript
 // app.routes.ts
+import { STORAGE_ROUTES } from '@flusys/ng-storage';
+
 export const routes: Routes = [
   {
     path: 'storage',
-    loadChildren: () =>
-      import('@flusys/ng-storage').then((m) => m.STORAGE_ROUTES),
+    loadChildren: () => STORAGE_ROUTES,
   },
 ];
 ```
 
-### Route Structure
-
-All routes are wrapped by `StorageContainerComponent` which provides tab navigation (Files, Folders, Configs).
-
-| Path | Component | Description |
-|------|-----------|-------------|
-| `/storage` | StorageContainerComponent | Container with tab navigation |
-| `/storage/files` | FileManagerListComponent | List all files (default) |
-| `/storage/files/new` | FileManagerFormComponent | Upload new file |
-| `/storage/files/:id` | FileManagerFormComponent | Edit file metadata |
-| `/storage/folders` | FolderListComponent | List all folders |
-| `/storage/folders/new` | FolderFormComponent | Create folder |
-| `/storage/folders/:id` | FolderFormComponent | Edit folder |
-| `/storage/configs` | StorageConfigListComponent | List storage configurations |
-| `/storage/configs/new` | StorageConfigFormComponent | Create storage config |
-| `/storage/configs/:id` | StorageConfigFormComponent | Edit storage config |
-
-Default redirect: `/storage` -> `/storage/files`
-
----
-
-## Enums
+Routes included (all protected by `permissionGuard`):
 
-### FileLocationEnum
+## 4. Fetch File URLs (Critical Rule)
 
-Storage provider types (matches backend).
+Never construct file URLs manually. Always use `FileUrlService` from `ng-shared` — the backend generates presigned, access-controlled URLs for all storage providers.
 
 ```typescript
-enum FileLocationEnum {
-  LOCAL = 'local',
-  AWS = 'aws',
-  AZURE = 'azure',
-  SFTP = 'sftp',
-}
-```
-
-### ImageFormat
-
-Image compression output formats.
-
-```typescript
-enum ImageFormat {
-  ORIGINAL = 'original',
-  JPEG = 'jpeg',
-  PNG = 'png',
-  WEBP = 'webp',
-}
-```
-
----
-
-## Interfaces
+import { FileUrlService } from '@flusys/ng-shared';
 
-### Upload
-
-```typescript
-interface IUploadOptionsDto {
-  storageConfigId?: string;  // Storage config to use (uses default if not set)
-  folderPath?: string;       // Target folder path
-  maxWidth?: number;         // Image max width (default: 1280)
-  maxHeight?: number;        // Image max height (default: 1280)
-  quality?: number;          // Image quality 1-100 (default: 85)
-  format?: ImageFormat;      // Output format
-  compress?: boolean;        // Enable compression (default: true)
-}
+@Component({ ... })
+export class MyComponent {
+  private readonly fileUrlService = inject(FileUrlService);
 
-interface IUploadedFileInfo {
-  name: string;        // Original filename
-  key: string;         // Storage key/path
-  size: number;        // File size in bytes
-  contentType: string; // MIME type
+  async loadAvatar(fileId: string) {
+    // POST /file-manager/get-files → returns presigned URL
+    const files = await firstValueFrom(this.fileUrlService.getFileUrls([fileId]));
+    const url = files?.data?.[0]?.url ?? null;
+  }
 }
 ```
 
-### File Manager
-
-```typescript
-interface IFileManager {
-  id: string;
-  createdAt: Date;
-  updatedAt: Date;
-  name: string;
-  contentType: string;
-  size: string;                      // In KB (string)
-  key: string;                       // File key/path in storage
-  url: string | null;                // Presigned URL (regenerated by backend)
-  location: FileLocationEnum;
-  storageConfigId: string | null;
-  expiresAt: Date | null;            // URL expiration time
-  isPrivate: boolean;
-  companyId?: string;                // Only in company mode
-  folderId?: string | null;
-}
-
-interface ICreateFileManagerDto {
-  name: string;
-  key: string;
-  size: string;
-  contentType: string;
-  isPrivate: boolean;
-  folderId?: string;
-  storageConfigId?: string;
-  location?: FileLocationEnum;
-}
-
-interface IUpdateFileManagerDto {
-  id: string;
-  name?: string;
-  isPrivate?: boolean;
-  folderId?: string | null;
-}
-
-// For fetching files with valid presigned URLs
-interface IGetFilesRequestDto { id: string; }
-interface IFilesResponseDto { id: string; name: string; contentType: string; url: string; }
-```
-
-### Folder
-
-```typescript
-interface IFolder extends IBaseEntity {
-  name: string;
-  slug: string;              // URL-friendly name
-  companyId?: string | null;
-}
-
-interface ICreateFolderDto { name: string; }
-interface IUpdateFolderDto { id: string; name?: string; }
-```
-
-### Storage Config
-
-```typescript
-interface IStorageConfig extends IBaseEntity {
-  name: string;
-  storage: FileLocationEnum;
-  config: Record<string, any>;   // Provider-specific configuration
-  isActive: boolean;             // Whether config is active and usable
-  isDefault: boolean;            // Set as default configuration
-  companyId?: string | null;
-}
-
-interface ICreateStorageConfigDto {
-  name: string;
-  storage: FileLocationEnum;
-  config: Record<string, any>;
-  isActive?: boolean;
-  isDefault?: boolean;
-}
-
-interface IUpdateStorageConfigDto {
-  id: string;
-  name?: string;
-  storage?: FileLocationEnum;
-  config?: Record<string, any>;
-  isActive?: boolean;
-  isDefault?: boolean;
-}
-```
-
-### Provider-Specific Configs
-
-These define the shape of `IStorageConfig.config` for each provider:
-
-```typescript
-interface IAwsS3Config {
-  region: string;
-  bucket: string;
-  accessKeyId: string;
-  secretAccessKey: string;
-  endpoint?: string;         // Custom S3-compatible endpoint
-}
-
-interface IAzureBlobConfig {
-  accountName: string;
-  accountKey: string;
-  containerName: string;
-}
-
-interface ISftpConfig {
-  host: string;
-  port: number;
-  username: string;
-  password?: string;
-  privateKey?: string;
-  basePath: string;
-}
-
-interface ILocalStorageConfig {
-  basePath: string;
-}
-```
-
----
-
-## Services
-
-All services are `providedIn: 'root'`. Company scoping is automatic when the company feature is enabled.
-
-### UploadService
-
-Handles file upload and deletion. Extends `BaseApiService` (from ng-core).
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `uploadSingleFile(file, options?)` | `POST /storage/upload/single-file` | Upload single file |
-| `uploadMultipleFiles(files, options?)` | `POST /storage/upload/multiple-file` | Upload multiple files (max 50) |
-| `deleteSingleFile(key, storageConfigId?)` | `POST /storage/upload/delete-single-file` | Delete single file from storage |
-| `deleteMultipleFiles(keys, storageConfigId?)` | `POST /storage/upload/delete-multiple-file` | Delete multiple files |
-| `getFileUrl(key)` | `GET /storage/upload/file/:key` | Get direct file download URL |
-
-Upload options are sent as **query parameters**, not form data:
-
-```typescript
-// POST /storage/upload/single-file?storageConfigId=abc&folderPath=docs&compress=true
-this.uploadService.uploadSingleFile(file, {
-  storageConfigId: 'abc',
-  folderPath: 'docs',
-  compress: true,
-  quality: 85,
-  format: ImageFormat.WEBP,
-});
-```
-
-### FileManagerApiService
-
-File metadata CRUD. Extends `ApiResourceService<IUpdateFileManagerDto, IFileManager>`.
-
-**Inherited CRUD methods** (from ApiResourceService): `insert`, `update`, `findById`, `getAll`, `delete` and their `*Async` variants.
-
-**Additional methods:**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `getFiles(fileIds)` | `POST /storage/file-manager/get-files` | Get files with valid presigned URLs |
-| `getFilesByFolder(folderId, page?, limit?)` | `POST /storage/file-manager/get-all` | Filter files by folder |
-| `getPrivateFiles(page?, limit?)` | `POST /storage/file-manager/get-all` | Filter by `isPrivate: true` |
-
-**Presigned URL pattern:** Always use `getFiles()` to get valid URLs. Backend regenerates expired presigned URLs for cloud storage.
-
-```typescript
-const response = await firstValueFrom(
-  this.fileService.getFiles(['file-id-1', 'file-id-2'])
-);
-// response.data → [{ id, name, contentType, url }]
-```
-
-### FolderApiService
-
-Folder CRUD. Extends `ApiResourceService<IUpdateFolderDto, IFolder>`. Standard CRUD operations only, no custom methods.
-
-### StorageConfigApiService
-
-Storage provider configuration CRUD. Extends `ApiResourceService<IUpdateStorageConfigDto, IStorageConfig>`. Standard CRUD operations only, no custom methods.
-
----
-
-## Components
-
-All components are standalone, use Angular 21 signal forms, and lazy-load via routes.
-
-### StorageContainerComponent
-
-Main container with tab navigation between Files, Folders, and Configs sections. Uses inline CSS with theme variables (`--primary-color`, `--surface-ground`, etc.).
-
-**Selector:** `lib-storage-container`
+Manual URL construction breaks with S3/Azure (presigned URLs expire) and does not enforce access control.
 
-### List Components
-
-All list components share:
-- **Lazy pagination** via `p-datatable`
-- **Company info display** when company feature enabled (via `APP_CONFIG`)
-- **Delete confirmation** via `ConfirmationService`
-- **Signal-based state:** `isLoading`, `files`/`folders`/`configs`, `totalRecords`, `pageSize`, `currentPage`
-
-**FileManagerListComponent** additionally supports:
-- File content type icons (image, video, audio, PDF, Word, Excel, generic)
-- View file (opens presigned URL in new tab)
-- **Soft delete** - marks as deleted (recoverable)
-- **Permanent delete** - removes from storage provider (irreversible)
-
-### Form Components
-
-All form components share:
-- **Signal Forms** using Angular 21 `form()` helper with `required()` validators
-- **Create/Edit mode** auto-detection based on route param (`:id`)
-- **Navigation** back to list on save/cancel
-
-**FileManagerFormComponent** additionally supports:
-- PrimeNG file upload with drag-drop
-- Storage config selection dropdown
-- Folder assignment
-- Auto-filling filename from uploaded file
-
-**StorageConfigFormComponent** has dynamic form fields based on selected provider:
-- AWS S3: region, bucket, accessKeyId, secretAccessKey, endpoint
-- Azure Blob: accountName, accountKey, containerName
-- SFTP: host, port, username, password, basePath
-- Local: basePath
-- **Active toggle** - enables/disables the configuration
-- **Set as Default toggle** - marks configuration as the default for uploads
-
-**Default Configuration:**
-When `isDefault: true`, this configuration will be used automatically when no `storageConfigId` is provided in upload requests.
-
----
-
-## Usage Examples
-
-### Upload a File
-
-```typescript
-import { UploadService, ImageFormat } from '@flusys/ng-storage';
-
-private readonly uploadService = inject(UploadService);
-
-async uploadImage(file: File): Promise<IUploadedFileInfo | null> {
-  const response = await firstValueFrom(
-    this.uploadService.uploadSingleFile(file, {
-      storageConfigId: 'my-config-id',
-      folderPath: 'images/avatars',
-      compress: true,
-      maxWidth: 800,
-      maxHeight: 800,
-      quality: 80,
-      format: ImageFormat.WEBP,
-    })
-  );
-  return response.success ? response.data : null;
-}
-```
-
-### Get Files with Presigned URLs
-
-```typescript
-import { FileManagerApiService } from '@flusys/ng-storage';
-
-private readonly fileService = inject(FileManagerApiService);
-
-async getFileUrls(ids: string[]): Promise<IFilesResponseDto[]> {
-  const response = await firstValueFrom(this.fileService.getFiles(ids));
-  return response.data ?? [];
-}
-```
-
-### Delete with Confirmation
-
-Two delete modes are available:
-
-```typescript
-// Soft delete - marks as deleted, recoverable
-onSoftDelete(file: IFileManager): void {
-  this.confirmationService.confirm({
-    message: `Delete "${file.name}"?`,
-    header: 'Delete File',
-    acceptButtonStyleClass: 'p-button-danger',
-    accept: async () => {
-      await this.fileService.deleteAsync({ id: file.id, type: 'delete' });
-      this.loadFiles();
-    },
-  });
-}
-
-// Permanent delete - removes from storage provider, irreversible
-onPermanentDelete(file: IFileManager): void {
-  this.confirmationService.confirm({
-    message: `Permanently delete "${file.name}"? This cannot be undone.`,
-    header: 'Permanent Delete',
-    acceptButtonStyleClass: 'p-button-danger',
-    accept: async () => {
-      await firstValueFrom(
-        this.uploadService.deleteSingleFile(file.key, file.storageConfigId ?? undefined)
-      );
-      await this.fileService.deleteAsync({ id: file.id, type: 'permanent' });
-      this.loadFiles();
-    },
-  });
-}
-```
-
----
-
-## Backend Integration
-
-All endpoints use **POST-only RPC** style (not REST).
-
-| Service | Endpoint | Description |
-|---------|----------|-------------|
-| Upload | `POST /storage/upload/single-file` | Upload single file |
-| Upload | `POST /storage/upload/multiple-file` | Upload multiple files |
-| Upload | `POST /storage/upload/delete-single-file` | Delete file from storage |
-| Upload | `POST /storage/upload/delete-multiple-file` | Delete multiple files |
-| Upload | `GET /storage/upload/file/:filePath` | Direct file download |
-| FileManager | `POST /storage/file-manager/get-files` | Get files with presigned URLs |
-| FileManager | `POST /storage/file-manager/insert` | Create file metadata |
-| FileManager | `POST /storage/file-manager/get/:id` | Get file by ID |
-| FileManager | `POST /storage/file-manager/get-all` | List files (paginated) |
-| FileManager | `POST /storage/file-manager/update` | Update file metadata |
-| FileManager | `POST /storage/file-manager/delete` | Delete file |
-| Folder | `POST /storage/folder/insert` | Create folder |
-| Folder | `POST /storage/folder/get/:id` | Get folder by ID |
-| Folder | `POST /storage/folder/get-all` | List folders |
-| Folder | `POST /storage/folder/update` | Update folder |
-| Folder | `POST /storage/folder/delete` | Delete folder |
-| StorageConfig | `POST /storage/storage-config/insert` | Create config |
-| StorageConfig | `POST /storage/storage-config/get/:id` | Get config by ID |
-| StorageConfig | `POST /storage/storage-config/get-all` | List configs |
-| StorageConfig | `POST /storage/storage-config/update` | Update config |
-| StorageConfig | `POST /storage/storage-config/delete` | Delete config |
-
----
-
-## Best Practices
-
-### 1. Always Use Presigned URLs
-
-Never construct file URLs manually. Use `FileManagerApiService.getFiles()` or `FileUrlService` from ng-shared.
-
-```typescript
-// Wrong: manual URL
-const url = `${apiBaseUrl}/storage/${fileId}`;
-
-// Correct: backend-generated presigned URL
-const files = await firstValueFrom(this.fileService.getFiles([fileId]));
-const url = files.data?.[0]?.url ?? null;
-```
-
-### 2. Specify Storage Config for Multi-Provider Setups
-
-```typescript
-// Specify which storage provider to use
-await firstValueFrom(
-  this.uploadService.uploadSingleFile(file, {
-    storageConfigId: 'aws-media-bucket',
-    folderPath: 'images',
-  })
-);
-```
-
-### 3. Compress Images for Web
-
-```typescript
-const options: IUploadOptionsDto = {
-  compress: true,
-  maxWidth: 1920,
-  maxHeight: 1080,
-  quality: 85,
-  format: ImageFormat.WEBP,
-};
-```
-
-### 4. Provide ConfirmationService at App Level
-
-Storage list components use `ConfirmationService` for delete dialogs. Provide it in `app.config.ts`:
-
-```typescript
-export const appConfig: ApplicationConfig = {
-  providers: [ConfirmationService, MessageService],
-};
-```
-
-### 5. Enable Storage in APP_CONFIG
-
-```typescript
-// environment.ts
-services: {
-  storage: { baseUrl: 'http://localhost:2002/storage', enabled: true },
-}
-```
-
----
-
-## Provider Functions
-
-### provideStorageProviders()
-
-Registers provider adapters that enable other packages (ng-auth) to access storage functionality without direct dependencies.
-
-```typescript
-import { provideStorageProviders } from '@flusys/ng-storage';
-
-// app.config.ts
-export const appConfig: ApplicationConfig = {
-  providers: [
-    ...provideStorageProviders(),  // Register storage providers
-  ],
-};
-```
-
-**Registers:**
-
-| Token | Adapter | Purpose |
-|-------|---------|---------|
-| `PROFILE_UPLOAD_PROVIDER` | `ProfileUploadProviderAdapter` | Profile picture upload for ng-auth |
-
-### ProfileUploadProviderAdapter
-
-Implements `IProfileUploadProvider` from ng-shared. Enables ng-auth's profile page to upload profile pictures.
-
-```typescript
-interface IProfileUploadProvider {
-  uploadProfilePicture(
-    file: File,
-    options?: IProfileUploadOptions
-  ): Observable<ISingleResponse<IProfileUploadResult>>;
-}
-```
-
-**Usage in ng-auth profile page:**
-
-```typescript
-// Optional injection - graceful degradation when storage disabled
-private readonly uploadProvider = inject(PROFILE_UPLOAD_PROVIDER, { optional: true });
-
-// Upload profile picture
-if (this.uploadProvider) {
-  this.uploadProvider.uploadProfilePicture(file, { compress: true }).subscribe(response => {
-    // response.data.id contains the file manager ID
-    this.updateUserProfile({ profilePictureId: response.data.id });
-  });
-}
-```
-
----
-
-## Public API Exports
-
-```typescript
-// Enums
-export { FileLocationEnum, ImageFormat } from '@flusys/ng-storage';
-
-// Interfaces (all from interfaces/)
-export {
-  IFileManager, ICreateFileManagerDto, IUpdateFileManagerDto,
-  IGetFilesRequestDto, IFilesResponseDto,
-  IFolder, ICreateFolderDto, IUpdateFolderDto,
-  IStorageConfig, ICreateStorageConfigDto, IUpdateStorageConfigDto,
-  IAwsS3Config, IAzureBlobConfig, ISftpConfig, ILocalStorageConfig,
-  IUploadOptionsDto, IUploadedFileInfo,
-} from '@flusys/ng-storage';
-
-// Services
-export {
-  FileManagerApiService, FolderApiService,
-  StorageConfigApiService, UploadService,
-} from '@flusys/ng-storage';
-
-// Routes & Components
-export { STORAGE_ROUTES } from '@flusys/ng-storage';
-export { StorageContainerComponent } from '@flusys/ng-storage';
-
-// Provider Functions
-export { provideStorageProviders } from '@flusys/ng-storage';
-```
-
----
+## License
 
-**Last Updated:** 2026-02-16
-**Angular Version:** 21
+MIT © FLUSYS