@capgo/capacitor-downloader 8.3.21 → 8.5.0

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  notification: 'hidden', // Android: no system notification; use downloadProgress events\n});\n```"
+            "text": "```typescript\nconst task = await Downloader.download({\n  id: 'my-download',\n  url: 'https://example.com/file.pdf',\n  destination: 'files/offline/package.zip',\n  androidHttpEngine: 'auto',\n  notification: 'hidden', // Android OkHttp: no notification during download; use downloadProgress events\n  downloadCompletedNotificationText: 'Your file is ready', // opt-in completion alert\n});\n```"
           }
         ],
         "docs": "Start a new download task.",
@@ -364,7 +364,7 @@
         {
           "name": "destination",
           "tags": [],
-          "docs": "Local file path where the download will be saved",
+          "docs": "Local file path where the download will be saved.\n\nOn Android, relative paths without `androidHttpEngine` behave like earlier releases: every relative path,\nincluding `cache/...` and `files/...`, is stored under app external files via DownloadManager.\n\nWhen you set `androidHttpEngine` to `'auto'` or `'okhttp'`, optional roots apply:\n- `cache/...` saves under app cache (OkHttp with `'auto'`).\n- `files/...` saves under app-private internal storage (OkHttp with `'auto'`).\n- `public-downloads/...` saves to the public Downloads folder (DownloadManager).\n- Any other relative path saves under app external files (DownloadManager with `'auto'`).\nAbsolute paths and `file://` URIs are supported; `'auto'` picks OkHttp when the path is under cache, data, or files dirs.",
           "complexTypes": [],
           "type": "string"
         },
@@ -397,9 +397,33 @@
               "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.",
+          "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 DownloadManager progress notification; use plugin progress events instead.\n  `downloadCompletedNotificationText` can still post a completion notification when the transfer succeeds.\n\nOn the OkHttp Android path, notifications are not shown during the transfer. With `'completed'`, a single\ncompletion notification may be posted when the file finishes (Android 13+ requires runtime\n`POST_NOTIFICATIONS` in the host app). Ignored on iOS and Web.",
           "complexTypes": [],
           "type": "'completed' | 'progress' | 'hidden' | undefined"
+        },
+        {
+          "name": "androidHttpEngine",
+          "tags": [
+            {
+              "text": "next release",
+              "name": "since"
+            }
+          ],
+          "docs": "Android HTTP stack used for the download.\n\n- Omitted: always DownloadManager with legacy destination resolution (same as releases before this option).\n- `'auto'`: OkHttp for app-private destinations (`cache/...`, `files/...`, or an absolute path under\n  cache/data/files when extended roots apply); DownloadManager for legacy relative paths under app external storage\n  and `public-downloads/...`.\n- `'okhttp'`: always use OkHttp for extended-root destinations. Rejects `public-downloads/...` paths. Transfers run\n  in the app process and do not continue after the process is killed (unlike DownloadManager on those paths).\n- `'downloadManager'`: always use the system DownloadManager with legacy destination resolution.\n\nIgnored on iOS and Web.",
+          "complexTypes": [],
+          "type": "'auto' | 'okhttp' | 'downloadManager' | undefined"
+        },
+        {
+          "name": "downloadCompletedNotificationText",
+          "tags": [
+            {
+              "text": "next release",
+              "name": "since"
+            }
+          ],
+          "docs": "Optional localized text for a system notification when the download finishes.\n\nWhen set, iOS and Android may show a local notification after a successful download\nif the user granted notification permission. If permission is denied, the download\nstill completes and no notification is shown. Tapping the notification reopens the app.\n\nOmitted or empty means no completion notification from the plugin (use\n`downloadCompleted` events while the app is open).",
+          "complexTypes": [],
+          "type": "string | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -18,7 +18,19 @@ export interface DownloadOptions {
     id: string;
     /** URL of the file to download */
     url: string;
-    /** Local file path where the download will be saved */
+    /**
+     * Local file path where the download will be saved.
+     *
+     * On Android, relative paths without `androidHttpEngine` behave like earlier releases: every relative path,
+     * including `cache/...` and `files/...`, is stored under app external files via DownloadManager.
+     *
+     * When you set `androidHttpEngine` to `'auto'` or `'okhttp'`, optional roots apply:
+     * - `cache/...` saves under app cache (OkHttp with `'auto'`).
+     * - `files/...` saves under app-private internal storage (OkHttp with `'auto'`).
+     * - `public-downloads/...` saves to the public Downloads folder (DownloadManager).
+     * - Any other relative path saves under app external files (DownloadManager with `'auto'`).
+     * Absolute paths and `file://` URIs are supported; `'auto'` picks OkHttp when the path is under cache, data, or files dirs.
+     */
     destination: string;
     /** Optional HTTP headers to include in the request */
     headers?: {
@@ -33,13 +45,45 @@ export interface DownloadOptions {
      *
      * - `'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.
+     * - `'hidden'`: no DownloadManager progress notification; use plugin progress events instead.
+     *   `downloadCompletedNotificationText` can still post a completion notification when the transfer succeeds.
      *
-     * Ignored on iOS and Web.
+     * On the OkHttp Android path, notifications are not shown during the transfer. With `'completed'`, a single
+     * completion notification may be posted when the file finishes (Android 13+ requires runtime
+     * `POST_NOTIFICATIONS` in the host app). Ignored on iOS and Web.
      *
      * @since 8.2.0
      */
     notification?: 'completed' | 'progress' | 'hidden';
+    /**
+     * Android HTTP stack used for the download.
+     *
+     * - Omitted: always DownloadManager with legacy destination resolution (same as releases before this option).
+     * - `'auto'`: OkHttp for app-private destinations (`cache/...`, `files/...`, or an absolute path under
+     *   cache/data/files when extended roots apply); DownloadManager for legacy relative paths under app external storage
+     *   and `public-downloads/...`.
+     * - `'okhttp'`: always use OkHttp for extended-root destinations. Rejects `public-downloads/...` paths. Transfers run
+     *   in the app process and do not continue after the process is killed (unlike DownloadManager on those paths).
+     * - `'downloadManager'`: always use the system DownloadManager with legacy destination resolution.
+     *
+     * Ignored on iOS and Web.
+     *
+     * @since next release
+     */
+    androidHttpEngine?: 'auto' | 'okhttp' | 'downloadManager';
+    /**
+     * Optional localized text for a system notification when the download finishes.
+     *
+     * When set, iOS and Android may show a local notification after a successful download
+     * if the user granted notification permission. If permission is denied, the download
+     * still completes and no notification is shown. Tapping the notification reopens the app.
+     *
+     * Omitted or empty means no completion notification from the plugin (use
+     * `downloadCompleted` events while the app is open).
+     *
+     * @since next release
+     */
+    downloadCompletedNotificationText?: string;
 }
 /**
  * Capacitor plugin for downloading files with background support.
@@ -56,8 +100,10 @@ export interface CapacitorDownloaderPlugin {
      * const task = await Downloader.download({
      *   id: 'my-download',
      *   url: 'https://example.com/file.pdf',
-     *   destination: 'downloads/file.pdf',
-     *   notification: 'hidden', // Android: no system notification; use downloadProgress events
+     *   destination: 'files/offline/package.zip',
+     *   androidHttpEngine: 'auto',
+     *   notification: 'hidden', // Android OkHttp: no notification during download; use downloadProgress events
+     *   downloadCompletedNotificationText: 'Your file is ready', // opt-in completion alert
      * });
      * ```
      */

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   * 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"]}
+{"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  /**\n   * Local file path where the download will be saved.\n   *\n   * On Android, relative paths without `androidHttpEngine` behave like earlier releases: every relative path,\n   * including `cache/...` and `files/...`, is stored under app external files via DownloadManager.\n   *\n   * When you set `androidHttpEngine` to `'auto'` or `'okhttp'`, optional roots apply:\n   * - `cache/...` saves under app cache (OkHttp with `'auto'`).\n   * - `files/...` saves under app-private internal storage (OkHttp with `'auto'`).\n   * - `public-downloads/...` saves to the public Downloads folder (DownloadManager).\n   * - Any other relative path saves under app external files (DownloadManager with `'auto'`).\n   * Absolute paths and `file://` URIs are supported; `'auto'` picks OkHttp when the path is under cache, data, or files dirs.\n   */\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 DownloadManager progress notification; use plugin progress events instead.\n   *   `downloadCompletedNotificationText` can still post a completion notification when the transfer succeeds.\n   *\n   * On the OkHttp Android path, notifications are not shown during the transfer. With `'completed'`, a single\n   * completion notification may be posted when the file finishes (Android 13+ requires runtime\n   * `POST_NOTIFICATIONS` in the host app). Ignored on iOS and Web.\n   *\n   * @since 8.2.0\n   */\n  notification?: 'completed' | 'progress' | 'hidden';\n  /**\n   * Android HTTP stack used for the download.\n   *\n   * - Omitted: always DownloadManager with legacy destination resolution (same as releases before this option).\n   * - `'auto'`: OkHttp for app-private destinations (`cache/...`, `files/...`, or an absolute path under\n   *   cache/data/files when extended roots apply); DownloadManager for legacy relative paths under app external storage\n   *   and `public-downloads/...`.\n   * - `'okhttp'`: always use OkHttp for extended-root destinations. Rejects `public-downloads/...` paths. Transfers run\n   *   in the app process and do not continue after the process is killed (unlike DownloadManager on those paths).\n   * - `'downloadManager'`: always use the system DownloadManager with legacy destination resolution.\n   *\n   * Ignored on iOS and Web.\n   *\n   * @since next release\n   */\n  androidHttpEngine?: 'auto' | 'okhttp' | 'downloadManager';\n  /**\n   * Optional localized text for a system notification when the download finishes.\n   *\n   * When set, iOS and Android may show a local notification after a successful download\n   * if the user granted notification permission. If permission is denied, the download\n   * still completes and no notification is shown. Tapping the notification reopens the app.\n   *\n   * Omitted or empty means no completion notification from the plugin (use\n   * `downloadCompleted` events while the app is open).\n   *\n   * @since next release\n   */\n  downloadCompletedNotificationText?: string;\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: 'files/offline/package.zip',\n   *   androidHttpEngine: 'auto',\n   *   notification: 'hidden', // Android OkHttp: no notification during download; use downloadProgress events\n   *   downloadCompletedNotificationText: 'Your file is ready', // opt-in completion alert\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.3.21"
+    private let pluginVersion: String = "8.5.0"
     public let identifier = "CapacitorDownloaderPlugin"
     public let jsName = "CapacitorDownloader"
     public let pluginMethods: [CAPPluginMethod] = [
@@ -22,6 +22,8 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
     ]
 
     private var tasks: [String: URLSessionDownloadTask] = [:]
+    private var downloadGenerations: [String: UInt64] = [:]
+    private var taskGenerations: [Int: UInt64] = [:]
     private let tasksLock = NSLock()
     private lazy var session: URLSession = {
         let config = URLSessionConfiguration.background(withIdentifier: "CapacitorDownloader")
@@ -29,6 +31,13 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
         return URLSession(configuration: config, delegate: self, delegateQueue: nil)
     }()
 
+    public override func load() {
+        tasksLock.lock()
+        downloadGenerations = DownloadIdGenerationStore.shared.allGenerations()
+        taskGenerations = DownloadTaskGenerationStore.shared.allGenerations()
+        tasksLock.unlock()
+    }
+
     private func setTask(_ task: URLSessionDownloadTask, for id: String) {
         tasksLock.lock()
         defer { tasksLock.unlock() }
@@ -41,10 +50,48 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
         return tasks[id]
     }
 
-    private func removeTask(for id: String) {
+    private func removeTask(for id: String, completing task: URLSessionDownloadTask) {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        if tasks[id] === task {
+            tasks.removeValue(forKey: id)
+        }
+        taskGenerations.removeValue(forKey: task.taskIdentifier)
+    }
+
+    private func nextGeneration(for id: String) -> UInt64 {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        let generation = (downloadGenerations[id] ?? 0) &+ 1
+        downloadGenerations[id] = generation
+        DownloadIdGenerationStore.shared.setGeneration(generation, forDownloadId: id)
+        return generation
+    }
+
+    private func generation(for id: String) -> UInt64? {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        return downloadGenerations[id]
+    }
+
+    private func setTaskGeneration(_ generation: UInt64, for task: URLSessionDownloadTask) {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        taskGenerations[task.taskIdentifier] = generation
+        DownloadTaskGenerationStore.shared.setGeneration(generation, forTaskIdentifier: task.taskIdentifier)
+    }
+
+    private func generation(for task: URLSessionTask) -> UInt64? {
         tasksLock.lock()
         defer { tasksLock.unlock() }
-        tasks.removeValue(forKey: id)
+        return taskGenerations[task.taskIdentifier]
+    }
+
+    private func clearTaskGeneration(for task: URLSessionTask) {
+        tasksLock.lock()
+        defer { tasksLock.unlock() }
+        taskGenerations.removeValue(forKey: task.taskIdentifier)
+        DownloadTaskGenerationStore.shared.removeGeneration(forTaskIdentifier: task.taskIdentifier)
     }
 
     private func idForTask(_ task: URLSessionDownloadTask) -> String? {
@@ -86,7 +133,13 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
         }
 
         let destination = call.getString("destination") ?? ""
+        let generation = nextGeneration(for: id)
         DownloadDestinationStore.shared.setDestination(destination, for: id)
+        DownloadCompletedNotificationStore.shared.setText(
+            call.getString("downloadCompletedNotificationText"),
+            for: id,
+            generation: generation
+        )
 
         var request = URLRequest(url: url)
         if let headers = call.getObject("headers") as? [String: String] {
@@ -98,6 +151,7 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
         let task = session.downloadTask(with: request)
         task.taskDescription = id
         setTask(task, for: id)
+        setTaskGeneration(generation, for: task)
         task.resume()
 
         call.resolve([
@@ -136,9 +190,13 @@ public class CapacitorDownloaderPlugin: CAPPlugin, CAPBridgedPlugin {
             return
         }
 
+        let generation = generation(for: id)
         task.cancel()
-        removeTask(for: id)
+        removeTask(for: id, completing: task)
         DownloadDestinationStore.shared.removeDestination(for: id)
+        if let generation {
+            DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+        }
         call.resolve()
     }
 
@@ -203,7 +261,12 @@ extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
         }
 
         let storedDestination = DownloadDestinationStore.shared.takeDestination(for: id)
+        let generation = generation(for: downloadTask)
+
         guard let destinationURL = destinationURL(for: id, storedDestination: storedDestination) else {
+            if let generation {
+                DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+            }
             notifyListeners("downloadFailed", data: ["id": id, "error": "Unable to resolve destination"])
             return
         }
@@ -211,6 +274,9 @@ extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
         if let httpResponse = downloadTask.response as? HTTPURLResponse,
            !DownloadHTTPValidator.isSuccessfulStatusCode(httpResponse.statusCode) {
             try? FileManager.default.removeItem(at: location)
+            if let generation {
+                DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+            }
             notifyListeners(
                 "downloadFailed",
                 data: ["id": id, "error": "HTTP \(httpResponse.statusCode)"]
@@ -225,9 +291,17 @@ extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
             }
             try FileManager.default.moveItem(at: location, to: destinationURL)
             notifyListeners("downloadCompleted", data: ["id": id])
+            if let completionText = DownloadCompletedNotificationStore.shared.takeText(for: id, generation: generation) {
+                DownloadCompletedNotificationPresenter.presentIfAllowed(downloadId: id, body: completionText)
+            }
         } catch {
+            if let generation {
+                DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+            }
             notifyListeners("downloadFailed", data: ["id": id, "error": error.localizedDescription])
         }
+
+        clearTaskGeneration(for: downloadTask)
     }
 
     public func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
@@ -236,15 +310,21 @@ extension CapacitorDownloaderPlugin: URLSessionDownloadDelegate {
             return
         }
 
-        removeTask(for: id)
+        let generation = generation(for: downloadTask)
+        removeTask(for: id, completing: downloadTask)
 
         if error != nil {
             _ = DownloadDestinationStore.shared.takeDestination(for: id)
         }
 
-        if let error = error {
+        if let error {
+            if let generation {
+                DownloadCompletedNotificationStore.shared.removeText(for: id, generation: generation)
+            }
             notifyListeners("downloadFailed", data: ["id": id, "error": error.localizedDescription])
         }
+
+        clearTaskGeneration(for: downloadTask)
     }
 
     public func urlSession(

package/ios/Sources/CapacitorDownloaderPlugin/DownloadCompletedNotificationPresenter.swift

@@ -0,0 +1,38 @@
+import Foundation
+import UserNotifications
+
+enum DownloadCompletedNotificationPresenter {
+    static func presentIfAllowed(downloadId: String, body: String) {
+        guard let bodyText = DownloadCompletedNotificationText.normalize(body) else {
+            return
+        }
+
+        UNUserNotificationCenter.current().getNotificationSettings { settings in
+            let allowed: Bool
+            switch settings.authorizationStatus {
+            case .authorized, .provisional, .ephemeral:
+                allowed = true
+            case .denied, .notDetermined:
+                allowed = false
+            @unknown default:
+                allowed = false
+            }
+
+            guard allowed else {
+                return
+            }
+
+            let content = UNMutableNotificationContent()
+            content.body = bodyText
+            content.sound = .default
+
+            let request = UNNotificationRequest(
+                identifier: "capacitor-downloader-completed-\(downloadId)",
+                content: content,
+                trigger: nil
+            )
+
+            UNUserNotificationCenter.current().add(request)
+        }
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadCompletedNotificationStore.swift

@@ -0,0 +1,74 @@
+import Foundation
+
+final class DownloadCompletedNotificationStore {
+    static let shared = DownloadCompletedNotificationStore()
+
+    static let userDefaultsKey = "CapacitorDownloaderCompletedNotificationTexts"
+
+    private let defaults: UserDefaults
+    private let lock = NSLock()
+
+    init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
+
+    func setText(_ text: String?, for id: String, generation: UInt64) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = entriesMapUnlocked()
+        if let normalized = DownloadCompletedNotificationText.normalize(text) {
+            map[id] = Self.encodeEntry(text: normalized, generation: generation)
+        } else {
+            map.removeValue(forKey: id)
+        }
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    func takeText(for id: String, generation: UInt64?) -> String? {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = entriesMapUnlocked()
+        guard let entry = map[id] else {
+            return nil
+        }
+        if let generation, Self.generation(from: entry) != generation {
+            return nil
+        }
+        map.removeValue(forKey: id)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+        return Self.text(from: entry)
+    }
+
+    func removeText(for id: String, generation: UInt64?) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = entriesMapUnlocked()
+        guard let entry = map[id] else {
+            return
+        }
+        if let generation, Self.generation(from: entry) != generation {
+            return
+        }
+        map.removeValue(forKey: id)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    private func entriesMapUnlocked() -> [String: [String: Any]] {
+        defaults.dictionary(forKey: Self.userDefaultsKey) as? [String: [String: Any]] ?? [:]
+    }
+
+    private static func encodeEntry(text: String, generation: UInt64) -> [String: Any] {
+        ["text": text, "generation": NSNumber(value: generation)]
+    }
+
+    private static func text(from entry: [String: Any]) -> String? {
+        entry["text"] as? String
+    }
+
+    private static func generation(from entry: [String: Any]) -> UInt64? {
+        if let number = entry["generation"] as? NSNumber {
+            return number.uint64Value
+        }
+        return entry["generation"] as? UInt64
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadCompletedNotificationText.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+enum DownloadCompletedNotificationText {
+    static func normalize(_ text: String?) -> String? {
+        guard let text else {
+            return nil
+        }
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadIdGenerationStore.swift

@@ -0,0 +1,39 @@
+import Foundation
+
+final class DownloadIdGenerationStore {
+    static let shared = DownloadIdGenerationStore()
+
+    static let userDefaultsKey = "CapacitorDownloaderDownloadGenerations"
+
+    private let defaults: UserDefaults
+    private let lock = NSLock()
+
+    init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
+
+    func setGeneration(_ generation: UInt64, forDownloadId id: String) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = generationsMapUnlocked()
+        map[id] = NSNumber(value: generation)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    func allGenerations() -> [String: UInt64] {
+        lock.lock()
+        defer { lock.unlock() }
+        var result: [String: UInt64] = [:]
+        for (key, value) in generationsMapUnlocked() {
+            guard let number = value as? NSNumber else {
+                continue
+            }
+            result[key] = number.uint64Value
+        }
+        return result
+    }
+
+    private func generationsMapUnlocked() -> [String: Any] {
+        defaults.dictionary(forKey: Self.userDefaultsKey) ?? [:]
+    }
+}

package/ios/Sources/CapacitorDownloaderPlugin/DownloadTaskGenerationStore.swift

@@ -0,0 +1,47 @@
+import Foundation
+
+final class DownloadTaskGenerationStore {
+    static let shared = DownloadTaskGenerationStore()
+
+    static let userDefaultsKey = "CapacitorDownloaderTaskGenerations"
+
+    private let defaults: UserDefaults
+    private let lock = NSLock()
+
+    init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
+
+    func setGeneration(_ generation: UInt64, forTaskIdentifier taskIdentifier: Int) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = generationsMapUnlocked()
+        map[String(taskIdentifier)] = NSNumber(value: generation)
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    func removeGeneration(forTaskIdentifier taskIdentifier: Int) {
+        lock.lock()
+        defer { lock.unlock() }
+        var map = generationsMapUnlocked()
+        map.removeValue(forKey: String(taskIdentifier))
+        defaults.set(map, forKey: Self.userDefaultsKey)
+    }
+
+    func allGenerations() -> [Int: UInt64] {
+        lock.lock()
+        defer { lock.unlock() }
+        var result: [Int: UInt64] = [:]
+        for (key, value) in generationsMapUnlocked() {
+            guard let taskIdentifier = Int(key), let number = value as? NSNumber else {
+                continue
+            }
+            result[taskIdentifier] = number.uint64Value
+        }
+        return result
+    }
+
+    private func generationsMapUnlocked() -> [String: Any] {
+        defaults.dictionary(forKey: Self.userDefaultsKey) ?? [:]
+    }
+}