@wlindabla/file_uploader 1.0.0

package/README.md

@@ -0,0 +1,2172 @@
+# @wlindabla/file_uploader
+
+> A powerful, event-driven chunked file uploader for Browser and Node.js — Universal, Resumable, and Production-Ready.
+---
+
+## 📖 Table of Contents
+
+- [@wlindabla/file\_uploader](#wlindablafile_uploader)
+  - [📖 Table of Contents](#-table-of-contents)
+  - [Overview](#overview)
+  - [Features](#features)
+  - [Installation](#installation)
+  - [Requirements](#requirements)
+  - [Quick Start](#quick-start)
+    - [Browser (Minimal Example)](#browser-minimal-example)
+  - [Core Concepts](#core-concepts)
+    - [How It Works](#how-it-works)
+    - [Upload Lifecycle](#upload-lifecycle)
+    - [The Three-Endpoint Pattern](#the-three-endpoint-pattern)
+  - [API Reference](#api-reference)
+    - [ChunkedFileUploader](#chunkedfileuploader)
+      - [Constructor](#constructor)
+      - [Methods](#methods)
+        - [`.withFile(file: File): this`](#withfilefile-file-this)
+        - [`.withEndpoints(endpoints: UploadEndpoints): this`](#withendpointsendpoints-uploadendpoints-this)
+        - [`.upload(): Promise<void>`](#upload-promisevoid)
+        - [`.pause(): void`](#pause-void)
+        - [`.resume(): void`](#resume-void)
+        - [`.cancel(): void`](#cancel-void)
+        - [`.getState(): UploadState`](#getstate-uploadstate)
+        - [`.resumeUpload(resumeData: ResumeData): Promise<void>`](#resumeuploadresumedata-resumedata-promisevoid)
+        - [`.loadResumeData(fileName: string): Promise<ResumeData | null>`](#loadresumedatafilename-string-promiseresumedata--null)
+    - [HttpFileUploaderEvents](#httpfileuploaderevents)
+    - [UploadOptions](#uploadoptions)
+      - [Chunk Size Auto-Calculation](#chunk-size-auto-calculation)
+    - [UploadEndpoints](#uploadendpoints)
+    - [UploadResumeCacheInterface](#uploadresumecacheinterface)
+      - [Example Implementations](#example-implementations)
+        - [Browser — localStorage](#browser--localstorage)
+        - [Browser — IndexedDB](#browser--indexeddb)
+        - [Node.js — Redis](#nodejs--redis)
+        - [Node.js — Filesystem](#nodejs--filesystem)
+  - [Events System](#events-system)
+    - [Event Architecture](#event-architecture)
+    - [All Available Events](#all-available-events)
+      - [Initialize Events](#initialize-events)
+      - [Chunk Upload Events](#chunk-upload-events)
+      - [Upload State Events](#upload-state-events)
+      - [Completion Events](#completion-events)
+      - [Metadata Events](#metadata-events)
+    - [Event Classes Reference](#event-classes-reference)
+      - [`UploadProgressEvent`](#uploadprogressevent)
+      - [`UploadStateChangedEvent`](#uploadstatechangedevent)
+      - [`UploadMediaCompleteEvent`](#uploadmediacompleteevent)
+      - [`UploadCancelledEvent`](#uploadcancelledevent)
+      - [`UploadPausedEvent`](#uploadpausedevent)
+      - [`UploadResumedEvent`](#uploadresumedevent)
+      - [`ChunkUploadHttpErrorResponseEvent`](#chunkuploadhttperrorresponseevent)
+      - [`InitializeUploadStartedEvent`](#initializeuploadstartedevent)
+      - [`InitializeUploadSuccessEvent`](#initializeuploadsuccessevent)
+      - [`InitializeUploadFailureEvent`](#initializeuploadfailureevent)
+      - [`ResumeUploadEvent`](#resumeuploadevent)
+- [Subscribers — Upload Lifecycle Handlers](#subscribers--upload-lifecycle-handlers)
+  - [⚠️ Important — You Must Register the Subscribers](#️-important--you-must-register-the-subscribers)
+  - [Registration](#registration)
+    - [Browser Environment](#browser-environment)
+    - [Node.js Environment](#nodejs-environment)
+  - [Complete Setup Example](#complete-setup-example)
+    - [Browser](#browser)
+    - [Node.js](#nodejs)
+  - [InitializeUploadSubscriber](#initializeuploadsubscriber)
+    - [What It Does Internally](#what-it-does-internally)
+    - [Events It Dispatches](#events-it-dispatches)
+    - [Retry Behavior](#retry-behavior)
+    - [Error Cases Handled](#error-cases-handled)
+  - [FinalizeUploadSubscriber](#finalizeuploadsubscriber)
+    - [What It Does Internally](#what-it-does-internally-1)
+    - [Events It Dispatches](#events-it-dispatches-1)
+    - [Error Cases Handled](#error-cases-handled-1)
+  - [Subscriber Priority](#subscriber-priority)
+  - [Common Mistakes](#common-mistakes)
+    - [❌ Forgetting to register subscribers](#-forgetting-to-register-subscribers)
+    - [❌ Registering subscribers AFTER calling upload()](#-registering-subscribers-after-calling-upload)
+    - [✅ Correct order](#-correct-order)
+  - [Subscribers](#subscribers)
+    - [InitializeUploadSubscriber](#initializeuploadsubscriber-1)
+    - [FinalizeUploadSubscriber](#finalizeuploadsubscriber-1)
+  - [Types Reference](#types-reference)
+    - [`UploadState` (enum)](#uploadstate-enum)
+    - [`ChunkInfo`](#chunkinfo)
+    - [`UploadProgress`](#uploadprogress)
+    - [`ResumeData`](#resumedata)
+    - [`UploadResult`](#uploadresult)
+    - [`ChunkError`](#chunkerror)
+    - [`InitializeUploadResponse`](#initializeuploadresponse)
+  - [Exceptions](#exceptions)
+    - [`InitializeUploadFailureException`](#initializeuploadfailureexception)
+    - [`FileUploadChunkError`](#fileuploadchunkerror)
+    - [`ChunkUploadHttpErrorException`](#chunkuploadhttperrorexception)
+    - [`UploadCancelledException`](#uploadcancelledexception)
+  - [Advanced Usage](#advanced-usage)
+    - [Concurrency Control](#concurrency-control)
+    - [Pause and Resume](#pause-and-resume)
+    - [Cancel Upload](#cancel-upload)
+    - [Resumable Upload](#resumable-upload)
+    - [Custom Logger](#custom-logger)
+    - [Custom Cache Implementation](#custom-cache-implementation)
+  - [Environment-Specific Examples](#environment-specific-examples)
+    - [Browser Example](#browser-example)
+    - [Node.js Example](#nodejs-example)
+  - [Server-Side Integration Guide](#server-side-integration-guide)
+    - [Init Endpoint](#init-endpoint)
+    - [Chunk Upload Endpoint](#chunk-upload-endpoint)
+    - [Finalize Endpoint](#finalize-endpoint)
+  - [Error Handling](#error-handling)
+    - [Complete Error Handling Example](#complete-error-handling-example)
+  - [Contributing](#contributing)
+    - [Development Setup](#development-setup)
+    - [Running Tests](#running-tests)
+  - [License](#license)
+  - [Support](#support)
+
+---
+
+## Overview
+
+`@wlindabla/file_uploader` is a **universal chunked file upload library** built on top of
+[`@wlindabla/http_client`](https://github.com/Agbokoudjo/http_client) and
+[`@wlindabla/event_dispatcher`](https://github.com/Agbokoudjo/event_dispatcher).
+
+It splits large files into small chunks, uploads them in parallel with configurable
+concurrency, and provides a **Symfony-inspired event system** so your application
+can react to every stage of the upload lifecycle — from initialization to completion.
+
+The library is designed to work seamlessly in **browsers** (via the File API) and
+in **Node.js** (server-to-server transfers), with full TypeScript support.
+
+---
+
+## Features
+
+- 🚀 **Chunked Upload** — Split large files into manageable chunks
+- ⚡ **Concurrent Uploads** — Upload multiple chunks in parallel (configurable)
+- 🔄 **Resumable** — Resume interrupted uploads from where they stopped
+- 🎯 **Event-Driven** — Rich Symfony-style event system for full lifecycle control
+- 🌐 **Universal** — Works in Browser and Node.js
+- 💪 **TypeScript-First** — Full type safety with generics
+- 🔌 **Extensible** — Bring your own cache, logger, and event dispatcher
+- 🛡️ **Robust** — Built-in retry logic, exponential backoff, and error handling
+- 🪶 **Lightweight** — Minimal core dependencies
+
+---
+
+## Installation
+
+```bash
+# Using yarn (recommended)
+yarn add @wlindabla/file_uploader @wlindabla/http_client @wlindabla/event_dispatcher
+
+# Using npm
+npm install @wlindabla/file_uploader @wlindabla/http_client @wlindabla/event_dispatcher
+
+# Using pnpm
+pnpm add @wlindabla/file_uploader @wlindabla/http_client @wlindabla/event_dispatcher
+```
+
+---
+
+## Requirements
+
+| Requirement | Version |
+|-------------|---------|
+| Node.js | >= 18.0.0 |
+| TypeScript | >= 5.3.0 |
+| `@wlindabla/http_client` | >=^1.0.0 |
+| `@wlindabla/event_dispatcher` | >=^1.0.0 |
+
+---
+
+## Quick Start
+
+### Browser (Minimal Example)
+
+```typescript
+import {
+  ChunkedFileUploader,
+  HttpFileUploaderEvents,
+  UploadStateChangedEvent,
+  UploadProgressEvent,
+  UploadMediaCompleteEvent
+} from '@wlindabla/file_uploader';
+
+import { BrowserEventDispatcher } from '@wlindabla/event_dispatcher';
+
+// 1. Implement your cache (localStorage example)
+class LocalStorageCache {
+  async getItem(key: string) {
+    const item = localStorage.getItem(key);
+    return item ? JSON.parse(item) : null;
+  }
+
+  async setItem(key: string, value: any) {
+    localStorage.setItem(key, JSON.stringify(value));
+  }
+
+  async removeItem(key: string) {
+    localStorage.removeItem(key);
+  }
+}
+
+// 2. Create the event dispatcher
+const dispatcher = new BrowserEventDispatcher();
+
+// 3. Listen to upload events
+dispatcher.addListener(
+  HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_SUCCESS,
+  (event: UploadProgressEvent) => {
+    console.log(`Progress: ${event.percentage}%`);
+  }
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.DOWNLOAD_MEDIA_COMPLETE,
+  (event: UploadMediaCompleteEvent) => {
+    console.log('Upload complete! File ID:', event.mediaId);
+  }
+);
+
+// 4. Create the uploader
+const uploader = new ChunkedFileUploader(
+  dispatcher,
+  new LocalStorageCache(),
+  {
+    maxRetries: 3,
+    concurrency: 3,
+    timeout: 60000
+  }
+);
+
+// 5. Set the file and endpoints, then upload
+const fileInput = document.getElementById('file') as HTMLInputElement;
+const file = fileInput.files![0];
+
+await uploader
+  .withFile(file)
+  .withEndpoints({
+    init: 'https://api.example.com/upload/init',
+    upload: 'https://api.example.com/upload/chunk',
+    finalize: 'https://api.example.com/upload/finalize'
+  })
+  .upload();
+```
+
+---
+
+## Core Concepts
+
+### How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         YOUR APPLICATION                         │
+│   dispatcher.addListener(HttpFileUploaderEvents.*, handler)      │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │ listens to
+                               │
+               ┌───────────────▼──────────────────┐
+               │       UPLOAD EVENTS (public)      │
+               │  HttpFileUploaderEvents.*         │
+               │  e.g. MEDIA_CHUNK_UPLOAD_SUCCESS  │
+               └───────────────▲──────────────────┘
+                               │ emitted by
+                               │
+               ┌───────────────┴──────────────────┐
+               │       ChunkedFileUploader         │
+               │  - Slices file into chunks        │
+               │  - Manages concurrency (p-limit)  │
+               │  - Manages state machine          │
+               └──────┬───────────────┬────────────┘
+                      │               │
+            ┌─────────▼───┐   ┌───────▼──────────┐
+            │  safeFetch  │   │    Subscribers    │
+            │  (init &    │   │  Initialize &     │
+            │  finalize)  │   │  Finalize Upload  │
+            └─────────────┘   └──────────────────┘
+```
+
+### Upload Lifecycle
+
+```
+IDLE → INITIALIZING → UPLOADING → FINALIZING → COMPLETED
+                ↓           ↓
+              FAILED      PAUSED ↔ UPLOADING
+                            ↓
+                         CANCELLED
+```
+
+### The Three-Endpoint Pattern
+
+Your server must expose **three endpoints**:
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `init` | POST | Creates an upload session, returns a `mediaId` |
+| `upload` | POST | Receives individual file chunks |
+| `finalize` | POST | Assembles chunks and finalizes the upload |
+
+---
+
+## API Reference
+
+### ChunkedFileUploader
+
+The main class. Implements `ChunkedFileUploaderInterface`.
+
+#### Constructor
+
+```typescript
+new ChunkedFileUploader(
+  uploadEventDispatcher: EventDispatcherInterface,
+  uploadResumeData: UploadResumeCacheInterface,
+  options: UploadOptions,
+  logger?: LoggerInterface
+)
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `uploadEventDispatcher` | `EventDispatcherInterface` | ✅ | Dispatcher for upload lifecycle events |
+| `uploadResumeData` | `UploadResumeCacheInterface` | ✅ | Cache implementation for resumable uploads |
+| `options` | `UploadOptions` | ✅ | Upload configuration options |
+| `logger` | `LoggerInterface` | ❌ | Custom logger (default: `NoopLogger`) |
+
+#### Methods
+
+##### `.withFile(file: File): this`
+
+Sets the file to upload. **Must be called before `.upload()`.**
+
+```typescript
+uploader.withFile(file);
+```
+
+| Throws | Condition |
+|--------|-----------|
+| `Error` | If `file` is null or undefined |
+| `Error` | If `file.size === 0` (empty file) |
+| `TypeError` | If value is not a `File` or `Blob` instance |
+
+---
+
+##### `.withEndpoints(endpoints: UploadEndpoints): this`
+
+Sets the server endpoints. **Must be called before `.upload()`.**
+
+```typescript
+uploader.withEndpoints({
+  init: 'https://api.example.com/upload/init',
+  upload: 'https://api.example.com/upload/chunk',
+  finalize: 'https://api.example.com/upload/finalize'
+});
+```
+
+| Throws | Condition |
+|--------|-----------|
+| `Error` | If any endpoint is missing |
+
+---
+
+##### `.upload(): Promise<void>`
+
+Starts the upload process. Internally:
+1. Hashes the file (SHA-256 of first 1MB)
+2. Dispatches `INITIALIZE_UPLOAD` → handled by `InitializeUploadSubscriber`
+3. Splits file into chunks and uploads them with concurrency control
+4. Dispatches `FINALIZE_UPLOAD` → handled by `FinalizeUploadSubscriber`
+
+```typescript
+await uploader
+  .withFile(file)
+  .withEndpoints(endpoints)
+  .upload();
+```
+
+| Throws | Condition |
+|--------|-----------|
+| `Error` | If `.withFile()` was not called |
+| `Error` | If `.withEndpoints()` was not called |
+| `InitializeUploadFailureException` | If the server init request fails |
+| `FileUploadChunkError` | If a chunk fails after all retries |
+
+---
+
+##### `.pause(): void`
+
+Pauses the upload. The current chunk finishes uploading before pausing.
+
+```typescript
+uploader.pause();
+```
+
+Dispatches: `HttpFileUploaderEvents.UPLOAD_PAUSED`
+
+---
+
+##### `.resume(): void`
+
+Resumes a paused upload.
+
+```typescript
+uploader.resume();
+```
+
+Dispatches: `HttpFileUploaderEvents.UPLOAD_RESUMED`
+
+---
+
+##### `.cancel(): void`
+
+Cancels the upload immediately using `AbortController`.
+
+```typescript
+uploader.cancel();
+```
+
+Dispatches: `HttpFileUploaderEvents.UPLOAD_CANCELLED`
+
+---
+
+##### `.getState(): UploadState`
+
+Returns the current state of the upload.
+
+```typescript
+const state = uploader.getState();
+// 'idle' | 'initializing' | 'uploading' | 'paused' | 'cancelled' | 'finalizing' | 'completed' | 'failed'
+```
+
+---
+
+##### `.resumeUpload(resumeData: ResumeData): Promise<void>`
+
+Resumes an upload from a saved state (after page refresh or network failure).
+
+```typescript
+const resumeData = await uploader.loadResumeData('my-video.mp4');
+
+if (resumeData) {
+  await uploader
+    .withFile(file)
+    .withEndpoints(endpoints)
+    .resumeUpload(resumeData);
+}
+```
+
+---
+
+##### `.loadResumeData(fileName: string): Promise<ResumeData | null>`
+
+Loads previously saved upload progress from the cache.
+
+```typescript
+const resumeData = await uploader.loadResumeData('my-video.mp4');
+
+if (resumeData) {
+  console.log(`${resumeData.uploadedChunks} chunks already uploaded`);
+}
+```
+
+---
+
+### HttpFileUploaderEvents
+
+Abstract class containing all event name constants.
+**This is the single source of truth for event names.**
+
+```typescript
+import { HttpFileUploaderEvents } from '@wlindabla/file_uploader';
+
+dispatcher.addListener(HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_SUCCESS, handler);
+```
+
+> See [All Available Events](#all-available-events) for the complete list.
+
+---
+
+### UploadOptions
+
+```typescript
+interface UploadOptions {
+  // Chunk configuration
+  chunkSize?: number;          // Chunk size in bytes (auto-calculated if not set)
+  speedMbps?: number;          // Connection speed hint for auto chunk size calculation
+  config?: ChunkSizeConfig;    // Custom chunk size thresholds
+
+  // Retry & concurrency
+  maxRetries?: number;         // Max retry attempts per chunk (default: 3)
+  concurrency?: number;        // Max parallel chunk uploads (default: 3)
+
+  // Timeouts
+  timeout?: number;            // Chunk upload timeout in ms (default: 60000)
+  initTimeout?: number;        // Init request timeout in ms (default: 45000)
+
+  // Headers
+  headers?: HeadersInit;                  // Headers for chunk upload requests
+  headerInitialzingUpload?: HeadersInit;  // Headers for init request
+  headerFinalezingUpload?: HeadersInit;   // Headers for finalize request
+
+  // Metadata
+  metadata?: Record<string, any>;         // Extra data sent to the init endpoint
+  chunkOtherData?: Record<string, any>;   // Extra data appended to each chunk FormData
+
+  // Resume
+  autoSave?: boolean;          // Auto-save progress after each chunk (default: false)
+}
+```
+
+#### Chunk Size Auto-Calculation
+
+When `chunkSize` is not provided, the library automatically calculates the optimal
+chunk size based on `fileSize` and the `config` thresholds:
+
+```typescript
+// Default thresholds (DEFAULT_CONFIG)
+{
+  defaultChunkSizeMB: 50,
+  slowSpeedThresholdMbps: 5,
+  slowSpeedChunkSizeMB: 2,
+  fileSizeThresholds: [
+    { maxSizeMB: 200,     chunkSizeMB: 50  },
+    { maxSizeMB: 400,     chunkSizeMB: 100 },
+    { maxSizeMB: 800,     chunkSizeMB: 300 },
+    { maxSizeMB: 1000,    chunkSizeMB: 500 },
+    { maxSizeMB: Infinity, chunkSizeMB: 700 }
+  ]
+}
+```
+
+---
+
+### UploadEndpoints
+
+```typescript
+interface UploadEndpoints {
+  init: string | URL;      // Upload session initialization endpoint
+  upload: string | URL;    // Chunk upload endpoint
+  finalize: string | URL;  // Upload finalization endpoint
+}
+```
+
+---
+
+### UploadResumeCacheInterface
+
+Your cache implementation **must** implement this interface.
+The library does **not** provide a default implementation to avoid
+unnecessary dependencies (localStorage, IndexedDB, Redis, filesystem, etc.).
+
+```typescript
+interface UploadResumeCacheInterface {
+  getItem(key: string): Promise<ResumeData | null>;
+  setItem(key: string, value: ResumeData): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+```
+
+#### Example Implementations
+
+##### Browser — localStorage
+
+```typescript
+class LocalStorageCache implements UploadResumeCacheInterface {
+  async getItem(key: string): Promise<ResumeData | null> {
+    const item = localStorage.getItem(key);
+    return item ? JSON.parse(item) : null;
+  }
+
+  async setItem(key: string, value: ResumeData): Promise<void> {
+    localStorage.setItem(key, JSON.stringify(value));
+  }
+
+  async removeItem(key: string): Promise<void> {
+    localStorage.removeItem(key);
+  }
+}
+```
+
+##### Browser — IndexedDB
+
+```typescript
+class IndexedDBCache implements UploadResumeCacheInterface {
+  private db: IDBDatabase | null = null;
+
+  private async openDB(): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open('file-uploader-cache', 1);
+      request.onupgradeneeded = () => {
+        request.result.createObjectStore('uploads');
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async getItem(key: string): Promise<ResumeData | null> {
+    const db = await this.openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction('uploads', 'readonly');
+      const request = tx.objectStore('uploads').get(key);
+      request.onsuccess = () => resolve(request.result ?? null);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async setItem(key: string, value: ResumeData): Promise<void> {
+    const db = await this.openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction('uploads', 'readwrite');
+      tx.objectStore('uploads').put(value, key);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+
+  async removeItem(key: string): Promise<void> {
+    const db = await this.openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction('uploads', 'readwrite');
+      tx.objectStore('uploads').delete(key);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+  }
+}
+```
+
+##### Node.js — Redis
+
+```typescript
+import { createClient } from 'redis';
+
+class RedisCache implements UploadResumeCacheInterface {
+  private client = createClient({ url: process.env.REDIS_URL });
+
+  constructor() {
+    this.client.connect();
+  }
+
+  async getItem(key: string): Promise<ResumeData | null> {
+    const item = await this.client.get(key);
+    return item ? JSON.parse(item) : null;
+  }
+
+  async setItem(key: string, value: ResumeData): Promise<void> {
+    // TTL: 24 hours
+    await this.client.set(key, JSON.stringify(value), { EX: 86400 });
+  }
+
+  async removeItem(key: string): Promise<void> {
+    await this.client.del(key);
+  }
+}
+```
+
+##### Node.js — Filesystem
+
+```typescript
+import fs from 'fs/promises';
+import path from 'path';
+
+class FileSystemCache implements UploadResumeCacheInterface {
+  constructor(private readonly cacheDir: string = '/tmp/upload-cache') {
+    fs.mkdir(cacheDir, { recursive: true }).catch(() => {});
+  }
+
+  private filePath(key: string): string {
+    return path.join(this.cacheDir, `${key}.json`);
+  }
+
+  async getItem(key: string): Promise<ResumeData | null> {
+    try {
+      const content = await fs.readFile(this.filePath(key), 'utf-8');
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+
+  async setItem(key: string, value: ResumeData): Promise<void> {
+    await fs.writeFile(this.filePath(key), JSON.stringify(value), 'utf-8');
+  }
+
+  async removeItem(key: string): Promise<void> {
+    await fs.unlink(this.filePath(key)).catch(() => {});
+  }
+}
+```
+
+## Events System
+
+### Event Architecture
+
+The library uses a **two-level event architecture**:
+
+```
+YOUR APPLICATION
+└── listens to Upload Events (public)
+       └── dispatched by ChunkedFileUploader
+              └── which internally handles HTTP events (private)
+```
+
+You **only need to interact with Upload Events** via `HttpFileUploaderEvents.*`.
+HTTP-level events are handled internally by the library's subscribers.
+
+### All Available Events
+
+#### Initialize Events
+
+| Constant | Value | Dispatched When |
+|----------|-------|-----------------|
+| `INITIALIZE_UPLOAD` | `"initializeUpload"` | Upload session is about to start (internal) |
+| `INITIALIZE_UPLOAD_STARTED` | `"initializeUploadStarted"` | Init HTTP request is sent |
+| `INITIALIZE_UPLOAD_SUCCESS` | `"initializeUploadSuccess"` | Server confirmed the session |
+| `INITIALIZE_UPLOAD_FAILURE` | `"initializeUploadFailure"` | Init request failed |
+
+#### Chunk Upload Events
+
+| Constant | Value | Dispatched When |
+|----------|-------|-----------------|
+| `MEDIA_CHUNK_UPLOAD_STARTED` | `"mediaChunkUploadStarted"` | A chunk is about to be uploaded |
+| `MEDIA_CHUNK_UPLOAD_SUCCESS` | `"mediaChunkUploadSuccess"` | A chunk was uploaded successfully |
+| `MEDIA_CHUNK_UPLOAD_FAILED` | `"mediaChunkUploadFailed"` | A chunk upload attempt failed |
+| `MEDIA_CHUNK_UPLOAD_HTTP_ERROR_RESPONSE` | `"mediaChunkUploadHttpErrorResponse"` | Server returned 4xx/5xx for a chunk |
+| `MEDIA_CHUNK_UPLOAD_STATUS` | `"mediaChunkUploadStatus"` | Chunk status update |
+| `MEDIA_CHUNK_UPLOAD_MAXRETRY_EXPIRE` | `"mediaChunkUploadMaxRetryExpire"` | All retry attempts exhausted |
+| `MEDIA_CHUNK_UPLOAD_RESUME` | `"mediaChunkUploadResume"` | Upload resumed from saved state |
+
+#### Upload State Events
+
+| Constant | Value | Dispatched When |
+|----------|-------|-----------------|
+| `UPLOAD_PAUSED` | `"uploadPaused"` | Upload was paused |
+| `UPLOAD_RESUMED` | `"uploadResumed"` | Upload was resumed after pause |
+| `UPLOAD_CANCELLED` | `"uploadCancelled"` | Upload was cancelled |
+| `UPLOAD_STATE_CHANGED` | `"uploadStateChanged"` | Any state transition occurs |
+
+#### Completion Events
+
+| Constant | Value | Dispatched When |
+|----------|-------|-----------------|
+| `FINALIZE_UPLOAD` | `"finalizeUpload"` | Finalize request is about to be sent (internal) |
+| `FINALIZE_UPLOAD_FAILURE` | `"finalizeUploadFailure"` | Finalize request failed |
+| `DOWNLOAD_MEDIA_COMPLETE` | `"downloadMediaComplete"` | Upload fully completed |
+| `DOWNLOAD_MEDIA_FAILURE` | `"downloadMediaFailure"` | Upload failed completely |
+| `DOWNLOAD_MEDIA_RESUME` | `"downloadMediaResume"` | Upload resumed from cache |
+
+#### Metadata Events
+
+| Constant | Value | Dispatched When |
+|----------|-------|-----------------|
+| `MEDIA_METADATA_SAVE_SUCCESS` | `"mediaMetadataSaveSuccess"` | Media metadata was saved |
+
+---
+
+### Event Classes Reference
+
+#### `UploadProgressEvent`
+
+Dispatched on `MEDIA_CHUNK_UPLOAD_SUCCESS`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_SUCCESS,
+  (event: UploadProgressEvent) => {
+    console.log(event.percentage);             // 0-100
+    console.log(event.uploadedChunks);         // number of chunks uploaded
+    console.log(event.totalChunks);            // total number of chunks
+    console.log(event.uploadedBytes);          // bytes uploaded so far
+    console.log(event.totalBytes);             // total file size in bytes
+    console.log(event.currentChunk);           // current chunk index
+    console.log(event.speed);                  // bytes per second (optional)
+    console.log(event.estimatedTimeRemaining); // seconds remaining (optional)
+    console.log(event.elapsed);               // seconds elapsed
+    console.log(event.responseData);           // raw server response data
+    console.log(event.httpStatus);             // HTTP status code
+  }
+);
+```
+
+---
+
+#### `UploadStateChangedEvent`
+
+Dispatched on `UPLOAD_STATE_CHANGED`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.UPLOAD_STATE_CHANGED,
+  (event: UploadStateChangedEvent) => {
+    console.log(event.oldState);   // Previous UploadState
+    console.log(event.newState);   // New UploadState
+    console.log(event.changedAt);  // Timestamp (Date.now())
+  }
+);
+```
+
+---
+
+#### `UploadMediaCompleteEvent`
+
+Dispatched on `DOWNLOAD_MEDIA_COMPLETE`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.DOWNLOAD_MEDIA_COMPLETE,
+  (event: UploadMediaCompleteEvent) => {
+    console.log(event.success);                    // boolean
+    console.log(event.mediaId);                    // string | number
+    console.log(event.totalBytes);                 // number
+    console.log(event.totalChunks);                // number
+    console.log(event.operationDuration);          // seconds
+    console.log(event.averageSpeed);               // bytes/second
+    console.log(event.finalizeUploadHttpResponse); // server response
+  }
+);
+```
+
+---
+
+#### `UploadCancelledEvent`
+
+Dispatched on `UPLOAD_CANCELLED`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.UPLOAD_CANCELLED,
+  (event: UploadCancelledEvent) => {
+    console.log(event.mediaName);        // file name
+    console.log(event.totalChunks);      // number
+    console.log(event.uploadedBytes);    // number
+    console.log(event.percentage);       // number
+    console.log(event.currentChunkIndex); // number
+    console.log(event.message);          // string
+    console.log(event.cancelledAt);      // timestamp
+  }
+);
+```
+
+---
+
+#### `UploadPausedEvent`
+
+Dispatched on `UPLOAD_PAUSED`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.UPLOAD_PAUSED,
+  (event: UploadPausedEvent) => {
+    console.log(event.mediaName);     // file name
+    console.log(event.totalChunks);   // number
+    console.log(event.uploadedBytes); // number
+    console.log(event.percentage);    // number
+    console.log(event.pausedAt);      // timestamp
+  }
+);
+```
+
+---
+
+#### `UploadResumedEvent`
+
+Dispatched on `UPLOAD_RESUMED`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.UPLOAD_RESUMED,
+  (event: UploadResumedEvent) => {
+    console.log(event.mediaName);     // file name
+    console.log(event.totalChunks);   // number
+    console.log(event.uploadedBytes); // number
+    console.log(event.percentage);    // number
+    console.log(event.resumedAt);     // timestamp
+  }
+);
+```
+
+---
+
+#### `ChunkUploadHttpErrorResponseEvent`
+
+Dispatched on `MEDIA_CHUNK_UPLOAD_HTTP_ERROR_RESPONSE`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_HTTP_ERROR_RESPONSE,
+  (event: ChunkUploadHttpErrorResponseEvent) => {
+    console.log(event.statusResponse); // 4xx or 5xx status code
+    console.log(event.errorPayload);   // server error body
+    console.log(event.urlEndpoint);    // endpoint URL
+    console.log(event.chunkIndex);     // which chunk failed
+    console.log(event.chunkInfo);      // full ChunkInfo object
+  }
+);
+```
+
+---
+
+#### `InitializeUploadStartedEvent`
+
+Dispatched on `INITIALIZE_UPLOAD_STARTED`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.INITIALIZE_UPLOAD_STARTED,
+  (event: InitializeUploadStartedEvent) => {
+    console.log(event.fileName); // string
+    console.log(event.fileSize); // number (bytes)
+    console.log(event.fileHash); // SHA-256 hex string
+  }
+);
+```
+
+---
+
+#### `InitializeUploadSuccessEvent`
+
+Dispatched on `INITIALIZE_UPLOAD_SUCCESS`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.INITIALIZE_UPLOAD_SUCCESS,
+  (event: InitializeUploadSuccessEvent) => {
+    console.log(event.status);       // HTTP status code
+    console.log(event.sessionId);    // server-assigned session/media ID
+    console.log(event.responseData); // full server response
+  }
+);
+```
+
+---
+
+#### `InitializeUploadFailureEvent`
+
+Dispatched on `INITIALIZE_UPLOAD_FAILURE`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.INITIALIZE_UPLOAD_FAILURE,
+  (event: InitializeUploadFailureEvent) => {
+    console.log(event.error);          // Error instance
+    console.log(event.status);         // HTTP status (optional)
+    console.log(event.errorData);      // raw error data (optional)
+    console.log(event.isNetworkError); // boolean (optional)
+  }
+);
+```
+
+---
+
+#### `ResumeUploadEvent`
+
+Dispatched on `MEDIA_CHUNK_UPLOAD_RESUME`.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_RESUME,
+  (event: ResumeUploadEvent) => {
+    console.log(event.mediaId);         // string | number
+    console.log(event.fileName);        // string
+    console.log(event.uploadedChunks);  // number
+    console.log(event.lastChunkIndex);  // number
+    console.log(event.lastBytePosition); // number
+    console.log(event.chunkSize);       // number
+    console.log(event.fileSize);        // number
+    console.log(event.message);         // info message
+  }
+);
+```
+
+---
+
+# Subscribers — Upload Lifecycle Handlers
+
+The library ships with two built-in **EventSubscribers** that handle the critical
+HTTP communication phases of the upload lifecycle:
+
+| Subscriber | Listens To | Responsibility |
+|------------|-----------|----------------|
+| `InitializeUploadSubscriber` | `HttpFileUploaderEvents.INITIALIZE_UPLOAD` | Opens an upload session with the server |
+| `FinalizeUploadSubscriber` | `HttpFileUploaderEvents.FINALIZE_UPLOAD` | Assembles chunks and closes the upload session |
+
+> These subscribers follow the **Symfony EventSubscriber pattern** via
+> `@wlindabla/event_dispatcher`. They must be **registered manually**
+> on your event dispatcher before calling `.upload()`.
+
+---
+
+## ⚠️ Important — You Must Register the Subscribers
+
+Unlike regular event listeners, subscribers are **not auto-registered**.
+You are responsible for adding them to your dispatcher instance.
+**If you forget to register them, the upload will fail silently.**
+
+---
+
+## Registration
+
+### Browser Environment
+
+```typescript
+import {
+  InitializeUploadSubscriber,
+  FinalizeUploadSubscriber
+} from '@wlindabla/file_uploader';
+
+import { BrowserEventDispatcher } from '@wlindabla/event_dispatcher';
+
+// BrowserEventDispatcher accepts: document, window, or new EventTarget()
+const dispatcher = new BrowserEventDispatcher(document);
+// or: new BrowserEventDispatcher(window)
+// or: new BrowserEventDispatcher(new EventTarget())
+
+// ✅ Register both subscribers BEFORE calling .upload()
+dispatcher.addSubscriber(new InitializeUploadSubscriber(dispatcher));
+dispatcher.addSubscriber(new FinalizeUploadSubscriber(dispatcher));
+```
+
+### Node.js Environment
+
+```typescript
+import {
+  InitializeUploadSubscriber,
+  FinalizeUploadSubscriber
+} from '@wlindabla/file_uploader';
+
+import { NodeEventDispatcher } from '@wlindabla/event_dispatcher';
+
+const dispatcher = new NodeEventDispatcher();
+
+// ✅ Register both subscribers BEFORE calling .upload()
+dispatcher.addSubscriber(new InitializeUploadSubscriber(dispatcher));
+dispatcher.addSubscriber(new FinalizeUploadSubscriber(dispatcher));
+```
+
+> **Note:** Both subscribers receive the **same dispatcher instance** as their
+> constructor argument. They use it internally to dispatch their own
+> success/failure events back to your application.
+
+---
+
+## Complete Setup Example
+
+### Browser
+
+```typescript
+import {
+  ChunkedFileUploader,
+  InitializeUploadSubscriber,
+  FinalizeUploadSubscriber,
+  HttpFileUploaderEvents,
+  InitializeUploadSuccessEvent,
+  InitializeUploadFailureEvent,
+  FinalizeUploadFailureEvent,
+  UploadMediaCompleteEvent
+} from '@wlindabla/file_uploader';
+
+import { BrowserEventDispatcher } from '@wlindabla/event_dispatcher';
+
+// 1. Create the dispatcher
+const dispatcher = new BrowserEventDispatcher(document);
+
+// 2. Register the subscribers ← MANDATORY
+dispatcher.addSubscriber(new InitializeUploadSubscriber(dispatcher));
+dispatcher.addSubscriber(new FinalizeUploadSubscriber(dispatcher));
+
+// 3. (Optional) Listen to events emitted BY the subscribers
+dispatcher.addListener(
+  HttpFileUploaderEvents.INITIALIZE_UPLOAD_STARTED,
+  () => console.log('⏳ Initializing upload session...')
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.INITIALIZE_UPLOAD_SUCCESS,
+  (event: InitializeUploadSuccessEvent) => {
+    console.log('✅ Session created. Media ID:', event.sessionId);
+  }
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.INITIALIZE_UPLOAD_FAILURE,
+  (event: InitializeUploadFailureEvent) => {
+    console.error('❌ Init failed:', event.error.message);
+  }
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.FINALIZE_UPLOAD_FAILURE,
+  (event: FinalizeUploadFailureEvent) => {
+    console.error('❌ Finalize failed:', event.error.message);
+  }
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.DOWNLOAD_MEDIA_COMPLETE,
+  (event: UploadMediaCompleteEvent) => {
+    console.log('🎉 Upload complete! Media ID:', event.mediaId);
+  }
+);
+
+// 4. Create and use the uploader
+const uploader = new ChunkedFileUploader(dispatcher, cache, options);
+
+await uploader
+  .withFile(file)
+  .withEndpoints(endpoints)
+  .upload();
+```
+
+---
+
+### Node.js
+
+```typescript
+import {
+  ChunkedFileUploader,
+  InitializeUploadSubscriber,
+  FinalizeUploadSubscriber,
+  HttpFileUploaderEvents,
+  InitializeUploadSuccessEvent,
+  FinalizeUploadFailureEvent
+} from '@wlindabla/file_uploader';
+
+import { NodeEventDispatcher } from '@wlindabla/event_dispatcher';
+
+// 1. Create the dispatcher
+const dispatcher = new NodeEventDispatcher();
+
+// 2. Register the subscribers ← MANDATORY
+dispatcher.addSubscriber(new InitializeUploadSubscriber(dispatcher));
+dispatcher.addSubscriber(new FinalizeUploadSubscriber(dispatcher));
+
+// 3. (Optional) Listen to events emitted BY the subscribers
+dispatcher.addListener(
+  HttpFileUploaderEvents.INITIALIZE_UPLOAD_SUCCESS,
+  (event: InitializeUploadSuccessEvent) => {
+    console.log('Session ID:', event.sessionId);
+  }
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.FINALIZE_UPLOAD_FAILURE,
+  (event: FinalizeUploadFailureEvent) => {
+    console.error('Finalize error:', event.error.message);
+  }
+);
+
+// 4. Create and use the uploader
+const uploader = new ChunkedFileUploader(dispatcher, cache, options);
+
+await uploader
+  .withFile(file)
+  .withEndpoints(endpoints)
+  .upload();
+```
+
+---
+
+## InitializeUploadSubscriber
+
+### What It Does Internally
+
+```
+INITIALIZE_UPLOAD event received
+        ↓
+Dispatch INITIALIZE_UPLOAD_STARTED
+        ↓
+POST → endpoints.init
+        ↓
+    ┌───┴────────────────────┐
+    │ response.failed?        │
+    │ YES → dispatch          │
+    │   INITIALIZE_UPLOAD_    │
+    │   FAILURE + throw       │
+    └───┬────────────────────┘
+        ↓
+Validate responseData structure
+        ↓
+Extract sessionId from response
+  (mediaId | mediaIdFromServer
+   | sessionId | uploadId)
+        ↓
+event.setMediaId(sessionId)
+        ↓
+Dispatch INITIALIZE_UPLOAD_SUCCESS
+```
+
+### Events It Dispatches
+
+| Event | When |
+|-------|------|
+| `INITIALIZE_UPLOAD_STARTED` | Before the HTTP request is sent |
+| `INITIALIZE_UPLOAD_SUCCESS` | Server returned a valid session ID |
+| `INITIALIZE_UPLOAD_FAILURE` | HTTP error, network error, or invalid response |
+
+### Retry Behavior
+
+The subscriber uses `safeFetch` internally with:
+
+```
+retryCount: 3
+retryOnStatusCode: true  ← Retries on 5xx errors
+timeout: 45000           ← 45 seconds
+```
+
+> 4xx errors (client errors) are **not retried** — they dispatch
+> `INITIALIZE_UPLOAD_FAILURE` immediately.
+
+### Error Cases Handled
+
+| Scenario | Behavior |
+|----------|----------|
+| HTTP 4xx from server | Dispatch `INITIALIZE_UPLOAD_FAILURE` + throw |
+| HTTP 5xx from server | Retry up to 3 times, then dispatch `INITIALIZE_UPLOAD_FAILURE` + throw |
+| Network error / Timeout | Dispatch `INITIALIZE_UPLOAD_FAILURE` + return silently |
+| Invalid response structure | Throw `InitializeUploadFailureException` |
+| Missing session ID in response | Throw `InitializeUploadFailureException` |
+
+---
+
+## FinalizeUploadSubscriber
+
+### What It Does Internally
+
+```
+FINALIZE_UPLOAD event received
+        ↓
+POST → endpoints.finalize
+  body: { mediaId, mediaHash }
+        ↓
+    ┌───┴──────────────────┐
+    │ HttpFetchError?       │
+    │ YES → dispatch        │
+    │  FINALIZE_UPLOAD_     │
+    │  FAILURE + return     │
+    └───┬──────────────────┘
+        ↓
+event.setResponse(response)
+(ChunkedFileUploader reads it
+ to build the UploadResult)
+```
+
+### Events It Dispatches
+
+| Event | When |
+|-------|------|
+| `FINALIZE_UPLOAD_FAILURE` | Network error or timeout during finalize |
+
+### Error Cases Handled
+
+| Scenario | Behavior |
+|----------|----------|
+| Network error / Timeout | Dispatch `FINALIZE_UPLOAD_FAILURE` + return silently |
+| Any other error | Re-thrown to `ChunkedFileUploader` |
+
+---
+
+## Subscriber Priority
+
+Both subscribers are registered with **priority 100**, which means they execute
+**before** any listeners you add manually at the default priority (0).
+
+```typescript
+// This returns:
+getSubscribedEvents() {
+  return {
+    [HttpFileUploaderEvents.INITIALIZE_UPLOAD]: {
+      listener: 'onInitializeUpload',
+      priority: 100  // ← Executes first
+    }
+  };
+}
+```
+
+> If you add your own listener on `INITIALIZE_UPLOAD` or `FINALIZE_UPLOAD`,
+> it will run **after** the subscriber has already handled the event,
+> unless you set a priority higher than 100.
+
+---
+
+## Common Mistakes
+
+### ❌ Forgetting to register subscribers
+
+```typescript
+const dispatcher = new BrowserEventDispatcher(document);
+
+// ❌ Missing addSubscriber() calls!
+
+const uploader = new ChunkedFileUploader(dispatcher, cache, options);
+await uploader.upload();
+// → Upload will hang or fail: no one handles INITIALIZE_UPLOAD
+```
+
+### ❌ Registering subscribers AFTER calling upload()
+
+```typescript
+const dispatcher = new BrowserEventDispatcher(document);
+
+uploader.upload(); // ← upload starts immediately
+
+// ❌ Too late! INITIALIZE_UPLOAD was already dispatched
+dispatcher.addSubscriber(new InitializeUploadSubscriber(dispatcher));
+```
+
+### ✅ Correct order
+
+```typescript
+const dispatcher = new BrowserEventDispatcher(document);
+
+// ✅ 1. Register subscribers first
+dispatcher.addSubscriber(new InitializeUploadSubscriber(dispatcher));
+dispatcher.addSubscriber(new FinalizeUploadSubscriber(dispatcher));
+
+// ✅ 2. Add your own listeners
+dispatcher.addListener(HttpFileUploaderEvents.DOWNLOAD_MEDIA_COMPLETE, handler);
+
+// ✅ 3. Then upload
+await uploader.withFile(file).withEndpoints(endpoints).upload();
+```
+
+## Subscribers
+
+The library uses two internal `EventSubscriberInterface` implementations.
+You do **not** need to instantiate them manually — `ChunkedFileUploader` does it
+automatically. However, you can **extend** them if needed.
+
+### InitializeUploadSubscriber
+
+Handles the `INITIALIZE_UPLOAD` event internally.
+
+**What it does:**
+1. Sends a POST request to `endpoints.init` using `safeFetch`
+2. Validates the server response
+3. Extracts the `mediaId`/`sessionId`/`uploadId` from the response
+4. Dispatches `INITIALIZE_UPLOAD_STARTED`, `INITIALIZE_UPLOAD_SUCCESS`,
+   or `INITIALIZE_UPLOAD_FAILURE`
+
+**Expected server response** (any of these keys is accepted):
+
+```json
+{
+  "mediaId": "abc-123",
+  "message": "Upload session created"
+}
+```
+
+or
+
+```json
+{ "sessionId": "abc-123" }
+```
+
+or
+
+```json
+{ "uploadId": "abc-123" }
+```
+
+or
+
+```json
+{ "mediaIdFromServer": "abc-123" }
+```
+
+---
+
+### FinalizeUploadSubscriber
+
+Handles the `FINALIZE_UPLOAD` event internally.
+
+**What it does:**
+1. Sends a POST request to `endpoints.finalize` using `safeFetch`
+2. Passes `{ mediaId, mediaHash }` in the request body
+3. Dispatches `FINALIZE_UPLOAD_FAILURE` on error
+
+**Request body sent to finalize endpoint:**
+
+```json
+{
+  "mediaId": "abc-123",
+  "mediaHash": "sha256hexstring..."
+}
+```
+
+---
+
+## Types Reference
+
+### `UploadState` (enum)
+
+```typescript
+enum UploadState {
+  IDLE        = 'idle',
+  INITIALIZING = 'initializing',
+  UPLOADING   = 'uploading',
+  PAUSED      = 'paused',
+  CANCELLED   = 'cancelled',
+  FINALIZING  = 'finalizing',
+  COMPLETED   = 'completed',
+  FAILED      = 'failed'
+}
+```
+
+---
+
+### `ChunkInfo`
+
+```typescript
+interface ChunkInfo {
+  index: number;          // Zero-based chunk index
+  start: number;          // Start byte position in file
+  end: number;            // End byte position in file
+  size: number;           // Chunk size in bytes
+  attempt: number;        // Current attempt number
+  status: UploadStatus;   // 'pending' | 'uploading' | 'success' | 'error'
+}
+```
+
+---
+
+### `UploadProgress`
+
+```typescript
+interface UploadProgress {
+  uploadedChunks: number;
+  totalChunks: number;
+  uploadedBytes: number;
+  totalBytes: number;
+  percentage: number;                    // 0-100
+  currentChunk: number;
+  speed?: number;                        // bytes per second
+  estimatedTimeRemaining?: number | null; // seconds
+  elapsed: number;                       // seconds elapsed
+}
+```
+
+---
+
+### `ResumeData`
+
+```typescript
+interface ResumeData {
+  fileId: string;
+  fileName: string;
+  fileSize: number;
+  uploadedChunks: number;
+  lastChunkIndex: number;
+  lastBytePosition: number;
+  chunkSize: number;
+  concurrency: number;
+}
+```
+
+---
+
+### `UploadResult`
+
+```typescript
+interface UploadResult {
+  success: boolean;
+  fileId?: string;
+  totalChunks: number;
+  totalBytes: number;
+  duration: number;                           // seconds
+  averageSpeed: number;                       // bytes per second
+  finalizeUploadResponse?: FetchResponseInterface | null;
+  statusResponse?: number;
+}
+```
+
+---
+
+### `ChunkError`
+
+```typescript
+interface ChunkError {
+  chunk: ChunkInfo;
+  error: Error;
+  attempt: number;
+  willRetry: boolean;
+}
+```
+
+---
+
+### `InitializeUploadResponse`
+
+Your server's init endpoint must return an object with **at least one** of these keys:
+
+```typescript
+interface InitializeUploadResponse {
+  mediaId?: string | number;
+  mediaIdFromServer?: string | number;
+  sessionId?: string | number;
+  uploadId?: string | number;
+  message?: string;
+  [key: string]: any; // Additional fields are allowed
+}
+```
+
+---
+
+## Exceptions
+
+### `InitializeUploadFailureException`
+
+Thrown when the server init request fails or returns an invalid response.
+
+```typescript
+try {
+  await uploader.upload();
+} catch (error) {
+  if (error instanceof InitializeUploadFailureException) {
+    console.log(error.message);       // Error description
+    console.log(error.responseData);  // Raw server response
+  }
+}
+```
+
+---
+
+### `FileUploadChunkError`
+
+Thrown when a chunk fails after all retry attempts.
+
+```typescript
+try {
+  await uploader.upload();
+} catch (error) {
+  if (error instanceof FileUploadChunkError) {
+    console.log(error.message);          // "Failed to upload chunk X after N attempts"
+    console.log(error.chunkIndex);       // Which chunk failed (0-based)
+    console.log(error.attemptNumber);    // How many attempts were made
+    console.log(error.willRetry);        // false (max retries exhausted)
+    console.log(error.underlyingError);  // Original error
+    console.log(error.chunk);            // Full ChunkInfo object
+    console.log(error.toJSON());         // JSON representation
+  }
+}
+```
+
+---
+
+### `ChunkUploadHttpErrorException`
+
+Thrown internally when the server returns a 4xx/5xx response for a chunk.
+You can catch it via the `MEDIA_CHUNK_UPLOAD_HTTP_ERROR_RESPONSE` event.
+
+```typescript
+dispatcher.addListener(
+  HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_HTTP_ERROR_RESPONSE,
+  (event: ChunkUploadHttpErrorResponseEvent) => {
+    console.log(event.statusResponse); // e.g. 413 (Payload Too Large)
+    console.log(event.errorPayload);   // server error body
+  }
+);
+```
+
+---
+
+### `UploadCancelledException`
+
+Thrown when an upload is cancelled via `.cancel()`.
+
+```typescript
+try {
+  await uploader.upload();
+} catch (error) {
+  if (error instanceof UploadCancelledException) {
+    console.log(error.chunkIndex);    // Which chunk was being uploaded
+    console.log(error.totalChunks);   // Total number of chunks
+    console.log(error.uploadedBytes); // How many bytes were uploaded
+  }
+}
+```
+
+---
+
+## Advanced Usage
+
+### Concurrency Control
+
+Control how many chunks are uploaded in parallel.
+
+```typescript
+// Conservative: 1 chunk at a time (slow connections, mobile)
+new ChunkedFileUploader(dispatcher, cache, { concurrency: 1 });
+
+// Balanced: 3 chunks in parallel (default, recommended)
+new ChunkedFileUploader(dispatcher, cache, { concurrency: 3 });
+
+// Aggressive: 5 chunks in parallel (fast connections)
+new ChunkedFileUploader(dispatcher, cache, { concurrency: 5 });
+```
+
+**Concurrency visual:**
+
+```
+concurrency = 3
+
+Time  → → → → → →
+Chunk 0: [████████]
+Chunk 1: [████████]   ← 3 chunks in parallel
+Chunk 2: [████████]
+                  ↓ batch complete
+Chunk 3: [████████]
+Chunk 4: [████████]   ← next batch
+Chunk 5: [████████]
+```
+
+> **Note:** Values higher than 5 are not recommended as they may trigger
+> server-side rate limiting or browser connection limits.
+
+---
+
+### Pause and Resume
+
+```typescript
+const uploader = new ChunkedFileUploader(dispatcher, cache, options);
+
+// Start upload
+uploader.withFile(file).withEndpoints(endpoints);
+uploader.upload(); // Don't await here if you want to control it
+
+// Pause after 2 seconds
+setTimeout(() => {
+  uploader.pause();
+  console.log('Upload paused. State:', uploader.getState()); // 'paused'
+}, 2000);
+
+// Resume after 5 seconds
+setTimeout(() => {
+  uploader.resume();
+  console.log('Upload resumed. State:', uploader.getState()); // 'uploading'
+}, 5000);
+```
+
+---
+
+### Cancel Upload
+
+```typescript
+const uploader = new ChunkedFileUploader(dispatcher, cache, options);
+
+// Listen for cancellation
+dispatcher.addListener(
+  HttpFileUploaderEvents.UPLOAD_CANCELLED,
+  (event: UploadCancelledEvent) => {
+    console.log(`Upload of "${event.mediaName}" was cancelled`);
+    console.log(`${event.percentage}% was completed`);
+  }
+);
+
+// Start upload (fire and forget)
+uploader.withFile(file).withEndpoints(endpoints).upload().catch(() => {});
+
+// Cancel after 3 seconds
+setTimeout(() => {
+  uploader.cancel();
+}, 3000);
+```
+
+---
+
+### Resumable Upload
+
+Enable upload resumption after page refresh or network failure.
+
+```typescript
+// Step 1: Enable auto-save during upload
+const uploader = new ChunkedFileUploader(
+  dispatcher,
+  new IndexedDBCache(),
+  {
+    autoSave: true,    // ← Save progress after each chunk
+    concurrency: 3
+  }
+);
+
+// Step 2: On page load, check for saved progress
+async function startOrResumeUpload(file: File) {
+  const resumeData = await uploader.loadResumeData(file.name);
+
+  uploader.withFile(file).withEndpoints(endpoints);
+
+  if (resumeData) {
+    const confirmed = confirm(
+      `Resume upload from ${resumeData.uploadedChunks} chunks? ` +
+      `(${Math.round(resumeData.lastBytePosition / 1024 / 1024)}MB already uploaded)`
+    );
+
+    if (confirmed) {
+      // Resume from where we left off
+      await uploader.resumeUpload(resumeData);
+      return;
+    }
+  }
+
+  // Start fresh
+  await uploader.upload();
+}
+```
+
+---
+
+### Custom Logger
+
+```typescript
+import { LoggerInterface } from '@wlindabla/file_uploader';
+
+// Example: Send logs to a monitoring service
+class MonitoringLogger implements LoggerInterface {
+  info(message: string, ...args: any[]) {
+    myMonitoringService.track('info', message, args);
+  }
+  warn(message: string, ...args: any[]) {
+    myMonitoringService.track('warn', message, args);
+  }
+  error(message: string, ...args: any[]) {
+    myMonitoringService.track('error', message, args);
+    alertOnCallTeam(message);
+  }
+  debug(message: string, ...args: any[]) {
+    if (process.env.DEBUG) {
+      console.debug('[FileUploader]', message, ...args);
+    }
+  }
+}
+
+const uploader = new ChunkedFileUploader(
+  dispatcher,
+  cache,
+  options,
+  new MonitoringLogger()
+);
+```
+
+---
+
+### Custom Cache Implementation
+
+Implement `UploadResumeCacheInterface` with any storage backend you prefer.
+See [UploadResumeCacheInterface](#uploadresumecacheinterface) for ready-to-use examples.
+
+---
+
+## Environment-Specific Examples
+
+### Browser Example
+
+Complete browser example with progress bar and UI controls.
+
+```typescript
+import {
+  ChunkedFileUploader,
+  HttpFileUploaderEvents,
+  UploadProgressEvent,
+  UploadStateChangedEvent,
+  UploadMediaCompleteEvent,
+  UploadCancelledEvent,
+  ConsoleLogger
+} from '@wlindabla/file_uploader';
+
+import { BrowserEventDispatcher } from '@wlindabla/event_dispatcher';
+
+// Cache
+class LocalStorageCache {
+  async getItem(key: string) {
+    const v = localStorage.getItem(key);
+    return v ? JSON.parse(v) : null;
+  }
+  async setItem(key: string, value: any) {
+    localStorage.setItem(key, JSON.stringify(value));
+  }
+  async removeItem(key: string) {
+    localStorage.removeItem(key);
+  }
+}
+
+// Setup
+const dispatcher = new BrowserEventDispatcher();
+
+// Progress bar
+dispatcher.addListener(
+  HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_SUCCESS,
+  (event: UploadProgressEvent) => {
+    const bar = document.getElementById('progress-bar') as HTMLElement;
+    const label = document.getElementById('progress-label') as HTMLElement;
+    const speed = document.getElementById('speed') as HTMLElement;
+
+    bar.style.width = `${event.percentage}%`;
+    label.textContent = `${event.percentage}%`;
+
+    if (event.speed) {
+      const mbps = (event.speed / 1024 / 1024).toFixed(2);
+      speed.textContent = `${mbps} MB/s`;
+    }
+
+    if (event.estimatedTimeRemaining) {
+      const eta = document.getElementById('eta') as HTMLElement;
+      eta.textContent = `${Math.ceil(event.estimatedTimeRemaining)}s remaining`;
+    }
+  }
+);
+
+// State changes
+dispatcher.addListener(
+  HttpFileUploaderEvents.UPLOAD_STATE_CHANGED,
+  (event: UploadStateChangedEvent) => {
+    const status = document.getElementById('status') as HTMLElement;
+    status.textContent = event.newState.toUpperCase();
+  }
+);
+
+// Completion
+dispatcher.addListener(
+  HttpFileUploaderEvents.DOWNLOAD_MEDIA_COMPLETE,
+  (event: UploadMediaCompleteEvent) => {
+    const duration = event.operationDuration.toFixed(1);
+    alert(`✅ Upload complete in ${duration}s! Media ID: ${event.mediaId}`);
+  }
+);
+
+// Error
+dispatcher.addListener(
+  HttpFileUploaderEvents.DOWNLOAD_MEDIA_FAILURE,
+  (error: Error) => {
+    alert(`❌ Upload failed: ${error.message}`);
+  }
+);
+
+// Uploader instance
+const uploader = new ChunkedFileUploader(
+  dispatcher,
+  new LocalStorageCache(),
+  {
+    concurrency: 3,
+    maxRetries: 3,
+    autoSave: true,
+    timeout: 60000
+  },
+  new ConsoleLogger()
+);
+
+// Wire up DOM
+document.getElementById('upload-btn')?.addEventListener('click', async () => {
+  const fileInput = document.getElementById('file-input') as HTMLInputElement;
+  const file = fileInput.files?.[0];
+
+  if (!file) return alert('Please select a file');
+
+  uploader
+    .withFile(file)
+    .withEndpoints({
+      init: '/api/upload/init',
+      upload: '/api/upload/chunk',
+      finalize: '/api/upload/finalize'
+    });
+
+  try {
+    await uploader.upload();
+  } catch (error) {
+    console.error('Upload failed:', error);
+  }
+});
+
+document.getElementById('pause-btn')?.addEventListener('click', () => uploader.pause());
+document.getElementById('resume-btn')?.addEventListener('click', () => uploader.resume());
+document.getElementById('cancel-btn')?.addEventListener('click', () => uploader.cancel());
+```
+
+---
+
+### Node.js Example
+
+Server-to-server file transfer.
+
+```typescript
+import {
+  ChunkedFileUploader,
+  HttpFileUploaderEvents,
+  UploadProgressEvent,
+  UploadMediaCompleteEvent,
+  ConsoleLogger
+} from '@wlindabla/file_uploader';
+
+import { NodeEventDispatcher } from '@wlindabla/event_dispatcher';
+import fs from 'fs';
+
+// Node.js File-like object
+function createFileFromPath(filePath: string): File {
+  const buffer = fs.readFileSync(filePath);
+  const blob = new Blob([buffer]);
+  return new File([blob], path.basename(filePath));
+}
+
+// Setup
+const dispatcher = new NodeEventDispatcher();
+
+// Track progress
+dispatcher.addListener(
+  HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_SUCCESS,
+  (event: UploadProgressEvent) => {
+    process.stdout.write(`\r⬆️  ${event.percentage}% uploaded...`);
+  }
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.DOWNLOAD_MEDIA_COMPLETE,
+  (event: UploadMediaCompleteEvent) => {
+    console.log(`\n✅ Done! Media ID: ${event.mediaId}`);
+    console.log(`   Duration: ${event.operationDuration.toFixed(1)}s`);
+    console.log(`   Average speed: ${(event.averageSpeed / 1024 / 1024).toFixed(2)} MB/s`);
+  }
+);
+
+// File system cache for Node.js
+class FileSystemCache {
+  async getItem(key: string) {
+    try {
+      const data = fs.readFileSync(`/tmp/${key}.json`, 'utf-8');
+      return JSON.parse(data);
+    } catch { return null; }
+  }
+  async setItem(key: string, value: any) {
+    fs.writeFileSync(`/tmp/${key}.json`, JSON.stringify(value));
+  }
+  async removeItem(key: string) {
+    try { fs.unlinkSync(`/tmp/${key}.json`); } catch {}
+  }
+}
+
+// Upload
+async function uploadFile(filePath: string) {
+  const file = createFileFromPath(filePath);
+  
+  const uploader = new ChunkedFileUploader(
+    dispatcher,
+    new FileSystemCache(),
+    {
+      concurrency: 5,
+      maxRetries: 3,
+      autoSave: true,
+      headers: {
+        'Authorization': `Bearer ${process.env.API_TOKEN}`,
+        'X-Server-ID': process.env.SERVER_ID ?? 'unknown'
+      }
+    }
+  );
+
+  await uploader
+    .withFile(file)
+    .withEndpoints({
+      init: 'https://api.example.com/upload/init',
+      upload: 'https://api.example.com/upload/chunk',
+      finalize: 'https://api.example.com/upload/finalize'
+    })
+    .upload();
+}
+
+uploadFile('/path/to/large-video.mp4').catch(console.error);
+```
+
+---
+
+## Server-Side Integration Guide
+
+### Init Endpoint
+
+**Request received:**
+
+```json
+{
+  "fileName": "video.mp4",
+  "fileSize": 1073741824,
+  "fileType": "video/mp4",
+  "fileHash": "a3f5b9c...",
+  "metadata": { "userId": "42", "albumId": "5" }
+}
+```
+
+**Expected response (HTTP 200/201):**
+
+```json
+{
+  "mediaId": "upload-session-abc-123",
+  "message": "Upload session created"
+}
+```
+
+---
+
+### Chunk Upload Endpoint
+
+**FormData fields received per chunk:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `chunk` | `Blob` | The binary chunk data |
+| `chunkIndex` | `string` | Zero-based chunk index |
+| `chunkSize` | `string` | Chunk size in bytes |
+| `totalChunks` | `string` | Total number of chunks |
+| `fileName` | `string` | Original file name |
+| `fileSize` | `string` | Total file size in bytes |
+| `fileHash` | `string` | SHA-256 hash of the file |
+| `mediaId` | `string` | Session ID from init |
+
+**Expected response (HTTP 200):**
+
+```json
+{
+  "chunkIndex": 5,
+  "received": true,
+  "message": "Chunk received"
+}
+```
+
+---
+
+### Finalize Endpoint
+
+**Request received:**
+
+```json
+{
+  "mediaId": "upload-session-abc-123",
+  "mediaHash": "a3f5b9c..."
+}
+```
+
+**Expected response (HTTP 200):**
+
+```json
+{
+  "success": true,
+  "fileUrl": "https://cdn.example.com/videos/video.mp4",
+  "mediaId": "upload-session-abc-123"
+}
+```
+
+---
+
+## Error Handling
+
+### Complete Error Handling Example
+
+```typescript
+import {
+  ChunkedFileUploader,
+  HttpFileUploaderEvents,
+  InitializeUploadFailureEvent,
+  FileUploadChunkError,
+  InitializeUploadFailureException,
+  UploadCancelledException
+} from '@wlindabla/file_uploader';
+
+// Listen to granular error events
+dispatcher.addListener(
+  HttpFileUploaderEvents.INITIALIZE_UPLOAD_FAILURE,
+  (event: InitializeUploadFailureEvent) => {
+    console.error('Init failed:', event.error.message);
+    if (event.status === 401) {
+      // Redirect to login
+    }
+  }
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_HTTP_ERROR_RESPONSE,
+  (event: ChunkUploadHttpErrorResponseEvent) => {
+    console.warn(
+      `Chunk ${event.chunkIndex} got HTTP ${event.statusResponse}`,
+      event.errorPayload
+    );
+  }
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.MEDIA_CHUNK_UPLOAD_MAXRETRY_EXPIRE,
+  (error: FileUploadChunkError) => {
+    console.error(
+      `Chunk ${error.chunkIndex} permanently failed after ${error.attemptNumber} attempts`
+    );
+  }
+);
+
+dispatcher.addListener(
+  HttpFileUploaderEvents.DOWNLOAD_MEDIA_FAILURE,
+  (error: Error) => {
+    console.error('Upload completely failed:', error.message);
+  }
+);
+
+// Handle thrown exceptions
+try {
+  await uploader.upload();
+} catch (error) {
+  if (error instanceof UploadCancelledException) {
+    console.log('User cancelled the upload');
+
+  } else if (error instanceof InitializeUploadFailureException) {
+    console.error('Could not start upload session:', error.message);
+
+  } else if (error instanceof FileUploadChunkError) {
+    console.error(`Chunk ${error.chunkIndex} failed:`, error.message);
+    console.error('Underlying cause:', error.underlyingError.message);
+
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository: [github.com/Agbokoudjo/file_uploader](https://github.com/Agbokoudjo/file_uploader)
+2. Create your feature branch: `git checkout -b feature/my-feature`
+3. Commit your changes: `git commit -m 'feat: add my feature'`
+4. Push to the branch: `git push origin feature/my-feature`
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+git clone https://github.com/Agbokoudjo/file_uploader.git
+cd file_uploader
+yarn install
+yarn build
+yarn test
+```
+
+### Running Tests
+
+```bash
+yarn test             # Run all tests
+yarn test:watch       # Watch mode
+yarn test:coverage    # With coverage report
+yarn test:ui          # Vitest UI
+```
+
+---
+
+## License
+
+MIT © [AGBOKOUDJO Franck — INTERNATIONALES WEB APPS & SERVICES](https://github.com/Agbokoudjo)
+
+---
+
+## Support
+
+- 📧 Email: [internationaleswebservices@gmail.com](mailto:internationaleswebservices@gmail.com)
+- 🐛 Issues: [GitHub Issues](https://github.com/Agbokoudjo/file_uploader/issues)
+- 💼 LinkedIn: [INTERNATIONALES WEB APPS & SERVICES](https://www.linkedin.com/in/internationales-web-apps-services-120520193/)
+- 📞 Phone: +229 0167 25 18 86
+
+---
+
+**Built with ❤️ by AGBOKOUDJO Franck — INTERNATIONALES WEB APPS & SERVICES**