http-request-manager 18.15.34 → 18.16.1

package/src/docs/UPLOAD_REQUEST_README.md

@@ -1,324 +0,0 @@
-# File Upload Request
-
-The `uploadRequest` method provides a complete file upload solution with progress tracking, client-side validation, and configurable options. It is available on both `HTTPManagerService` (Observable) and `HTTPManagerSignalsService` (Signals).
-
-## Overview
-
-```typescript
-uploadRequest<T>(files: File | File[], options: ApiRequest, params?: any[]): Observable<T>
-```
-
-The method sends files as `multipart/form-data` via HTTP POST (or PUT) with upload progress reporting.
-
-## ApiRequest Upload Parameters
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `server` | `string` | `''` | Server key mapped via proxy config (e.g. `'gtlcApi'`) |
-| `path` | `string[]` | `[]` | URL path segments (e.g. `['uploader']`) |
-| `uploadFieldName` | `string` | `'file'` (single) / `'files'` (multiple) | Form-data field name for the file(s) |
-| `uploadHttpMethod` | `'POST' \| 'PUT'` | `'POST'` | HTTP method for the upload request |
-| `allowedTypes` | `string[]` | `[]` | Allowed MIME types (e.g. `['image/jpeg', 'image/png']`). Empty array = all types allowed |
-| `maxFileSize` | `number` | `Infinity` | Maximum file size in bytes (e.g. `40 * 1024 * 1024` = 40MB) |
-| `maxTotalSize` | `number` | `Infinity` | Maximum total size across all files in bytes |
-| `headers` | `object` | `{}` | Custom HTTP headers |
-| `displayError` | `boolean` | `false` | Show error toast on failure |
-| `displaySuccess` | `boolean` | `false` | Show success toast on completion |
-| `errorMessage` | `string` | — | Custom error message for toast |
-| `successMessage` | `string` | — | Custom success message for toast |
-| `retry` | `RetryOptions` | — | Retry configuration |
-| `polling` | `number` | `0` | Polling interval in seconds |
-
-## Method Signature
-
-```typescript
-uploadRequest<T>(
-  files: File | File[],     // Single file or array of files
-  options: ApiRequest,      // Upload configuration
-  params?: any[]            // Optional path params appended to `path`
-): Observable<T>
-```
-
-### Parameters
-
-| Param | Type | Description |
-|-------|------|-------------|
-| `files` | `File \| File[]` | One or more files to upload |
-| `options` | `ApiRequest` | Upload configuration (see table above) |
-| `params` | `any[]` | (Optional) Additional path segments appended to `options.path` |
-
-### Returns
-
-An `Observable<T>` that emits the server response on success. The observable also provides upload progress updates via the service's `progress$` observable.
-
-## Progress Tracking
-
-The service exposes a `progress$` observable that emits upload progress as a percentage (0–100):
-
-```typescript
-this.httpManager.progress$.subscribe(percent => {
-  console.log(`Upload progress: ${percent}%`);
-});
-```
-
-Progress is tracked using Angular's `HttpEventType.UploadProgress` events.
-
-## Client-Side Validation
-
-Before sending, the service validates files against the configured constraints:
-
-- **File type** — Checks against `allowedTypes` array (supports wildcards like `image/*`)
-- **File size** — Checks each file against `maxFileSize`
-- **Total size** — Checks combined size against `maxTotalSize`
-
-Invalid files are collected and returned as an `UploadValidationErrorModel` error.
-
-## Complete Demo Example
-
-### Upload State Model
-
-```typescript
-// models/upload-state.model.ts
-export interface UploadStateInterface {
-  selectedFiles: File[]
-  isUploading: boolean
-  progress: number
-  currentFile: string | null
-  errorMessage: string | null
-  successMessage: string | null
-}
-
-export class UploadStateModel implements UploadStateInterface {
-  constructor(
-    public selectedFiles: File[] = [],
-    public isUploading: boolean = false,
-    public progress: number = 0,
-    public currentFile: string | null = null,
-    public errorMessage: string | null = null,
-    public successMessage: string | null = null
-  ) {}
-
-  static adapt(item?: any): UploadStateModel {
-    return new UploadStateModel(
-      Array.isArray(item?.selectedFiles) ? item.selectedFiles : [],
-      item?.isUploading ?? false,
-      item?.progress ?? 0,
-      item?.currentFile ?? null,
-      item?.errorMessage ?? null,
-      item?.successMessage ?? null
-    )
-  }
-}
-```
-
-### Component
-
-```typescript
-import { Component, inject } from '@angular/core'
-import { ApiRequest, HTTPManagerService } from 'http-request-manager'
-import { UploadStateModel } from './models/upload-state.model'
-
-@Component({
-  selector: 'app-file-upload',
-  templateUrl: './file-upload.component.html'
-})
-export class FileUploadComponent {
-
-  private httpManager = inject(HTTPManagerService)
-
-  uploadState = UploadStateModel.adapt()
-
-  allowedTypes = ['image/jpeg', 'image/png', 'application/pdf']
-  maxFileSize = 40 * 1024 * 1024 // 40MB
-
-  onFileSelected(event: Event): void {
-    const input = event.target as HTMLInputElement
-    const files = input.files
-
-    if (!files || files.length === 0) return
-
-    this.uploadState.selectedFiles = []
-    this.uploadState.errorMessage = null
-
-    for (let i = 0; i < files.length; i++) {
-      const file = files[i]
-      const validationError = this.validateFile(file)
-
-      if (validationError) {
-        this.uploadState.errorMessage = validationError
-        continue
-      }
-
-      this.uploadState.selectedFiles.push(file)
-    }
-  }
-
-  validateFile(file: File): string | null {
-    if (!this.allowedTypes.includes(file.type)) {
-      return `File "${file.name}" is not a valid type.`
-    }
-    if (file.size > this.maxFileSize) {
-      return `File "${file.name}" exceeds maximum size of 40MB.`
-    }
-    return null
-  }
-
-  startUpload(): void {
-    if (this.uploadState.selectedFiles.length === 0) return
-
-    this.uploadState.isUploading = true
-    this.uploadState.progress = 0
-    this.uploadState.errorMessage = null
-    this.uploadState.successMessage = null
-
-    const options = ApiRequest.adapt({
-      server: 'gtlcApi',
-      path: ['uploader'],
-      uploadFieldName: 'files',
-      allowedTypes: this.allowedTypes,
-      maxFileSize: this.maxFileSize
-    })
-
-    // Track upload progress
-    this.httpManager.progress$.subscribe(percent => {
-      this.uploadState.progress = percent
-    })
-
-    this.httpManager.uploadRequest<any>(
-      this.uploadState.selectedFiles,
-      options,
-      ['upload']  // optional path params
-    ).subscribe({
-      next: (response) => {
-        this.uploadState.progress = 100
-        this.uploadState.successMessage = `Uploaded ${this.uploadState.selectedFiles.length} file(s)`
-        this.uploadState.isUploading = false
-      },
-      error: (error) => {
-        this.uploadState.errorMessage = error.message || 'Upload failed'
-        this.uploadState.isUploading = false
-        this.uploadState.progress = 0
-      }
-    })
-  }
-
-  clearSelection(): void {
-    this.uploadState = UploadStateModel.adapt()
-  }
-
-  getFileSizeString(size: number): string {
-    if (size < 1024) return `${size} bytes`
-    if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`
-    return `${(size / (1024 * 1024)).toFixed(1)} MB`
-  }
-}
-```
-
-### Template
-
-```html
-<div class="upload-container">
-  <h2>File Upload</h2>
-
-  <div class="upload-controls">
-    <button (click)="fileInput.click()" [disabled]="uploadState.isUploading">
-      Select Files
-    </button>
-    <input #fileInput type="file" multiple
-           accept="image/jpeg,image/png,application/pdf"
-           (change)="onFileSelected($event)" hidden>
-    <button (click)="clearSelection()"
-            [disabled]="uploadState.selectedFiles.length === 0">
-      Clear
-    </button>
-  </div>
-
-  <!-- Selected Files -->
-  <div *ngIf="uploadState.selectedFiles.length > 0">
-    <h3>Selected Files ({{uploadState.selectedFiles.length}})</h3>
-    <ul>
-      <li *ngFor="let file of uploadState.selectedFiles">
-        {{file.name}} — {{getFileSizeString(file.size)}}
-      </li>
-    </ul>
-  </div>
-
-  <!-- Progress Bar -->
-  <div *ngIf="uploadState.isUploading" class="progress-bar">
-    <div class="progress-fill" [style.width.%]="uploadState.progress">
-      {{uploadState.progress}}%
-    </div>
-  </div>
-
-  <!-- Messages -->
-  <div *ngIf="uploadState.errorMessage" class="error">
-    {{uploadState.errorMessage}}
-  </div>
-  <div *ngIf="uploadState.successMessage" class="success">
-    {{uploadState.successMessage}}
-  </div>
-
-  <!-- Upload Button -->
-  <button (click)="startUpload()"
-          [disabled]="uploadState.selectedFiles.length === 0 || uploadState.isUploading">
-    {{uploadState.isUploading ? 'Uploading...' : 'Start Upload'}}
-  </button>
-</div>
-```
-
-## Signals Service
-
-The same API is available on `HTTPManagerSignalsService`:
-
-```typescript
-import { HTTPManagerSignalsService } from 'http-request-manager'
-
-private httpManagerSignals = inject(HTTPManagerSignalsService)
-
-// Progress as a signal
-const progress = this.httpManagerSignals.progress
-
-this.httpManagerSignals.uploadRequest<any>(files, options, ['upload'])
-  .subscribe({ ... })
-```
-
-## Error Handling
-
-The service throws an `UploadValidationErrorModel` when client-side validation fails:
-
-```typescript
-interface UploadValidationErrorModel {
-  invalidFiles: InvalidFileInfoModel[]
-  validCount: number
-  totalCount: number
-}
-
-interface InvalidFileInfoModel {
-  fileName: string
-  fileSize: number
-  fileType: string
-  errors: string[]  // e.g. ['type not allowed', 'exceeds maxFileSize']
-}
-```
-
-## Proxy Configuration
-
-When using Angular's proxy, ensure the proxy pattern matches the `server` key:
-
-```json
-{
-  "/gtlcApi/**": {
-    "target": "http://your-api-server:8550/rest/oidc",
-    "secure": false,
-    "changeOrigin": true,
-    "pathRewrite": { "^/gtlcApi": "" },
-    "logLevel": "debug"
-  }
-}
-```
-
-## Important Notes
-
-- **Content-Type** — The browser automatically sets `multipart/form-data` with the correct boundary when sending `FormData`. Do NOT manually set `Content-Type` in interceptors for upload requests.
-- **Form field naming** — Files are appended with the key specified by `uploadFieldName`. Each file uses the same key (e.g. `files`), not indexed keys like `files[0]`.
-- **Large files** — For files over 40MB, consider chunked upload strategies or adjust server limits accordingly.