@kesha-antonov/react-native-background-downloader 3.2.6 → 4.0.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## v4.0.0-alpha.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

@@ -1,7 +1,32 @@
-![react-native-background-downloader banner](https://d1w2zhnqcy4l8f.cloudfront.net/content/falcon/production/projects/V5EEOX_fast/RNBD-190702083358.png)
+
+<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-alpha.0 Released!
+
+**v4.0.0-alpha.0** is now available with full **React Native New Architecture (TurboModules)** support!
+
+> ⚠️ **Alpha Release:** This version is in alpha state. Please report any issues you encounter.
+
+### 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 large files on iOS and Android both in the foreground and most importantly in the background.
@@ -41,6 +66,35 @@ Then:
 cd ios && pod install
 ```
 
+#### Manual Setup (Advanced)
+If you need to manually configure the package for New Architecture:
+
+**iOS**: The library automatically detects New Architecture via compile-time flags.
+
+**Android**: For New Architecture, you can optionally use `RNBackgroundDownloaderTurboPackage` instead of the default package:
+```java
+import com.eko.RNBackgroundDownloaderTurboPackage;
+
+// In your MainApplication.java
+@Override
+protected List<ReactPackage> getPackages() {
+  return Arrays.<ReactPackage>asList(
+    // ... other packages
+    new RNBackgroundDownloaderTurboPackage() // For New Architecture
+  );
+}
+```
+
+#### 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.
+
 ### Mostly automatic installation
 Any React Native version **`>= 0.60`** supports autolinking so nothing should be done.
 
@@ -76,21 +130,99 @@ For anything **`< 0.60`** run the following link command
 </details>
 
 ### iOS - Extra Mandatory Step
-In your `AppDelegate.m` add the following code:
-```objc
-...
-#import <RNBackgroundDownloader.h>
 
-...
+#### 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 iOS native code:
 
-- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)(void))completionHandler
+**In your `app.json`:**
+```json
 {
-  [RNBackgroundDownloader setCompletionHandlerWithIdentifier:identifier completionHandler:completionHandler];
+  "expo": {
+    "name": "Your App",
+    "plugins": [
+      "@kesha-antonov/react-native-background-downloader"
+    ]
+  }
 }
+```
 
-...
+**Or in your `app.config.js`:**
+```js
+export default {
+  expo: {
+    name: "Your App",
+    plugins: [
+      "@kesha-antonov/react-native-background-downloader"
+    ]
+  }
+}
 ```
-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.
+
+The plugin will automatically:
+- Add the required import to your AppDelegate (Objective-C) or Bridging Header (Swift)
+- Add the `handleEventsForBackgroundURLSession` method to your AppDelegate
+- Handle both React Native < 0.77 (Objective-C) and >= 0.77 (Swift) projects
+
+After adding the plugin, run:
+```bash
+expo prebuild --clean
+```
+
+#### Option 2: Manual Setup
+
+<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:
+
+  ```objc
+  ...
+  #import <RNBackgroundDownloader.h>
+  ```
+
+  Then in your `AppDelegate.swift` add the following method inside of your `AppDelegate` class:
+
+  ```swift
+  ...
+
+  @main
+  class AppDelegate: UIResponder, UIApplicationDelegate
+    ...
+
+    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>
+
+  In your `AppDelegate.m` add the following code:
+  ```objc
+  ...
+  #import <RNBackgroundDownloader.h>
+
+  ...
+
+  - (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>
 
 ## Usage
 
@@ -98,11 +230,11 @@ Failing to add this code will result in canceled background downloads. If Xcode
 
 ```javascript
 import { Platform } from 'react-native'
-import { download, completeHandler, directories } from '@kesha-antonov/react-native-background-downloader'
+import { createDownloadTask, completeHandler, directories } from '@kesha-antonov/react-native-background-downloader'
 
 const jobId = 'file123'
 
-let task = download({
+let task = createDownloadTask({
   id: jobId,
   url: 'https://link-to-very.large/file.zip',
   destination: `${directories.documents}/file.zip`,
@@ -122,16 +254,64 @@ let task = download({
   console.log('Download canceled due to error: ', { error, errorCode });
 })
 
+// starts download
+task.start()
+
 // Pause the task (iOS only)
+// Note: On Android, pause/resume is not supported by DownloadManager
 task.pause()
 
 // Resume after pause (iOS only)
+// Note: On Android, pause/resume is not supported by DownloadManager
 task.resume()
 
 // Cancel the task
 task.stop()
 ```
 
+### Platform-Aware Pause/Resume
+
+```javascript
+import { Platform } from 'react-native'
+import { createDownloadTask, directories } from '@kesha-antonov/react-native-background-downloader'
+
+const task = createDownloadTask({
+  id: 'file123',
+  url: 'https://link-to-very.large/file.zip',
+  destination: `${directories.documents}/file.zip`,
+  metadata: {}
+}).begin(({ expectedBytes, headers }) => {
+  console.log(`Going to download ${expectedBytes} bytes!`)
+}).progress(({ bytesDownloaded, bytesTotal }) => {
+  console.log(`Downloaded: ${bytesDownloaded / bytesTotal * 100}%`)
+}).done(({ bytesDownloaded, bytesTotal }) => {
+  console.log('Download is done!', { bytesDownloaded, bytesTotal })
+}).error(({ error, errorCode }) => {
+  console.log('Download canceled due to error: ', { error, errorCode });
+})
+
+task.start()
+
+// Platform-aware pause/resume handling
+function pauseDownloadTask() {
+  if (Platform.OS === 'ios') {
+    task.pause()
+    console.log('Download paused')
+  } else {
+    console.log('Pause not supported on Android. Consider using stop() instead.')
+  }
+}
+
+function resumeDownloadTask() {
+  if (Platform.OS === 'ios') {
+    task.resume()
+    console.log('Download resumed')
+  } else {
+    console.log('Resume not supported on Android. You may need to restart the download.')
+  }
+}
+```
+
 ### Re-Attaching to background downloads
 
 This is the main selling point of this library (but it's free!).
@@ -141,9 +321,9 @@ What happens to your downloads after the OS stopped your app? Well, they are sti
 Add this code to app's init stage, and you'll never lose a download again!
 
 ```javascript
-import RNBackgroundDownloader from '@kesha-antonov/react-native-background-downloader'
+import { getExistingDownloadTasks } from '@kesha-antonov/react-native-background-downloader'
 
-let lostTasks = await RNBackgroundDownloader.checkForExistingDownloads()
+let lostTasks = await getExistingDownloadTasks()
 for (let task of lostTasks) {
   console.log(`Task ${task.id} was found!`)
   task.progress(({ bytesDownloaded, bytesTotal }) => {
@@ -161,9 +341,11 @@ for (let task of lostTasks) {
 ### Using custom headers
 If you need to send custom headers with your download request, you can do in it 2 ways:
 
-1) Globally using `RNBackgroundDownloader.setConfig()`:
+1) Globally using `setConfig()`:
 ```javascript
-RNBackgroundDownloader.setConfig({
+import { setConfig } from '@kesha-antonov/react-native-background-downloader'
+
+setConfig({
   headers: {
     Authorization: 'Bearer 2we$@$@Ddd223',
   }
@@ -171,12 +353,14 @@ RNBackgroundDownloader.setConfig({
 ```
 This way, all downloads with have the given headers.
 
-2) Per download by passing a headers object in the options of `RNBackgroundDownloader.download()`:
+2) Per download by passing a headers object in the options of `createDownloadTask()`:
 ```javascript
-let task = RNBackgroundDownloader.download({
+import { createDownloadTask, directories } from '@kesha-antonov/react-native-background-downloader'
+
+const task = createDownloadTask({
   id: 'file123',
   url: 'https://link-to-very.large/file.zip'
-  destination: `${RNBackgroundDownloader.directories.documents}/file.zip`,
+  destination: `${directories.documents}/file.zip`,
   headers: {
     Authorization: 'Bearer 2we$@$@Ddd223'
   }
@@ -189,14 +373,93 @@ let task = RNBackgroundDownloader.download({
 }).error(({ error, errorCode }) => {
   console.log('Download canceled due to error: ', { error, errorCode })
 })
+
+task.start()
+```
+Headers given in `createDownloadTask()` are **merged** with the ones given in `setConfig({ headers: { ... } })`.
+
+### Handling Slow-Responding URLs
+
+This library automatically includes connection timeout improvements for slow-responding URLs. By default, the following headers are added to all download requests on Android:
+
+- `Connection: keep-alive` - Keeps the connection open for better handling
+- `Keep-Alive: timeout=600, max=1000` - Sets a 10-minute keep-alive timeout
+- `User-Agent: ReactNative-BackgroundDownloader/3.2.6` - Proper user agent for better server compatibility
+
+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)
+
+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.).
+
+To handle this, you can use the `maxRedirects` option to pre-resolve redirects before passing the final URL to DownloadManager:
+
+```javascript
+import { Platform } from 'react-native'
+import { createDownloadTask, directories } from '@kesha-antonov/react-native-background-downloader'
+
+// Example: Podcast URL with multiple redirects
+const task = createDownloadTask({
+  id: 'podcast-episode',
+  url: 'https://pdst.fm/e/chrt.fm/track/479722/arttrk.com/p/example.mp3',
+  destination: `${directories.documents}/episode.mp3`,
+  maxRedirects: 10, // Follow up to 10 redirects before downloading
+}).begin(({ expectedBytes }) => {
+  console.log(`Going to download ${expectedBytes} bytes!`)
+}).progress(({ bytesDownloaded, bytesTotal }) => {
+  console.log(`Downloaded: ${bytesDownloaded / bytesTotal * 100}%`)
+}).done(({ bytesDownloaded, bytesTotal }) => {
+  console.log('Download is done!', { bytesDownloaded, bytesTotal })
+}).error(({ error, errorCode }) => {
+  console.log('Download canceled due to error: ', { error, errorCode })
+
+  if (errorCode === 1005) { // ERROR_TOO_MANY_REDIRECTS
+    console.log('Consider increasing maxRedirects or using a different URL')
+  }
+})
+
+task.start()
 ```
-Headers given in the `download` function are **merged** with the ones given in `setConfig({ headers: { ... } })`.
+
+**Notes on maxRedirects:**
+- Only available on Android (iOS handles redirects automatically)
+- If not specified or set to 0, no redirect resolution is performed
+- Uses HEAD requests to resolve redirects efficiently
+- Falls back to original URL if redirect resolution fails
+- Respects the same headers and timeouts as the main download
 
 ## API
 
-### RNBackgroundDownloader
+### Named Exports
+
+The library exports the following functions and objects:
+
+```typescript
+import {
+  setConfig,
+  createDownloadTask,
+  getExistingDownloadTasks,
+  ensureDownloadsAreRunning,
+  completeHandler,
+  directories
+} from '@kesha-antonov/react-native-background-downloader'
+```
+
+**Default Export:**
+
+```typescript
+import RNBackgroundDownloader from '@kesha-antonov/react-native-background-downloader'
 
-### `download(options)`
+// Contains all the above as properties:
+RNBackgroundDownloader.setConfig
+RNBackgroundDownloader.createDownloadTask
+RNBackgroundDownloader.getExistingDownloadTasks
+RNBackgroundDownloader.ensureDownloadsAreRunning
+RNBackgroundDownloader.completeHandler
+RNBackgroundDownloader.directories
+```
+
+### `createDownloadTask(options)`
 
 Download a file to destination
 
@@ -206,11 +469,12 @@ 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 |
+| `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 |
-| `metadata`    | Object |           |    All    | Data to be preserved on reboot. |
-| `headers`     | Object |           |    All    | Costume headers to add to the download request. These are merged with the headers given in the `setConfig({ headers: { ... } })` function |
+| `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 |
@@ -218,47 +482,65 @@ An object containing options properties
 
 **returns**
 
-`DownloadTask` - The download task to control and monitor this download
+`DownloadTask` - The download task to control and monitor this download. Call `task.start()` to begin the download.
 
-### `checkForExistingDownloads()`
+### `getExistingDownloadTasks()`
 
-Checks for downloads that ran in background while you app was terminated. And also forces them to resume downloads.
+Checks for downloads that ran in background while your app was terminated.
 
 Recommended to run at the init stage of the app.
 
 **returns**
 
-`DownloadTask[]` - Array of tasks that were running in the background so you can re-attach callbacks to them
+`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
+
+### `setConfig(config)`
+
+Sets global configuration for the downloader.
 
-### `setConfig({})`
+**config**
+
+An object containing configuration properties
 
 | Name           | Type   | Info                                                                                                 |
 | -------------- | ------ | ---------------------------------------------------------------------------------------------------- |
-| `headers`     | Object | optional headers to use in all future downloads |
-| `progressInterval` | Number | Interval in which download progress sent from downloader. Number should be >= 250. It's in ms |
-| `isLogsEnabled`   | Boolean | Enables/disables logs in library |
+| `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 debug logs in library. Default is false |
 
 ### DownloadTask
 
-A class representing a download task created by `RNBackgroundDownloader.download`
+A class representing a download task created by `createDownloadTask()`. Note: You must call `task.start()` to begin the download after setting up event handlers.
 
 ### `Members`
 | Name           | Type   | Info                                                                                                 |
 | -------------- | ------ | ---------------------------------------------------------------------------------------------------- |
-| `id`           | String | The id you gave the task when calling `RNBackgroundDownloader.download`                              |
-| `metadata`     | Object | The metadata you gave the task when calling `RNBackgroundDownloader.download`                        |
+| `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 |
+| `downloadParams` | DownloadParams | The download parameters set for this task |
 
-### `completeHandler(jobId)`
+### `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.
 
-### `ensureDownloadsAreRunning` (iOS only)
+**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.
+
+### `ensureDownloadsAreRunning()` (iOS only)
 
 Pauses and resumes all downloads - this is fix for stuck downloads. Use it when your app loaded and is ready for handling downloads (all your logic loaded and ready to handle download callbacks).
 
+**returns**
+
+`Promise<void>` - A promise that resolves when all downloads have been paused and resumed
+
 Here's example of how you can use it:
 
 1. When your app just loaded
@@ -266,7 +548,9 @@ Here's example of how you can use it:
 Either stop all tasks:
 
 ```javascript
-const tasks = await checkForExistingDownloads()
+import { getExistingDownloadTasks } from '@kesha-antonov/react-native-background-downloader'
+
+const tasks = await getExistingDownloadTasks()
 for (const task of tasks)
   task.stop()
 ```
@@ -274,7 +558,9 @@ for (const task of tasks)
 Or re-attach them:
 
 ```javascript
-const tasks = await checkForExistingDownloads()
+import { getExistingDownloadTasks } from '@kesha-antonov/react-native-background-downloader'
+
+const tasks = await getExistingDownloadTasks()
 for (const task of tasks) {
   task.pause()
   //
@@ -289,6 +575,7 @@ for (const task of tasks) {
 3. Add listener to handle when your app goes foreground (be sure to do it only after you stopped all tasks or re-attached them!)
 
 ```javascript
+import { ensureDownloadsAreRunning } from '@kesha-antonov/react-native-background-downloader'
 
 function handleAppStateChange (appState) {
   if (appState !== 'active')
@@ -309,17 +596,21 @@ All callback methods return the current instance of the `DownloadTask` for chain
 
 | Function   | Callback Arguments                | Info|
 | ---------- | --------------------------------- | ---- |
-| `begin`    | { expectedBytes, headers } | 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, bytesTotal } | Called at max every 1.5s so you can update your progress bar accordingly |
-| `done`     | { bytesDownloaded, bytesTotal } | Called when the download is done, the file is at the destination you've set |
-| `error`    | { error, errorCode } | Called when the download stops due to an error |
+| `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 |
+| `done`     | `{ bytesDownloaded: number, bytesTotal: number }` | Called when the download is done, the file is at the destination you've set |
+| `error`    | `{ error: string, errorCode: number }` | Called when the download stops due to an error |
 
 ### `pause()`  (iOS only)
 Pauses the download
 
+**Note:** This functionality is not supported on Android due to limitations in the DownloadManager API. On Android, calling this method will log a warning but will not crash the application.
+
 ### `resume()`  (iOS only)
 Resumes a paused download
 
+**Note:** This functionality is not supported on Android due to limitations in the DownloadManager API. On Android, calling this method will log a warning but will not crash the application.
+
 ### `stop()`
 Stops the download for good and removes the file that was written so far
 
@@ -331,6 +622,24 @@ Stops the download for good and removes the file that was written so far
 
 An absolute path to the app's documents directory. It is recommended that you use this path as the target of downloaded files.
 
+## Platform-Specific Limitations
+
+### Android DownloadManager Limitations
+
+The Android implementation uses the system's `DownloadManager` service, which has some limitations compared to iOS:
+
+#### Pause/Resume Not Supported
+- **Issue**: Android's DownloadManager does not provide a public API for pausing and resuming downloads
+- **Impact**: Calling `task.pause()` or `task.resume()` on Android will log a warning but not perform any action
+- **Workaround**: If you need to stop a download, use `task.stop()` and restart it later with a new download request
+- **Technical Details**: The private APIs needed for pause/resume functionality are not accessible to third-party applications
+
+#### Alternative Approaches for Android
+If pause/resume functionality is critical for your application, consider:
+1. Using `task.stop()` and tracking progress to restart downloads from where they left off (if the server supports range requests)
+2. Implementing a custom download solution for Android that doesn't use DownloadManager
+3. Designing your app flow to minimize the need for pause/resume functionality
+
 ## Rules for proguard-rules.pro
 
 In case of error `java.lang.IllegalStateException: TypeToken must be created with a type argument: new TypeToken<...>()` in Android release add this to `proguard-rules.pro`: