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

package/CHANGELOG.md

@@ -0,0 +1,294 @@
+# Changelog
+
+## v4.5.3
+
+### ✨ New Features
+
+- **Android: Notification Grouping Mode (`summaryOnly`):** Added `mode` option to `NotificationsGroupingConfig`. Set `mode: 'summaryOnly'` to show only the summary notification for a group while individual download notifications are minimized (ultra-silent, no alert). Useful for keeping the notification shade clean during large batch downloads.
+  - `'individual'` (default) — all notifications shown, current behavior unchanged
+  - `'summaryOnly'` — only the group summary notification is shown with aggregate progress; individual notifications are invisible/silent
+- **Android: Progress-Based Summary Notification:** In `summaryOnly` mode, the group summary notification now displays aggregate progress (total bytes downloaded / total bytes) across all downloads in the group.
+- **Android: Auto-Remove Completed Downloads from Group:** Completed downloads are now automatically removed from notification groups, keeping the summary accurate.
+
+### 🏗️ Architecture Changes
+
+- **JS: `NotificationGroupingMode` Type:** New exported type `'individual' | 'summaryOnly'` for the `mode` field in `NotificationsGroupingConfig`.
+- **Android: Ultra-Silent Notification Channel:** Added `NOTIFICATION_CHANNEL_ULTRA_SILENT_ID` (`IMPORTANCE_MIN`) channel used for individual notifications in `summaryOnly` mode.
+- **Android: `updateSummaryNotificationForGroup()`:** New method that dispatches to the correct summary update strategy based on grouping mode.
+
+---
+
+## v4.5.2
+
+### ✨ New Features
+
+- **Update Headers on Paused Downloads:** Added ability to update headers (e.g., refresh auth tokens) on paused download tasks before resuming. Use `task.setDownloadParams()` to update headers while paused, then `task.resume()` to continue the download with new headers.
+  - **Use case:** User pauses a large download, returns hours/days later when auth token has expired. Now you can refresh the token and resume without restarting the download.
+  - **iOS:** Creates a fresh request with HTTP Range header and updated headers on resume
+  - **Android:** Updates both in-memory headers and persisted paused download state
+
+### 🏗️ Architecture Changes
+
+- **JS: `setDownloadParams()` Now Async:** The `DownloadTask.setDownloadParams()` method is now async and returns `Promise<boolean>` indicating whether native headers were updated (true when task is paused).
+- **Native: Added `updateTaskHeaders` Method:** New native method on iOS and Android to update headers for paused tasks.
+
+### 📚 Documentation
+
+- Added "Updating headers on paused downloads" section to README
+- Added `setDownloadParams()` method documentation to API.md
+- Added iOS "Updating Headers on Paused Downloads" section to PLATFORM_NOTES.md
+
+---
+
+## v4.5.1
+
+### 🏗️ Architecture Changes
+
+- **Android: UIDT Code Refactoring:** Extracted 980-line monolithic `UIDTDownloadJobService.kt` into modular components:
+  - `uidt/UIDTJobState.kt` - Data classes, constants, job registry
+  - `uidt/UIDTNotificationManager.kt` - All notification logic
+  - `uidt/UIDTJobManager.kt` - Job scheduling, cancel, pause, resume
+  - `utils/ProgressUtils.kt` - Progress calculation utilities
+  - Backward compatibility maintained via companion object delegates
+- **Android: Removed Redundant jobScheduler.cancel():** In `pauseJob()`, removed unnecessary `jobScheduler.cancel()` after `jobFinished(params, false)` since `wantsReschedule=false` already tells the system the job is complete.
+
+---
+
+## v4.5.0
+
+### ✨ New Features
+
+- **Android: Global Notification Configuration:** Added `showNotificationsEnabled` and `notificationsGrouping` config options for controlling UIDT notifications globally via `setConfig()`.
+- **Android: Customizable Paused Notification Text:** Added `downloadPaused` to `NotificationTexts` interface for customizing the "Paused" notification text.
+- **Android: Notification Update Throttling:** Notification updates are now synced with `progressInterval` for consistent UI/notification progress display.
+
+### 🐛 Bug Fixes
+
+- **Android: Paused Downloads Continuing in Background:** Fixed paused UIDT downloads continuing to download in background after app restart. Now UIDT job is fully cancelled on pause, with a detached "Paused" notification shown.
+- **Android: Duplicate Notifications After Resume:** Fixed duplicate notifications appearing when resuming downloads after app restart. Now uses stable notification IDs based on `configId.hashCode()`.
+- **Android: Notification Not Updating After Resume:** Fixed notification stuck on old progress after resuming. Now resets notification timing on resume and shows correct progress immediately.
+- **Android: Notification Updating While Paused:** Fixed notification progress updating even when download is paused.
+- **Android: Stale Notifications on App Close:** All download notifications are now cancelled when the app closes via `invalidate()`.
+
+### 💥 Breaking Changes
+
+- **Removed Per-Task Notification Options:** `isNotificationVisible` and `notificationTitle` removed from `DownloadParams` and `UploadParams`. Use global `setConfig({ showNotificationsEnabled, notificationsGrouping })` instead.
+
+### 🏗️ Architecture Changes
+
+- **Android: Pause Behavior on Android 14+:** Complete redesign of pause/resume for User-Initiated Data Transfer (UIDT) jobs:
+  - **Problem:** UIDT jobs continue running in background even after app closes, causing "paused" downloads to secretly continue downloading.
+  - **Solution:** On pause, the UIDT job is properly terminated via `jobFinished(params, false)`. Download state is persisted to disk for resumption via HTTP Range headers.
+  - **UX:** A detached "Paused" notification (using `JOB_END_NOTIFICATION_POLICY_DETACH`) remains visible after job termination. On resume, a new UIDT job is created.
+  - **Follows Google's UIDT best practices:** State saved even without `onStopJob`, `jobFinished()` called on completion, notifications updated periodically with throttling.
+- **Android: Separate Notification Channels:** Added separate channels for visible (`IMPORTANCE_LOW`) and silent (`IMPORTANCE_MIN`) notifications.
+
+### ✨ Improvements
+
+- **Android: Cleaner Notifications:** Added `setOnlyAlertOnce(true)` and `setShowWhen(false)` to all notifications for less intrusive updates.
+- **Example App: Persistent Notification Settings:** Show Notifications and Notification Grouping toggles are now persisted with MMKV.
+- **Example App: Android 13+ Permission Request:** Added POST_NOTIFICATIONS permission request when enabling notifications.
+
+### 📚 Documentation
+
+- Updated README with notification behavior during pause/resume
+- Updated API.md with new notification configuration options
+- Documented that notifications are removed when app closes
+
+---
+
+## v4.4.5
+
+### 🐛 Bug Fixes
+
+- **Android: Stop Task Not Working on Android 14+:** Fixed `stopTask()` not actually stopping UIDT downloads on Android 14+. The JobScheduler job was cancelled but the underlying HTTP download continued. Now properly calls `resumableDownloader.cancel()` before removing from active jobs.
+- **Android: Paused Tasks Not Persisting Across App Restarts:** Fixed paused UIDT downloads losing their state when the app was restarted. Added `getJobDownloadState()` to retrieve download state from active UIDT jobs and `savePausedDownloadState()` to properly persist pause state.
+- **Android: ACCESS_NETWORK_STATE Permission:** Added missing permission required for JobScheduler network connectivity constraints on Android 14+.
+- **Android: Downloaded Files List Showing Incomplete Files:** The "Downloaded Files" section in the example app now correctly filters out files that have active (non-DONE) download tasks, preventing incomplete files from appearing in the list.
+
+### 🧹 Code Cleanup
+
+- **Removed Verbose Debug Logs:** Cleaned up extensive debug logging in `StorageManager`, `Downloader`, and `RNBackgroundDownloaderModuleImpl` that was cluttering production logs. Removed serialization/deserialization logs, verification reads, and per-item iteration logs while keeping error logging.
+- **Simplified Kotlin Code:** Removed unnecessary `else` blocks containing only debug/warning logs from `pauseTask()` and `resumeTask()` methods for cleaner code.
+
+### ✨ Improvements
+
+- **TypeScript: Added `destination` to Task Info:** The `destination` field is now returned from `getExistingDownloadTasks()` for paused downloads, allowing the app to know where the file will be saved.
+
+### 📚 Documentation
+
+- Added `skipMmkvDependency` option documentation to README for Expo plugin
+
+---
+
+## v4.4.4
+
+### 🐛 Bug Fixes
+
+- **Expo Plugin: Fixed TypeScript Types:** Corrected TypeScript type definitions in the Expo config plugin.
+
+---
+
+## v4.4.3
+
+### ✨ New Features
+
+- **Expo Plugin: Auto-detect react-native-mmkv:** The Expo config plugin now automatically detects if `react-native-mmkv` is installed and skips adding the MMKV dependency to avoid duplicate class errors. Use `skipMmkvDependency: true` option to manually skip if needed.
+- **Android: Version from package.json:** Android native code now reads the library version from `package.json` instead of hardcoding it.
+
+---
+
+## v4.4.2
+
+### 🐛 Bug Fixes
+
+- **Kotlin 2.0 Compatibility:** Fixed compilation error with Kotlin 2.0 (React Native 0.77+) by updating `progressReporter` to use named parameter syntax. This ensures compatibility with both Kotlin 1.9 (RN 0.76) and Kotlin 2.x (RN 0.77+).
+
+---
+
+## v4.4.1
+
+### 🐛 Bug Fixes
+
+- **Android: Paused Tasks Persistence:** Fixed paused downloads not being restored after app restart on Android. Added persistent storage for paused download state using MMKV/SharedPreferences.
+- **iOS: Improved Pause/Resume Handling:** Better handling of pause/resume operations on app restarts for iOS.
+- **Upload Task App Restart Recovery:** Fixed upload tasks not being recoverable after app restart (#143). Added persistent storage for upload task configurations.
+
+### ✨ Improvements
+
+- **Example App:** Added task list display with animations and improved UI for managing downloads.
+
+### 📚 Documentation
+
+- Updated README with clearer MMKV dependency instructions
+- Added information about resuming tasks after app restarts
+- Updated authors section
+
+---
+
+## v4.4.0
+
+### ✨ New Features
+
+- **Android 16 UIDT Support:** Downloads are now automatically marked as User-Initiated Data Transfers on Android 16+ (API 36) to prevent thermal throttling and job quota restrictions. Downloads will continue reliably even under moderate thermal conditions (~40°C).
+
+### 🐛 Bug Fixes
+
+- **iOS MMKV Conflict Fix:** Removed hard MMKV dependency from iOS podspec to prevent symbol conflicts with `react-native-mmkv`. Apps using `react-native-mmkv` no longer experience crashes (EXC_BAD_ACCESS) on iOS.
+
+### 📦 Dependencies & Infrastructure
+
+- **New Android Permission:** Added `RUN_USER_INITIATED_JOBS` permission for Android 16+ UIDT support
+- **iOS MMKV Dependency:** MMKV is no longer a hard dependency in the podspec. Apps not using `react-native-mmkv` must add `pod 'MMKV', '>= 1.0.0'` to their Podfile.
+
+### 📚 Documentation
+
+- Added documentation about Android 16+ UIDT support in README
+- Added iOS MMKV dependency section in README (similar to Android section)
+- Added migration guide for iOS MMKV dependency change
+
+---
+
+## v4.2.0
+
+> 📖 **Upgrading from v4.1.x?** See the [Migration Guide](./MIGRATION.md) for details on the new Android pause/resume functionality.
+
+### ✨ New Features
+
+- **Android Pause/Resume Support:** Android now fully supports `task.pause()` and `task.resume()` methods using HTTP Range headers. Downloads can be paused and resumed just like on iOS.
+- **Background Download Service:** Added `ResumableDownloadService` - a foreground service that ensures downloads continue even when the app is in the background or the screen is off.
+- **WakeLock Support:** Downloads maintain a partial wake lock to prevent the device from sleeping during active downloads.
+- **`bytesTotal` Unknown Size Handling:** When the server doesn't provide a `Content-Length` header, `bytesTotal` now returns `-1` instead of `0` to distinguish "unknown size" from "zero bytes".
+
+### 🐛 Bug Fixes
+
+- **Android Pause Error:** Fixed `COULD_NOT_FIND` error when pausing downloads on Android by properly tracking pausing state
+- **Temp File Cleanup:** Fixed temp files (`.tmp`) not being deleted when stopping or deleting paused downloads
+- **Content-Length Handling:** Fixed progress percentage calculation when server doesn't provide Content-Length header
+
+### 📦 Dependencies & Infrastructure
+
+- **New Android Permissions:** Added `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_DATA_SYNC`, and `WAKE_LOCK` permissions for background download support
+- **New Service:** Added `ResumableDownloadService` with `dataSync` foreground service type
+
+### 📚 Documentation
+
+- Updated README to reflect Android pause/resume support
+- Removed "iOS only" notes from pause/resume documentation
+- Added documentation about `bytesTotal` returning `-1` for unknown sizes
+- Updated Android DownloadManager Limitations section with new pause/resume implementation details
+
+---
+
+## v4.1.0
+
+> 📖 **Upgrading from v4.0.x?** See the [Migration Guide](./MIGRATION.md) for the MMKV dependency change.
+
+### ⚠️ Breaking Changes
+
+- **MMKV Dependency Changed to `compileOnly`:** The MMKV dependency is now `compileOnly` instead of `implementation` to avoid duplicate class errors when the app also uses `react-native-mmkv`. Apps not using `react-native-mmkv` must now explicitly add the MMKV dependency.
+
+### ✨ New Features
+
+- **Expo Plugin Android Support:** The Expo config plugin now automatically adds the MMKV dependency on Android. Use `addMmkvDependency: false` option if you're already using `react-native-mmkv`.
+
+### 🐛 Bug Fixes
+
+- **Duplicate Class Errors:** Fixed potential duplicate class errors when app uses both this library and `react-native-mmkv` by changing MMKV to `compileOnly` dependency
+
+### 📚 Documentation
+
+- Added documentation for MMKV dependency requirements in README
+- Updated Platform-Specific Limitations section with MMKV setup instructions
+- Added Expo plugin options documentation
+
+---
+
+## v4.0.0
+
+> 📖 **Upgrading from v3.x?** See the [Migration Guide](./MIGRATION.md) for detailed instructions.
+
+### ⚠️ Breaking Changes
+
+- **API Renamed:** `checkForExistingDownloads()` → `getExistingDownloadTasks()` - Now returns a Promise with better naming
+- **API Renamed:** `download()` → `createDownloadTask()` - Downloads now require explicit `.start()` call
+- **Download Tasks Start Explicitly:** Tasks created with `createDownloadTask()` are now in `PENDING` state and must call `.start()` to begin downloading
+- **New Config Option:** Added `progressMinBytes` to `setConfig()` - controls minimum bytes change before progress callback fires (default: 1MB)
+- **Source Structure Changed:** Code moved from `lib/` to `src/` directory with proper TypeScript types
+
+### ✨ New Features
+
+- **React Native New Architecture Support:** Full TurboModules support for both iOS and Android
+- **Expo Config Plugin:** Added automatic iOS native code integration for Expo projects via `app.plugin.js`
+- **Android Kotlin Migration:** All Java code converted to Kotlin
+- **`maxRedirects` Option:** Configure maximum redirects for Android downloads (resolves #15)
+- **`progressMinBytes` Option:** Hybrid progress reporting - callbacks fire based on time interval OR bytes downloaded
+- **Android 15+ Support:** Added support for 16KB memory page sizes
+- **Architecture Fallback:** Comprehensive x86/ARMv7 support with SharedPreferences fallback
+
+### 🐛 Bug Fixes
+
+- **iOS Pause/Resume:** Fixed pause and resume functionality on iOS
+- **RN 0.78+ Compatibility:** Fixed bridge checks with safe emitter checks
+- **New Architecture Events:** Fixed `downloadBegin` and `downloadProgress` events emission
+- **Android Background Downloads:** Fixed completed files not moving to destination
+- **Progress Callback Unknown Total:** Fixed progress callback not firing when total bytes unknown
+- **Android 12 MMKV Crash:** Added robust error handling
+- **`checkForExistingDownloads` TypeError:** Fixed TypeError on Android with architecture fallback
+- **Firebase Performance Compatibility:** Fixed `completeHandler` method compatibility on Android
+- **Slow Connection Handling:** Better handling of slow-responding URLs with timeouts
+- **Android OldArch Export:** Fixed module method export issue (#79)
+- **MMKV Compatibility:** Support for react-native-mmkv 4+ with mmkv-shared dependency
+
+### 📦 Dependencies & Infrastructure
+
+- **React Native:** Updated example app to RN 0.81.4
+- **TypeScript:** Full TypeScript types in `src/types.ts`
+- **iOS Native:** Converted from `.m` to `.mm` (Objective-C++)
+- **Package Manager:** Switched to yarn as preferred package manager
+
+### 📚 Documentation
+
+- Added documentation for `progressMinBytes` option
+- Updated README for React Native 0.77+ instructions
+- Improved Expo config plugin examples

package/README.md

@@ -15,14 +15,14 @@
 <h1 align="center">React Native Background Downloader</h1>
 
 <p align="center">
-  Download and upload large files on iOS & Android — even when your app is in the background or terminated.
+  Download and upload large files on iOS & Android — even when your app is in the background or terminated by the OS.
 </p>
 
 ---
 
 ## ✨ Features
 
-- 📥 **Background Downloads** - Downloads continue even when app is in background or terminated
+- 📥 **Background Downloads** - Downloads continue even when app is in background or terminated by the OS
 - 📤 **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
@@ -37,7 +37,7 @@
 **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.
 
 **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
+- **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 by the OS. Note: if the user explicitly force-kills the app via the App Switcher, iOS cancels all background tasks — this is an iOS system limitation that cannot be overridden
 - **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
 
 **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.
@@ -53,6 +53,7 @@
 - [📦 Installation](#-installation)
   - [Expo Projects](#expo-projects)
   - [Bare React Native Projects](#bare-react-native-projects)
+    - [MMKV version comparison](#mmkv-version-comparison)
 - [🚀 Usage](#-usage)
   - [Downloading a file](#downloading-a-file)
   - [Re-Attaching to background tasks](#re-attaching-to-background-tasks)
@@ -113,7 +114,7 @@ export default {
   expo: {
     plugins: [
       ["@kesha-antonov/react-native-background-downloader", {
-        mmkvVersion: "2.2.4",  // Customize MMKV version on Android
+        mmkvVersion: "1.3.16",  // Customize MMKV version on Android
         skipMmkvDependency: true  // Skip if you want to add MMKV manually
       }]
     ]
@@ -123,8 +124,8 @@ export default {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `mmkvVersion` | string | `'2.2.4'` | The version of [MMKV](https://github.com/Tencent/MMKV/releases) to use on Android. |
-| `skipMmkvDependency` | boolean | `false` | Skip adding MMKV dependency. Set to `true` if you're using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) to avoid duplicate class errors. The plugin auto-detects `react-native-mmkv` but you can use this option to explicitly skip. |
+| `mmkvVersion` | string | `'1.3.16'` | The version of [MMKV](https://github.com/Tencent/MMKV/releases) to use on Android. See [MMKV version comparison](#mmkv-version-comparison) for details. |
+| `skipMmkvDependency` | boolean | `false` | Skip adding MMKV dependency. Set to `true` if you're using [react-native-mmkv](https://github.com/mrousavy/react-native-mmkv) to avoid duplicate class errors. The plugin auto-detects `react-native-mmkv` but you can use this option to explicitly skip. See [MMKV version comparison](#mmkv-version-comparison). |
 
 </details>
 
@@ -214,11 +215,29 @@ Add MMKV to your `android/app/build.gradle`:
 
 ```gradle
 dependencies {
-    implementation 'com.tencent:mmkv-shared:2.2.4'
+    implementation 'com.tencent:mmkv-shared:1.3.16'
 }
 ```
 
-> **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.
+> **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. Note that `react-native-mmkv` v4.x uses [Margelo's fork of MMKV](https://github.com/margelo/MMKV) (`io.github.zhongwuzw:mmkv`) which re-adds armeabi-v7a (32-bit ARM) support that was dropped in the official MMKV 2.x release.
+
+> **⚠️ armeabi-v7a (32-bit ARM) users:** MMKV 2.x dropped 32-bit ABI support (since v2.0.0). If you need armeabi-v7a support and get a CMake error like `No compatible library found for //mmkv/mmkv`, use the MMKV 1.3.x LTS series instead — it supports both armeabi-v7a **and** 16KB page sizes (since v1.3.14):
+> ```gradle
+> dependencies {
+>     implementation 'com.tencent:mmkv-shared:1.3.16'
+> }
+> ```
+
+#### MMKV version comparison
+
+| Dependency | armeabi-v7a (32-bit) | arm64-v8a | 16KB page size | Recommended for |
+|---|:---:|:---:|:---:|---|
+| `com.tencent:mmkv-shared:1.3.16` (**default**) | ✅ | ✅ | ✅ (since 1.3.14) | Most apps — broadest device coverage |
+| `com.tencent:mmkv-shared:2.x` | ❌ | ✅ | ✅ | 64-bit only apps (no legacy devices) |
+| `io.github.zhongwuzw:mmkv:2.3.0` ([Margelo fork](https://github.com/margelo/MMKV)) | ✅ | ✅ | ✅ | Used automatically by `react-native-mmkv` v4.x — skip manual dependency |
+| `react-native-mmkv` (already in project) | ✅ | ✅ | ✅ | If you already use `react-native-mmkv` — skip Step 4 entirely |
+
+**TL;DR:** Use the default `1.3.16`. If you already have `react-native-mmkv` in your project, skip Step 4.
 
 ## 🚀 Usage
 
@@ -836,6 +855,8 @@ This can happen with slow-responding servers. The library automatically adds kee
 <summary><strong>Duplicate class errors with react-native-mmkv (Android)</strong></summary>
 
 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.
+
+`react-native-mmkv` v4.x uses [Margelo's fork of MMKV](https://github.com/margelo/MMKV) (`io.github.zhongwuzw:mmkv`) which re-adds armeabi-v7a (32-bit ARM) support, so you have full ABI coverage including 32-bit devices when using `react-native-mmkv`.
 </details>
 
 <details>

package/android/build.gradle

@@ -36,6 +36,8 @@ android {
         versionName '1.0'
 
         // Support for 16KB memory page sizes (Android 15+)
+        // Note: MMKV 2.x dropped armeabi-v7a support. If your app targets armeabi-v7a,
+        // downgrade to MMKV 1.x in your app's build.gradle (see README for details).
         ndk {
             abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
         }
@@ -78,8 +80,8 @@ dependencies {
     // MMKV dependency for persistent download state storage
     // Uses compileOnly to avoid duplicate class errors when app also uses react-native-mmkv
     // The app must provide MMKV dependency (either directly or via react-native-mmkv)
-    // MMKV 2.0.0+ is required for 16KB memory page size support (Android 15+)
-    compileOnly 'com.tencent:mmkv-shared:2.0.0'
+    // MMKV 1.3.14+ supports both armeabi-v7a (32-bit) and 16KB page sizes (Android 15+)
+    compileOnly 'com.tencent:mmkv-shared:1.3.16'
 
     implementation 'com.google.code.gson:gson:2.12.1'
 }

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

@@ -111,8 +111,18 @@ class Downloader(private val context: Context, private val storageManager: com.e
 
   /**
    * Set the download listener for resumable downloads.
+   * Also sets the UIDT listener on Android 14+ so that ongoing UIDT jobs
+   * (e.g. ones that survived app termination) can forward events to JS after
+   * the app is reopened.
    */
   fun setResumableDownloadListener(listener: ResumableDownloader.DownloadListener) {
+    // For UIDT jobs (Android 14+), set the listener directly on the registry.
+    // This reconnects event forwarding after app restart when UIDT jobs are
+    // already running but UIDTJobRegistry.downloadListener was null in the
+    // fresh process.
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+      UIDTDownloadJobService.downloadListener = listener
+    }
     executeWhenServiceReady {
       downloadService?.setDownloadListener(listener)
     }

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

@@ -225,6 +225,8 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
     }
 
     override fun onComplete(id: String, location: String, bytesDownloaded: Long, bytesTotal: Long) {
+      // Drop any buffered progress for this task so it cannot arrive in JS after downloadComplete
+      progressReporter.clearPendingReport(id)
       eventEmitter.emitComplete(id, location, bytesDownloaded, bytesTotal)
 
       // Clean up all download state
@@ -234,6 +236,8 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
     }
 
     override fun onError(id: String, error: String, errorCode: Int) {
+      // Drop any buffered progress for this task so it cannot arrive in JS after downloadFailed
+      progressReporter.clearPendingReport(id)
       eventEmitter.emitFailed(id, error, errorCode)
 
       // Clean up all download state
@@ -385,6 +389,9 @@ class RNBackgroundDownloaderModuleImpl(private val reactContext: ReactApplicatio
           stopTaskProgress(config.id)
 
           synchronized(sharedLock) {
+            // Drop any buffered progress that slipped past stopTaskProgress's clearPendingReport
+            // (the polling thread may have re-added it between clearPendingReport and this lock)
+            progressReporter.clearPendingReport(config.id)
             when (status) {
               DownloadManager.STATUS_SUCCESSFUL -> {
                 onSuccessfulDownload(config, downloadStatus)

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

@@ -148,7 +148,7 @@ class UIDTDownloadJobService : JobService() {
         }
         val url = extras.getString(UIDTConstants.KEY_URL) ?: return false
         val destination = extras.getString(UIDTConstants.KEY_DESTINATION) ?: return false
-        val startByte = extras.getLong(UIDTConstants.KEY_START_BYTE, 0)
+        val startByteFromExtras = extras.getLong(UIDTConstants.KEY_START_BYTE, 0)
         val totalBytes = extras.getLong(UIDTConstants.KEY_TOTAL_BYTES, -1)
 
         // Extract group info from metadata (for notification grouping)
@@ -165,8 +165,36 @@ class UIDTDownloadJobService : JobService() {
             RNBackgroundDownloaderModuleImpl.logE(UIDTConstants.TAG, "Failed to parse metadata: ${e.message}")
         }
 
-        // Retrieve headers
-        val headers = UIDTJobRegistry.pendingHeaders.remove(configId) ?: emptyMap()
+        // Resolve headers and start byte.
+        // In-memory pendingHeaders is populated in the same process (scheduleDownload / onStopJob).
+        // The disk-persisted resume state is the fallback for a fresh process after a restart.
+        val inMemoryHeaders = UIDTJobRegistry.pendingHeaders.remove(configId)
+        val diskResumeState = UIDTJobRegistry.loadResumeState(this, configId)
+        // Clear disk state now that we've consumed it.
+        UIDTJobRegistry.clearResumeState(this, configId)
+
+        val headers: Map<String, String>
+        val startByte: Long
+        when {
+            inMemoryHeaders != null -> {
+                // Same-process restart: use in-memory headers.
+                // Prefer the disk byte position if it is more advanced than the extras
+                // (written by onStopJob with the actual download offset).
+                headers = inMemoryHeaders
+                startByte = if (diskResumeState != null && diskResumeState.second > startByteFromExtras)
+                    diskResumeState.second else startByteFromExtras
+            }
+            diskResumeState != null -> {
+                // Cross-process restart: use the persisted state.
+                headers = diskResumeState.first
+                startByte = diskResumeState.second
+            }
+            else -> {
+                headers = emptyMap()
+                startByte = startByteFromExtras
+            }
+        }
+        RNBackgroundDownloaderModuleImpl.logD(UIDTConstants.TAG, "onStartJob: configId=$configId, startByte=$startByte, headers=${headers.size}")
 
         // Create notification for UIDT job (required)
         val notificationId = UIDTNotificationManager.getNotificationIdForConfig(configId)
@@ -233,8 +261,12 @@ class UIDTDownloadJobService : JobService() {
                 // Save state for potential resume
                 val state = jobState.resumableDownloader.getState(configId)
                 if (state != null) {
-                    // Store resume info
+                    val bytesDownloaded = state.bytesDownloaded.get()
+                    // Keep in-memory headers so the same-process reschedule works.
                     UIDTJobRegistry.pendingHeaders[configId] = state.headers
+                    // Persist to disk so a fresh process can resume from the right position.
+                    UIDTJobRegistry.saveResumeState(this, configId, state.headers, bytesDownloaded)
+                    RNBackgroundDownloaderModuleImpl.logD(UIDTConstants.TAG, "onStopJob: saved resume state for $configId at $bytesDownloaded bytes")
                 }
             }
             UIDTJobRegistry.activeJobs.remove(configId)
@@ -364,6 +396,9 @@ class UIDTDownloadJobService : JobService() {
                 // Signal job completion - this triggers the REMOVE policy
                 jobFinished(params, false)
 
+                // Clear persisted resume state - no longer needed after successful completion
+                UIDTJobRegistry.clearResumeState(this@UIDTDownloadJobService, id)
+
                 // Notify external listener
                 UIDTJobRegistry.downloadListener?.onComplete(id, location, bytesDownloaded, bytesTotal)
             }
@@ -402,6 +437,9 @@ class UIDTDownloadJobService : JobService() {
                 // Signal job completion with no reschedule - this triggers the REMOVE policy
                 jobFinished(params, false)
 
+                // Clear persisted resume state - no longer needed after failure
+                UIDTJobRegistry.clearResumeState(this@UIDTDownloadJobService, id)
+
                 // Notify external listener
                 UIDTJobRegistry.downloadListener?.onError(id, error, errorCode)
             }

package/android/src/main/java/com/eko/uidt/UIDTJobManager.kt

@@ -66,6 +66,9 @@ object UIDTJobManager {
 
         // Store headers for later retrieval (PersistableBundle can't store Map<String, String>)
         UIDTJobRegistry.pendingHeaders[configId] = headers
+        // Also persist to disk so headers survive process death and are available
+        // in onStartJob even when the process is restarted by the JobScheduler.
+        UIDTJobRegistry.saveResumeState(context, configId, headers, startByte)
 
         // Create extras bundle
         val extras = PersistableBundle().apply {
@@ -77,9 +80,14 @@ object UIDTJobManager {
             putString(UIDTConstants.KEY_METADATA, metadata)
         }
 
-        // Build network request - require internet connectivity
+        // Build network request - require internet connectivity.
+        // Remove NET_CAPABILITY_NOT_VPN (added by Builder default) so that VPN networks
+        // (e.g. Proton VPN, full-tunnel VPNs) are accepted. Without this, the JobScheduler
+        // only considers non-VPN networks; a kill-switch VPN blocks that traffic and the
+        // job never starts, causing callbacks to never fire.
         val networkRequest = NetworkRequest.Builder()
             .addCapability(android.net.NetworkCapabilities.NET_CAPABILITY_INTERNET)
+            .removeCapability(android.net.NetworkCapabilities.NET_CAPABILITY_NOT_VPN)
             .build()
 
         // Build the job with UIDT flag
@@ -150,6 +158,8 @@ object UIDTJobManager {
         jobScheduler.cancel(jobId)
         UIDTJobRegistry.pendingHeaders.remove(configId)
         UIDTJobRegistry.activeJobs.remove(configId)
+        // Clear persisted resume state so stale headers/bytes don't affect future downloads
+        UIDTJobRegistry.clearResumeState(context, configId)
 
         // Update summary notification if grouping was enabled
         if (jobState != null && config.groupingEnabled && jobState.groupId.isNotEmpty()) {

package/android/src/main/java/com/eko/uidt/UIDTJobState.kt

@@ -1,7 +1,10 @@
 package com.eko.uidt
 
 import android.app.job.JobParameters
+import android.content.Context
+import com.eko.RNBackgroundDownloaderModuleImpl
 import com.eko.ResumableDownloader
+import org.json.JSONObject
 import java.util.concurrent.ConcurrentHashMap
 
 /**
@@ -127,6 +130,65 @@ data class UIDTJobInfo(
  * Singleton for managing active UIDT jobs state.
  */
 object UIDTJobRegistry {
+
+    private const val PREFS_NAME = "rnbd_uidt_resume"
+    private const val KEY_BYTES_PREFIX = "bytes_"
+    private const val KEY_HEADERS_PREFIX = "headers_"
+
+    /**
+     * Persist UIDT resume state (headers + byte position) to disk so it
+     * survives process death and can be used when the job is rescheduled in a
+     * new process.
+     */
+    fun saveResumeState(context: Context, configId: String, headers: Map<String, String>, bytesDownloaded: Long) {
+        try {
+            val headersJson = JSONObject(headers as Map<*, *>).toString()
+            context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).edit()
+                .putLong("$KEY_BYTES_PREFIX$configId", bytesDownloaded)
+                .putString("$KEY_HEADERS_PREFIX$configId", headersJson)
+                .apply()
+            RNBackgroundDownloaderModuleImpl.logD(UIDTConstants.TAG, "Saved UIDT resume state for $configId: bytes=$bytesDownloaded")
+        } catch (e: Exception) {
+            RNBackgroundDownloaderModuleImpl.logE(UIDTConstants.TAG, "Failed to save UIDT resume state for $configId: ${e.message}")
+        }
+    }
+
+    /**
+     * Load persisted UIDT resume state for a download.
+     * Returns (headers, bytesDownloaded) or null if no state was saved.
+     */
+    fun loadResumeState(context: Context, configId: String): Pair<Map<String, String>, Long>? {
+        try {
+            val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            val bytesDownloaded = prefs.getLong("$KEY_BYTES_PREFIX$configId", -1L)
+            val headersJson = prefs.getString("$KEY_HEADERS_PREFIX$configId", null)
+            if (bytesDownloaded < 0 || headersJson == null) return null
+            val json = JSONObject(headersJson)
+            val headers = mutableMapOf<String, String>()
+            for (key in json.keys()) headers[key] = json.getString(key)
+            RNBackgroundDownloaderModuleImpl.logD(UIDTConstants.TAG, "Loaded UIDT resume state for $configId: bytes=$bytesDownloaded, headers=${headers.size}")
+            return Pair(headers, bytesDownloaded)
+        } catch (e: Exception) {
+            RNBackgroundDownloaderModuleImpl.logE(UIDTConstants.TAG, "Failed to load UIDT resume state for $configId: ${e.message}")
+            return null
+        }
+    }
+
+    /**
+     * Clear persisted UIDT resume state for a download once it is no longer needed.
+     */
+    fun clearResumeState(context: Context, configId: String) {
+        try {
+            context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE).edit()
+                .remove("$KEY_BYTES_PREFIX$configId")
+                .remove("$KEY_HEADERS_PREFIX$configId")
+                .apply()
+            RNBackgroundDownloaderModuleImpl.logD(UIDTConstants.TAG, "Cleared UIDT resume state for $configId")
+        } catch (e: Exception) {
+            RNBackgroundDownloaderModuleImpl.logE(UIDTConstants.TAG, "Failed to clear UIDT resume state for $configId: ${e.message}")
+        }
+    }
+
     // Track active jobs for pause/resume
     val activeJobs = ConcurrentHashMap<String, JobState>()
 

package/ios/RNBackgroundDownloader.mm

@@ -66,6 +66,13 @@ static CompletionHandler storedCompletionHandler;
     // Controls whether debug logs are sent to JS
     BOOL isLogsEnabled;
 
+#ifdef RCT_NEW_ARCH_ENABLED
+    // Queue of events that arrived before the TurboModule event emitter callback was set.
+    // This prevents crashes (std::bad_function_call / SIGABRT) when NSURLSession delegate
+    // callbacks fire before JS has registered event listeners.
+    NSMutableArray<NSDictionary *> *pendingEmitEvents;
+#endif
+
     // Upload-specific instance variables
     NSMutableDictionary<NSNumber *, RNBGDUploadTaskConfig *> *uploadTaskToConfigMap;
     NSMutableDictionary<NSString *, NSURLSessionUploadTask *> *idToUploadTaskMap;
@@ -233,6 +240,10 @@ static const int kMaxEventRetries = 50;  // 50 retries * 100ms = 5 seconds max w
         isSessionActivated = NO;
         pendingDownloads = [[NSMutableArray alloc] init];
 
+#ifdef RCT_NEW_ARCH_ENABLED
+        pendingEmitEvents = [[NSMutableArray alloc] init];
+#endif
+
         // Initialize upload-specific data structures
         NSData *uploadTaskToConfigMapData = [mmkv getDataForKey:ID_TO_UPLOAD_CONFIG_MAP_KEY];
         NSMutableDictionary *uploadTaskToConfigMapDataDefault = [[NSMutableDictionary alloc] init];
@@ -1140,6 +1151,36 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
     }
 }
 
+#ifdef RCT_NEW_ARCH_ENABLED
+#pragma mark - Safe event emission (New Architecture)
+
+// Safely emit an event, queuing it if the TurboModule event emitter callback
+// has not been registered yet. This prevents std::bad_function_call crashes
+// when NSURLSession delegate callbacks fire before JS has registered listeners
+// (e.g., background session delivering completions from a prior app session).
+- (void)safeEmitEvent:(NSString *)eventName value:(id)value {
+    @synchronized (pendingEmitEvents) {
+        if (_eventEmitterCallback) {
+            _eventEmitterCallback(std::string([eventName UTF8String]), value);
+        } else {
+            [pendingEmitEvents addObject:@{@"name": eventName, @"value": value}];
+        }
+    }
+}
+
+- (void)setEventEmitterCallback:(EventEmitterCallbackWrapper *)eventEmitterCallbackWrapper {
+    @synchronized (pendingEmitEvents) {
+        [super setEventEmitterCallback:eventEmitterCallbackWrapper];
+
+        // Flush any events that arrived before the callback was set
+        for (NSDictionary *event in pendingEmitEvents) {
+            _eventEmitterCallback(std::string([event[@"name"] UTF8String]), event[@"value"]);
+        }
+        [pendingEmitEvents removeAllObjects];
+    }
+}
+#endif
+
 #pragma mark - NSURLSessionDownloadDelegate methods
 - (void)URLSession:(nonnull NSURLSession *)session downloadTask:(nonnull NSURLSessionDownloadTask *)downloadTask didFinishDownloadingToURL:(nonnull NSURL *)location {
     @synchronized (sharedLock) {
@@ -1161,6 +1202,9 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
             [self sendDebugLog:[NSString stringWithFormat:@"didFinishDownloadingToURL: error - %@", error.localizedDescription] taskId:taskConfig.id];
         }
 
+        // Drop any buffered progress for this task so it cannot arrive in JS after downloadComplete
+        [progressReports removeObjectForKey:taskConfig.id];
+
         [self sendDownloadCompletionEvent:taskConfig task:downloadTask error:error];
 
         [self removeTaskFromMap:downloadTask];
@@ -1170,7 +1214,7 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
 - (void)sendDownloadCompletionEvent:(RNBGDTaskConfig *)taskConfig task:(NSURLSessionDownloadTask *)task error:(NSError *)error {
     if (error) {
 #ifdef RCT_NEW_ARCH_ENABLED
-        [self emitOnDownloadFailed:@{
+        [self safeEmitEvent:@"onDownloadFailed" value:@{
             @"id": taskConfig.id,
             @"error": [error localizedDescription],
             @"errorCode": @(error.code)
@@ -1184,7 +1228,7 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
 #endif
     } else {
 #ifdef RCT_NEW_ARCH_ENABLED
-        [self emitOnDownloadComplete:@{
+        [self safeEmitEvent:@"onDownloadComplete" value:@{
             @"id": taskConfig.id,
             @"location": taskConfig.destination,
             @"bytesDownloaded": @(task.countOfBytesReceived),
@@ -1243,7 +1287,7 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
         responseHeaders = @{};
     }
 #ifdef RCT_NEW_ARCH_ENABLED
-    [self emitOnDownloadBegin:@{
+    [self safeEmitEvent:@"onDownloadBegin" value:@{
         @"id": taskConfig.id,
         @"expectedBytes": @(expectedBytes),
         @"headers": responseHeaders
@@ -1290,7 +1334,7 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
     NSDate *now = [NSDate date];
     if ([now timeIntervalSinceDate:lastProgressReportedAt] > progressInterval) {
 #ifdef RCT_NEW_ARCH_ENABLED
-        [self emitOnDownloadProgress:[progressReports allValues]];
+        [self safeEmitEvent:@"onDownloadProgress" value:[progressReports allValues]];
 #else
         [self sendEventWithName:@"downloadProgress" body:[progressReports allValues]];
 #endif
@@ -1385,7 +1429,7 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
 
         // Handle failure
 #ifdef RCT_NEW_ARCH_ENABLED
-        [self emitOnDownloadFailed:@{
+        [self safeEmitEvent:@"onDownloadFailed" value:@{
             @"id": taskConfig.id,
             @"error": [error localizedDescription],
             @"errorCode": @(error.code)
@@ -1764,7 +1808,7 @@ RCT_EXPORT_METHOD(getExistingUploadTasks:(RCTPromiseResolveBlock)resolve rejecte
         if (!taskConfig.reportedBegin) {
             taskConfig.reportedBegin = YES;
 #ifdef RCT_NEW_ARCH_ENABLED
-            [self emitOnUploadBegin:@{
+            [self safeEmitEvent:@"onUploadBegin" value:@{
                 @"id": taskConfig.id,
                 @"expectedBytes": @(totalBytesExpectedToSend)
             }];
@@ -1801,7 +1845,7 @@ RCT_EXPORT_METHOD(getExistingUploadTasks:(RCTPromiseResolveBlock)resolve rejecte
             NSDate *now = [NSDate date];
             if ([now timeIntervalSinceDate:lastUploadProgressReportedAt] > progressInterval) {
 #ifdef RCT_NEW_ARCH_ENABLED
-                [self emitOnUploadProgress:[uploadProgressReports allValues]];
+                [self safeEmitEvent:@"onUploadProgress" value:[uploadProgressReports allValues]];
 #else
                 [self sendEventWithName:@"uploadProgress" body:[uploadProgressReports allValues]];
 #endif
@@ -1847,7 +1891,7 @@ RCT_EXPORT_METHOD(getExistingUploadTasks:(RCTPromiseResolveBlock)resolve rejecte
 
             DLog(taskConfig.id, @"[RNBackgroundDownloader] - [handleUploadCompletion] error: %@", error);
 #ifdef RCT_NEW_ARCH_ENABLED
-            [self emitOnUploadFailed:@{
+            [self safeEmitEvent:@"onUploadFailed" value:@{
                 @"id": taskConfig.id,
                 @"error": [error localizedDescription],
                 @"errorCode": @(error.code)
@@ -1873,7 +1917,7 @@ RCT_EXPORT_METHOD(getExistingUploadTasks:(RCTPromiseResolveBlock)resolve rejecte
 
             DLog(taskConfig.id, @"[RNBackgroundDownloader] - [handleUploadCompletion] success, responseCode: %ld", (long)responseCode);
 #ifdef RCT_NEW_ARCH_ENABLED
-            [self emitOnUploadComplete:@{
+            [self safeEmitEvent:@"onUploadComplete" value:@{
                 @"id": taskConfig.id,
                 @"responseCode": @(responseCode),
                 @"responseBody": responseBody,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kesha-antonov/react-native-background-downloader",
-  "version": "4.5.3",
+  "version": "4.5.4",
   "description": "A library for React-Native to help you download large files on iOS and Android both in the foreground and most importantly in the background.",
   "keywords": [
     "react-native",

package/plugin/build/index.d.ts

@@ -3,12 +3,12 @@ interface PluginOptions {
     /**
      * Options for the MMKV dependency on Android.
      * Pass a string to specify the version, or an object with version property.
-     * @default '2.2.4'
+     * @default '1.3.16'
      * @example
      * // Use default version
      * ["@kesha-antonov/react-native-background-downloader"]
      * // Specify version
-     * ["@kesha-antonov/react-native-background-downloader", { mmkvVersion: "2.2.4" }]
+     * ["@kesha-antonov/react-native-background-downloader", { mmkvVersion: "1.3.16" }]
      */
     mmkvVersion?: string;
     /**

package/plugin/build/index.js

@@ -37,7 +37,7 @@ const config_plugins_1 = require("@expo/config-plugins");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const withRNBackgroundDownloader = (config, options) => {
-    const { mmkvVersion = '2.2.4', skipMmkvDependency = false } = options || {};
+    const { mmkvVersion = '1.3.16', skipMmkvDependency = false } = options || {};
     // Auto-detect react-native-mmkv in dependencies
     const hasReactNativeMmkv = checkForReactNativeMmkv(config);
     const shouldSkipMmkv = skipMmkvDependency || hasReactNativeMmkv;

package/plugin/package.json

@@ -1,6 +0,0 @@
-{
-  "name": "@kesha-antonov/react-native-background-downloader-expo-plugin",
-  "version": "1.0.0",
-  "main": "build/index.js",
-  "types": "build/index.d.ts"
-}