@kesha-antonov/react-native-background-downloader 4.4.0 → 4.4.4

package/README.md

@@ -1,141 +1,99 @@
-
 <p align="center">
   <img width="300" src="https://github.com/user-attachments/assets/25e89808-9eb7-42b2-8031-b48d8c24796c" />
 </p>
 
-[![npm version](https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader.svg)](https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader)
-
-## 🎉 Version 4.0.0 Released!
-
-**v4.0.0** is now available with full **React Native New Architecture (TurboModules)** support!
-
-### What's New
-- ✅ Full TurboModules support for iOS and Android
-- ✅ Expo Config Plugin for automatic iOS setup
-- ✅ Android code converted to Kotlin
-- ✅ Full TypeScript support
-- ✅ New `progressMinBytes` option for hybrid progress reporting
-- ✅ `maxRedirects` option for Android
-
-### Upgrading from v3.x?
-📖 See the [Migration Guide](./MIGRATION.md) for detailed upgrade instructions and breaking changes.
-
-📋 See the [Changelog](./CHANGELOG.md) for the full list of changes.
-
-### Looking for v3.2.6?
-If you need the previous stable version: [3.2.6 readme](https://github.com/kesha-antonov/react-native-background-downloader/blob/8f4b8a844a2d7f00d1558f6ea65bac94c8dd6fc9/README.md)
-
-# @kesha-antonov/react-native-background-downloader
-
-A library for React-Native to help you download and upload large files on iOS and Android both in the foreground and most importantly in the background.
-
-### Why?
+<p align="center">
+  <a href="https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader"><img src="https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@kesha-antonov/react-native-background-downloader"><img src="https://img.shields.io/npm/dm/@kesha-antonov/react-native-background-downloader.svg" alt="npm downloads"></a>
+  <a href="https://github.com/kesha-antonov/react-native-background-downloader/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="license"></a>
+  <img src="https://img.shields.io/badge/platforms-iOS%20%7C%20Android-lightgrey.svg" alt="platforms">
+  <img src="https://img.shields.io/badge/TypeScript-supported-blue.svg" alt="TypeScript">
+  <img src="https://img.shields.io/badge/Expo-compatible-000020.svg" alt="Expo compatible">
+  <img src="https://img.shields.io/badge/New%20Architecture-supported-green.svg" alt="New Architecture">
+</p>
 
-On iOS, if you want to download big files no matter the state of your app, wether it's in the background or terminated by the OS, you have to use a system API called `NSURLSession`.
+# React Native Background Downloader
 
-This API handles your downloads separately from your app and only keeps it informed using delegates (Read: [Downloading Files in the Background](https://developer.apple.com/documentation/foundation/url_loading_system/downloading_files_in_the_background)).
+Download and upload large files on iOS & Android — even when your app is in the background or terminated.
 
-On Android we are using similar process with [DownloadManager](https://developer.android.com/reference/android/app/DownloadManager)
+## ✨ Features
 
-The real challenge of using this method is making sure the app's UI is always up-to-date with the downloads that are happening in another process because your app might startup from scratch while the downloads are still running.
+- 📥 **Background Downloads** - Downloads continue even when app is in background or terminated
+- 📤 **Background Uploads** - Upload files reliably in the background
+- ⏸️ **Pause/Resume** - Full pause and resume support on both iOS and Android
+- 🔄 **Re-attach to Downloads** - Reconnect to ongoing downloads after app restart
+- 📊 **Progress Tracking** - Real-time progress updates with customizable intervals
+- 🔒 **Custom Headers** - Support for authentication and custom request headers
+- 📱 **Expo Support** - Config plugin for easy Expo integration
+- ⚡ **New Architecture** - Full TurboModules support for React Native
+- 📝 **TypeScript** - Complete TypeScript definitions included
 
-`@kesha-antonov/react-native-background-downloader` gives you an easy API to both downloading large files and re-attaching to those downloads once your app launches again.
+## Why?
 
-## ToC
+**The Problem:** Standard network requests in React Native are tied to your app's lifecycle. When the user switches to another app or the OS terminates your app to free memory, your downloads stop. For small files this is fine, but for large files (videos, podcasts, documents) this creates a frustrating user experience.
 
-- [Getting started](#getting-started)
-- [Usage](#usage)
-  - [Downloading](#downloading-a-file)
-  - [Uploading](#uploading-a-file)
-- [API](#api)
-- [Constants](#constants)
+**The Solution:** Both iOS and Android provide system-level APIs for background file transfers:
+- **iOS:** [`NSURLSession`](https://developer.apple.com/documentation/foundation/url_loading_system/downloading_files_in_the_background) - handles downloads in a separate process, continuing even after your app is terminated
+- **Android:** A combination of [`DownloadManager`](https://developer.android.com/reference/android/app/DownloadManager) for system-managed downloads, [Foreground Services](https://developer.android.com/develop/background-work/services/foreground-services) for pause/resume support, and [MMKV](https://github.com/Tencent/MMKV) for persistent state storage
 
-## Getting started
+**The Challenge:** These APIs are powerful but complex. Downloads run in a separate process, so your app might restart from scratch while downloads are still in progress. Keeping your UI in sync with background downloads requires careful state management.
 
-### Installation
+**This Library:** `@kesha-antonov/react-native-background-downloader` wraps these native APIs in a simple, unified JavaScript interface. Start a download, close your app, reopen it hours later, and seamlessly reconnect to your ongoing downloads with a single function call.
 
-```Terminal
-yarn add @kesha-antonov/react-native-background-downloader
-```
+## Table of Contents
 
-or
-```Terminal
-npm i @kesha-antonov/react-native-background-downloader
-```
+- [React Native Background Downloader](#react-native-background-downloader)
+  - [✨ Features](#-features)
+  - [Why?](#why)
+  - [Table of Contents](#table-of-contents)
+  - [Requirements](#requirements)
+  - [Installation](#installation)
+    - [Expo Projects](#expo-projects)
+    - [Bare React Native Projects](#bare-react-native-projects)
+  - [Usage](#usage)
+    - [Downloading a file](#downloading-a-file)
+    - [Re-Attaching to background tasks](#re-attaching-to-background-tasks)
+  - [Advanced Configuration](#advanced-configuration)
+      - [Max Parallel Downloads (iOS only)](#max-parallel-downloads-ios-only)
+      - [Cellular/WiFi Restrictions](#cellularwifi-restrictions)
+  - [API](#api)
+    - [Quick Reference](#quick-reference)
+  - [Platform Notes](#platform-notes)
+  - [Troubleshooting](#troubleshooting)
+  - [Example App](#example-app)
+  - [Use Cases](#use-cases)
+  - [Migration Guide](#migration-guide)
+  - [Contributing](#contributing)
+    - [Development Setup](#development-setup)
+  - [Authors](#authors)
+  - [License](#license)
 
-Then:
+## Requirements
 
-```Terminal
-cd ios && pod install
-```
+| Requirement | Version |
+|-------------|--------|
+| React Native | >= 0.70.0 |
+| iOS | >= 15.1 |
+| Android | API 24+ (Android 7.0) |
+| Expo | SDK 50+ (with config plugin) |
 
-<details>
-<summary>Manual Setup (Advanced)</summary>
+> **Note:** For older React Native versions (0.57.0 - 0.69.x), use version 2.x of this library.
 
-If you need to manually configure the package for New Architecture:
+## Installation
 
-**iOS**: The library automatically detects New Architecture via compile-time flags.
+### Expo Projects
 
-**Android**: For New Architecture, you can optionally use `RNBackgroundDownloaderTurboPackage` instead of the default package:
-```java
-import com.eko.RNBackgroundDownloaderTurboPackage;
+**Step 1:** Install the package
 
-// In your MainApplication.java
-@Override
-protected List<ReactPackage> getPackages() {
-  return Arrays.<ReactPackage>asList(
-    // ... other packages
-    new RNBackgroundDownloaderTurboPackage() // For New Architecture
-  );
-}
+```bash
+npx expo install @kesha-antonov/react-native-background-downloader
 ```
-</details>
-
-### Mostly automatic installation
-Any React Native version **`>= 0.60`** supports autolinking so nothing should be done.
-
-For anything **`< 0.60`** run the following link command
-
-`$ react-native link @kesha-antonov/react-native-background-downloader`
-
-### Manual installation
-
-<details>
 
-#### iOS
-
-1. In XCode, in the project navigator, right click `Libraries` ➜ `Add Files to [your project's name]`
-2. Go to `node_modules` ➜ `@kesha-antonov/react-native-background-downloader` and add `RNBackgroundDownloader.xcodeproj`
-3. In XCode, in the project navigator, select your project. Add `libRNBackgroundDownloader.a` to your project's `Build Phases` ➜ `Link Binary With Libraries`
-4. Run your project (`Cmd+R`)
-
-#### Android
-
-1. Open up `android/app/src/main/java/[...]/MainActivity.java`
-  - Add `import com.eko.RNBackgroundDownloaderPackage;` to the imports at the top of the file
-  - Add `new RNBackgroundDownloaderPackage()` to the list returned by the `getPackages()` method
-2. Append the following lines to `android/settings.gradle`:
-    ```
-    include ':react-native-background-downloader'
-    project(':react-native-background-downloader').projectDir = new File(rootProject.projectDir,   '../node_modules/@kesha-antonov/react-native-background-downloader/android')
-    ```
-3. Insert the following lines inside the dependencies block in `android/app/build.gradle`:
-    ```
-      compile project(':react-native-background-downloader')
-    ```
-</details>
-
-### iOS - Extra Mandatory Step
-
-#### Option 1: Using Expo Config Plugin (Recommended for Expo/EAS users)
-
-If you're using Expo or EAS Build, you can use the included Expo config plugin to automatically configure the native code:
+**Step 2:** Add the config plugin to your `app.json` or `app.config.js`:
 
-**In your `app.json`:**
 ```json
 {
   "expo": {
-    "name": "Your App",
     "plugins": [
       "@kesha-antonov/react-native-background-downloader"
     ]
@@ -143,33 +101,16 @@ If you're using Expo or EAS Build, you can use the included Expo config plugin t
 }
 ```
 
-**Or in your `app.config.js`:**
-```js
-export default {
-  expo: {
-    name: "Your App",
-    plugins: [
-      "@kesha-antonov/react-native-background-downloader"
-    ]
-  }
-}
-```
-
-**Plugin Options:**
-
-You can customize the plugin behavior with options:
+<details>
+<summary><strong>Plugin Options (optional)</strong></summary>
 
 ```js
 // app.config.js
 export default {
   expo: {
-    name: "Your App",
     plugins: [
       ["@kesha-antonov/react-native-background-downloader", {
-        // Set to false if you're already using react-native-mmkv
-        addMmkvDependency: true,
-        // Customize the MMKV version (default: '2.2.4')
-        mmkvVersion: "2.2.4"
+        mmkvVersion: "2.2.4"  // Customize MMKV version on Android
       }]
     ]
   }
@@ -178,75 +119,94 @@ export default {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `addMmkvDependency` | boolean | `true` | Whether to automatically add MMKV dependency on Android. Set to `false` if you're using `react-native-mmkv`. |
-| `mmkvVersion` | string | `'2.2.4'` | The version of MMKV to use on Android. |
+| `mmkvVersion` | string | `'2.2.4'` | The version of [MMKV](https://github.com/Tencent/MMKV/releases) to use on Android. |
 
-The plugin will automatically:
-- **iOS:** Add the required import to your AppDelegate (Objective-C) or Bridging Header (Swift)
-- **iOS:** Add the `handleEventsForBackgroundURLSession` method to your AppDelegate
-- **iOS:** Handle both React Native < 0.77 (Objective-C) and >= 0.77 (Swift) projects
-- **Android:** Add the required MMKV dependency (unless `addMmkvDependency: false`)
+</details>
+
+**Step 3:** Rebuild your app
 
-After adding the plugin, run:
 ```bash
-expo prebuild --clean
+npx expo prebuild --clean
+npx expo run:ios   # or npx expo run:android
 ```
 
-#### Option 2: Manual Setup
+The plugin automatically handles:
+- **iOS:** Adding the required `handleEventsForBackgroundURLSession` method to AppDelegate
+- **Android:** Adding the required MMKV dependency
 
-<details>
-  <summary>Manual setup for React Native 0.77+ (Click to expand)</summary>
+---
 
-  In your project bridging header file (e.g. `ios/{projectName}-Bridging-Header.h`)
-  add an import for RNBackgroundDownloader:
+### Bare React Native Projects
 
-  ```objc
-  ...
-  #import <RNBackgroundDownloader.h>
-  ```
+**Step 1:** Install the package
 
-  Then in your `AppDelegate.swift` add the following method inside of your `AppDelegate` class:
+```bash
+# Using yarn
+yarn add @kesha-antonov/react-native-background-downloader
 
-  ```swift
-  ...
+# Using npm
+npm install @kesha-antonov/react-native-background-downloader
+```
 
-  @main
-  class AppDelegate: UIResponder, UIApplicationDelegate
-    ...
+**Step 2:** Install iOS pods
+
+```bash
+cd ios && pod install && cd ..
+```
+
+**Step 3:** Configure iOS AppDelegate
+
+<details>
+<summary><strong>React Native 0.77+ (Swift)</strong></summary>
+
+In your project bridging header file (e.g. `ios/{projectName}-Bridging-Header.h`):
+
+```objc
+#import <RNBackgroundDownloader.h>
+```
+
+In your `AppDelegate.swift`:
+
+```swift
+func application(
+  _ application: UIApplication,
+  handleEventsForBackgroundURLSession identifier: String,
+  completionHandler: @escaping () -> Void
+) {
+  RNBackgroundDownloader.setCompletionHandlerWithIdentifier(identifier, completionHandler: completionHandler)
+}
+```
 
-    func application(
-      _ application: UIApplication,
-      handleEventsForBackgroundURLSession identifier: String,
-      completionHandler: @escaping () -> Void
-    ) {
-      RNBackgroundDownloader.setCompletionHandlerWithIdentifier(identifier, completionHandler: completionHandler)
-    }
-  }
-  ...
-  ```
-  Failing to add this code will result in canceled background downloads. If Xcode complains that RNBackgroundDownloader.h is missing, you might have forgotten to `pod install` first.
 </details>
 
 <details>
-  <summary>Manual setup for React Native < 0.77 (Click to expand)</summary>
+<summary><strong>React Native < 0.77 (Objective-C)</strong></summary>
 
-  In your `AppDelegate.m` add the following code:
-  ```objc
-  ...
-  #import <RNBackgroundDownloader.h>
+In your `AppDelegate.m`:
 
-  ...
+```objc
+#import <RNBackgroundDownloader.h>
 
-  - (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)(void))completionHandler
-  {
-    [RNBackgroundDownloader setCompletionHandlerWithIdentifier:identifier completionHandler:completionHandler];
-  }
+- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)(void))completionHandler
+{
+  [RNBackgroundDownloader setCompletionHandlerWithIdentifier:identifier completionHandler:completionHandler];
+}
+```
 
-  ...
-  ```
-  Failing to add this code will result in canceled background downloads. If Xcode complains that RNBackgroundDownloader.h is missing, you might have forgotten to `pod install` first.
 </details>
 
+**Step 4:** Configure Android MMKV dependency
+
+Add MMKV to your `android/app/build.gradle`:
+
+```gradle
+dependencies {
+    implementation 'com.tencent:mmkv-shared:2.2.4'
+}
+```
+
+> **Note:** If you're already using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) in your project, skip this step — it already includes MMKV.
+
 ## Usage
 
 ### Downloading a file
@@ -292,33 +252,56 @@ await task.resume()
 await task.stop()
 ```
 
-### Re-Attaching to background downloads
+### Re-Attaching to background tasks
+
+The killer feature of this library: **reconnect to downloads and uploads that continued running while your app was closed**, or **resume paused tasks from a previous session**.
 
-This is the main selling point of this library (but it's free!).
+When the OS terminates your app to free memory, background transfers keep running. When your app restarts, call `getExistingDownloadTasks()` or `getExistingUploadTasks()` to get back in sync. Paused tasks are also preserved and can be resumed with `task.resume()`.
 
-What happens to your downloads after the OS stopped your app? Well, they are still running, we just need to re-attach to them.
+> **💡 Tip:** Use meaningful task IDs (not random UUIDs) so you can match tasks to your UI components after restart.
 
-Add this code to app's init stage, and you'll never lose a download again!
+**Downloads:**
 
 ```javascript
 import { getExistingDownloadTasks } from '@kesha-antonov/react-native-background-downloader'
 
-let lostTasks = await getExistingDownloadTasks()
-for (let task of lostTasks) {
-  console.log(`Task ${task.id} was found!`)
+const lostTasks = await getExistingDownloadTasks()
+
+for (const task of lostTasks) {
+  console.log(`Found download: ${task.id}`)
+
   task.progress(({ bytesDownloaded, bytesTotal }) => {
     console.log(`Downloaded: ${bytesDownloaded / bytesTotal * 100}%`)
   }).done(({ location, bytesDownloaded, bytesTotal }) => {
-    console.log('Download is done!', { location, bytesDownloaded, bytesTotal })
+    console.log('Download complete!', { location, bytesDownloaded, bytesTotal })
   }).error(({ error, errorCode }) => {
-    console.log('Download canceled due to error: ', { error, errorCode })
+    console.log('Download failed:', { error, errorCode })
   })
 }
 ```
 
-`task.id` is very important for re-attaching the download task with any UI component representing that task. This is why you need to make sure to give sensible IDs that you know what to do with, try to avoid using random IDs.
+**Uploads:**
+
+```javascript
+import { getExistingUploadTasks } from '@kesha-antonov/react-native-background-downloader'
+
+const lostUploads = await getExistingUploadTasks()
+
+for (const task of lostUploads) {
+  console.log(`Found upload: ${task.id}`)
 
-### Uploading a file
+  task.progress(({ bytesUploaded, bytesTotal }) => {
+    console.log(`Uploaded: ${bytesUploaded / bytesTotal * 100}%`)
+  }).done(({ responseCode, responseBody }) => {
+    console.log('Upload complete!', { responseCode, responseBody })
+  }).error(({ error, errorCode }) => {
+    console.log('Upload failed:', { error, errorCode })
+  })
+}
+```
+
+<details>
+<summary><strong>Uploading a file</strong></summary>
 
 ```javascript
 import { Platform } from 'react-native'
@@ -368,27 +351,12 @@ await task.resume()
 await task.stop()
 ```
 
-### Re-Attaching to background uploads
-
-Similar to downloads, you can re-attach to uploads that were running when your app was terminated:
+</details>
 
-```javascript
-import { getExistingUploadTasks } from '@kesha-antonov/react-native-background-downloader'
+## Advanced Configuration
 
-let lostUploads = await getExistingUploadTasks()
-for (let task of lostUploads) {
-  console.log(`Upload task ${task.id} was found!`)
-  task.progress(({ bytesUploaded, bytesTotal }) => {
-    console.log(`Uploaded: ${bytesUploaded / bytesTotal * 100}%`)
-  }).done(({ responseCode, responseBody }) => {
-    console.log('Upload is done!', { responseCode, responseBody })
-  }).error(({ error, errorCode }) => {
-    console.log('Upload canceled due to error: ', { error, errorCode })
-  })
-}
-```
-
-### Using custom headers
+<details>
+<summary><strong>Using custom headers</strong></summary>
 If you need to send custom headers with your download request, you can do in it 2 ways:
 
 1) Globally using `setConfig()`:
@@ -428,7 +396,10 @@ task.start()
 ```
 Headers given in `createDownloadTask()` are **merged** with the ones given in `setConfig({ headers: { ... } })`.
 
-### Configuring Parallel Downloads and Network Types
+</details>
+
+<details>
+<summary><strong>Configuring parallel downloads and network types</strong></summary>
 
 You can configure global settings for download behavior using `setConfig()`:
 
@@ -480,7 +451,10 @@ const task = createDownloadTask({
 })
 ```
 
-### Enabling Debug Logs
+</details>
+
+<details>
+<summary><strong>Enabling debug logs</strong></summary>
 
 The library includes verbose debug logging that can help diagnose download issues. Logging is disabled by default but can be enabled at runtime using `setConfig()`. **Logging works in both debug and production/release builds.**
 
@@ -517,7 +491,10 @@ setConfig({
 - Logs include detailed information about download lifecycle, session management, and errors
 - In production builds, logs are only printed when explicitly enabled via `isLogsEnabled`
 
-### Handling Slow-Responding URLs
+</details>
+
+<details>
+<summary><strong>Handling slow-responding URLs</strong></summary>
 
 This library automatically includes connection timeout improvements for slow-responding URLs. By default, the following headers are added to all download requests on Android:
 
@@ -527,7 +504,10 @@ This library automatically includes connection timeout improvements for slow-res
 
 These headers help prevent downloads from getting stuck in "pending" state when servers take several minutes to respond initially. You can override these headers by providing your own in the `headers` option.
 
-### Handling URLs with Many Redirects (Android)
+</details>
+
+<details>
+<summary><strong>Handling URLs with many redirects (Android)</strong></summary>
 
 Android's DownloadManager has a built-in redirect limit that can cause `ERROR_TOO_MANY_REDIRECTS` for URLs with multiple redirects (common with podcast URLs, tracking services, CDNs, etc.).
 
@@ -567,11 +547,13 @@ task.start()
 - Falls back to original URL if redirect resolution fails
 - Respects the same headers and timeouts as the main download
 
+</details>
+
 ## API
 
-### Named Exports
+For complete API documentation, see the **[API Reference](./docs/API.md)**.
 
-The library exports the following functions and objects:
+### Quick Reference
 
 ```typescript
 import {
@@ -585,318 +567,151 @@ import {
 } from '@kesha-antonov/react-native-background-downloader'
 ```
 
-### `createDownloadTask(options)`
-
-Download a file to destination
-
-**options**
-
-An object containing options properties
-
-| Property      | Type                                             | Required | Platforms | Info                                                                                                                                                                                                                                 |
-| ------------- | ------------------------------------------------ | :------: | :-------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`          | String |    ✅     |    All    | A unique ID to provide for this download. This ID will help to identify the download task when the app re-launches |
-| `url`         | String |    ✅     |    All    | URL to file you want to download |
-| `destination` | String |    ✅     |    All    | Where to copy the file to once the download is done. The 'file://' prefix will be automatically removed if present |
-| `metadata`    | Record<string, unknown> |           |    All    | Custom data to be preserved across app restarts. Will be serialized to JSON |
-| `headers`     | Record<string, string \| null> |           |    All    | Custom headers to add to the download request. These are merged with the headers given in `setConfig({ headers: { ... } })`. Headers with null values will be removed |
-| `maxRedirects` | Number |          |  Android  | Maximum number of redirects to follow before passing URL to DownloadManager. If not specified or 0, no redirect resolution is performed. Helps avoid ERROR_TOO_MANY_REDIRECTS for URLs with many redirects (e.g., podcast URLs) |
-| `isAllowedOverRoaming` | Boolean   |          |  Android  | whether this download may proceed over a roaming connection. By default, roaming is allowed |
-| `isAllowedOverMetered` | Boolean   |          |  Android  | Whether this download may proceed over a metered network connection. By default, metered networks are allowed |
-| `isNotificationVisible`     | Boolean   |          |  Android  | Whether to show a download notification or not |
-| `notificationTitle`     | String   |          |  Android  | Title of the download notification |
-
-**returns**
-
-`DownloadTask` - The download task to control and monitor this download. Call `task.start()` to begin the download.
-
-### `getExistingDownloadTasks()`
-
-Checks for downloads that ran in background while your app was terminated.
-
-Recommended to run at the init stage of the app.
-
-**returns**
-
-`Promise<DownloadTask[]>` - A promise that resolves to an array of tasks that were running in the background so you can re-attach callbacks to them
-
-### `createUploadTask(options)`
-
-Upload a file to a server
-
-**options**
-
-An object containing options properties
-
-| Property      | Type                                             | Required | Platforms | Info                                                                                                                                                                                                                                 |
-| ------------- | ------------------------------------------------ | :------: | :-------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`          | String |    ✅     |    All    | A unique ID to provide for this upload. This ID will help to identify the upload task when the app re-launches |
-| `url`         | String |    ✅     |    All    | URL to upload the file to |
-| `source`      | String |    ✅     |    All    | Path to the local file to upload. The 'file://' prefix will be automatically removed if present |
-| `method`      | 'POST' \| 'PUT' \| 'PATCH' |          |    All    | HTTP method for upload. Default is 'POST' |
-| `metadata`    | Record<string, unknown> |           |    All    | Custom data to be preserved across app restarts. Will be serialized to JSON |
-| `headers`     | Record<string, string \| null> |           |    All    | Custom headers to add to the upload request. These are merged with the headers given in `setConfig({ headers: { ... } })`. Headers with null values will be removed |
-| `fieldName`   | String |          |    All    | Name of the multipart form field for the file. Default is 'file' |
-| `mimeType`    | String |          |    All    | MIME type of the file being uploaded. Default is inferred from file extension |
-| `parameters`  | Record<string, string> |          |    All    | Additional form parameters to send with the upload |
-| `isAllowedOverRoaming` | Boolean   |          |  Android  | Whether this upload may proceed over a roaming connection. By default, roaming is allowed |
-| `isAllowedOverMetered` | Boolean   |          |  Android  | Whether this upload may proceed over a metered network connection. By default, metered networks are allowed |
-| `isNotificationVisible`     | Boolean   |          |  Android  | Whether to show an upload notification or not |
-| `notificationTitle`     | String   |          |  Android  | Title of the upload notification |
-
-**returns**
-
-`UploadTask` - The upload task to control and monitor this upload. Call `task.start()` to begin the upload.
-
-### `getExistingUploadTasks()`
-
-Checks for uploads that ran in background while your app was terminated.
-
-Recommended to run at the init stage of the app.
-
-**returns**
-
-`Promise<UploadTask[]>` - A promise that resolves to an array of upload tasks that were running in the background so you can re-attach callbacks to them
-
-### `setConfig(config)`
-
-Sets global configuration for the downloader.
-
-**config**
-
-An object containing configuration properties
-
-| Name           | Type   | Info                                                                                                 |
-| -------------- | ------ | ---------------------------------------------------------------------------------------------------- |
-| `headers`     | Record<string, string \| null> | Optional headers to use in all future downloads. Headers with null values will be removed |
-| `progressInterval` | Number | Interval in milliseconds for download progress updates. Must be >= 250. Default is 1000 |
-| `progressMinBytes` | Number | Minimum number of bytes that must be downloaded before a progress event is emitted. When set to 0, only the percentage threshold (1% change) triggers progress updates. Default is 1048576 (1MB) |
-| `isLogsEnabled`   | Boolean | Enables/disables verbose debug logs in native code (iOS and Android). Works in both debug and release builds. Default is false |
-| `logCallback`   | (log: { message: string, taskId?: string }) => void | Optional callback function to receive native debug logs in JavaScript. Only called when `isLogsEnabled` is true |
-| `maxParallelDownloads` | Number | **iOS only**. Sets the maximum number of simultaneous connections per host for the download session. Must be >= 1. Default is 4. Note: Android's DownloadManager does not support this configuration |
-| `allowsCellularAccess` | Boolean | Controls whether downloads are allowed over cellular (metered) connections. When set to `false`, downloads will only occur over WiFi. Default is `true`. This is a cross-platform abstraction - on iOS it sets `allowsCellularAccess`, on Android it sets `isAllowedOverMetered` |
-
-**Example:**
-
-```javascript
-import { setConfig } from '@kesha-antonov/react-native-background-downloader'
-
-// Configure parallel downloads (iOS only) and cellular access
-setConfig({
-  maxParallelDownloads: 8,  // iOS only - max simultaneous connections per host
-  allowsCellularAccess: false,  // Only download over WiFi
-})
-
-// Enable verbose logging with callback
-setConfig({
-  isLogsEnabled: true,
-  logCallback: (log) => {
-    console.log('[BackgroundDownloader]', log.message, log.taskId ? `(${log.taskId})` : '')
-  }
-})
-
-// Or just enable native console logging without JS callback
-setConfig({
-  isLogsEnabled: true
-})
-```
-
-### DownloadTask
-
-A class representing a download task created by `createDownloadTask()`. Note: You must call `task.start()` to begin the download after setting up event handlers.
-
-### UploadTask
-
-A class representing an upload task created by `createUploadTask()`. Note: You must call `task.start()` to begin the upload after setting up event handlers.
-
-**Members** (same structure as DownloadTask with upload-specific properties)
-
-| Name           | Type   | Info                                                                                                 |
-| -------------- | ------ | ---------------------------------------------------------------------------------------------------- |
-| `id`           | String | The id you gave the task when calling `createUploadTask`                              |
-| `metadata`     | Record<string, unknown> | The metadata you gave the task when calling `createUploadTask`                        |
-| `state`        | 'PENDING' \| 'UPLOADING' \| 'PAUSED' \| 'DONE' \| 'FAILED' \| 'STOPPED' | Current state of the upload task |
-| `bytesUploaded` | Number | The number of bytes currently uploaded by the task                                                    |
-| `bytesTotal`   | Number | The total number bytes to be uploaded by this task |
-| `uploadParams` | UploadParams | The upload parameters set for this task |
-
-**Callback Methods**
-
-| Function   | Callback Arguments                | Info|
-| ---------- | --------------------------------- | ---- |
-| `begin`    | `{ expectedBytes: number }` | Called when upload starts |
-| `progress` | `{ bytesUploaded: number, bytesTotal: number }` | Called based on progressInterval (default: every 1000ms) so you can update your progress bar accordingly |
-| `done`     | `{ responseCode: number, responseBody: string, bytesUploaded: number, bytesTotal: number }` | Called when the upload is done. Includes server response code and body |
-| `error`    | `{ error: string, errorCode: number }` | Called when the upload stops due to an error |
-
-**Methods**
-
-- `pause(): Promise<void>` - Pauses the upload (platform support may vary)
-- `resume(): Promise<void>` - Resumes a paused upload
-- `stop(): Promise<void>` - Stops the upload and removes temporary data
-- `start(): void` - Starts the upload
-
-### `Members`
-| Name           | Type   | Info                                                                                                 |
-| -------------- | ------ | ---------------------------------------------------------------------------------------------------- |
-| `id`           | String | The id you gave the task when calling `createDownloadTask`                              |
-| `metadata`     | Record<string, unknown> | The metadata you gave the task when calling `createDownloadTask`                        |
-| `state`        | 'PENDING' \| 'DOWNLOADING' \| 'PAUSED' \| 'DONE' \| 'FAILED' \| 'STOPPED' | Current state of the download task |
-| `bytesDownloaded` | Number | The number of bytes currently written by the task                                                    |
-| `bytesTotal`   | Number | The number bytes expected to be written by this task or more plainly, the file size being downloaded. **Note:** This value will be `-1` if the server does not provide a `Content-Length` header |
-| `downloadParams` | DownloadParams | The download parameters set for this task |
-
-### `completeHandler(jobId: string)`
-
-Finishes download job and informs OS that app can be closed in background if needed.
-After finishing download in background you have some time to process your JS logic and finish the job.
-
-**Parameters:**
-- `jobId` (String) - The ID of the download task to complete
-
-**Note:** This should be called after processing your download in the `done` callback to properly signal completion to the OS.
-
-### `Callback Methods`
-Use these methods to stay updated on what's happening with the task.
-
-All callback methods return the current instance of the `DownloadTask` for chaining.
-
-| Function   | Callback Arguments                | Info|
-| ---------- | --------------------------------- | ---- |
-| `begin`    | `{ expectedBytes: number, headers: Record<string, string \| null> }` | Called when the first byte is received. 💡: this is good place to check if the device has enough storage space for this download |
-| `progress` | `{ bytesDownloaded: number, bytesTotal: number }` | Called based on progressInterval (default: every 1000ms) so you can update your progress bar accordingly. **Note:** `bytesTotal` will be `-1` if the server does not provide a `Content-Length` header |
-| `done`     | `{ location: string, bytesDownloaded: number, bytesTotal: number }` | Called when the download is done, the file is at the destination you've set. `location` is the final file path. **Note:** `bytesTotal` will be `-1` if the server did not provide a `Content-Length` header |
-| `error`    | `{ error: string, errorCode: number }` | Called when the download stops due to an error |
+| Function | Description |
+|----------|-------------|
+| `createDownloadTask(options)` | Create a new download task |
+| `createUploadTask(options)` | Create a new upload task |
+| `getExistingDownloadTasks()` | Get downloads running in background |
+| `getExistingUploadTasks()` | Get uploads running in background |
+| `setConfig(config)` | Set global configuration |
+| `completeHandler(jobId)` | Signal download completion to OS |
+| `directories.documents` | Path to app's documents directory |
 
-### `pause(): Promise<void>`
-Pauses the download. Returns a promise that resolves when the pause operation is complete.
+## Platform Notes
 
-**Note:** On Android, pause/resume is implemented using HTTP Range headers, which requires server support. The download progress is saved and resumed from where it left off.
+For detailed platform-specific information, see **[Platform Notes](./docs/PLATFORM_NOTES.md)**.
 
-### `resume(): Promise<void>`
-Resumes a paused download. Returns a promise that resolves when the resume operation is complete.
+Key points:
+- **iOS**: Uses `NSURLSession` for true background downloads
+- **Android**: Uses `DownloadManager` + Foreground Services + MMKV
+- **Pause/Resume**: Works on both platforms (Android requires server Range header support)
 
-**Note:** On Android, this uses HTTP Range headers to resume from the last downloaded byte position. If the server doesn't support range requests, the download will restart from the beginning.
+## Troubleshooting
 
-### `stop(): Promise<void>`
-Stops the download for good and removes the file that was written so far. Returns a promise that resolves when the stop operation is complete.
+<details>
+<summary><strong>Download stuck in "pending" state (Android)</strong></summary>
 
-## Constants
+This can happen with slow-responding servers. The library automatically adds keep-alive headers, but you can also try:
+- Increase timeout by setting custom headers
+- Check if the server supports the download URL
+- Enable debug logs to see what's happening: `setConfig({ isLogsEnabled: true })`
+</details>
 
-### directories
+<details>
+<summary><strong>Duplicate class errors with react-native-mmkv (Android)</strong></summary>
 
-### `documents`
+If you're using `react-native-mmkv`, you don't need to add the MMKV dependency manually - it's already included. The library uses `compileOnly` to avoid conflicts.
+</details>
 
-An absolute path to the app's documents directory. It is recommended that you use this path as the target of downloaded files.
+<details>
+<summary><strong>EXC_BAD_ACCESS crash on iOS with react-native-mmkv</strong></summary>
 
-## Platform-Specific Limitations
+This was fixed in v4.4.0. Update to the latest version. If you're not using `react-native-mmkv`, add `pod 'MMKV', '>= 1.0.0'` to your Podfile.
+</details>
 
-### iOS MMKV Dependency
+<details>
+<summary><strong>Downloads not resuming after app restart</strong></summary>
 
-This library uses MMKV for persistent storage of download state on iOS. The MMKV dependency is **not** declared in the podspec to avoid conflicts with `react-native-mmkv`.
+Make sure to call `getExistingDownloadTasks()` at app startup and re-attach your callbacks. The task IDs you provide are used to identify downloads across restarts.
+</details>
 
-**If you're using `react-native-mmkv`:** No additional setup needed - `react-native-mmkv` already provides the required MMKV dependency (via MMKVCore pod).
+<details>
+<summary><strong>Google Play Console asking about Foreground Service</strong></summary>
 
-**If you're NOT using `react-native-mmkv`:** Add the MMKV dependency to your `ios/Podfile`:
+See the [Google Play Console Declaration](#google-play-console-declaration) section for the required steps.
+</details>
 
-```ruby
-pod 'MMKV', '>= 1.0.0'
-```
+<details>
+<summary><strong>TypeToken errors in release builds (Android)</strong></summary>
 
-Then run `cd ios && pod install`.
+Add the Proguard rules mentioned in the [Proguard Rules](#proguard-rules) section.
+</details>
 
-### Android MMKV Dependency
+## Example App
 
-This library uses MMKV for persistent storage of download state on Android. The MMKV dependency is declared as `compileOnly`, meaning your app must provide it.
+The repository includes a full example app demonstrating all features:
 
-**If you're using `react-native-mmkv`:** No additional setup needed - `react-native-mmkv` already provides the required MMKV dependency.
+```bash
+cd example
+yarn install
 
-**If you're NOT using `react-native-mmkv`:** Add the MMKV dependency to your app's `android/app/build.gradle`:
+# iOS
+cd ios && pod install && cd ..
+yarn ios
 
-```gradle
-dependencies {
-    // ... other dependencies
-    implementation 'com.tencent:mmkv-shared:2.2.4'  // or newer
-}
+# Android
+yarn android
 ```
 
-**Note:** MMKV 2.0.0+ is required for Android 15+ support (16KB memory page sizes).
+The example app shows:
+- Starting multiple downloads
+- Pause/resume functionality
+- Progress tracking with animations
+- Re-attaching to background tasks
+- File management
 
-### Android DownloadManager Limitations
+## Use Cases
 
-The Android implementation uses the system's `DownloadManager` service for downloads, with custom pause/resume support:
+This library is perfect for apps that need reliable file transfers:
 
-#### Android 16+ User-Initiated Data Transfer (UIDT) Support
-- **Android 16 Compatibility**: Downloads are automatically marked as user-initiated data transfers on Android 16+ (API 36)
-- **What this fixes**: Prevents background downloads from being killed due to thermal throttling or job quota restrictions
-- **Requirements**: The library automatically includes the `RUN_USER_INITIATED_JOBS` permission and marks downloads as user-initiated when running on Android 16+
-- **No action needed**: This is handled automatically by the library - your downloads will continue reliably even under moderate thermal conditions (~40°C) on Android 16+
+- 🎵 **Music/Podcast Apps** - Download episodes for offline listening
+- 📚 **E-book Readers** - Download books in the background
+- 🎬 **Video Streaming** - Offline video downloads
+- 📁 **File Managers** - Large file transfers
+- 🎮 **Games** - Download game assets and updates
+- 📱 **Enterprise Apps** - Sync large documents and media
 
-#### Pause/Resume Support
-- **Implementation**: Pause/resume on Android is implemented using HTTP Range headers
-- **How it works**: When you pause a download, the current progress is saved. When resumed, a new download starts from where it left off using the `Range` header
-- **Server requirement**: The server must support HTTP Range requests for resume to work correctly. If the server doesn't support range requests, the download will restart from the beginning
-- **Temp files**: During pause/resume, progress is stored in a `.tmp` file which is renamed to the final destination upon completion
+## Migration Guide
 
-### Google Play Console Declaration
+Upgrading from an older version? Check the [Migration Guide](./MIGRATION.md) for detailed instructions:
 
-The library uses Foreground Service permissions (`FOREGROUND_SERVICE` and `FOREGROUND_SERVICE_DATA_SYNC`) to enable reliable background downloads. **Google Play requires you to declare foreground service usage in the Play Console** when publishing your app.
+- [v4.3.x → v4.4.0](./MIGRATION.md#migration-guide-v43x--v440) - iOS MMKV dependency change
+- [v4.1.x → v4.2.0](./MIGRATION.md#migration-guide-v41x--v420) - Android pause/resume support
+- [v4.0.x → v4.1.0](./MIGRATION.md#migration-guide-v40x--v410) - MMKV dependency change
+- [v3.2.6 → v4.0.0](./MIGRATION.md#migration-guide-v326--v400) - Major API changes
 
-If you see this error when submitting to Google Play:
+See the [Changelog](./CHANGELOG.md) for a complete list of changes in each version.
 
-> "You must let us know whether your app uses any Foreground Service permissions."
+## Contributing
 
-Complete these steps in the Google Play Console:
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-1. Go to your app in the [Google Play Console](https://play.google.com/console)
-2. Navigate to **App content** → **Foreground Service**
-3. Select **Yes** when asked if your app uses Foreground Service permissions
-4. Choose **Data sync** as the Foreground Service type
-5. Select **Network processing** as the task
-6. Provide a justification explaining that your app downloads files in the background with a user-visible notification
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Install dependencies (`yarn install`)
+4. Make your changes
+5. Run tests (`yarn test`)
+6. Run linting (`yarn lint`)
+7. Commit your changes (`git commit -m 'Add amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
 
-Example justification:
-> "This app downloads files in the background using a foreground service with a user-visible notification. The foreground service ensures downloads continue reliably when the app is in the background or when the device is under memory pressure. Users initiate downloads and can see download progress via the notification."
+### Development Setup
 
-This is a Play Console compliance step only—no additional code changes are required.
-
-## Rules for proguard-rules.pro
+```bash
+# Install dependencies
+yarn install
 
-If you encounter `java.lang.IllegalStateException: TypeToken must be created with a type argument: new TypeToken<...>()` in Android release builds, add these rules to your `proguard-rules.pro`:
+# Run tests
+yarn test
 
-```
-# react-native-background-downloader - Keep config class used by Gson
--keep class com.eko.RNBGDTaskConfig { *; }
+# Run linting
+yarn lint
 
-# Gson TypeToken support
--keepattributes Signature
--keep class com.google.gson.reflect.TypeToken { *; }
--keep class * extends com.google.gson.reflect.TypeToken
+# Build the Expo plugin
+yarn build-plugin
 
-# MMKV
--keep class com.tencent.mmkv.** { *; }
--dontwarn com.tencent.mmkv.**
+# Run the example app
+cd example && yarn install
+yarn ios  # or yarn android
 ```
 
-## Known Issues with New Architecture
-When using larger files with the New Architecture, you may encounter `ERROR_CANNOT_RESUME` (error code 1008). This is a known limitation of Android's DownloadManager, not specific to this library or the New Architecture. The error includes enhanced messaging to help diagnose the issue.
-
-**Workaround:** If you encounter this error frequently with large files, consider:
-1. Breaking large downloads into smaller chunks
-2. Implementing retry logic in your app
-3. Using alternative download strategies for very large files
-
-The library now provides enhanced error handling for this specific case with detailed logging and cleanup.
-
-## TODO
-
-- [ ] Write better API for downloads - current kinda boilerplate
-
 ## Authors
 
-Re-written & maintained by [Kesha Antonov](https://github.com/kesha-antonov)
+Maintained by [Kesha Antonov](https://github.com/kesha-antonov)
 
-Originally developed by [Elad Gil](https://github.com/ptelad) of [Eko](https://github.com/ekolabs/react-native-background-downloader)
+Based on [react-native-background-downloader](https://github.com/ekolabs/react-native-background-downloader) by [Elad Gil](https://github.com/ptelad) (unmaintained since 2019)
 
 ## License
-Apache 2
+
+[Apache 2.0](./LICENSE)