@capgo/capacitor-downloader 8.4.1 → 8.5.0

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

@@ -0,0 +1,420 @@
+package ee.forgr.capacitor.plugin.downloader;
+
+import android.content.Context;
+import android.net.ConnectivityManager;
+import android.net.Network;
+import android.net.NetworkCapabilities;
+import com.getcapacitor.JSObject;
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.Semaphore;
+import java.util.concurrent.atomic.AtomicBoolean;
+import okhttp3.Call;
+import okhttp3.OkHttpClient;
+import okhttp3.Request;
+import okhttp3.Response;
+import okhttp3.ResponseBody;
+
+public class OkHttpDownloadExecutor {
+
+    public static final long TRACKED_DOWNLOAD_ID = -2L;
+    private static final int MAX_CONCURRENT_TRANSFERS = 4;
+
+    public enum State {
+        PENDING,
+        RUNNING,
+        DONE,
+        ERROR,
+        CANCELLED
+    }
+
+    public static final class ActiveDownload {
+
+        public final String id;
+        public volatile State state = State.PENDING;
+        public volatile float progress;
+        public volatile long bytesWritten;
+        public volatile long bytesTotal;
+        public volatile String errorMessage;
+        public volatile Call call;
+        public volatile File tempFile;
+        public volatile File committedDestination;
+        public volatile Network boundWifiNetwork;
+        public final AtomicBoolean cancelled = new AtomicBoolean(false);
+
+        ActiveDownload(String id) {
+            this.id = id;
+        }
+    }
+
+    private final OkHttpClient defaultClient;
+    private final Map<String, ActiveDownload> activeDownloads = new ConcurrentHashMap<>();
+    private final Semaphore transferSlots = new Semaphore(MAX_CONCURRENT_TRANSFERS);
+    private final Context context;
+
+    public OkHttpDownloadExecutor(Context context) {
+        this.context = context.getApplicationContext();
+        this.defaultClient = new OkHttpClient.Builder().followRedirects(true).followSslRedirects(false).build();
+    }
+
+    public ActiveDownload getActive(String id) {
+        return activeDownloads.get(id);
+    }
+
+    /**
+     * Reserve an in-memory slot before the transfer id is published to JS. Prevents a race where
+     * {@code stop()} runs between marker publication and worker registration.
+     */
+    public boolean beginTransfer(String id) {
+        ActiveDownload active = new ActiveDownload(id);
+        active.state = State.PENDING;
+        return activeDownloads.putIfAbsent(id, active) == null;
+    }
+
+    public void abandonTransfer(String id) {
+        ActiveDownload active = activeDownloads.remove(id);
+        if (active != null && active.call != null) {
+            active.call.cancel();
+        }
+    }
+
+    public void start(
+        String id,
+        String url,
+        File destinationFile,
+        JSObject headers,
+        String network,
+        ProgressReporter reporter,
+        CompletionListener completionListener
+    ) {
+        ActiveDownload active = activeDownloads.get(id);
+        if (active == null) {
+            throw new IllegalStateException("Download not registered");
+        }
+
+        Network wifiNetwork = resolveWifiNetworkForTransfer(network);
+        if ("wifi-only".equals(network) && (wifiNetwork == null || !isWifiNetworkUsable(wifiNetwork))) {
+            activeDownloads.remove(id, active);
+            throw new IllegalStateException("Wi-Fi required for this download");
+        }
+
+        boolean acquired = false;
+        try {
+            transferSlots.acquire();
+            acquired = true;
+
+            synchronized (active) {
+                if (active.cancelled.get()) {
+                    finishCancelled(active, null, id, completionListener);
+                    return;
+                }
+            }
+
+            if (wifiNetwork != null) {
+                active.boundWifiNetwork = wifiNetwork;
+            }
+            OkHttpClient client = buildClientForNetwork(network, wifiNetwork);
+
+            File tempFile = null;
+            try {
+                synchronized (active) {
+                    if (active.cancelled.get()) {
+                        finishCancelled(active, null, id, completionListener);
+                        return;
+                    }
+                }
+
+                Request.Builder requestBuilder = new Request.Builder().url(url);
+                if (headers != null) {
+                    Iterator<String> it = headers.keys();
+                    if (it != null) {
+                        while (it.hasNext()) {
+                            String key = it.next();
+                            requestBuilder.addHeader(key, headers.getString(key));
+                        }
+                    }
+                }
+
+                Request request = requestBuilder.build();
+                Call call = client.newCall(request);
+                synchronized (active) {
+                    if (active.cancelled.get()) {
+                        call.cancel();
+                        finishCancelled(active, null, id, completionListener);
+                        return;
+                    }
+                    active.call = call;
+                }
+                active.state = State.RUNNING;
+
+                File parent = destinationFile.getParentFile();
+                if (parent != null && !parent.exists() && !parent.mkdirs()) {
+                    throw new IOException("Could not create destination directory");
+                }
+
+                tempFile = createTempDownloadFile(destinationFile, parent);
+                active.tempFile = tempFile;
+
+                try (Response response = call.execute()) {
+                    if (active.cancelled.get()) {
+                        finishCancelled(active, tempFile, id, completionListener);
+                        return;
+                    }
+
+                    if (url.regionMatches(true, 0, "https:", 0, 6) && !response.request().url().isHttps()) {
+                        active.state = State.ERROR;
+                        active.errorMessage = "HTTPS to HTTP redirect is not allowed";
+                        tempFile.delete();
+                        completionListener.onFinished(id, false, false, active.errorMessage);
+                        return;
+                    }
+
+                    int code = response.code();
+                    if (code == 206) {
+                        active.state = State.ERROR;
+                        active.errorMessage = "Partial content (HTTP 206) is not supported";
+                        tempFile.delete();
+                        completionListener.onFinished(id, false, false, active.errorMessage);
+                        return;
+                    }
+
+                    if (!response.isSuccessful()) {
+                        active.state = State.ERROR;
+                        active.errorMessage = "HTTP " + code;
+                        tempFile.delete();
+                        completionListener.onFinished(id, false, false, active.errorMessage);
+                        return;
+                    }
+
+                    ResponseBody body = response.body();
+                    if (body == null) {
+                        active.state = State.ERROR;
+                        active.errorMessage = "Empty response body";
+                        tempFile.delete();
+                        completionListener.onFinished(id, false, false, active.errorMessage);
+                        return;
+                    }
+
+                    long total = body.contentLength();
+                    active.bytesTotal = total > 0 ? total : 0L;
+
+                    try (InputStream input = body.byteStream(); FileOutputStream output = new FileOutputStream(tempFile)) {
+                        byte[] buffer = new byte[8192];
+                        long written = 0L;
+                        int read;
+                        int lastReportedPercent = -1;
+                        while ((read = input.read(buffer)) != -1) {
+                            if (active.cancelled.get()) {
+                                finishCancelled(active, tempFile, id, completionListener);
+                                return;
+                            }
+                            output.write(buffer, 0, read);
+                            written += read;
+                            active.bytesWritten = written;
+                            if (total > 0) {
+                                active.progress = (float) written / (float) total;
+                            }
+                            int percent = (int) (active.progress * 100f);
+                            if (percent != lastReportedPercent) {
+                                lastReportedPercent = percent;
+                                reporter.reportProgress(id, active.progress);
+                            }
+                        }
+                    }
+
+                    if (!commitTempToDestination(active, tempFile, destinationFile)) {
+                        finishCancelled(active, tempFile, id, completionListener);
+                        return;
+                    }
+                    tempFile = null;
+
+                    reporter.reportProgress(id, 1f);
+                    completionListener.onFinished(id, true, false, null);
+                }
+            } catch (IOException e) {
+                if (tempFile != null && tempFile.exists()) {
+                    tempFile.delete();
+                }
+                if (active.cancelled.get()) {
+                    active.state = State.CANCELLED;
+                    completionListener.onFinished(id, false, true, null);
+                } else {
+                    active.state = State.ERROR;
+                    active.errorMessage = e.getMessage() != null ? e.getMessage() : "Download failed";
+                    completionListener.onFinished(id, false, false, active.errorMessage);
+                }
+            } catch (RuntimeException e) {
+                activeDownloads.remove(id, active);
+                throw e;
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            active.state = State.ERROR;
+            active.errorMessage = "Download interrupted";
+            completionListener.onFinished(id, false, false, active.errorMessage);
+        } finally {
+            if (acquired) {
+                transferSlots.release();
+            }
+        }
+    }
+
+    private boolean commitTempToDestination(ActiveDownload active, File tempFile, File destinationFile) throws IOException {
+        synchronized (active) {
+            if (active.cancelled.get()) {
+                tempFile.delete();
+                active.state = State.CANCELLED;
+                return false;
+            }
+            active.tempFile = null;
+            if (destinationFile.exists() && !destinationFile.delete()) {
+                throw new IOException("Could not replace existing destination file");
+            }
+            if (active.cancelled.get()) {
+                tempFile.delete();
+                active.state = State.CANCELLED;
+                return false;
+            }
+            if (!tempFile.renameTo(destinationFile)) {
+                throw new IOException("Could not move downloaded file into place");
+            }
+            if (active.cancelled.get()) {
+                destinationFile.delete();
+                active.state = State.CANCELLED;
+                return false;
+            }
+            active.committedDestination = destinationFile;
+            active.bytesWritten = destinationFile.length();
+            active.progress = 1f;
+            active.state = State.DONE;
+            return true;
+        }
+    }
+
+    private void finishCancelled(ActiveDownload active, File tempFile, String id, CompletionListener completionListener) {
+        active.state = State.CANCELLED;
+        File toDelete = tempFile;
+        if (toDelete == null) {
+            synchronized (active) {
+                toDelete = active.tempFile;
+            }
+        }
+        if (toDelete != null && toDelete.exists()) {
+            toDelete.delete();
+        }
+        completionListener.onFinished(id, false, true, null);
+    }
+
+    private static File createTempDownloadFile(File destinationFile, File parent) throws IOException {
+        String baseName = destinationFile.getName();
+        if (baseName.isEmpty()) {
+            baseName = "download";
+        }
+        String prefix = baseName.length() >= 3 ? baseName : "dl" + baseName;
+        if (prefix.length() < 3) {
+            prefix = "cap";
+        }
+        return File.createTempFile(prefix + "-", ".capgo-download", parent != null ? parent : destinationFile.getParentFile());
+    }
+
+    private OkHttpClient buildClientForNetwork(String network, Network wifiNetwork) {
+        if (!"wifi-only".equals(network)) {
+            return defaultClient;
+        }
+        if (wifiNetwork == null) {
+            throw new IllegalStateException("Wi-Fi required for this download");
+        }
+        return defaultClient.newBuilder().socketFactory(wifiNetwork.getSocketFactory()).build();
+    }
+
+    Network resolveWifiNetworkForTransfer(String network) {
+        if (!"wifi-only".equals(network)) {
+            return null;
+        }
+        return findWifiNetwork();
+    }
+
+    private Network findWifiNetwork() {
+        ConnectivityManager connectivityManager = (ConnectivityManager) context.getSystemService(Context.CONNECTIVITY_SERVICE);
+        if (connectivityManager == null) {
+            return null;
+        }
+        for (Network network : connectivityManager.getAllNetworks()) {
+            NetworkCapabilities capabilities = connectivityManager.getNetworkCapabilities(network);
+            if (capabilities != null && capabilities.hasTransport(NetworkCapabilities.TRANSPORT_WIFI)) {
+                return network;
+            }
+        }
+        return null;
+    }
+
+    public boolean cancel(String id, File destinationFile) {
+        ActiveDownload active = activeDownloads.get(id);
+        if (active == null) {
+            if (destinationFile != null && destinationFile.exists()) {
+                return destinationFile.delete();
+            }
+            return false;
+        }
+        active.cancelled.set(true);
+        Call call = active.call;
+        if (call != null) {
+            call.cancel();
+        }
+        synchronized (active) {
+            File temp = active.tempFile;
+            if (temp != null && temp.exists()) {
+                temp.delete();
+            }
+            File committed = active.committedDestination;
+            if (committed != null && committed.exists()) {
+                committed.delete();
+            } else if (destinationFile != null && destinationFile.exists() && active.state == State.DONE) {
+                destinationFile.delete();
+            }
+        }
+        activeDownloads.remove(id, active);
+        return true;
+    }
+
+    public void clearCompleted(String id) {
+        ActiveDownload active = activeDownloads.get(id);
+        if (active != null && (active.state == State.DONE || active.state == State.ERROR || active.state == State.CANCELLED)) {
+            activeDownloads.remove(id, active);
+        }
+    }
+
+    public boolean isWifiSatisfied(String network) {
+        if (!"wifi-only".equals(network)) {
+            return true;
+        }
+        Network wifi = resolveWifiNetworkForTransfer(network);
+        return wifi != null && isWifiNetworkUsable(wifi);
+    }
+
+    private boolean isWifiNetworkUsable(Network network) {
+        ConnectivityManager connectivityManager = (ConnectivityManager) context.getSystemService(Context.CONNECTIVITY_SERVICE);
+        if (connectivityManager == null || network == null) {
+            return false;
+        }
+        NetworkCapabilities capabilities = connectivityManager.getNetworkCapabilities(network);
+        return (
+            capabilities != null &&
+            capabilities.hasTransport(NetworkCapabilities.TRANSPORT_WIFI) &&
+            capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
+        );
+    }
+
+    public interface ProgressReporter {
+        void reportProgress(String id, float progress);
+    }
+
+    public interface CompletionListener {
+        void onFinished(String id, boolean success, boolean cancelled, String errorMessage);
+    }
+}

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  downloadCompletedNotificationText: 'Your file is ready', // opt-in completion alert\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,15 +397,27 @@
               "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": "8.4.0",
+              "text": "next release",
               "name": "since"
             }
           ],

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,32 @@ 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.
      *
@@ -50,7 +81,7 @@ export interface DownloadOptions {
      * Omitted or empty means no completion notification from the plugin (use
      * `downloadCompleted` events while the app is open).
      *
-     * @since 8.4.0
+     * @since next release
      */
     downloadCompletedNotificationText?: string;
 }
@@ -69,8 +100,9 @@ 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   * 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 8.4.0\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: 'downloads/file.pdf',\n   *   notification: 'hidden', // Android: no system notification; 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"]}
+{"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.4.1"
+    private let pluginVersion: String = "8.5.0"
     public let identifier = "CapacitorDownloaderPlugin"
     public let jsName = "CapacitorDownloader"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-downloader",
-  "version": "8.4.1",
+  "version": "8.5.0",
   "description": "Download file in background or foreground",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",