@capgo/capacitor-downloader 8.1.32 → 8.3.1

package/README.md

@@ -187,16 +187,16 @@ Get information about a downloaded file.
 ### addListener('downloadProgress', ...)
 
 ```typescript
-addListener(eventName: 'downloadProgress', listenerFunc: (progress: { id: string; progress: number; }) => void) => Promise<PluginListenerHandle>
+addListener(eventName: 'downloadProgress', listenerFunc: (progress: { id: string; progress: number; bytesWritten?: number | undefined; bytesTotal?: number | undefined; }) => void) => Promise<PluginListenerHandle>
 ```
 
 Listen for download progress updates.
 Fired periodically as download progresses.
 
-| Param              | Type                                                                  | Description                           |
-| ------------------ | --------------------------------------------------------------------- | ------------------------------------- |
-| **`eventName`**    | <code>'downloadProgress'</code>                                       | - Must be 'downloadProgress'          |
-| **`listenerFunc`** | <code>(progress: { id: string; progress: number; }) =&gt; void</code> | - Callback receiving progress updates |
+| Param              | Type                                                                                                              | Description                           |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| **`eventName`**    | <code>'downloadProgress'</code>                                                                                   | - Must be 'downloadProgress'          |
+| **`listenerFunc`** | <code>(progress: { id: string; progress: number; bytesWritten?: number; bytesTotal?: number; }) =&gt; void</code> | - Callback receiving progress updates |
 
 **Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
 
@@ -284,14 +284,15 @@ Represents the current state and progress of a download task.
 
 Configuration options for starting a download.
 
-| Prop              | Type                                     | Description                                      |
-| ----------------- | ---------------------------------------- | ------------------------------------------------ |
-| **`id`**          | <code>string</code>                      | Unique identifier for this download task         |
-| **`url`**         | <code>string</code>                      | URL of the file to download                      |
-| **`destination`** | <code>string</code>                      | Local file path where the download will be saved |
-| **`headers`**     | <code>{ [key: string]: string; }</code>  | Optional HTTP headers to include in the request  |
-| **`network`**     | <code>'cellular' \| 'wifi-only'</code>   | Network type requirement for download            |
-| **`priority`**    | <code>'high' \| 'normal' \| 'low'</code> | Download priority level                          |
+| Prop               | Type                                               | Description                                                                                                                                                                                                                                                                                                                     | Since |
+| ------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`id`**           | <code>string</code>                                | Unique identifier for this download task                                                                                                                                                                                                                                                                                        |       |
+| **`url`**          | <code>string</code>                                | URL of the file to download                                                                                                                                                                                                                                                                                                     |       |
+| **`destination`**  | <code>string</code>                                | Local file path where the download will be saved                                                                                                                                                                                                                                                                                |       |
+| **`headers`**      | <code>{ [key: string]: string; }</code>            | Optional HTTP headers to include in the request                                                                                                                                                                                                                                                                                 |       |
+| **`network`**      | <code>'cellular' \| 'wifi-only'</code>             | Network type requirement for download                                                                                                                                                                                                                                                                                           |       |
+| **`priority`**     | <code>'high' \| 'normal' \| 'low'</code>           | Download priority level                                                                                                                                                                                                                                                                                                         |       |
+| **`notification`** | <code>'completed' \| 'progress' \| 'hidden'</code> | Android DownloadManager notification visibility. - `'completed'` (default): show while downloading and keep the notification after completion. - `'progress'`: show while downloading, remove the notification when finished. - `'hidden'`: no system notification; use plugin progress events instead. Ignored on iOS and Web. | 8.2.0 |
 
 
 #### PluginListenerHandle

package/android/build.gradle

@@ -40,6 +40,11 @@ android {
         sourceCompatibility JavaVersion.VERSION_21
         targetCompatibility JavaVersion.VERSION_21
     }
+    testOptions {
+        unitTests {
+            returnDefaultValues = true
+        }
+    }
 }
 
 repositories {
@@ -53,6 +58,7 @@ dependencies {
     annotationProcessor project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     testImplementation "junit:junit:$junitVersion"
+    testImplementation "org.mockito:mockito-core:5.14.2"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
 }

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,3 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION" />
 </manifest>

package/android/src/main/java/ee/forgr/capacitor/plugin/downloader/CapacitorDownloaderPlugin.java

@@ -16,23 +16,30 @@ import com.getcapacitor.PluginCall;
 import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
 import java.io.File;
-import java.util.HashMap;
 import java.util.Iterator;
 import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.RejectedExecutionException;
+import java.util.concurrent.atomic.AtomicLong;
 
 @CapacitorPlugin(name = "CapacitorDownloader")
 public class CapacitorDownloaderPlugin extends Plugin {
 
-    private final String pluginVersion = "8.1.32";
+    private final String pluginVersion = "8.3.1";
 
     private DownloadManager downloadManager;
-    private final Map<String, Long> downloads = new HashMap<>();
+    private final Map<String, Long> downloads = new ConcurrentHashMap<>();
+    private final AtomicLong pendingDownloadSequence = new AtomicLong(0);
+    private ExecutorService downloadManagerExecutor;
     private final Handler handler = new Handler(Looper.getMainLooper());
     private BroadcastReceiver downloadReceiver;
 
     @Override
     public void load() {
         downloadManager = (DownloadManager) getContext().getSystemService(Context.DOWNLOAD_SERVICE);
+        downloadManagerExecutor = Executors.newCachedThreadPool();
         registerDownloadReceiver();
     }
 
@@ -57,13 +64,26 @@ public class CapacitorDownloaderPlugin extends Plugin {
 
     private String getDownloadIdByValue(long value) {
         for (Map.Entry<String, Long> entry : downloads.entrySet()) {
-            if (entry.getValue() == value) {
+            if (entry.getValue() == value && value > 0) {
                 return entry.getKey();
             }
         }
         return null;
     }
 
+    private static boolean isPendingDownload(long downloadId) {
+        return downloadId < 0;
+    }
+
+    private long reservePendingDownload() {
+        return -pendingDownloadSequence.incrementAndGet();
+    }
+
+    private boolean isTrackedDownload(String id, long systemDownloadId) {
+        Long trackedDownloadId = downloads.get(id);
+        return trackedDownloadId != null && trackedDownloadId.longValue() == systemDownloadId;
+    }
+
     @PluginMethod
     public void download(PluginCall call) {
         String id = call.getString("id");
@@ -76,7 +96,7 @@ public class CapacitorDownloaderPlugin extends Plugin {
         }
 
         DownloadManager.Request request = new DownloadManager.Request(Uri.parse(url))
-            .setNotificationVisibility(DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED)
+            .setNotificationVisibility(DownloadNotificationVisibility.resolve(call.getString("notification")))
             .setAllowedOverMetered(true)
             .setAllowedOverRoaming(true);
 
@@ -100,69 +120,161 @@ public class CapacitorDownloaderPlugin extends Plugin {
             request.setAllowedNetworkTypes(DownloadManager.Request.NETWORK_MOBILE | DownloadManager.Request.NETWORK_WIFI);
         }
 
-        long downloadId = downloadManager.enqueue(request);
-        downloads.put(id, downloadId);
-
-        JSObject result = new JSObject();
-        result.put("id", id);
-        result.put("status", DownloadManager.STATUS_PENDING);
-        call.resolve(result);
+        final String notification = call.getString("notification");
+        final long pendingToken = reservePendingDownload();
+        if (downloads.putIfAbsent(id, pendingToken) != null) {
+            call.reject("Download already exists");
+            return;
+        }
+        runDownloadManagerWork(
+            call,
+            () -> {
+                if (!isTrackedDownload(id, pendingToken)) {
+                    call.reject("Download was cancelled");
+                    return;
+                }
 
-        // Start a periodic progress check
-        startProgressCheck(id, downloadId);
-    }
+                long downloadId;
+                try {
+                    downloadId = downloadManager.enqueue(request);
+                } catch (SecurityException e) {
+                    downloads.remove(id, pendingToken);
+                    if ("hidden".equals(notification)) {
+                        call.reject("Hidden downloads require android.permission.DOWNLOAD_WITHOUT_NOTIFICATION in the app manifest", e);
+                    } else {
+                        call.reject("Download could not be enqueued due to missing permission", e);
+                    }
+                    return;
+                } catch (RuntimeException e) {
+                    downloads.remove(id, pendingToken);
+                    call.reject("Download could not be enqueued", e);
+                    return;
+                }
 
-    private void startProgressCheck(final String id, final long downloadId) {
-        handler.post(
-            new Runnable() {
-                @Override
-                public void run() {
-                    if (checkDownloadStatus(id)) {
-                        handler.postDelayed(this, 1000); // Check every second
+                if (!downloads.replace(id, pendingToken, downloadId)) {
+                    try {
+                        downloadManager.remove(downloadId);
+                    } catch (RuntimeException e) {
+                        call.reject("Download was cancelled", e);
+                        return;
                     }
+                    call.reject("Download was cancelled");
+                    return;
                 }
-            }
+
+                JSObject result = new JSObject();
+                result.put("id", id);
+                result.put("status", DownloadManager.STATUS_PENDING);
+                call.resolve(result);
+
+                // Start a periodic progress check
+                startProgressCheck(id, downloadId);
+            },
+            () -> downloads.remove(id, pendingToken)
         );
     }
 
-    private boolean checkDownloadStatus(String id) {
-        Long downloadId = downloads.get(id);
+    private void startProgressCheck(final String id, final long downloadId) {
+        runProgressQuery(id, true, downloadId);
+    }
 
-        if (downloadId == null) {
-            return false; // Download was removed, stop polling
+    private void checkDownloadStatus(String id) {
+        Long trackedDownloadId = downloads.get(id);
+        if (trackedDownloadId == null || isPendingDownload(trackedDownloadId)) {
+            return;
         }
+        runProgressQuery(id, false, trackedDownloadId);
+    }
 
-        DownloadManager.Query query = new DownloadManager.Query().setFilterById(downloadId);
-        try (Cursor cursor = downloadManager.query(query)) {
-            if (cursor.moveToFirst()) {
-                int status = cursor.getInt(cursor.getColumnIndexOrThrow(DownloadManager.COLUMN_STATUS));
-                long bytesDownloaded = cursor.getLong(cursor.getColumnIndexOrThrow(DownloadManager.COLUMN_BYTES_DOWNLOADED_SO_FAR));
-                long bytesTotal = cursor.getLong(cursor.getColumnIndexOrThrow(DownloadManager.COLUMN_TOTAL_SIZE_BYTES));
-
-                float progress = bytesTotal > 0 ? (float) bytesDownloaded / bytesTotal : 0f;
-
-                JSObject progressData = new JSObject();
-                progressData.put("id", id);
-                progressData.put("progress", progress);
-                notifyListeners("downloadProgress", progressData);
-
-                if (status == DownloadManager.STATUS_SUCCESSFUL) {
-                    JSObject completedData = new JSObject();
-                    completedData.put("id", id);
-                    notifyListeners("downloadCompleted", completedData);
-                    return false; // Stop checking progress
-                } else if (status == DownloadManager.STATUS_FAILED) {
-                    JSObject failedData = new JSObject();
-                    failedData.put("id", id);
-                    failedData.put("error", "Download failed");
-                    notifyListeners("downloadFailed", failedData);
-                    return false; // Stop checking progress
-                }
-            } else {
-                return false; // Download no longer in DownloadManager, stop polling
+    private void runProgressQuery(final String id, final boolean scheduleNext, final long systemDownloadId) {
+        if (!isTrackedDownload(id, systemDownloadId)) {
+            return;
+        }
+
+        ExecutorService executor = downloadManagerExecutor;
+        if (executor == null) {
+            return;
+        }
+
+        try {
+            executor.execute(() -> {
+                ProgressSnapshot snapshot = queryProgressSnapshot(id, systemDownloadId);
+                handler.post(() -> deliverProgressSnapshot(id, systemDownloadId, scheduleNext, snapshot));
+            });
+        } catch (RejectedExecutionException ignored) {
+            // Plugin is shutting down; stop polling quietly.
+        }
+    }
+
+    private ProgressSnapshot queryProgressSnapshot(String id, long systemDownloadId) {
+        if (!isTrackedDownload(id, systemDownloadId)) {
+            return null;
+        }
+
+        DownloadManager.Query query = new DownloadManager.Query().setFilterById(systemDownloadId);
+        Cursor cursor = downloadManager.query(query);
+        if (cursor == null) {
+            return ProgressSnapshot.notFound(id);
+        }
+        try (cursor) {
+            if (!cursor.moveToFirst()) {
+                return ProgressSnapshot.notFound(id);
             }
+
+            int status = cursor.getInt(cursor.getColumnIndexOrThrow(DownloadManager.COLUMN_STATUS));
+            long bytesDownloaded = cursor.getLong(cursor.getColumnIndexOrThrow(DownloadManager.COLUMN_BYTES_DOWNLOADED_SO_FAR));
+            long bytesTotal = cursor.getLong(cursor.getColumnIndexOrThrow(DownloadManager.COLUMN_TOTAL_SIZE_BYTES));
+            float progress = bytesTotal > 0 ? (float) bytesDownloaded / bytesTotal : 0f;
+            return new ProgressSnapshot(id, progress, status, true);
+        }
+    }
+
+    private void deliverProgressSnapshot(String id, long systemDownloadId, boolean scheduleNext, ProgressSnapshot snapshot) {
+        if (snapshot == null || !snapshot.found || !isTrackedDownload(id, systemDownloadId)) {
+            return;
+        }
+
+        JSObject progressData = new JSObject();
+        progressData.put("id", snapshot.id);
+        progressData.put("progress", snapshot.progress);
+        notifyListeners("downloadProgress", progressData);
+
+        boolean shouldContinue = true;
+        if (snapshot.status == DownloadManager.STATUS_SUCCESSFUL) {
+            JSObject completedData = new JSObject();
+            completedData.put("id", snapshot.id);
+            notifyListeners("downloadCompleted", completedData);
+            shouldContinue = false;
+        } else if (snapshot.status == DownloadManager.STATUS_FAILED) {
+            JSObject failedData = new JSObject();
+            failedData.put("id", snapshot.id);
+            failedData.put("error", "Download failed");
+            notifyListeners("downloadFailed", failedData);
+            shouldContinue = false;
+        }
+
+        if (scheduleNext && shouldContinue) {
+            handler.postDelayed(() -> runProgressQuery(id, true, systemDownloadId), 1000);
+        }
+    }
+
+    private static final class ProgressSnapshot {
+
+        private final String id;
+        private final float progress;
+        private final int status;
+        private final boolean found;
+
+        private ProgressSnapshot(String id, float progress, int status, boolean found) {
+            this.id = id;
+            this.progress = progress;
+            this.status = status;
+            this.found = found;
+        }
+
+        private static ProgressSnapshot notFound(String id) {
+            return new ProgressSnapshot(id, 0f, -1, false);
         }
-        return true; // Continue checking progress
     }
 
     @PluginMethod
@@ -180,31 +292,96 @@ public class CapacitorDownloaderPlugin extends Plugin {
     @PluginMethod
     public void stop(PluginCall call) {
         String id = call.getString("id");
-        if (id == null || !downloads.containsKey(id)) {
+        if (id == null) {
+            call.reject("Download not found");
+            return;
+        }
+
+        Long downloadId = downloads.remove(id);
+        if (downloadId == null) {
             call.reject("Download not found");
             return;
         }
-        int removedDownloads = downloadManager.remove(downloads.get(id));
-        downloads.remove(id);
-        call.resolve(new JSObject().put("removed", removedDownloads > 0));
+
+        if (isPendingDownload(downloadId)) {
+            call.resolve(new JSObject().put("removed", false));
+            return;
+        }
+
+        final long systemDownloadId = downloadId;
+        final String stoppedId = id;
+        runDownloadManagerWork(
+            call,
+            () -> {
+                try {
+                    int removedDownloads = downloadManager.remove(systemDownloadId);
+                    call.resolve(new JSObject().put("removed", removedDownloads > 0));
+                } catch (RuntimeException e) {
+                    downloads.putIfAbsent(stoppedId, systemDownloadId);
+                    call.reject("Download could not be removed", e);
+                }
+            },
+            () -> downloads.putIfAbsent(stoppedId, systemDownloadId)
+        );
     }
 
     @PluginMethod
     public void checkStatus(PluginCall call) {
         String id = call.getString("id");
-        if (id == null || !downloads.containsKey(id)) {
+        if (id == null) {
             call.reject("Download not found");
             return;
         }
 
-        DownloadManager.Query query = new DownloadManager.Query().setFilterById(downloads.get(id));
-        try (Cursor cursor = downloadManager.query(query)) {
-            if (cursor.moveToFirst()) {
-                JSObject result = getDownloadStatus(cursor);
-                call.resolve(result);
-            } else {
-                call.reject("Download not found");
+        Long trackedDownloadId = downloads.get(id);
+        if (trackedDownloadId == null || isPendingDownload(trackedDownloadId)) {
+            call.reject("Download not found");
+            return;
+        }
+
+        final long downloadId = trackedDownloadId;
+        runDownloadManagerWork(call, () -> {
+            DownloadManager.Query query = new DownloadManager.Query().setFilterById(downloadId);
+            try {
+                Cursor cursor = downloadManager.query(query);
+                if (cursor == null) {
+                    call.reject("Download not found");
+                    return;
+                }
+                try (cursor) {
+                    if (cursor.moveToFirst()) {
+                        call.resolve(getDownloadStatus(cursor));
+                    } else {
+                        call.reject("Download not found");
+                    }
+                }
+            } catch (RuntimeException e) {
+                call.reject("Download status could not be read", e);
             }
+        });
+    }
+
+    private void runDownloadManagerWork(PluginCall call, Runnable work) {
+        runDownloadManagerWork(call, work, null);
+    }
+
+    private void runDownloadManagerWork(PluginCall call, Runnable work, Runnable onFailure) {
+        ExecutorService executor = downloadManagerExecutor;
+        if (executor == null) {
+            if (onFailure != null) {
+                onFailure.run();
+            }
+            call.reject("Download manager is not available");
+            return;
+        }
+
+        try {
+            executor.execute(work);
+        } catch (RejectedExecutionException e) {
+            if (onFailure != null) {
+                onFailure.run();
+            }
+            call.reject("Download manager is shutting down", e);
         }
     }
 
@@ -274,6 +451,10 @@ public class CapacitorDownloaderPlugin extends Plugin {
         if (downloadReceiver != null) {
             getContext().unregisterReceiver(downloadReceiver);
         }
+        if (downloadManagerExecutor != null) {
+            downloadManagerExecutor.shutdown();
+            downloadManagerExecutor = null;
+        }
     }
 
     @PluginMethod

package/android/src/main/java/ee/forgr/capacitor/plugin/downloader/DownloadNotificationVisibility.java

@@ -0,0 +1,20 @@
+package ee.forgr.capacitor.plugin.downloader;
+
+import android.app.DownloadManager;
+
+final class DownloadNotificationVisibility {
+
+    private DownloadNotificationVisibility() {}
+
+    static int resolve(String notification) {
+        if ("progress".equals(notification)) {
+            return DownloadManager.Request.VISIBILITY_VISIBLE;
+        }
+
+        if ("hidden".equals(notification)) {
+            return DownloadManager.Request.VISIBILITY_HIDDEN;
+        }
+
+        return DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED;
+    }
+}

package/dist/docs.json

@@ -27,7 +27,7 @@
           },
           {
             "name": "example",
-            "text": "```typescript\nconst task = await Downloader.download({\n  id: 'my-download',\n  url: 'https://example.com/file.pdf',\n  destination: 'downloads/file.pdf'\n});\n```"
+            "text": "```typescript\nconst task = await Downloader.download({\n  id: 'my-download',\n  url: 'https://example.com/file.pdf',\n  destination: 'downloads/file.pdf',\n  notification: 'hidden', // Android: no system notification; use downloadProgress events\n});\n```"
           }
         ],
         "docs": "Start a new download task.",
@@ -166,7 +166,7 @@
       },
       {
         "name": "addListener",
-        "signature": "(eventName: 'downloadProgress', listenerFunc: (progress: { id: string; progress: number; }) => void) => Promise<PluginListenerHandle>",
+        "signature": "(eventName: 'downloadProgress', listenerFunc: (progress: { id: string; progress: number; bytesWritten?: number | undefined; bytesTotal?: number | undefined; }) => void) => Promise<PluginListenerHandle>",
         "parameters": [
           {
             "name": "eventName",
@@ -176,7 +176,7 @@
           {
             "name": "listenerFunc",
             "docs": "- Callback receiving progress updates",
-            "type": "(progress: { id: string; progress: number; }) => void"
+            "type": "(progress: { id: string; progress: number; bytesWritten?: number | undefined; bytesTotal?: number | undefined; }) => void"
           }
         ],
         "returns": "Promise<PluginListenerHandle>",
@@ -388,6 +388,18 @@
           "docs": "Download priority level",
           "complexTypes": [],
           "type": "'high' | 'normal' | 'low' | undefined"
+        },
+        {
+          "name": "notification",
+          "tags": [
+            {
+              "text": "8.2.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Android DownloadManager notification visibility.\n\n- `'completed'` (default): show while downloading and keep the notification after completion.\n- `'progress'`: show while downloading, remove the notification when finished.\n- `'hidden'`: no system notification; use plugin progress events instead.\n\nIgnored on iOS and Web.",
+          "complexTypes": [],
+          "type": "'completed' | 'progress' | 'hidden' | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -28,6 +28,18 @@ export interface DownloadOptions {
     network?: 'cellular' | 'wifi-only';
     /** Download priority level */
     priority?: 'high' | 'normal' | 'low';
+    /**
+     * Android DownloadManager notification visibility.
+     *
+     * - `'completed'` (default): show while downloading and keep the notification after completion.
+     * - `'progress'`: show while downloading, remove the notification when finished.
+     * - `'hidden'`: no system notification; use plugin progress events instead.
+     *
+     * Ignored on iOS and Web.
+     *
+     * @since 8.2.0
+     */
+    notification?: 'completed' | 'progress' | 'hidden';
 }
 /**
  * Capacitor plugin for downloading files with background support.
@@ -44,7 +56,8 @@ export interface CapacitorDownloaderPlugin {
      * const task = await Downloader.download({
      *   id: 'my-download',
      *   url: 'https://example.com/file.pdf',
-     *   destination: 'downloads/file.pdf'
+     *   destination: 'downloads/file.pdf',
+     *   notification: 'hidden', // Android: no system notification; use downloadProgress events
      * });
      * ```
      */
@@ -117,6 +130,10 @@ export interface CapacitorDownloaderPlugin {
     addListener(eventName: 'downloadProgress', listenerFunc: (progress: {
         id: string;
         progress: number;
+        /** Bytes written so far */
+        bytesWritten?: number;
+        /** Total bytes expected, or 0 when the server did not report a length */
+        bytesTotal?: number;
     }) => void): Promise<PluginListenerHandle>;
     /**
      * Listen for download completion.

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Represents the current state and progress of a download task.\n */\nexport interface DownloadTask {\n  /** Unique identifier for the download task */\n  id: string;\n  /** Download progress from 0 to 100 */\n  progress: number;\n  /** Current state of the download */\n  state: 'PENDING' | 'RUNNING' | 'PAUSED' | 'DONE' | 'ERROR';\n}\n\n/**\n * Configuration options for starting a download.\n */\nexport interface DownloadOptions {\n  /** Unique identifier for this download task */\n  id: string;\n  /** URL of the file to download */\n  url: string;\n  /** Local file path where the download will be saved */\n  destination: string;\n  /** Optional HTTP headers to include in the request */\n  headers?: { [key: string]: string };\n  /** Network type requirement for download */\n  network?: 'cellular' | 'wifi-only';\n  /** Download priority level */\n  priority?: 'high' | 'normal' | 'low';\n}\n\n/**\n * Capacitor plugin for downloading files with background support.\n * Provides resumable downloads with progress tracking.\n */\nexport interface CapacitorDownloaderPlugin {\n  /**\n   * Start a new download task.\n   *\n   * @param options - Download configuration\n   * @returns Promise with initial download task status\n   * @example\n   * ```typescript\n   * const task = await Downloader.download({\n   *   id: 'my-download',\n   *   url: 'https://example.com/file.pdf',\n   *   destination: 'downloads/file.pdf'\n   * });\n   * ```\n   */\n  download(options: DownloadOptions): Promise<DownloadTask>;\n\n  /**\n   * Pause an active download.\n   * Download can be resumed later from the same position.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when paused\n   */\n  pause(options: { id: string }): Promise<void>;\n\n  /**\n   * Resume a paused download.\n   * Continues from where it was paused.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when resumed\n   */\n  resume(options: { id: string }): Promise<void>;\n\n  /**\n   * Stop and cancel a download permanently.\n   * Downloaded data will be deleted.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when stopped\n   */\n  stop(options: { id: string }): Promise<void>;\n\n  /**\n   * Check the current status of a download.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise with current download task status\n   */\n  checkStatus(options: { id: string }): Promise<DownloadTask>;\n\n  /**\n   * Get information about a downloaded file.\n   *\n   * @param options - Options containing the file path\n   * @returns Promise with file size and MIME type\n   */\n  getFileInfo(options: { path: string }): Promise<{ size: number; type: string }>;\n\n  /**\n   * Listen for download progress updates.\n   * Fired periodically as download progresses.\n   *\n   * @param eventName - Must be 'downloadProgress'\n   * @param listenerFunc - Callback receiving progress updates\n   * @returns Promise with listener handle for removal\n   * @example\n   * ```typescript\n   * const listener = await Downloader.addListener('downloadProgress', (data) => {\n   *   console.log(`Download ${data.id}: ${data.progress}%`);\n   * });\n   * ```\n   */\n  addListener(\n    eventName: 'downloadProgress',\n    listenerFunc: (progress: { id: string; progress: number }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listen for download completion.\n   * Fired when a download finishes successfully.\n   *\n   * @param eventName - Must be 'downloadCompleted'\n   * @param listenerFunc - Callback receiving completion notification\n   * @returns Promise with listener handle for removal\n   */\n  addListener(\n    eventName: 'downloadCompleted',\n    listenerFunc: (result: { id: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listen for download failures.\n   * Fired when a download encounters an error.\n   *\n   * @param eventName - Must be 'downloadFailed'\n   * @param listenerFunc - Callback receiving error information\n   * @returns Promise with listener handle for removal\n   */\n  addListener(\n    eventName: 'downloadFailed',\n    listenerFunc: (error: { id: string; error: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Remove all event listeners.\n   * Cleanup method to prevent memory leaks.\n   *\n   * @returns Promise that resolves when all listeners removed\n   */\n  removeAllListeners(): Promise<void>;\n\n  /**\n   * Get the plugin version number.\n   *\n   * @returns Promise with version string\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Represents the current state and progress of a download task.\n */\nexport interface DownloadTask {\n  /** Unique identifier for the download task */\n  id: string;\n  /** Download progress from 0 to 100 */\n  progress: number;\n  /** Current state of the download */\n  state: 'PENDING' | 'RUNNING' | 'PAUSED' | 'DONE' | 'ERROR';\n}\n\n/**\n * Configuration options for starting a download.\n */\nexport interface DownloadOptions {\n  /** Unique identifier for this download task */\n  id: string;\n  /** URL of the file to download */\n  url: string;\n  /** Local file path where the download will be saved */\n  destination: string;\n  /** Optional HTTP headers to include in the request */\n  headers?: { [key: string]: string };\n  /** Network type requirement for download */\n  network?: 'cellular' | 'wifi-only';\n  /** Download priority level */\n  priority?: 'high' | 'normal' | 'low';\n  /**\n   * Android DownloadManager notification visibility.\n   *\n   * - `'completed'` (default): show while downloading and keep the notification after completion.\n   * - `'progress'`: show while downloading, remove the notification when finished.\n   * - `'hidden'`: no system notification; use plugin progress events instead.\n   *\n   * Ignored on iOS and Web.\n   *\n   * @since 8.2.0\n   */\n  notification?: 'completed' | 'progress' | 'hidden';\n}\n\n/**\n * Capacitor plugin for downloading files with background support.\n * Provides resumable downloads with progress tracking.\n */\nexport interface CapacitorDownloaderPlugin {\n  /**\n   * Start a new download task.\n   *\n   * @param options - Download configuration\n   * @returns Promise with initial download task status\n   * @example\n   * ```typescript\n   * const task = await Downloader.download({\n   *   id: 'my-download',\n   *   url: 'https://example.com/file.pdf',\n   *   destination: 'downloads/file.pdf',\n   *   notification: 'hidden', // Android: no system notification; use downloadProgress events\n   * });\n   * ```\n   */\n  download(options: DownloadOptions): Promise<DownloadTask>;\n\n  /**\n   * Pause an active download.\n   * Download can be resumed later from the same position.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when paused\n   */\n  pause(options: { id: string }): Promise<void>;\n\n  /**\n   * Resume a paused download.\n   * Continues from where it was paused.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when resumed\n   */\n  resume(options: { id: string }): Promise<void>;\n\n  /**\n   * Stop and cancel a download permanently.\n   * Downloaded data will be deleted.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise that resolves when stopped\n   */\n  stop(options: { id: string }): Promise<void>;\n\n  /**\n   * Check the current status of a download.\n   *\n   * @param options - Options containing the download task ID\n   * @returns Promise with current download task status\n   */\n  checkStatus(options: { id: string }): Promise<DownloadTask>;\n\n  /**\n   * Get information about a downloaded file.\n   *\n   * @param options - Options containing the file path\n   * @returns Promise with file size and MIME type\n   */\n  getFileInfo(options: { path: string }): Promise<{ size: number; type: string }>;\n\n  /**\n   * Listen for download progress updates.\n   * Fired periodically as download progresses.\n   *\n   * @param eventName - Must be 'downloadProgress'\n   * @param listenerFunc - Callback receiving progress updates\n   * @returns Promise with listener handle for removal\n   * @example\n   * ```typescript\n   * const listener = await Downloader.addListener('downloadProgress', (data) => {\n   *   console.log(`Download ${data.id}: ${data.progress}%`);\n   * });\n   * ```\n   */\n  addListener(\n    eventName: 'downloadProgress',\n    listenerFunc: (progress: {\n      id: string;\n      progress: number;\n      /** Bytes written so far */\n      bytesWritten?: number;\n      /** Total bytes expected, or 0 when the server did not report a length */\n      bytesTotal?: number;\n    }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listen for download completion.\n   * Fired when a download finishes successfully.\n   *\n   * @param eventName - Must be 'downloadCompleted'\n   * @param listenerFunc - Callback receiving completion notification\n   * @returns Promise with listener handle for removal\n   */\n  addListener(\n    eventName: 'downloadCompleted',\n    listenerFunc: (result: { id: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Listen for download failures.\n   * Fired when a download encounters an error.\n   *\n   * @param eventName - Must be 'downloadFailed'\n   * @param listenerFunc - Callback receiving error information\n   * @returns Promise with listener handle for removal\n   */\n  addListener(\n    eventName: 'downloadFailed',\n    listenerFunc: (error: { id: string; error: string }) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Remove all event listeners.\n   * Cleanup method to prevent memory leaks.\n   *\n   * @returns Promise that resolves when all listeners removed\n   */\n  removeAllListeners(): Promise<void>;\n\n  /**\n   * Get the plugin version number.\n   *\n   * @returns Promise with version string\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}

package/ios/Sources/CapacitorDownloaderPlugin/CapacitorDownloaderPlugin.swift

@@ -8,7 +8,7 @@ import Capacitor
 
 @objc(CapacitorDownloaderPlugin)
 public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.1.32"
+    private let pluginVersion: String = "8.3.1"
     public let identifier = "CapacitorDownloaderPlugin"
     public let jsName = "CapacitorDownloader"
     public let pluginMethods: [CAPPluginMethod] = [
@@ -56,15 +56,38 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
         return tasks.first(where: { $0.value == task })?.key
     }
 
+    private func documentsDirectoryURL() -> URL? {
+        FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first
+    }
+
+    private func destinationURL(for id: String, storedDestination: String?) -> URL? {
+        guard let documentsDirectory = documentsDirectoryURL() else {
+            return nil
+        }
+
+        return DownloadDestinationResolver.resolveDestinationURL(
+            destination: storedDestination,
+            id: id,
+            documentsDirectory: documentsDirectory
+        )
+    }
+
+    private func prepareDestinationDirectory(for destinationURL: URL) throws {
+        let directoryURL = destinationURL.deletingLastPathComponent()
+        try FileManager.default.createDirectory(at: directoryURL, withIntermediateDirectories: true)
+    }
+
     @objc func download(_ call: CAPPluginCall) {
         guard let id = call.getString("id"),
               let urlString = call.getString("url"),
-              let destination = call.getString("destination"),
               let url = URL(string: urlString) else {
             call.reject("Invalid parameters")
             return
         }
 
+        let destination = call.getString("destination") ?? ""
+        DownloadDestinationStore.shared.setDestination(destination, for: id)
+
         var request = URLRequest(url: url)
         if let headers = call.getObject("headers") as? [String: String] {
             for (key, value) in headers {
@@ -115,6 +138,7 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
 
         task.cancel()
         removeTask(for: id)
+        DownloadDestinationStore.shared.removeDestination(for: id)
         call.resolve()
     }
 
@@ -166,16 +190,39 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
             "type": type
         ])
     }
+
+    @objc func getPluginVersion(_ call: CAPPluginCall) {
+        call.resolve(["version": self.pluginVersion])
+    }
 }
 
 extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
     public func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didFinishDownloadingTo location: URL) {
-        guard let id = idForTask(downloadTask),
-              let destinationURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first?.appendingPathComponent(id) else {
+        guard let id = idForTask(downloadTask) else {
+            return
+        }
+
+        let storedDestination = DownloadDestinationStore.shared.takeDestination(for: id)
+        guard let destinationURL = destinationURL(for: id, storedDestination: storedDestination) else {
+            notifyListeners("downloadFailed", data: ["id": id, "error": "Unable to resolve destination"])
+            return
+        }
+
+        if let httpResponse = downloadTask.response as? HTTPURLResponse,
+           !DownloadHTTPValidator.isSuccessfulStatusCode(httpResponse.statusCode) {
+            try? FileManager.default.removeItem(at: location)
+            notifyListeners(
+                "downloadFailed",
+                data: ["id": id, "error": "HTTP \(httpResponse.statusCode)"]
+            )
             return
         }
 
         do {
+            try prepareDestinationDirectory(for: destinationURL)
+            if FileManager.default.fileExists(atPath: destinationURL.path) {
+                try FileManager.default.removeItem(at: destinationURL)
+            }
             try FileManager.default.moveItem(at: location, to: destinationURL)
             notifyListeners("downloadCompleted", data: ["id": id])
         } catch {
@@ -191,22 +238,36 @@ extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
 
         removeTask(for: id)
 
+        if error != nil {
+            _ = DownloadDestinationStore.shared.takeDestination(for: id)
+        }
+
         if let error = error {
             notifyListeners("downloadFailed", data: ["id": id, "error": error.localizedDescription])
         }
     }
 
-    public func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didWriteData bytesWritten: Int64, totalBytesWritten: Int64, totalBytesExpectedToWrite: Int64) {
+    public func urlSession(
+        _ session: URLSession,
+        downloadTask: URLSessionDownloadTask,
+        didWriteData bytesWritten: Int64,
+        totalBytesWritten: Int64,
+        totalBytesExpectedToWrite: Int64
+    ) {
         guard let id = idForTask(downloadTask) else {
             return
         }
 
-        let progress = Float(totalBytesWritten) / Float(totalBytesExpectedToWrite)
-        notifyListeners("downloadProgress", data: ["id": id, "progress": progress])
+        let bytesTotal = totalBytesExpectedToWrite > 0 ? totalBytesExpectedToWrite : 0
+        let progress = bytesTotal > 0 ? Float(totalBytesWritten) / Float(bytesTotal) : 0
+        notifyListeners(
+            "downloadProgress",
+            data: [
+                "id": id,
+                "progress": progress,
+                "bytesWritten": totalBytesWritten,
+                "bytesTotal": bytesTotal
+            ]
+        )
     }
-
-    @objc func getPluginVersion(_ call: CAPPluginCall) {
-        call.resolve(["version": self.pluginVersion])
-    }
-
 }

package/ios/Sources/CapacitorDownloaderPlugin/DownloadDestinationResolver.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+enum DownloadDestinationResolver {
+    static func resolveDestinationURL(
+        destination: String?,
+        id: String,
+        documentsDirectory: URL
+    ) -> URL {
+        let trimmedDestination = destination?.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let destination = trimmedDestination, !destination.isEmpty else {
+            return documentsDirectory.appendingPathComponent(id)
+        }
+
+        if destination.hasPrefix("file://"), let url = URL(string: destination) {
+            return url
+        }
+
+        if destination.hasPrefix("/") {
+            return URL(fileURLWithPath: destination)
+        }
+
+        return documentsDirectory.appendingPathComponent(destination)
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadDestinationStore.swift

@@ -0,0 +1,36 @@
+import Foundation
+
+final class DownloadDestinationStore {
+    static let shared = DownloadDestinationStore()
+
+    static let userDefaultsKey = "CapacitorDownloaderDestinations"
+
+    private let defaults: UserDefaults
+
+    init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
+
+    func setDestination(_ destination: String, for id: String) {
+        var map = destinationsMap()
+        map[id] = destination
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    func takeDestination(for id: String) -> String? {
+        var map = destinationsMap()
+        let destination = map.removeValue(forKey: id)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+        return destination
+    }
+
+    func removeDestination(for id: String) {
+        var map = destinationsMap()
+        map.removeValue(forKey: id)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    private func destinationsMap() -> [String: String] {
+        defaults.dictionary(forKey: Self.userDefaultsKey) as? [String: String] ?? [:]
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadHTTPValidator.swift

@@ -0,0 +1,7 @@
+import Foundation
+
+enum DownloadHTTPValidator {
+    static func isSuccessfulStatusCode(_ statusCode: Int) -> Bool {
+        statusCode >= 200 && statusCode < 300
+    }
+}

package/ios/Tests/CapacitorDownloaderPluginTests/CapacitorDownloaderPluginTests.swift

@@ -1,15 +1,102 @@
 import XCTest
 @testable import CapacitorDownloaderPlugin
 
-class CapacitorDownloaderTests: XCTestCase {
-    func testEcho() {
-        // This is an example of a functional test case for a plugin.
-        // Use XCTAssert and related functions to verify your tests produce the correct results.
+final class DownloadDestinationResolverTests: XCTestCase {
+    private let documentsDirectory = URL(fileURLWithPath: "/var/mobile/Documents")
 
-        let implementation = CapacitorDownloader()
-        let value = "Hello, World!"
-        let result = implementation.echo(value)
+    func testEmptyDestinationFallsBackToDocumentsPlusId() {
+        let url = DownloadDestinationResolver.resolveDestinationURL(
+            destination: nil,
+            id: "download-1",
+            documentsDirectory: documentsDirectory
+        )
 
-        XCTAssertEqual(value, result)
+        XCTAssertEqual(url, documentsDirectory.appendingPathComponent("download-1"))
+    }
+
+    func testBlankDestinationFallsBackToDocumentsPlusId() {
+        let url = DownloadDestinationResolver.resolveDestinationURL(
+            destination: "   ",
+            id: "download-1",
+            documentsDirectory: documentsDirectory
+        )
+
+        XCTAssertEqual(url, documentsDirectory.appendingPathComponent("download-1"))
+    }
+
+    func testRelativeDestinationUsesDocumentsDirectory() {
+        let url = DownloadDestinationResolver.resolveDestinationURL(
+            destination: "downloads/sample.zip",
+            id: "download-1",
+            documentsDirectory: documentsDirectory
+        )
+
+        XCTAssertEqual(url, documentsDirectory.appendingPathComponent("downloads/sample.zip"))
+    }
+
+    func testAbsolutePathUsesFileURL() {
+        let url = DownloadDestinationResolver.resolveDestinationURL(
+            destination: "/tmp/custom-file.bin",
+            id: "download-1",
+            documentsDirectory: documentsDirectory
+        )
+
+        XCTAssertEqual(url, URL(fileURLWithPath: "/tmp/custom-file.bin"))
+    }
+
+    func testFileURLDestinationIsUsedDirectly() {
+        let url = DownloadDestinationResolver.resolveDestinationURL(
+            destination: "file:///tmp/custom-file.bin",
+            id: "download-1",
+            documentsDirectory: documentsDirectory
+        )
+
+        XCTAssertEqual(url, URL(string: "file:///tmp/custom-file.bin"))
+    }
+}
+
+final class DownloadDestinationStoreTests: XCTestCase {
+    private var defaults: UserDefaults!
+    private var store: DownloadDestinationStore!
+
+    override func setUp() {
+        super.setUp()
+        defaults = UserDefaults(suiteName: "CapacitorDownloaderPluginTests")!
+        defaults.removePersistentDomain(forName: "CapacitorDownloaderPluginTests")
+        store = DownloadDestinationStore(defaults: defaults)
+    }
+
+    override func tearDown() {
+        defaults.removePersistentDomain(forName: "CapacitorDownloaderPluginTests")
+        super.tearDown()
+    }
+
+    func testSetAndTakeDestination() {
+        store.setDestination("downloads/file.zip", for: "task-1")
+
+        XCTAssertEqual(store.takeDestination(for: "task-1"), "downloads/file.zip")
+        XCTAssertNil(store.takeDestination(for: "task-1"))
+    }
+
+    func testRemoveDestination() {
+        store.setDestination("downloads/file.zip", for: "task-1")
+
+        store.removeDestination(for: "task-1")
+
+        XCTAssertNil(store.takeDestination(for: "task-1"))
+    }
+}
+
+final class DownloadHTTPValidatorTests: XCTestCase {
+    func testSuccessfulStatusCodes() {
+        XCTAssertTrue(DownloadHTTPValidator.isSuccessfulStatusCode(200))
+        XCTAssertTrue(DownloadHTTPValidator.isSuccessfulStatusCode(204))
+        XCTAssertTrue(DownloadHTTPValidator.isSuccessfulStatusCode(299))
+    }
+
+    func testNonSuccessfulStatusCodesAreRejected() {
+        XCTAssertFalse(DownloadHTTPValidator.isSuccessfulStatusCode(199))
+        XCTAssertFalse(DownloadHTTPValidator.isSuccessfulStatusCode(404))
+        XCTAssertFalse(DownloadHTTPValidator.isSuccessfulStatusCode(500))
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-downloader",
-  "version": "8.1.32",
+  "version": "8.3.1",
   "description": "Download file in background or foreground",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
@@ -36,17 +36,17 @@
     "download file in foreground"
   ],
   "scripts": {
-    "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",
-    "verify:ios": "xcodebuild -scheme CapgoCapacitorDownloader -destination generic/platform=iOS",
+    "verify": "bun run verify:ios && bun run verify:android && bun run verify:web",
+    "verify:ios": "bun scripts/verify-ios.mjs",
     "verify:android": "cd android && ./gradlew clean build test && cd ..",
-    "verify:web": "npm run build",
-    "lint": "npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint",
-    "fmt": "npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- --fix --format",
+    "verify:web": "bun run build",
+    "lint": "bun run eslint && bun run prettier -- --check && bun run swiftlint -- lint",
+    "fmt": "bun run eslint -- --fix && bun run prettier -- --write && bun run swiftlint -- --fix --format",
     "eslint": "eslint . --ext .ts",
     "prettier": "prettier-pretty-check \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java",
     "swiftlint": "node-swiftlint",
     "docgen": "docgen --api CapacitorDownloaderPlugin --output-readme README.md --output-json dist/docs.json",
-    "build": "npm run clean && npm run docgen && tsc && rollup -c rollup.config.mjs",
+    "build": "bun run clean && bun run docgen && tsc && rollup -c rollup.config.mjs",
     "clean": "rimraf ./dist",
     "watch": "tsc --watch",
     "prepublishOnly": "bun run build",