@flusys/ng-storage 3.0.0-rc → 3.0.1

package/README.md

@@ -1,6 +1,7 @@
 # Storage Package Guide
 
 > **Package:** `@flusys/ng-storage`
+> **Version:** 3.0.1
 > **Type:** File storage management with upload, folder organization, and multi-provider support
 
 ---
@@ -14,14 +15,15 @@
 - **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)
+- **Permission Guards** - All routes protected by permission guards
 - **Lazy Loading** - All page components are lazy-loaded via routes
 
 ### Package Hierarchy
 
 ```
-@flusys/ng-core           <- Foundation (BaseApiService, APP_CONFIG)
+@flusys/ng-core           <- Foundation (BaseApiService, APP_CONFIG, getDefaultStorageConfigId)
         |
-@flusys/ng-shared         <- Shared utilities (ApiResourceService, IBaseEntity)
+@flusys/ng-shared         <- Shared utilities (ApiResourceService, IBaseEntity, BaseListPage)
         |
 @flusys/ng-layout         <- Layout (LAYOUT_AUTH_STATE for company context)
         |
@@ -30,17 +32,7 @@
 
 ### 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,
-);
-```
+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. See `BaseStoragePage` class for implementation.
 
 ---
 
@@ -106,20 +98,20 @@ export const routes: 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 |
+All routes are wrapped by `StorageContainerComponent` which provides tab navigation (Files, Folders, Configs). Routes are protected by permission guards.
+
+| Path | Component | Permission |
+|------|-----------|------------|
+| `/storage` | StorageContainerComponent | - |
+| `/storage/files` | FileManagerListComponent | `FILE_PERMISSIONS.READ` |
+| `/storage/files/new` | FileManagerFormComponent | `FILE_PERMISSIONS.CREATE` |
+| `/storage/files/:id` | FileManagerFormComponent | `FILE_PERMISSIONS.UPDATE` |
+| `/storage/folders` | FolderListComponent | `FOLDER_PERMISSIONS.READ` |
+| `/storage/folders/new` | FolderFormComponent | `FOLDER_PERMISSIONS.CREATE` |
+| `/storage/folders/:id` | FolderFormComponent | `FOLDER_PERMISSIONS.UPDATE` |
+| `/storage/configs` | StorageConfigListComponent | `STORAGE_CONFIG_PERMISSIONS.READ` |
+| `/storage/configs/new` | StorageConfigFormComponent | `STORAGE_CONFIG_PERMISSIONS.CREATE` |
+| `/storage/configs/:id` | StorageConfigFormComponent | `STORAGE_CONFIG_PERMISSIONS.UPDATE` |
 
 Default redirect: `/storage` -> `/storage/files`
 
@@ -171,20 +163,19 @@ interface IUploadOptionsDto {
 }
 
 interface IUploadedFileInfo {
-  name: string;        // Original filename
-  key: string;         // Storage key/path
-  size: number;        // File size in bytes
-  contentType: string; // MIME type
+  name: string;              // Original filename
+  key: string;               // Storage key/path
+  size: number;              // File size in bytes
+  contentType: string;       // MIME type
+  location?: string;         // Storage location (optional)
+  storageConfigId?: string;  // Config used for upload (optional)
 }
 ```
 
 ### File Manager
 
 ```typescript
-interface IFileManager {
-  id: string;
-  createdAt: Date;
-  updatedAt: Date;
+interface IFileManager extends IBaseEntity {
   name: string;
   contentType: string;
   size: string;                      // In KB (string)
@@ -232,7 +223,7 @@ interface IFolder extends IBaseEntity {
 }
 
 interface ICreateFolderDto { name: string; }
-interface IUpdateFolderDto { id: string; name?: string; }
+interface IUpdateFolderDto extends Partial<ICreateFolderDto> { id: string; }
 ```
 
 ### Storage Config
@@ -241,27 +232,22 @@ interface IUpdateFolderDto { id: string; name?: string; }
 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
+  config: Record<string, unknown>;   // 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>;
+  config: Record<string, unknown>;
   isActive?: boolean;
   isDefault?: boolean;
 }
 
-interface IUpdateStorageConfigDto {
+interface IUpdateStorageConfigDto extends Partial<ICreateStorageConfigDto> {
   id: string;
-  name?: string;
-  storage?: FileLocationEnum;
-  config?: Record<string, any>;
-  isActive?: boolean;
-  isDefault?: boolean;
 }
 ```
 
@@ -269,34 +255,12 @@ interface IUpdateStorageConfigDto {
 
 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;
-}
-```
+| Interface | Required Fields | Optional Fields |
+|-----------|-----------------|-----------------|
+| `IAwsS3Config` | `region`, `bucket`, `accessKeyId`, `secretAccessKey` | `endpoint` (custom S3-compatible) |
+| `IAzureBlobConfig` | `accountName`, `accountKey`, `containerName` | - |
+| `ISftpConfig` | `host`, `port`, `username`, `basePath` | `password`, `privateKey` |
+| `ILocalStorageConfig` | `basePath` | - |
 
 ---
 
@@ -306,7 +270,9 @@ All services are `providedIn: 'root'`. Company scoping is automatic when the com
 
 ### UploadService
 
-Handles file upload and deletion. Extends `BaseApiService` (from ng-core).
+Handles file upload and deletion. Extends `BaseApiService` (from ng-core) with base path `/storage`.
+
+**Methods:**
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
@@ -318,85 +284,52 @@ Handles file upload and deletion. Extends `BaseApiService` (from ng-core).
 | `getFileUrl(key)` | `GET /storage/upload/file/:key` | Get direct file download URL |
 | `getDefaultConfigId()` | - | Get default storage config ID from APP_CONFIG |
 
-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,
-});
-```
+**Upload options** are sent as query parameters. **Storage Config Resolution:** Uses `storageConfigId` from options if provided, otherwise falls back to `getDefaultConfigId()` from APP_CONFIG. See Usage Examples for code samples.
 
 ### FileManagerApiService
 
-File metadata CRUD. Extends `ApiResourceService<IUpdateFileManagerDto, IFileManager>`.
+File metadata CRUD. Extends `ApiResourceService<IUpdateFileManagerDto, IFileManager>` with endpoint `/storage/file-manager`.
 
-**Inherited CRUD methods** (from ApiResourceService): `insert`, `update`, `findById`, `getAll`, `delete` and their `*Async` variants.
+**Inherited CRUD:** `insert`, `update`, `findById`, `getAll`, `delete` (and `*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.
+| `getFiles(fileIds: string[])` | `POST /storage/file-manager/get-files` | Get files with valid presigned URLs |
+| `createFile(dto: ICreateFileManagerDto)` | `POST /storage/file-manager/insert` | Create file record (Observable) |
+| `createFileAsync(dto: ICreateFileManagerDto)` | `POST /storage/file-manager/insert` | Create file record (Promise) |
 
-```typescript
-const response = await firstValueFrom(
-  this.fileService.getFiles(['file-id-1', 'file-id-2'])
-);
-// response.data → [{ id, name, contentType, url }]
-```
+**Presigned URL pattern:** Always use `getFiles()` to get valid URLs. Backend regenerates expired presigned URLs for cloud storage. See Usage Examples.
 
 ### FolderApiService
 
-Folder CRUD. Extends `ApiResourceService<IUpdateFolderDto, IFolder>`. Standard CRUD operations only, no custom methods.
+Folder CRUD. Extends `ApiResourceService<ICreateFolderDto | IUpdateFolderDto, IFolder>` with endpoint `/storage/folder`. Standard CRUD operations only.
 
 ### StorageConfigApiService
 
-Storage provider configuration CRUD. Extends `ApiResourceService<IUpdateStorageConfigDto, IStorageConfig>`. Standard CRUD operations only, no custom methods.
+Storage config CRUD. Extends `ApiResourceService<ICreateStorageConfigDto | IUpdateStorageConfigDto, IStorageConfig>` with endpoint `/storage/storage-config`. Standard CRUD operations only.
 
 ---
 
-## Components
+## Base Classes
 
-All components are standalone, use Angular 21 signal forms, and lazy-load via routes.
+Components extend shared base classes from `utils/base-storage-page.ts`:
 
-### Base Classes
+| Class | Extends | Purpose | Key Members |
+|-------|---------|---------|-------------|
+| `BaseStoragePage` | - | Form pages | `isLoading`, `showCompanyInfo`, `currentCompanyName`, `showSuccess()`, `showError()`, `navigateTo()` |
+| `BaseStorageListPage<T>` | `BaseListPage<T>` | List pages | `pageSize=50`, `totalRecords`, `currentCompanyName`, `getDeleteConfirmMessage()` |
 
-Components extend shared base classes from `utils/base-storage-page.ts`:
+Both inject: `Router`, `MessageService`, `APP_CONFIG`, `LAYOUT_AUTH_STATE`
 
-```typescript
-// BaseStoragePage - Common functionality for all storage pages
-abstract class BaseStoragePage {
-  readonly isLoading = signal(false);
-  readonly showCompanyInfo = computed(() => this.appConfig.enableCompanyFeature);
-  readonly currentCompanyName = computed(() =>
-    this.companyContext.currentCompanyInfo()?.name ?? DEFAULT_APP_NAME
-  );
-
-  protected showSuccess(detail: string): void;
-  protected showError(detail: string): void;
-  protected navigateTo(path: string[]): void;
-}
+**BaseStorageListPage inherits from BaseListPage:** `items`, `total`, `isLoading`, `currentPage`, `onPageChange()`, `getPaginationParams()`, `onCreate()`, `onEdit()`, `onDeleteAsync()`, `loadData()` (abstract), `getResourceRoute()` (abstract)
 
-// BaseStorageListPage - Adds pagination support
-abstract class BaseStorageListPage extends BaseStoragePage {
-  readonly totalRecords = signal(0);
-  readonly pageSize = signal(50);
-  readonly currentPage = signal(1);
+---
 
-  onPageChange(event: { first?: number; rows?: number }): void;
-  protected getPaginationParams(): { currentPage: number; pageSize: number };
-  abstract loadData(): Promise<void>;
-}
-```
+## Components
+
+All components are standalone, use Angular 21 signal forms, and lazy-load via routes.
 
 ### StorageContainerComponent
 
@@ -405,91 +338,65 @@ Main container with tab navigation between Files, Folders, and Configs sections.
 **Selector:** `lib-storage-container`
 
 **Features:**
-- Tab navigation with `scrollbar-hide` CSS (horizontal scroll without visible scrollbar on mobile)
+- Tab navigation filtered by user permissions (via `PermissionValidatorService`)
+- Horizontal scroll without visible scrollbar (`scrollbar-hide`)
+- Dynamic subtitle based on visible tabs
 - Responsive padding: `p-2 sm:p-4`
-- Dark mode compatible using Tailwind theme classes
+- Dark mode compatible (Tailwind theme classes)
 
 ### List Components
 
-All list components share:
-- **Extends `BaseStorageListPage`** for common functionality
-- **Lazy pagination** via `p-table` with `[paginator]="totalRecords() > 0"` (hidden when no data)
-- **Responsive columns** with `hidden sm:table-cell`, `hidden md:table-cell`, etc.
-- **Company info display** when company feature enabled
-- **Delete confirmation** via `ConfirmationService`
-- **Signal-based state:** `isLoading`, data signal, `totalRecords`, `pageSize`, `currentPage`
-- **Responsive title:** `text-lg sm:text-xl`
-- **Responsive buttons:** `w-full sm:w-auto`
-
-**FileManagerListComponent** additionally supports:
+All list components extend `BaseStorageListPage<T>` with: lazy pagination (`p-table`), responsive columns (`hidden sm:table-cell`), company info display, delete confirmation (`ConfirmationService`), signal-based state (`isLoading`, `totalRecords`, `pageSize`, `currentPage`), and permission-based actions (`*hasPermission`). Responsive styling: titles `text-lg sm:text-xl`, buttons `w-full sm:w-auto`.
+
+#### FileManagerListComponent
+
+**Selector:** `lib-file-manager-list`
+
+**Features:**
 - 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)
+- Provider location tags with severity colors
+- View file: fetches presigned URL via `getFiles()`, opens in new tab (tracks loading with `viewingFileId` signal)
+- **Soft delete** (`type: 'delete'`) - recoverable | **Permanent delete** (`type: 'permanent'`) - irreversible
+
+#### FolderListComponent
+
+**Selector:** `lib-folder-list`
+
+Simple CRUD list with folder icon, name, slug, and created date columns.
+
+#### StorageConfigListComponent
+
+**Selector:** `lib-storage-config-list`
+
+Lists storage configurations with provider icons and tags.
 
 ### 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
-- **Button styling pattern:**
-  - Cancel: `severity="secondary" [outlined]="true"`
-  - Submit: Primary style (no severity attribute)
-  - Order: Cancel first, then Submit (right-aligned)
-  - Responsive: `flex justify-end gap-4 pt-4`
-
-**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.
+All form components share: Signal Forms with `form()` + `required()` validators, create/edit mode detection via `:id` route param, `effect()` + `toSignal(route.paramMap)` initialization, navigation back on save/cancel, computed validation, and consistent button styling (`Cancel: secondary outlined`, `Submit: primary`, order: Cancel → Submit, container: `flex justify-end gap-2 mt-4`).
+
+| Component | Selector | Form Fields | Notes |
+|-----------|----------|-------------|-------|
+| FileManagerForm | `lib-file-manager-form` | `id`, `name`, `isPrivate`, `folderId`, `storageConfigId` | PrimeNG file upload (50MB max), storage config required for upload, edit mode shows metadata only |
+| FolderForm | `lib-folder-form` | `id`, `name` | Simple name-only form |
+| StorageConfigForm | `lib-storage-config-form` | `id`, `name`, `storage`, `isActive`, `isDefault`, provider-specific fields | Dynamic fields based on provider; defaults: `storage: AWS`, `isActive: true`, `sftpPort: '22'` |
+
+**FileManagerForm Upload Flow:** 1) Upload file via `uploadSingleFile()` 2) Create metadata via `createFileAsync()`. Edit mode only calls `updateAsync()`.
 
 ---
 
 ## Utility Functions
 
-The `utils/storage-utils.ts` file provides helper functions used across components:
+The `utils/storage-utils.ts` file provides helper functions:
 
-```typescript
-// Get display label for storage provider
-getProviderLabel(storage: FileLocationEnum): string;
-// Returns: 'AWS S3', 'Azure Blob', 'SFTP', 'Local'
-
-// Get icon class for storage provider
-getProviderIcon(storage: FileLocationEnum): string;
-// Returns: 'pi pi-cloud', 'pi pi-server', 'pi pi-folder'
-
-// Get severity for p-tag based on provider
-getProviderSeverity(storage: FileLocationEnum): 'success' | 'info' | 'warn' | 'danger' | 'secondary' | 'contrast';
-
-// Get file icon based on content type
-getFileIcon(contentType: string): string;
-// Returns: 'pi pi-image', 'pi pi-video', 'pi pi-file-pdf', etc.
-
-// Format file size to human readable
-formatFileSize(bytes: number): string;
-// Returns: '1.5 MB', '256 KB', etc.
-
-// Storage provider options for dropdowns
-const STORAGE_PROVIDERS = [
-  { label: 'AWS S3', value: FileLocationEnum.AWS },
-  { label: 'Azure Blob Storage', value: FileLocationEnum.AZURE },
-  { label: 'SFTP', value: FileLocationEnum.SFTP },
-  { label: 'Local Storage', value: FileLocationEnum.LOCAL },
-];
-```
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `getProviderLabel(storage)` | `string` | Display label: 'AWS S3', 'Azure Blob', 'SFTP', 'Local' |
+| `getProviderIcon(storage)` | `string` | Icon class: `pi pi-cloud`, `pi pi-server`, `pi pi-folder` |
+| `getProviderSeverity(storage)` | severity | Tag severity: `warn` (AWS), `info` (Azure), `contrast` (SFTP), `secondary` (Local) |
+| `getFileIcon(contentType)` | `string` | File icon based on MIME type (image, video, audio, pdf, word, excel, generic) |
+| `formatFileSize(bytes)` | `string` | Human readable: '256 KB', '1.5 MB', '2.3 GB' |
+
+**Constants:** `STORAGE_PROVIDERS` - Dropdown options array with `{ label, value }` for AWS S3, Azure Blob, SFTP, Local Storage.
 
 ---
 
@@ -498,24 +405,13 @@ const STORAGE_PROVIDERS = [
 ### 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;
-}
+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;
 ```
 
 ### Upload and Register (Combined)
@@ -523,100 +419,55 @@ async uploadImage(file: File): Promise<IUploadedFileInfo | null> {
 Use `uploadAndRegister` for a single call that uploads and creates the file manager record:
 
 ```typescript
-import { UploadService, IFileManager } from '@flusys/ng-storage';
-
-private readonly uploadService = inject(UploadService);
-
-async uploadProfilePicture(file: File): Promise<IFileManager | null> {
-  const response = await firstValueFrom(
-    this.uploadService.uploadAndRegister(file, {
-      compress: true,
-      quality: 85,
-      isPrivate: false,
-      folderId: 'avatars-folder-id',
-    })
-  );
-  return response.success ? response.data : null;
-}
+const response = await firstValueFrom(
+  this.uploadService.uploadAndRegister(file, { compress: true, quality: 85, isPrivate: false, folderId: 'avatars-folder-id' })
+);
+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 ?? [];
-}
+const response = await firstValueFrom(this.fileService.getFiles(['file-id-1', 'file-id-2']));
+// response.data → [{ id, name, contentType, url }]
 ```
 
-### Delete with Confirmation
+### Delete Files
 
-Two delete modes are available:
+| Mode | Type | Description |
+|------|------|-------------|
+| Soft delete | `type: 'delete'` | Marks as deleted (recoverable) |
+| Permanent delete | `type: 'permanent'` | Removes from storage provider (irreversible) |
 
 ```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();
-    },
-  });
-}
+await this.fileService.deleteAsync({ id: file.id, type: 'delete' });     // Soft
+await this.fileService.deleteAsync({ id: file.id, type: 'permanent' });  // Permanent
+```
 
-// 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();
-    },
-  });
-}
+### Create Storage Configuration
+
+```typescript
+await this.configService.insertAsync({
+  name: 'Production AWS S3',
+  storage: FileLocationEnum.AWS,
+  config: { region: 'us-east-1', bucket: 'my-bucket', accessKeyId: 'AKIA...', secretAccessKey: '...' },
+  isActive: true,
+  isDefault: true,
+});
 ```
 
 ---
 
 ## 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 |
+All endpoints use **POST-only RPC** style (not REST). Base paths:
+
+| Service | Base Path | Standard CRUD |
+|---------|-----------|---------------|
+| Upload | `/storage/upload` | Custom methods (see Services section) |
+| FileManager | `/storage/file-manager` | `insert`, `get/:id`, `get-all`, `update`, `delete` + `get-files` |
+| Folder | `/storage/folder` | `insert`, `get/:id`, `get-all`, `update`, `delete` |
+| StorageConfig | `/storage/storage-config` | `insert`, `get/:id`, `get-all`, `update`, `delete` |
 
 ---
 
@@ -627,10 +478,8 @@ All endpoints use **POST-only RPC** style (not REST).
 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
+// Wrong: const url = `${apiBaseUrl}/storage/${fileId}`;
+// Correct:
 const files = await firstValueFrom(this.fileService.getFiles([fileId]));
 const url = files.data?.[0]?.url ?? null;
 ```
@@ -638,70 +487,34 @@ 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',
-  })
-);
+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,
-};
+{ compress: true, maxWidth: 1920, maxHeight: 1080, quality: 85, format: ImageFormat.WEBP }
 ```
 
-### 4. Provide ConfirmationService at App Level
+### 4. Provide Required Services 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],
-};
-```
+Provide `ConfirmationService` and `MessageService` in `app.config.ts` for dialogs and toasts.
 
 ### 5. Enable Storage in APP_CONFIG
 
 ```typescript
-// environment.ts
-services: {
-  storage: { baseUrl: 'http://localhost:2002/storage', enabled: true },
-}
+services: { storage: { baseUrl: 'http://localhost:2002/storage', enabled: true } }
 ```
 
 ### 6. Responsive Design Patterns
 
-All components follow these responsive patterns:
-
-```html
-<!-- Titles: smaller on mobile -->
-<h3 class="text-lg sm:text-xl font-semibold">Title</h3>
-
-<!-- Buttons: full width on mobile, auto on larger -->
-<p-button label="New" styleClass="w-full sm:w-auto" />
-
-<!-- Form grids: stack on mobile, 2 columns on md+ -->
-<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-
-<!-- Labels: smaller text on mobile -->
-<label class="text-sm sm:text-base">Label</label>
-
-<!-- Table columns: hide on smaller screens -->
-<th class="hidden sm:table-cell">Column</th>
-<th class="hidden md:table-cell">Column</th>
-
-<!-- Tab navigation: horizontal scroll without visible scrollbar -->
-<div class="scrollbar-hide flex overflow-x-auto">
-```
+| Pattern | Classes |
+|---------|---------|
+| Titles | `text-lg sm:text-xl` |
+| Buttons | `w-full sm:w-auto` |
+| Form grids | `grid grid-cols-1 md:grid-cols-2 gap-4` |
+| Table columns | `hidden sm:table-cell`, `hidden md:table-cell`, etc. |
+| Tab navigation | `scrollbar-hide flex overflow-x-auto` |
 
 ---
 
@@ -712,83 +525,32 @@ All components follow these responsive patterns:
 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
-  ],
-};
+// app.config.ts - add to providers array
+...provideStorageProviders()
 ```
 
-**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.
+**Registers:** `PROFILE_UPLOAD_PROVIDER` → `ProfileUploadProviderAdapter` (implements `IProfileUploadProvider` from ng-shared)
 
-```typescript
-interface IProfileUploadProvider {
-  uploadProfilePicture(
-    file: File,
-    options?: IProfileUploadOptions
-  ): Observable<ISingleResponse<IProfileUploadResult>>;
-}
-```
+**ProfileUploadProviderAdapter defaults:** `folderPath: 'profile-pictures'`, `compress: true`, `maxWidth: 400`, `maxHeight: 400`
 
-**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 });
-  });
-}
-```
+**Usage:** `inject(PROFILE_UPLOAD_PROVIDER, { optional: true })?.uploadProfilePicture(file)`
 
 ---
 
 ## 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';
-```
+| Category | Exports |
+|----------|---------|
+| Enums | `FileLocationEnum`, `ImageFormat` |
+| Interfaces | `IFileManager`, `ICreateFileManagerDto`, `IUpdateFileManagerDto`, `IGetFilesRequestDto`, `IFilesResponseDto`, `IFolder`, `ICreateFolderDto`, `IUpdateFolderDto`, `IStorageConfig`, `ICreateStorageConfigDto`, `IUpdateStorageConfigDto`, `IAwsS3Config`, `IAzureBlobConfig`, `ISftpConfig`, `ILocalStorageConfig`, `IUploadOptionsDto`, `IUploadedFileInfo` |
+| Utils | `getProviderLabel`, `getProviderIcon`, `getProviderSeverity`, `getFileIcon`, `formatFileSize`, `STORAGE_PROVIDERS`, `BaseStoragePage`, `BaseStorageListPage` |
+| Adapters | `ProfileUploadProviderAdapter` |
+| Services | `FileManagerApiService`, `FolderApiService`, `StorageConfigApiService`, `UploadService` |
+| Routes | `STORAGE_ROUTES`, `StorageContainerComponent` |
+| Providers | `provideStorageProviders` |
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25
+**Version:** 3.0.1
 **Angular Version:** 21