@kesha-antonov/react-native-background-downloader 4.7.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/README.md +85 -37
  2. package/android/build.gradle +5 -1
  3. package/android/consumer-rules.pro +14 -0
  4. package/android/src/main/AndroidManifest.xml +18 -1
  5. package/android/src/main/java/com/eko/UIDTDownloadJobService.kt +5 -567
  6. package/android/src/main/java/com/eko/uidt/CancelDownloadReceiver.kt +4 -58
  7. package/android/src/main/java/com/{eko → kesha_antonov}/DownloadConstants.kt +6 -1
  8. package/android/src/main/java/com/{eko → kesha_antonov}/DownloadEventEmitter.kt +1 -1
  9. package/android/src/main/java/com/{eko → kesha_antonov}/DownloadResult.kt +1 -1
  10. package/android/src/main/java/com/{eko → kesha_antonov}/Downloader.kt +14 -7
  11. package/android/src/main/java/com/{eko → kesha_antonov}/ProgressReporter.kt +1 -1
  12. package/android/src/main/java/com/{eko → kesha_antonov}/PromiseExtensions.kt +1 -1
  13. package/android/src/main/java/com/{eko → kesha_antonov}/RNBGDTaskConfig.kt +1 -1
  14. package/android/src/main/java/com/kesha_antonov/RNBGDUploadTaskConfig.kt +57 -0
  15. package/android/src/main/java/com/{eko → kesha_antonov}/RNBackgroundDownloaderModuleImpl.kt +103 -63
  16. package/android/src/main/java/com/{eko → kesha_antonov}/RNBackgroundDownloaderPackage.kt +1 -1
  17. package/android/src/main/java/com/{eko → kesha_antonov}/ResumableDownloadService.kt +11 -9
  18. package/android/src/main/java/com/{eko → kesha_antonov}/ResumableDownloader.kt +36 -15
  19. package/android/src/main/java/com/kesha_antonov/UIDTDownloadJobService.kt +590 -0
  20. package/android/src/main/java/com/{eko → kesha_antonov}/UnmeteredNetworkGate.kt +136 -19
  21. package/android/src/main/java/com/{eko → kesha_antonov}/UploadEventEmitter.kt +27 -2
  22. package/android/src/main/java/com/{eko → kesha_antonov}/Uploader.kt +189 -19
  23. package/android/src/main/java/com/{eko → kesha_antonov}/handlers/OnBegin.kt +4 -4
  24. package/android/src/main/java/com/{eko → kesha_antonov}/handlers/OnBeginState.kt +1 -1
  25. package/android/src/main/java/com/{eko → kesha_antonov}/handlers/OnProgress.kt +5 -5
  26. package/android/src/main/java/com/{eko → kesha_antonov}/handlers/OnProgressState.kt +1 -1
  27. package/android/src/main/java/com/{eko → kesha_antonov}/interfaces/BeginCallback.kt +1 -1
  28. package/android/src/main/java/com/{eko → kesha_antonov}/interfaces/ProgressCallback.kt +1 -1
  29. package/android/src/main/java/com/kesha_antonov/uidt/CancelDownloadReceiver.kt +68 -0
  30. package/android/src/main/java/com/{eko → kesha_antonov}/uidt/RNBGDFileProvider.kt +1 -1
  31. package/android/src/main/java/com/{eko → kesha_antonov}/uidt/UIDTJobIds.kt +9 -4
  32. package/android/src/main/java/com/{eko → kesha_antonov}/uidt/UIDTJobManager.kt +6 -6
  33. package/android/src/main/java/com/{eko → kesha_antonov}/uidt/UIDTJobState.kt +7 -5
  34. package/android/src/main/java/com/{eko → kesha_antonov}/uidt/UIDTNotificationIds.kt +1 -1
  35. package/android/src/main/java/com/{eko → kesha_antonov}/uidt/UIDTNotificationManager.kt +18 -10
  36. package/android/src/main/java/com/{eko → kesha_antonov}/utils/FileUtils.kt +1 -1
  37. package/android/src/main/java/com/{eko → kesha_antonov}/utils/HeaderUtils.kt +11 -2
  38. package/android/src/main/java/com/{eko → kesha_antonov}/utils/NetworkRequestUtils.kt +1 -1
  39. package/android/src/main/java/com/kesha_antonov/utils/NotificationUtils.kt +24 -0
  40. package/android/src/main/java/com/{eko → kesha_antonov}/utils/ProgressUtils.kt +1 -1
  41. package/android/src/main/java/com/{eko → kesha_antonov}/utils/ReadableConverters.kt +1 -1
  42. package/android/src/main/java/com/{eko → kesha_antonov}/utils/RedirectResolver.kt +32 -4
  43. package/android/src/main/java/com/{eko → kesha_antonov}/utils/StorageManager.kt +5 -5
  44. package/android/src/main/java/com/{eko → kesha_antonov}/utils/TempFileUtils.kt +2 -2
  45. package/android/src/newarch/java/com/{eko → kesha_antonov}/RNBackgroundDownloaderModule.kt +1 -1
  46. package/android/src/oldarch/java/com/{eko → kesha_antonov}/RNBackgroundDownloaderModule.kt +1 -1
  47. package/android/src/test/java/com/kesha_antonov/DownloadCompleteReceiverTest.kt +57 -0
  48. package/android/src/test/java/com/{eko → kesha_antonov}/DownloaderRecoveryTest.kt +2 -2
  49. package/android/src/test/java/com/{eko → kesha_antonov}/DownloaderResumeTest.kt +3 -3
  50. package/android/src/test/java/com/{eko → kesha_antonov}/ResumableDownloaderConcurrencyTest.kt +1 -1
  51. package/android/src/test/java/com/kesha_antonov/ResumableDownloaderRedirectTest.kt +77 -0
  52. package/android/src/test/java/com/{eko → kesha_antonov}/ResumableDownloaderStallTest.kt +1 -1
  53. package/android/src/test/java/com/kesha_antonov/UnmeteredNetworkGateTest.kt +248 -0
  54. package/android/src/test/java/com/kesha_antonov/UploadPartRangesTest.kt +33 -0
  55. package/android/src/test/java/com/{eko → kesha_antonov}/UploaderMultipartTest.kt +11 -2
  56. package/android/src/test/java/com/kesha_antonov/UploaderPartsTest.kt +222 -0
  57. package/android/src/test/java/com/kesha_antonov/UploaderResponseTest.kt +26 -0
  58. package/android/src/test/java/com/{eko → kesha_antonov}/handlers/OnBeginTest.kt +2 -2
  59. package/android/src/test/java/com/{eko → kesha_antonov}/uidt/CancelDownloadReceiverTest.kt +25 -2
  60. package/android/src/test/java/com/{eko → kesha_antonov}/uidt/UIDTJobIdsTest.kt +13 -2
  61. package/android/src/test/java/com/{eko → kesha_antonov}/uidt/UIDTJobManagerTest.kt +1 -1
  62. package/android/src/test/java/com/{eko → kesha_antonov}/uidt/UIDTNotificationIdsTest.kt +1 -1
  63. package/android/src/test/java/com/kesha_antonov/utils/RedirectResolverTest.kt +133 -0
  64. package/bin/react-native-background-downloader.js +197 -0
  65. package/ios/RNBGDUploadTaskConfig.h +26 -0
  66. package/ios/RNBGDUploadTaskConfig.mm +69 -3
  67. package/ios/RNBackgroundDownloader.mm +587 -47
  68. package/lib/NativeRNBackgroundDownloader.d.ts +15 -0
  69. package/lib/UploadTask.d.ts +5 -1
  70. package/lib/UploadTask.js +22 -4
  71. package/lib/index.js +57 -27
  72. package/lib/types.d.ts +33 -2
  73. package/package.json +5 -2
  74. package/src/NativeRNBackgroundDownloader.ts +23 -0
  75. package/src/UploadTask.ts +23 -1
  76. package/src/index.ts +60 -27
  77. package/src/types.ts +42 -2
  78. package/android/src/main/java/com/eko/RNBGDUploadTaskConfig.kt +0 -22
  79. package/android/src/test/java/com/eko/utils/RedirectResolverTest.kt +0 -67
package/README.md CHANGED
@@ -1,15 +1,14 @@
1
1
  <p align="center">
2
- <img src="docs/images/example-main-dark.png" width="250" alt="Example app: main screen" />
3
- &nbsp;
4
- <img src="docs/images/example-download-dark.png" width="250" alt="Example app: downloads, one in progress" />
5
- &nbsp;
6
- <img src="docs/images/example-upload-dark.png" width="250" alt="Example app: uploads" />
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="docs/images/how-it-works-dark.gif" />
4
+ <img src="docs/images/how-it-works-light.gif" width="800" alt="A map download starts in the app, keeps going after the phone locks and iOS terminates the app, and is found again with getExistingDownloadTasks() when the app reopens" />
5
+ </picture>
7
6
  </p>
8
7
 
9
8
  <p align="center">
10
9
  <a href="https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader"><img src="https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader.svg" alt="npm version"></a>
11
10
  <a href="https://www.npmjs.com/package/@kesha-antonov/react-native-background-downloader"><img src="https://img.shields.io/npm/dm/@kesha-antonov/react-native-background-downloader.svg" alt="npm downloads"></a>
12
- <a href="https://npm-stat.com/charts.html?package=%40kesha-antonov%2Freact-native-background-downloader&from=2015-01-01"><img src="https://img.shields.io/badge/total%20downloads-1.07M-blue.svg" alt="total npm downloads"></a>
11
+ <a href="https://npm-stat.com/charts.html?package=%40kesha-antonov%2Freact-native-background-downloader&from=2015-01-01"><img src="https://img.shields.io/badge/total%20downloads-1.37M-blue.svg" alt="total npm downloads"></a>
13
12
  <a href="https://www.npmjs.com/package/@kesha-antonov/react-native-background-downloader"><img src="https://img.shields.io/npm/dt/@kesha-antonov/react-native-background-downloader.svg?label=18-months%20downloads" alt="npm downloads (last 18 months)"></a>
14
13
  <a href="https://github.com/kesha-antonov/react-native-background-downloader/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="license"></a>
15
14
  <img src="https://img.shields.io/badge/platforms-iOS%20%7C%20Android-lightgrey.svg" alt="platforms">
@@ -31,6 +30,10 @@
31
30
  <a href="https://kesha-antonov.github.io/react-native-background-downloader/troubleshooting">Troubleshooting</a>
32
31
  </p>
33
32
 
33
+ <p align="center">
34
+ <sub>Built and maintained by <a href="https://kesha-antonov.com">Kesha Antonov</a>, React Native lead engineer. More libraries, apps and case studies on <a href="https://kesha-antonov.com">kesha-antonov.com</a>.</sub>
35
+ </p>
36
+
34
37
  <p align="center">
35
38
  <sub>Using it in production? A ⭐ helps other developers find the library.</sub>
36
39
  </p>
@@ -51,17 +54,17 @@
51
54
  <table align="center">
52
55
  <tr>
53
56
  <td align="center" valign="top" width="190">
54
- <a href="https://cryptoc-app.web.app/"><img src="https://cryptoc-app.web.app/img/icon.png?v=3" width="76" height="76" alt="cryptoc app icon" /></a>
57
+ <a href="https://getcryptoc.app/"><img src="https://getcryptoc.app/img/icon.png?v=3" width="76" height="76" alt="cryptoc app icon" /></a>
55
58
  <br /><br />
56
- <img src="https://cryptoc-app.web.app/img/qr-get.png?v=2" width="124" height="124" alt="QR code that installs cryptoc" />
59
+ <img src="https://getcryptoc.app/img/qr-get.png?v=2" width="124" height="124" alt="QR code that installs cryptoc" />
57
60
  <br />
58
61
  <sub>Scan to install</sub>
59
62
  <br /><br />
60
63
  <!-- App Store button hidden for now
61
- <a href="https://apps.apple.com/app/cryptoc/id1333169178"><img height="40" src="https://cryptoc-app.web.app/img/appstore.svg?v=2" alt="Download on the App Store" /></a>
64
+ <a href="https://apps.apple.com/app/cryptoc/id1333169178"><img height="40" src="https://getcryptoc.app/img/appstore.svg?v=2" alt="Download on the App Store" /></a>
62
65
  <br />
63
66
  -->
64
- <a href="https://play.google.com/store/apps/details?id=co.ssoul.CryptoC"><img height="59" src="https://cryptoc-app.web.app/img/googleplay.png?v=2" alt="Get it on Google Play" /></a>
67
+ <a href="https://play.google.com/store/apps/details?id=co.ssoul.CryptoC"><img height="59" src="https://getcryptoc.app/img/googleplay.png?v=2" alt="Get it on Google Play" /></a>
65
68
  </td>
66
69
  <td valign="top">
67
70
 
@@ -158,8 +161,8 @@ How this library compares to other file transfer options in the React Native eco
158
161
  - [📚 API](#-api)
159
162
  - [Quick Reference](#quick-reference)
160
163
  - [📱 Platform Notes](#-platform-notes)
161
- - [❓ Troubleshooting](#-troubleshooting)
162
164
  - [🧪 Example App](#-example-app)
165
+ - [❓ Troubleshooting](#-troubleshooting)
163
166
  - [💡 Use Cases](#-use-cases)
164
167
  - [🔄 Migration Guide](#-migration-guide)
165
168
  - [🤝 Contributing](#-contributing)
@@ -484,6 +487,40 @@ await task.stop()
484
487
 
485
488
  </details>
486
489
 
490
+ <details>
491
+ <summary><strong>Uploading a large file in parts (S3 multipart upload)</strong></summary>
492
+
493
+ Pass one presigned URL per part as `partUrls`: the library sends each byte range of the file to its URL under one task, with combined progress, and hands back every part's `ETag` for `CompleteMultipartUpload`. No part files are created on Android; on iOS each part is copied to a temporary file while it uploads.
494
+
495
+ ```javascript
496
+ import { createUploadTask, directories } from '@kesha-antonov/react-native-background-downloader'
497
+
498
+ // From your backend: CreateMultipartUpload, then a presigned UploadPart URL per part
499
+ const { uploadId, partUrls, partSize } = await api.startMultipartUpload({ fileSize })
500
+
501
+ const task = createUploadTask({
502
+ id: 'video-upload',
503
+ source: `${directories.documents}/video.mp4`,
504
+ partUrls, // method defaults to PUT
505
+ partSize, // optional: defaults to Math.ceil(fileSize / partUrls.length)
506
+ mimeType: 'video/mp4',
507
+ metadata: { uploadId },
508
+ }).progress(({ bytesUploaded, bytesTotal }) => {
509
+ console.log(`Uploaded: ${bytesUploaded / bytesTotal * 100}%`)
510
+ }).done(async ({ parts }) => {
511
+ await api.completeMultipartUpload({
512
+ uploadId,
513
+ parts: parts.map(({ partNumber, responseHeaders }) => ({ PartNumber: partNumber, ETag: responseHeaders.etag })),
514
+ })
515
+ })
516
+
517
+ task.start()
518
+ ```
519
+
520
+ A single upload's response headers are in `done` too, as `responseHeaders` (lowercased names). On iOS, an upload that finishes while the app isn't running comes back from `getExistingUploadTasks()` as a `DONE` task with `parts` and `responseHeaders` set. See [Uploading in parts](docs/API.md#uploading-in-parts).
521
+
522
+ </details>
523
+
487
524
  <details>
488
525
  <summary><strong>Updating headers on paused downloads</strong></summary>
489
526
 
@@ -694,6 +731,7 @@ setConfig({
694
731
  - The `logCallback` function is called for each native debug log (iOS only sends logs to callback currently)
695
732
  - Logs include detailed information about download lifecycle, session management, and errors
696
733
  - In production builds, logs are only printed when explicitly enabled via `isLogsEnabled`
734
+ - Logs include URLs but not header values or upload response bodies; see [Security Notes](docs/PLATFORM_NOTES.md#security-notes) before forwarding them anywhere
697
735
 
698
736
  </details>
699
737
 
@@ -750,6 +788,7 @@ task.start()
750
788
  - Uses HEAD requests to resolve redirects efficiently
751
789
  - Falls back to original URL if redirect resolution fails
752
790
  - Respects the same headers and timeouts as the main download
791
+ - While `Authorization`, `Cookie` or `Proxy-Authorization` is set, stops before a redirect to another origin, so the credentials aren't sent there; never follows a redirect to a non-http(s) URL or from https to http
753
792
 
754
793
  </details>
755
794
 
@@ -1001,6 +1040,39 @@ Key points:
1001
1040
  - **Android**: Uses `DownloadManager` + Foreground Services + MMKV
1002
1041
  - **Pause/Resume**: Works on both platforms (Android requires server Range header support)
1003
1042
 
1043
+ ## 🧪 Example App
1044
+
1045
+ The repository includes a full example app demonstrating all features:
1046
+
1047
+ <p align="center">
1048
+ <img src="docs/images/example-main-dark.png" width="250" alt="Example app: main screen" />
1049
+ &nbsp;
1050
+ <img src="docs/images/example-download-dark.png" width="250" alt="Example app: downloads, one in progress" />
1051
+ &nbsp;
1052
+ <img src="docs/images/example-upload-dark.png" width="250" alt="Example app: uploads" />
1053
+ </p>
1054
+
1055
+ ```bash
1056
+ cd example
1057
+ yarn install
1058
+
1059
+ # iOS
1060
+ cd ios && pod install && cd ..
1061
+ yarn ios
1062
+
1063
+ # Android
1064
+ yarn android
1065
+ ```
1066
+
1067
+ The example app shows:
1068
+ - Starting multiple downloads
1069
+ - Pause/resume functionality
1070
+ - Progress tracking with animations
1071
+ - Re-attaching to background tasks
1072
+ - File management
1073
+ - Uploads to a test server
1074
+ - Light and dark theme, following the system setting
1075
+
1004
1076
  ## ❓ Troubleshooting
1005
1077
 
1006
1078
  <details>
@@ -1091,34 +1163,9 @@ See the [Google Play Console Declaration](#google-play-console-declaration) sect
1091
1163
  <details>
1092
1164
  <summary><strong>TypeToken errors in release builds (Android)</strong></summary>
1093
1165
 
1094
- Add the Proguard rules mentioned in the [Proguard Rules](#proguard-rules) section.
1166
+ Since v5.0.0 the library applies its ProGuard rules to your release build itself. On an older version, add the rules from the [Proguard Rules](#proguard-rules) section of that version's docs.
1095
1167
  </details>
1096
1168
 
1097
- ## 🧪 Example App
1098
-
1099
- The repository includes a full example app demonstrating all features:
1100
-
1101
- ```bash
1102
- cd example
1103
- yarn install
1104
-
1105
- # iOS
1106
- cd ios && pod install && cd ..
1107
- yarn ios
1108
-
1109
- # Android
1110
- yarn android
1111
- ```
1112
-
1113
- The example app shows:
1114
- - Starting multiple downloads
1115
- - Pause/resume functionality
1116
- - Progress tracking with animations
1117
- - Re-attaching to background tasks
1118
- - File management
1119
- - Uploads to a test server
1120
- - Light and dark theme, following the system setting
1121
-
1122
1169
  ## 💡 Use Cases
1123
1170
 
1124
1171
  This library is perfect for apps that need reliable file transfers:
@@ -1134,6 +1181,7 @@ This library is perfect for apps that need reliable file transfers:
1134
1181
 
1135
1182
  Upgrading from an older version? Check the [Migration Guide](./MIGRATION.md) for detailed instructions:
1136
1183
 
1184
+ - [v4.8.x to v5.0.0](./MIGRATION.md#migration-guide-v48x-to-v500) - Android package renamed from `com.eko` to `com.kesha_antonov`
1137
1185
  - [v4.3.x → v4.4.0](./MIGRATION.md#migration-guide-v43x--v440) - iOS MMKV dependency change
1138
1186
  - [v4.1.x → v4.2.0](./MIGRATION.md#migration-guide-v41x--v420) - Android pause/resume support
1139
1187
  - [v4.0.x → v4.1.0](./MIGRATION.md#migration-guide-v40x--v410) - MMKV dependency change
@@ -30,7 +30,7 @@ android {
30
30
  def agpVersion = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION
31
31
  // Check AGP version for backward compatibility reasons (for RN < 0.71)
32
32
  if (agpVersion.tokenize('.')[0].toInteger() >= 7) {
33
- namespace "com.eko"
33
+ namespace "com.kesha_antonov"
34
34
  }
35
35
 
36
36
  compileSdkVersion safeExtGet('compileSdkVersion', 36)
@@ -48,6 +48,10 @@ android {
48
48
  abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
49
49
  }
50
50
 
51
+ // Keep rules for the classes the library stores with Gson, applied to
52
+ // the app's release build so apps don't have to add them
53
+ consumerProguardFiles 'consumer-rules.pro'
54
+
51
55
  buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
52
56
  buildConfigField "String", "LIBRARY_VERSION", "\"${getVersionFromPackageJson()}\""
53
57
  }
@@ -0,0 +1,14 @@
1
+ # Applied to the app's release build automatically (consumerProguardFiles).
2
+ # These classes are saved and restored with Gson, which reads their fields by
3
+ # name, so R8 must not rename or strip them.
4
+ -keep class com.kesha_antonov.RNBGDTaskConfig { *; }
5
+ -keep class com.kesha_antonov.RNBGDUploadTaskConfig { *; }
6
+ -keep class com.kesha_antonov.UploadPartResult { *; }
7
+ -keep class com.kesha_antonov.utils.StorageManager$PausedDownloadInfoData { *; }
8
+
9
+ # Gson needs the generic type of each TypeToken
10
+ -keepattributes Signature
11
+ -keep class com.google.gson.reflect.TypeToken { *; }
12
+ -keep class * extends com.google.gson.reflect.TypeToken
13
+
14
+ -keep class com.tencent.mmkv.** { *; }
@@ -1,5 +1,5 @@
1
1
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
2
- package="com.eko">
2
+ package="com.kesha_antonov">
3
3
 
4
4
  <uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION" />
5
5
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
@@ -26,10 +26,27 @@
26
26
  android:permission="android.permission.BIND_JOB_SERVICE"
27
27
  android:exported="false" />
28
28
 
29
+ <!-- The job service under its name before v5.0.0: downloads scheduled by
30
+ v4.x name it, and keep running in it after the app is updated -->
31
+ <service
32
+ android:name="com.eko.UIDTDownloadJobService"
33
+ android:permission="android.permission.BIND_JOB_SERVICE"
34
+ android:exported="false" />
35
+
29
36
  <!-- Receiver for the in-notification "Cancel" action -->
30
37
  <receiver
31
38
  android:name=".uidt.CancelDownloadReceiver"
32
39
  android:exported="false">
40
+ <intent-filter>
41
+ <action android:name="com.kesha_antonov.uidt.ACTION_CANCEL_DOWNLOAD" />
42
+ </intent-filter>
43
+ </receiver>
44
+
45
+ <!-- The Cancel receiver under its name before v5.0.0, for notifications
46
+ v4.x posted that are still shown after the app is updated -->
47
+ <receiver
48
+ android:name="com.eko.uidt.CancelDownloadReceiver"
49
+ android:exported="false">
33
50
  <intent-filter>
34
51
  <action android:name="com.eko.uidt.ACTION_CANCEL_DOWNLOAD" />
35
52
  </intent-filter>