@kesha-antonov/react-native-background-downloader 4.4.5 → 4.5.3

package/README.md

@@ -12,9 +12,13 @@
   <img src="https://img.shields.io/badge/New%20Architecture-supported-green.svg" alt="New Architecture">
 </p>
 
-# React Native Background Downloader
+<h1 align="center">React Native Background Downloader</h1>
 
-Download and upload large files on iOS & Android — even when your app is in the background or terminated.
+<p align="center">
+  Download and upload large files on iOS & Android — even when your app is in the background or terminated.
+</p>
+
+---
 
 ## ✨ Features
 
@@ -28,7 +32,7 @@ Download and upload large files on iOS & Android — even when your app is in th
 - ⚡ **New Architecture** - Full TurboModules support for React Native
 - 📝 **TypeScript** - Complete TypeScript definitions included
 
-## Why?
+## 💡 Why?
 
 **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.
 
@@ -40,35 +44,34 @@ Download and upload large files on iOS & Android — even when your app is in th
 
 **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.
 
-## Table of Contents
-
-- [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)
-
-## Requirements
+## 📖 Table of Contents
+
+- [✨ 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)
+
+## 📋 Requirements
 
 | Requirement | Version |
 |-------------|--------|
@@ -79,7 +82,7 @@ Download and upload large files on iOS & Android — even when your app is in th
 
 > **Note:** For older React Native versions (0.57.0 - 0.69.x), use version 2.x of this library.
 
-## Installation
+## 📦 Installation
 
 ### Expo Projects
 
@@ -142,16 +145,24 @@ The plugin automatically handles:
 
 **Step 1:** Install the package
 
+**yarn:**
 ```bash
-# Using yarn
 yarn add @kesha-antonov/react-native-background-downloader
+```
 
-# Using npm
+**npm:**
+```bash
 npm install @kesha-antonov/react-native-background-downloader
 ```
 
 **Step 2:** Install iOS pods
 
+**yarn:**
+```bash
+cd ios && pod install && cd ..
+```
+
+**npm:**
 ```bash
 cd ios && pod install && cd ..
 ```
@@ -209,7 +220,7 @@ dependencies {
 
 > **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
+## 🚀 Usage
 
 ### Downloading a file
 
@@ -355,7 +366,45 @@ await task.stop()
 
 </details>
 
-## Advanced Configuration
+<details>
+<summary><strong>Updating headers on paused downloads</strong></summary>
+
+If your download uses authentication tokens that expire, you can update the headers of a paused download before resuming it. This is useful when auth tokens refresh while a download is paused:
+
+```javascript
+import { getExistingDownloadTasks } from '@kesha-antonov/react-native-background-downloader'
+
+// Get paused downloads
+const tasks = await getExistingDownloadTasks()
+
+for (const task of tasks) {
+  if (task.state === 'PAUSED') {
+    // Update headers with new auth token before resuming
+    await task.setDownloadParams({
+      ...task.downloadParams,
+      headers: {
+        ...task.downloadParams?.headers,
+        Authorization: 'Bearer new-refreshed-token'
+      }
+    })
+
+    // Now resume with the updated headers
+    await task.resume()
+  }
+}
+```
+
+**Notes:**
+- `setDownloadParams()` is async and returns `true` if native headers were updated
+- Headers are only updated in the native layer when the task is in `PAUSED` state
+- On iOS, the download will resume using HTTP Range headers with the new headers
+- On Android, both in-memory and persisted paused state are updated
+
+> **Use case:** User pauses a large download, closes the app, and returns hours or days later. By then, the auth token has expired. This feature allows refreshing the token and updating headers before resuming, without restarting the download from scratch.
+
+</details>
+
+## ⚙️ Advanced Configuration
 
 <details>
 <summary><strong>Using custom headers</strong></summary>
@@ -551,7 +600,191 @@ task.start()
 
 </details>
 
-## API
+<details>
+<summary><strong>Notification Configuration (Android)</strong></summary>
+
+On Android 14+ (API 34), downloads use User-Initiated Data Transfer (UIDT) jobs which **require** notifications. Due to Android system requirements, notifications cannot be completely disabled when using UIDT jobs. However, you can control their visibility:
+
+- When `showNotificationsEnabled: true` - Full notifications with progress, title, and custom texts
+- When `showNotificationsEnabled: false` (default) - Minimal silent notifications with lowest priority that are barely noticeable
+
+**Basic configuration:**
+
+```javascript
+import { setConfig } from '@kesha-antonov/react-native-background-downloader'
+
+// Enable notifications and notification grouping with custom texts
+setConfig({
+  showNotificationsEnabled: true, // Show full notifications (default: false - minimal silent notifications)
+  notificationsGrouping: {
+    enabled: true,           // Enable grouping (default: false)
+    texts: {
+      downloadTitle: 'Download',
+      downloadStarting: 'Starting download...',
+      downloadProgress: 'Downloading... {progress}%',
+      downloadPaused: 'Paused',
+      downloadFinished: 'Download complete',
+      groupTitle: 'Downloads',
+      groupText: '{count} downloads in progress',
+    },
+  },
+})
+
+// Use minimal silent notifications (default behavior)
+setConfig({
+  showNotificationsEnabled: false, // Minimal silent notifications (required by UIDT but barely visible)
+})
+```
+
+**Notification grouping modes:**
+
+When downloading many files (e.g., thousands of photos), you can use the `mode` option to control how notifications are displayed:
+
+| Mode | Description |
+|------|-------------|
+| `'individual'` | Default. Shows all individual notifications grouped together with a summary |
+| `'summaryOnly'` | Shows only ONE notification with real-time aggregate progress (e.g., "45% - 5 files"). Individual UIDT notifications are collapsed into an invisible group. Ideal for bulk downloads |
+
+```javascript
+import { setConfig } from '@kesha-antonov/react-native-background-downloader'
+
+// For bulk downloads (e.g., syncing thousands of photos)
+// Use 'summaryOnly' mode to show only ONE notification with aggregate progress
+setConfig({
+  showNotificationsEnabled: true,
+  notificationsGrouping: {
+    enabled: true,
+    mode: 'summaryOnly', // Only show summary notification with progress bar
+    texts: {
+      groupTitle: 'Syncing Photos',
+      groupText: '{count} files downloading',
+    },
+  },
+})
+```
+
+**Example: Batch downloading multiple files with grouped notifications:**
+
+```javascript
+import { setConfig, createDownloadTask, directories } from '@kesha-antonov/react-native-background-downloader'
+
+// Configure for bulk downloads with single summary notification
+setConfig({
+  showNotificationsEnabled: true,
+  notificationsGrouping: {
+    enabled: true,
+    mode: 'summaryOnly',
+    texts: {
+      groupTitle: 'Photo Sync',
+      groupText: '{count} photos downloading',
+    },
+  },
+})
+
+// Download multiple files - they all share ONE notification with aggregate progress
+const photos = [
+  { id: 'photo-1', url: 'https://example.com/photo1.jpg' },
+  { id: 'photo-2', url: 'https://example.com/photo2.jpg' },
+  { id: 'photo-3', url: 'https://example.com/photo3.jpg' },
+  // ... potentially thousands of files
+]
+
+const GROUP_ID = 'photo-sync-batch'
+
+for (const photo of photos) {
+  const task = createDownloadTask({
+    id: photo.id,
+    url: photo.url,
+    destination: `${directories.documents}/${photo.id}.jpg`,
+    metadata: {
+      groupId: GROUP_ID,        // Required for grouping
+      groupName: 'Photo Sync',  // Displayed in notification title
+    },
+  })
+    .progress(({ bytesDownloaded, bytesTotal }) => {
+      // Progress tracked per file, notification shows aggregate progress
+    })
+    .done(() => {
+      console.log(`Downloaded ${photo.id}`)
+    })
+    .error(({ error }) => {
+      console.error(`Failed ${photo.id}:`, error)
+    })
+
+  task.start()
+}
+
+// User sees: ONE notification showing "45% - 3 files" with progress bar
+// instead of 3 separate notifications cluttering the notification shade
+// Notification automatically disappears when all downloads complete
+```
+
+**Grouping downloads by category:**
+
+When notification grouping is enabled, you can group related downloads (e.g., by album, playlist, podcast) by passing `groupId` and `groupName` in the task `metadata`:
+
+```javascript
+import { createDownloadTask, directories } from '@kesha-antonov/react-native-background-downloader'
+
+// Download album songs - they will be grouped under one notification
+const task = createDownloadTask({
+  id: 'song-1',
+  url: 'https://example.com/albums/summer-hits/track01.mp3',
+  destination: `${directories.documents}/track01.mp3`,
+  metadata: {
+    groupId: 'album-summer-hits',  // Unique identifier for the group
+    groupName: 'Summer Hits 2024', // Display name in notification title
+  },
+})
+
+task.start()
+```
+
+**Notification behavior during pause/resume:**
+
+When a download is paused on Android 14+:
+- The background UIDT job is cancelled (to prevent downloads continuing in background)
+- A detached "Paused" notification remains visible showing current progress
+- When resumed, a new UIDT job is created and the notification switches to "Downloading" state
+- When stopped, the notification is removed
+- **When app is closed, all download notifications are automatically removed**
+
+This ensures users always see the download status without unexpected background activity.
+
+**Configuration options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `showNotificationsEnabled` | boolean | `false` | Show full download notifications. When `false`, creates minimal silent notifications (UIDT jobs require a notification, but it will be barely visible). This is a top-level config option. |
+| `notificationsGrouping.enabled` | boolean | `false` | Enable notification grouping |
+| `notificationsGrouping.mode` | `'individual'` \| `'summaryOnly'` | `'individual'` | Notification display mode. Use `'summaryOnly'` for bulk downloads to show only ONE notification with real-time aggregate progress |
+| `notificationsGrouping.texts` | object | See below | Customizable notification texts |
+
+**Notification texts (`notificationsGrouping.texts`):**
+
+| Key | Default | Placeholders | Description |
+|-----|---------|--------------|-------------|
+| `downloadTitle` | `'Download'` | — | Title for individual download notifications |
+| `downloadStarting` | `'Starting download...'` | — | Text when download is starting |
+| `downloadProgress` | `'Downloading... {progress}%'` | `{progress}` | Progress text with current percentage (0-100) |
+| `downloadPaused` | `'Paused'` | — | Text when download is paused |
+| `downloadFinished` | `'Download complete'` | — | Text when download is finished |
+| `groupTitle` | `'Downloads'` | — | Title for group summary notification |
+| `groupText` | `'{count} download(s) in progress'` | `{count}` | Group summary text with active downloads count |
+
+**Notes:**
+- Notifications cannot be completely disabled on Android 14+ due to UIDT requirements
+- When `showNotificationsEnabled: false`, notifications are created with minimal visibility (lowest priority, empty content)
+- Paused downloads show a non-ongoing notification (can be swiped away by user)
+- Active downloads show an ongoing notification (cannot be swiped away)
+- This feature only affects Android 14+ (API 34) where UIDT jobs are used
+- On older Android versions, the standard DownloadManager notifications are shown
+- iOS uses system download notifications and doesn't support custom grouping
+- **Use `mode: 'summaryOnly'` when downloading many files** to prevent notification spam - shows ONE notification with aggregate progress bar that updates in real-time
+
+</details>
+
+## 📚 API
 
 For complete API documentation, see the **[API Reference](./docs/API.md)**.
 
@@ -579,7 +812,7 @@ import {
 | `completeHandler(jobId)` | Signal download completion to OS |
 | `directories.documents` | Path to app's documents directory |
 
-## Platform Notes
+## 📱 Platform Notes
 
 For detailed platform-specific information, see **[Platform Notes](./docs/PLATFORM_NOTES.md)**.
 
@@ -588,7 +821,7 @@ Key points:
 - **Android**: Uses `DownloadManager` + Foreground Services + MMKV
 - **Pause/Resume**: Works on both platforms (Android requires server Range header support)
 
-## Troubleshooting
+## ❓ Troubleshooting
 
 <details>
 <summary><strong>Download stuck in "pending" state (Android)</strong></summary>
@@ -629,7 +862,7 @@ See the [Google Play Console Declaration](#google-play-console-declaration) sect
 Add the Proguard rules mentioned in the [Proguard Rules](#proguard-rules) section.
 </details>
 
-## Example App
+## 🧪 Example App
 
 The repository includes a full example app demonstrating all features:
 
@@ -652,7 +885,7 @@ The example app shows:
 - Re-attaching to background tasks
 - File management
 
-## Use Cases
+## 💡 Use Cases
 
 This library is perfect for apps that need reliable file transfers:
 
@@ -663,7 +896,7 @@ This library is perfect for apps that need reliable file transfers:
 - 🎮 **Games** - Download game assets and updates
 - 📱 **Enterprise Apps** - Sync large documents and media
 
-## Migration Guide
+## 🔄 Migration Guide
 
 Upgrading from an older version? Check the [Migration Guide](./MIGRATION.md) for detailed instructions:
 
@@ -674,7 +907,7 @@ Upgrading from an older version? Check the [Migration Guide](./MIGRATION.md) for
 
 See the [Changelog](./CHANGELOG.md) for a complete list of changes in each version.
 
-## Contributing
+## 🤝 Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
@@ -708,12 +941,14 @@ cd example && yarn install
 yarn ios  # or yarn android
 ```
 
-## Authors
+## 👥 Authors
 
 Maintained by [Kesha Antonov](https://github.com/kesha-antonov)
 
 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
+> Please note that this project is maintained in free time. If you find it helpful, please consider [becoming a sponsor](https://github.com/sponsors/kesha-antonov).
+
+## 📄 License
 
 [Apache 2.0](./LICENSE)

package/android/src/main/java/com/eko/Downloader.kt

@@ -248,6 +248,19 @@ class Downloader(private val context: Context, private val storageManager: com.e
     RNBackgroundDownloaderModuleImpl.logD(TAG, "Saved paused state for resumable download $configId at $bytesDownloaded/$bytesTotal bytes")
   }
 
+  /**
+   * Update headers for a paused download.
+   * This allows changing auth tokens before resuming.
+   */
+  fun updatePausedDownloadHeaders(configId: String, headers: Map<String, String>) {
+    val pausedInfo = pausedDownloads[configId] ?: return
+
+    pausedDownloads[configId] = pausedInfo.copy(headers = headers)
+    savePausedDownloads()
+
+    RNBackgroundDownloaderModuleImpl.logD(TAG, "Updated headers for paused download $configId")
+  }
+
   /**
    * Resume a paused download using the background service with HTTP Range headers.
    */
@@ -269,7 +282,8 @@ class Downloader(private val context: Context, private val storageManager: com.e
       pausedInfo.headers,
       pausedInfo.bytesDownloaded,
       pausedInfo.bytesTotal,
-      listener
+      listener,
+      pausedInfo.metadata
     )
 
     RNBackgroundDownloaderModuleImpl.logD(TAG, "Resuming download $configId from ${pausedInfo.bytesDownloaded} bytes via service")
@@ -293,7 +307,8 @@ class Downloader(private val context: Context, private val storageManager: com.e
     headers: Map<String, String>,
     startByte: Long,
     totalBytes: Long,
-    listener: ResumableDownloader.DownloadListener
+    listener: ResumableDownloader.DownloadListener,
+    metadata: String = "{}"
   ) {
     // On Android 14+, use UIDT jobs for better background execution
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
@@ -308,7 +323,8 @@ class Downloader(private val context: Context, private val storageManager: com.e
         destination = destination,
         headers = headers,
         startByte = startByte,
-        totalBytes = totalBytes
+        totalBytes = totalBytes,
+        metadata = metadata
       )
 
       if (scheduled) {
@@ -351,7 +367,8 @@ class Downloader(private val context: Context, private val storageManager: com.e
     url: String,
     destination: String,
     headers: Map<String, String>,
-    listener: ResumableDownloader.DownloadListener
+    listener: ResumableDownloader.DownloadListener,
+    metadata: String = "{}"
   ) {
     startDownloadService(
       configId,
@@ -360,7 +377,8 @@ class Downloader(private val context: Context, private val storageManager: com.e
       headers,
       0L,  // Start from beginning
       -1L, // Total bytes unknown
-      listener
+      listener,
+      metadata
     )
     RNBackgroundDownloaderModuleImpl.logD(TAG, "Started ResumableDownloader for $configId (DownloadManager fallback)")
   }
@@ -372,7 +390,7 @@ class Downloader(private val context: Context, private val storageManager: com.e
     // Check UIDT jobs on Android 14+
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
       if (UIDTDownloadJobService.isActiveJob(configId)) {
-        return UIDTDownloadJobService.pauseJob(configId)
+        return UIDTDownloadJobService.pauseJob(context, configId)
       }
     }
     return downloadService?.pauseDownload(configId) ?: false
@@ -385,7 +403,7 @@ class Downloader(private val context: Context, private val storageManager: com.e
     // Check UIDT jobs on Android 14+
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
       if (UIDTDownloadJobService.isActiveJob(configId)) {
-        return UIDTDownloadJobService.resumeJob(configId, listener)
+        return UIDTDownloadJobService.resumeJob(context, configId, listener)
       }
     }
     executeWhenServiceReady {

package/android/src/main/java/com/eko/RNBGDTaskConfig.kt

@@ -7,6 +7,5 @@ data class RNBGDTaskConfig(
     var url: String,
     var destination: String,
     var metadata: String = "{}",
-    var notificationTitle: String?,
     var reportedBegin: Boolean = false
 ) : Serializable

package/android/src/main/java/com/eko/RNBGDUploadTaskConfig.kt

@@ -14,7 +14,6 @@ data class RNBGDUploadTaskConfig(
     val fieldName: String? = null,
     val mimeType: String? = null,
     val parameters: Map<String, String>? = null,
-    val notificationTitle: String? = null,
     var reportedBegin: Boolean = false,
     var bytesUploaded: Long = 0,
     var bytesTotal: Long = 0,