@ammarahmed/react-native-upload 6.33.0 → 7.0.0-alpha.0

package/.eslintignore

@@ -1,2 +1 @@
-example/RNBackgroundExample/node_modules
-example/RNBackgroundExample/e2e
+example/UploadExample/node_modules

package/README.md

@@ -140,6 +140,171 @@ const options = {
 
 Note the `field` property is required for multipart uploads.
 
+## S3 / Cloud Multipart Upload (Chunked)
+
+For large files (e.g. > 25MB) that need to be uploaded in chunked parts to AWS S3, Google Cloud Storage, Cloudflare R2, or MinIO using presigned URLs:
+
+```typescript
+import Upload from "@ammarahmed/react-native-upload";
+
+const upload = Upload.createMultipartS3({
+  uploadId: "unique-upload-id-123",
+  path: "/path/to/large-video.mp4",
+  parts: [
+    "https://s3.amazonaws.com/bucket/file?partNumber=1&uploadId=...",
+    "https://s3.amazonaws.com/bucket/file?partNumber=2&uploadId=...",
+    // ... presigned URLs for each part
+  ],
+  maxParallel: 3, // Optional: maximum parallel chunk uploads (default: 3)
+  notification: {
+    enabled: true,
+    filename: "large-video.mp4", // Optional: human-readable name in notification
+  },
+  appGroup: "group.com.myapp", // Optional: iOS App Group for Share Extensions
+});
+
+// Track progress
+upload.onProgress((event) => {
+  console.log(`Uploaded ${event.bytesUploaded}/${event.totalBytes} bytes (${(event.progress * 100).toFixed(1)}%)`);
+  console.log(`Current chunk index: ${event.chunkIndex}`);
+});
+
+try {
+  const result = await upload.start();
+  if (result.success) {
+    // Array of ETags matching the order of the parts (for S3 CompleteMultipartUpload)
+    console.log("Upload completed with ETags:", result.etags);
+  }
+} catch (error) {
+  if (error.code === "CANCELLED") {
+    console.log("Upload was cancelled");
+  } else {
+    console.error("Upload failed:", error);
+  }
+}
+
+// To cancel mid-upload:
+// await upload.cancel();
+// or statically:
+// await Upload.cancelMultipartS3("unique-upload-id-123");
+```
+
+### Resumption on Network Failure
+
+If an upload is interrupted or network drops, you can resume by passing `existingEtags`. `onProgress` emits an `etags` array matching the parts list (with empty strings for pending parts):
+
+```typescript
+const upload = Upload.createMultipartS3({
+  uploadId: savedUploadId, // Re-use the existing S3 upload ID
+  path: "/path/to/large-video.mp4",
+  parts: presignedUrls,
+  existingEtags: savedEtags, // Fixed-length array with ETags for completed parts, "" for pending parts
+});
+```
+
+### Disabling resumability
+
+Uploads are resumable by default: their state is persisted so that they survive the app process being killed. Pass `resumable: false` to an individual upload to turn that off:
+
+```typescript
+Upload.createMultipartS3({ uploadId, path, parts, resumable: false });
+```
+
+A non-resumable upload still keeps running while the app is in the background, but nothing is written to disk. If the app process dies and the app is launched again, the upload is not resumed and does not show up in `getMultipartS3Uploads()`.
+
+- Android: the foreground service is not restarted for it and no headless completion runs after a process death.
+- iOS: iOS may keep sending parts that were already queued while the app is dead. On the next launch the library cancels them and deletes their chunk files. The multipart upload is never completed, so abort it on your server if needed.
+
+### Finishing the upload in the background
+
+An S3 multipart upload is only complete once you send `CompleteMultipartUpload` with the part ETags. To make that happen even when the app is suspended, or was killed and restarted for the upload, register a completion handler. Do it at the top level of your entry file (`index.js`), outside of any component, so it exists when the app is started in the background:
+
+```typescript
+import Upload from "@ammarahmed/react-native-upload";
+
+Upload.setMultipartCompletionHandler(async ({ uploadId, status, etags, error }) => {
+  if (status !== "completed") return;
+  // Load whatever you saved when you started the upload (bucket, key, ...)
+  await completeMultipartUpload(uploadId, etags);
+});
+```
+
+- The handler is called when every part has been uploaded (or the upload failed). When it resolves, the upload is acknowledged and its stored state is removed. If it throws, the upload is not acknowledged and stays pending.
+- It is called while the app is running and, on Android, from a headless JS task when the app process was not running. Save what you need to finish the upload (for example the S3 key) to storage before starting it; the headless task starts your JS bundle from scratch.
+- If you use the handler, don't also finish the upload from the `start()` promise.
+- Fallback: completed uploads are persisted natively. If the handler could not run, check on every app launch and finish them without uploading again:
+
+```typescript
+const pending = await Upload.getMultipartS3Uploads();
+for (const upload of pending) {
+  if (upload.status === "completed") {
+    await completeMultipartUpload(upload.uploadId, upload.etags);
+    await Upload.acknowledgeMultipartS3(upload.uploadId);
+  }
+}
+```
+
+`status` is `running`, `completed` or `failed`. A failed upload keeps its `etags`, so you can start it again with `existingEtags`.
+
+### iOS Background Behavior
+
+All multipart uploads share one background `NSURLSession`. Every part is queued when the upload starts, so iOS keeps uploading while the app is suspended and wakes the app when parts finish. Upload state is persisted and reattached when the app is relaunched.
+
+Forward the system's background session event to the library in your `AppDelegate`:
+
+```swift
+func application(
+  _ application: UIApplication,
+  handleEventsForBackgroundURLSession identifier: String,
+  completionHandler: @escaping () -> Void
+) {
+  RNFileUploader.setCompletionHandlerWithIdentifier(identifier, completionHandler: completionHandler)
+}
+```
+
+(With Swift, import the library header in your bridging header: `#import <react-native-upload/RNFileUploader.h>`.)
+
+Notes:
+- The system completion handler is released when your JS calls `canSuspendIfBackground()`, which the library calls after the handler runs. Keep the handler short, iOS gives the app limited time when it wakes it.
+- Chunk files are written to a copy in Application Support (or the App Group container when `appGroup` is set) until the upload ends, so you need free space for a second copy of the file.
+- If the user force-quits the app, iOS cancels the background transfers. Resume with `existingEtags`.
+
+### Android Foreground Service and Headless Task
+
+Background support on Android is opt-in. The library does not add any permissions or services to your app. Add the following to your app's `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+<application>
+  <service
+    android:name="com.appfolio.uploader.MultipartUploadService"
+    android:exported="false"
+    android:foregroundServiceType="dataSync" />
+  <service
+    android:name="com.appfolio.uploader.MultipartCompletionService"
+    android:exported="false" />
+</application>
+```
+
+How it works:
+- Uploads run in a native engine that is independent of your Activity and of the React instance. State (part URLs, ETags, status) is saved to disk after every part.
+- With `notification.enabled` the engine runs a foreground service, which also keeps your JS timers running while the app is in the background.
+- If the system restarts the service after killing the app's process, the engine resumes the remaining parts on its own.
+- When an upload finishes and no React instance is running, `MultipartCompletionService` starts a headless JS task that runs your completion handler.
+- After an upload ends, the service stays alive until the handler resolves (or `Upload.acknowledgeMultipartS3(uploadId)` is called), or for 30 seconds, or 2 minutes if the headless task was started.
+
+Notes:
+- Google Play requires a declaration for `FOREGROUND_SERVICE_DATA_SYNC`.
+- `POST_NOTIFICATIONS` must be requested at runtime on Android 13+ for the notification to appear.
+- The foreground service is only started while your app is in the foreground. Without it, the process can still be killed by the system, and uploads are then resumed the next time the app starts.
+- A force stop or an OEM that kills the app when it is removed from recents does not restart the service. The persisted uploads resume the next time the app is opened, and completed ones can be finished with `getMultipartS3Uploads()` as shown above.
+- On Android 15+ `dataSync` services have a time limit; the service stops itself when the system times it out.
+- The library compiles against `compileSdkVersion` 35 or higher.
+- Notification texts can be customized with `onProgressTitle`, `onStartMessage`, `onResumeMessage`, `onProgressMessage` (use `{progress}` for the percentage) and `notificationChannelName`.
+
 # API
 
 ## Top Level Functions
@@ -326,7 +491,7 @@ Is there an example/sandbox app to test out this package?
 
 > Yes, there is a simple react native app that comes with an [express](https://github.com/expressjs/express) server where you can see react-native-background-upload in action and try things out in an isolated local environment.
 
-[RNBackgroundExample](https://github.com/Vydia/react-native-background-upload/blob/master/example/RNBackgroundExample)
+[UploadExample](example/UploadExample)
 
 Does it support iOS camera roll assets?
 

package/android/build.gradle

@@ -22,7 +22,7 @@ buildscript {
 apply plugin: 'com.android.library'
 apply plugin: 'kotlin-android'
 
-def DEFAULT_COMPILE_SDK_VERSION = 31
+def DEFAULT_COMPILE_SDK_VERSION = 35
 def DEFAULT_BUILD_TOOLS_VERSION = "30.0.2"
 def DEFAULT_TARGET_SDK_VERSION = 29
 

package/android/src/main/java/com/appfolio/uploader/MultipartCompletionService.kt

@@ -0,0 +1,33 @@
+package com.appfolio.uploader
+
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+import com.facebook.react.HeadlessJsTaskService
+import com.facebook.react.jstasks.HeadlessJsTaskConfig
+
+class MultipartCompletionService : HeadlessJsTaskService() {
+    companion object {
+        private const val TAG = "MultipartCompletion"
+        private const val TASK_KEY = "RNMultipartUploadCompletion"
+        private const val TASK_TIMEOUT_MS = 120_000L
+        private const val EXTRA_UPLOAD_ID = "extra_upload_id"
+
+        fun start(context: Context, uploadId: String) {
+            try {
+                val intent = Intent(context, MultipartCompletionService::class.java).apply {
+                    putExtra(EXTRA_UPLOAD_ID, uploadId)
+                }
+                context.startService(intent)
+            } catch (e: Exception) {
+                Log.w(TAG, "Could not start MultipartCompletionService: ${e.message}")
+            }
+        }
+    }
+
+    override fun getTaskConfig(intent: Intent?): HeadlessJsTaskConfig? {
+        val uploadId = intent?.getStringExtra(EXTRA_UPLOAD_ID) ?: return null
+        val payload = MultipartUploader.getInstance(this).completionPayload(uploadId) ?: return null
+        return HeadlessJsTaskConfig(TASK_KEY, payload, TASK_TIMEOUT_MS, true)
+    }
+}

package/android/src/main/java/com/appfolio/uploader/MultipartUploadService.kt

@@ -0,0 +1,200 @@
+package com.appfolio.uploader
+
+import android.app.ActivityManager
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.content.pm.ServiceInfo
+import android.os.Binder
+import android.os.Build
+import android.os.IBinder
+import android.util.Log
+import androidx.core.app.NotificationCompat
+
+class MultipartUploadService : Service() {
+    companion object {
+        private const val TAG = "MultipartUploadService"
+        private const val CHANNEL_ID = "BackgroundUploadChannel"
+        private const val NOTIFICATION_ID = 1002
+
+        @Volatile
+        var instance: MultipartUploadService? = null
+
+        const val ACTION_START = "com.appfolio.uploader.START_FOREGROUND_UPLOAD"
+        const val ACTION_STOP = "com.appfolio.uploader.STOP_FOREGROUND_UPLOAD"
+
+        const val EXTRA_TITLE = "extra_title"
+        const val EXTRA_MESSAGE = "extra_message"
+
+        private fun isAppInForeground(context: Context): Boolean {
+            val state = ActivityManager.RunningAppProcessInfo()
+            ActivityManager.getMyMemoryState(state)
+            return state.importance <= ActivityManager.RunningAppProcessInfo.IMPORTANCE_VISIBLE
+        }
+
+        fun ensureChannel(context: Context, channelName: String) {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
+                val channel = NotificationChannel(CHANNEL_ID, channelName, NotificationManager.IMPORTANCE_LOW)
+                manager?.createNotificationChannel(channel)
+            }
+        }
+
+        fun start(context: Context, title: String, message: String, channelName: String) {
+            if (!isAppInForeground(context)) {
+                Log.w(TAG, "App is not in the foreground, uploading without a foreground service")
+                return
+            }
+            try {
+                ensureChannel(context, channelName)
+                val intent = Intent(context, MultipartUploadService::class.java).apply {
+                    action = ACTION_START
+                    putExtra(EXTRA_TITLE, title)
+                    putExtra(EXTRA_MESSAGE, message)
+                }
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                    context.startForegroundService(intent)
+                } else {
+                    context.startService(intent)
+                }
+            } catch (e: Exception) {
+                // If Android OS blocks startForegroundService (e.g. ForegroundServiceStartNotAllowedException),
+                // catch it so the app process does not crash. The coroutine will still run in process.
+                Log.w(TAG, "Could not start MultipartUploadService: ${e.message}")
+            }
+        }
+
+        fun updateProgress(context: Context, title: String, progress: Int, message: String) {
+            if (instance == null) return
+            try {
+                val notification = buildNotification(context, title, progress, message, ongoing = true)
+                val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
+                manager?.notify(NOTIFICATION_ID, notification)
+            } catch (e: Exception) {
+                Log.w(TAG, "Could not update progress: ${e.message}")
+            }
+        }
+
+        fun stop(context: Context) {
+            try {
+                instance?.stopForegroundAndSelf()
+                val notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
+                notificationManager?.cancel(NOTIFICATION_ID)
+            } catch (e: Exception) {
+                Log.w(TAG, "Could not stop MultipartUploadService: ${e.message}")
+            }
+        }
+
+        private fun buildNotification(context: Context, title: String, progress: Int, message: String, ongoing: Boolean): Notification {
+            val builder = NotificationCompat.Builder(context, CHANNEL_ID)
+                .setContentTitle(title)
+                .setContentText(message)
+                .setSmallIcon(android.R.drawable.stat_sys_upload)
+                .setPriority(NotificationCompat.PRIORITY_LOW)
+                .setOngoing(ongoing)
+                .setAutoCancel(!ongoing)
+
+            if (progress in 0..100) {
+                builder.setProgress(100, progress, false)
+            } else {
+                builder.setProgress(0, 0, true)
+            }
+
+            return builder.build()
+        }
+    }
+
+    private val binder = LocalBinder()
+    private var isStarted = false
+    private var notificationManager: NotificationManager? = null
+
+    inner class LocalBinder : Binder() {
+        fun getService(): MultipartUploadService = this@MultipartUploadService
+    }
+
+    override fun onCreate() {
+        super.onCreate()
+        instance = this
+        notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
+    }
+
+    override fun onBind(intent: Intent?): IBinder = binder
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        if (intent == null) {
+            val resumed = MultipartUploader.getInstance(this).resumeInterrupted().firstOrNull { it.notificationEnabled }
+            if (resumed == null) {
+                stopSelf()
+                return START_NOT_STICKY
+            }
+            try {
+                ensureChannel(this, resumed.channelName)
+                startForegroundWithNotification(resumed.title, 0, resumed.resumeMessage)
+            } catch (e: Exception) {
+                Log.e(TAG, "Failed startForeground on restart: ${e.message}")
+                stopSelf()
+                return START_NOT_STICKY
+            }
+            return START_STICKY
+        }
+        when (intent.action) {
+            ACTION_START -> {
+                val title = intent.getStringExtra(EXTRA_TITLE) ?: ""
+                val message = intent.getStringExtra(EXTRA_MESSAGE) ?: ""
+                try {
+                    startForegroundWithNotification(title, 0, message)
+                } catch (e: Exception) {
+                    Log.e(TAG, "Failed startForeground in onStartCommand: ${e.message}")
+                    // Stop service if foreground transition was denied to prevent ANR / crash
+                    stopSelf()
+                }
+            }
+            ACTION_STOP -> {
+                stopForegroundAndSelf()
+            }
+        }
+        return if (intent.action == ACTION_START) START_STICKY else START_NOT_STICKY
+    }
+
+    private fun startForegroundWithNotification(title: String, progress: Int, message: String) {
+        val notification = buildNotification(this, title, progress, message, ongoing = true)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            startForeground(NOTIFICATION_ID, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC)
+        } else {
+            startForeground(NOTIFICATION_ID, notification)
+        }
+        isStarted = true
+    }
+
+    fun stopForegroundAndSelf() {
+        isStarted = false
+        try {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+                stopForeground(STOP_FOREGROUND_REMOVE)
+            } else {
+                @Suppress("DEPRECATION")
+                stopForeground(true)
+            }
+            notificationManager?.cancel(NOTIFICATION_ID)
+        } catch (e: Exception) {
+            Log.w(TAG, "Error in stopForeground: ${e.message}")
+        } finally {
+            stopSelf()
+        }
+    }
+
+    override fun onTimeout(startId: Int, fgsType: Int) {
+        stopForegroundAndSelf()
+    }
+
+    override fun onDestroy() {
+        if (instance === this) {
+            instance = null
+        }
+        stopForegroundAndSelf()
+        super.onDestroy()
+    }
+}