@capgo/capacitor-downloader 8.1.31 → 8.3.0

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/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

@@ -23,7 +23,7 @@ import java.util.Map;
 @CapacitorPlugin(name = "CapacitorDownloader")
 public class CapacitorDownloaderPlugin extends Plugin {
 
-    private final String pluginVersion = "8.1.31";
+    private final String pluginVersion = "8.3.0";
 
     private DownloadManager downloadManager;
     private final Map<String, Long> downloads = new HashMap<>();
@@ -76,7 +76,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,7 +100,17 @@ public class CapacitorDownloaderPlugin extends Plugin {
             request.setAllowedNetworkTypes(DownloadManager.Request.NETWORK_MOBILE | DownloadManager.Request.NETWORK_WIFI);
         }
 
-        long downloadId = downloadManager.enqueue(request);
+        long downloadId;
+        try {
+            downloadId = downloadManager.enqueue(request);
+        } catch (SecurityException e) {
+            if ("hidden".equals(call.getString("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;
+        }
         downloads.put(id, downloadId);
 
         JSObject result = new JSObject();

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.31"
+    private let pluginVersion: String = "8.3.0"
     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.31",
+  "version": "8.3.0",
   "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",