@flusys/ng-storage 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -0,0 +1,590 @@
+# Storage Package Guide
+
+> **Package:** `@flusys/ng-storage`
+> **Type:** File storage management with upload, folder organization, and multi-provider support
+
+---
+
+## Overview
+
+`@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
+
+```
+@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.
+
+```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
+
+```
+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
+
+### Adding Storage Routes
+
+```typescript
+// app.routes.ts
+export const routes: Routes = [
+  {
+    path: 'storage',
+    loadChildren: () =>
+      import('@flusys/ng-storage').then((m) => m.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
+
+### FileLocationEnum
+
+Storage provider types (matches backend).
+
+```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
+
+### 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)
+}
+
+interface IUploadedFileInfo {
+  name: string;        // Original filename
+  key: string;         // Storage key/path
+  size: number;        // File size in bytes
+  contentType: string; // MIME type
+}
+```
+
+### 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
+  companyId?: string | null;
+}
+
+interface ICreateStorageConfigDto {
+  name: string;
+  storage: FileLocationEnum;
+  config: Record<string, any>;
+}
+
+interface IUpdateStorageConfigDto {
+  id: string;
+  name?: string;
+  storage?: FileLocationEnum;
+  config?: Record<string, any>;
+}
+```
+
+### 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`
+
+### 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
+
+---
+
+## 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 },
+}
+```
+
+---
+
+## 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';
+```
+
+---
+
+**Last Updated:** 2026-02-07
+**Angular Version:** 21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/ng-storage",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "File storage module for FLUSYS Angular applications",
   "license": "MIT",
   "peerDependencies": {