@capgo/capacitor-downloader 8.3.21 → 8.5.0

package/README.md

@@ -34,7 +34,61 @@ We build, improve and fix our plugins with heavy use of AI, so issues usually ge
 - **Control**: `pause()`, `resume()` and `stop()` for each download ID.
 - **Progress events**: `downloadProgress`, `downloadCompleted` and `downloadFailed` listeners.
 - **Status and files**: `checkStatus()` for a task and `getFileInfo()` for a downloaded file.
-- **Platforms**: iOS and Android. iOS uses a background `URLSession`, Android uses `DownloadManager`. Not available on web.
+- **Platforms**: iOS and Android. iOS uses a background `URLSession`. Android uses `DownloadManager` by default (same as earlier releases). **OkHttp** is opt in via `androidHttpEngine` for app-private destinations. Not available on web.
+- **Android private storage**: set `androidHttpEngine: 'auto'` or `'okhttp'` and use `cache/...` or `files/...` for internal storage. `notification: 'hidden'` hides DownloadManager progress UI; `downloadCompletedNotificationText` can still alert on success.
+
+## Android OkHttp engine (next release)
+
+**Opt in:** set `androidHttpEngine` to `'auto'` or `'okhttp'` for downloads into app-private storage (offline packs, encrypted assets, cache). When the option is omitted, every destination uses `DownloadManager` and legacy app external file paths, including existing `cache/...` and `files/...` strings.
+
+```typescript
+await CapacitorDownloader.download({
+  id: 'offline-pack',
+  url: 'https://cdn.example.com/pack.zip',
+  destination: 'files/offline/pack.zip',
+  androidHttpEngine: 'auto', // OkHttp for files/... and cache/...
+  notification: 'hidden', // no system notification during transfer; listen to downloadProgress
+});
+```
+
+| `androidHttpEngine` | Behavior |
+| ------------------- | -------- |
+| Omitted | DownloadManager only, legacy destination paths (matches pre-option releases) |
+| `'auto'` | OkHttp for `cache/...`, `files/...`, and paths under internal cache/data/files; DownloadManager for external app storage and `public-downloads/...` |
+| `'okhttp'` | Always OkHttp; rejects `public-downloads/...` paths |
+| `'downloadManager'` | Always system DownloadManager with legacy destination paths |
+
+**Android `destination` prefixes**
+
+| Prefix | Storage when `androidHttpEngine` is `'auto'` or `'okhttp'` | Storage when option is omitted |
+| ------ | ----------------------------------------------------------- | ------------------------------ |
+| `cache/...` | App cache dir (OkHttp with `'auto'`) | App external files (DownloadManager) |
+| `files/...` | App-private files dir (OkHttp with `'auto'`) | App external files (DownloadManager) |
+| `public-downloads/...` | Public Downloads folder (DownloadManager) | App external files under `public-downloads/...` (DownloadManager) |
+| Other relative paths | App external files dir (DownloadManager) | App external files dir (DownloadManager) |
+
+**Notifications on OkHttp:** no notification during the transfer. Use `notification: 'hidden'` with `downloadProgress` events, or `'completed'` to post one completion-style notification when the file finishes (not on failure). DownloadManager paths still honor `completed`, `progress`, and `hidden` as before. `downloadCompletedNotificationText` is separate and can still post on success when set.
+
+Full guide: https://capgo.app/docs/plugins/downloader/getting-started/#android-okhttp-engine
+
+## Download completed notifications
+
+Long downloads often finish while your user is in another app. Set `downloadCompletedNotificationText` on `download()` to show an opt-in, caller-localized system notification when the file is ready. Tapping it returns to your app.
+
+- **Opt in**: omit the option (or pass empty text) to rely on `downloadCompleted` events only.
+- **Permissions**: request notification permission in your app. If the user denies it, downloads still complete and the plugin skips the alert.
+- **Android**: the plugin manifest already merges `POST_NOTIFICATIONS`; on Android 13+ your app only needs to request it at runtime. Works alongside the DownloadManager `notification` visibility option. While your app is in the foreground, Android still posts the completion alert when the download succeeds.
+- **iOS**: request authorization with `UNUserNotificationCenter` before the download finishes. While your app is in the foreground, iOS shows a delivered notification only if your app's `UNUserNotificationCenter` delegate presents it, so without a notifications plugin it is usually silent; use `downloadCompleted` events in that case.
+
+```typescript
+await Downloader.download({
+  id: 'episode-12',
+  url: audioUrl,
+  destination: 'podcasts/episode-12.mp3',
+  notification: 'hidden',
+  downloadCompletedNotificationText: t('downloads.episodeReady'),
+});
+```
 
 ## Why Capacitor Downloader?
 
@@ -311,15 +365,17 @@ Represents the current state and progress of a download task.
 
 Configuration options for starting a download.
 
-| 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 |
+| 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. 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. |              |
+| **`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 DownloadManager progress notification; use plugin progress events instead. `downloadCompletedNotificationText` can still post a completion notification when the transfer succeeds. 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.                                                                                       | 8.2.0        |
+| **`androidHttpEngine`**                 | <code>'auto' \| 'okhttp' \| 'downloadManager'</code> | 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.                            | next release |
+| **`downloadCompletedNotificationText`** | <code>string</code>                                  | 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).                                                                                                                                                                                                                                                                                                                       | next release |
 
 
 #### PluginListenerHandle

package/android/build.gradle

@@ -57,8 +57,11 @@ dependencies {
     implementation project(':capacitor-android')
     annotationProcessor project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "com.squareup.okhttp3:okhttp:4.12.0"
     testImplementation "junit:junit:$junitVersion"
     testImplementation "org.mockito:mockito-core:5.24.0"
+    testImplementation "com.squareup.okhttp3:mockwebserver:4.12.0"
+    testImplementation "com.squareup.okhttp3:okhttp-tls:4.12.0"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
 }

package/android/src/main/AndroidManifest.xml

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

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

@@ -0,0 +1,143 @@
+package ee.forgr.capacitor.plugin.downloader;
+
+import android.content.Context;
+import java.io.File;
+import java.io.IOException;
+
+/**
+ * Resolves download destinations under app storage roots.
+ *
+ * <p>With legacy resolution (default when {@code androidHttpEngine} is omitted), relative paths match
+ * released plugin behavior: all paths are under app external files, including {@code cache/...} and
+ * {@code files/...} as literal subpaths. {@code file://} and absolute paths use the same {@code File}
+ * parent resolution as main: {@code new File(getExternalFilesDir(null), child)}.
+ *
+ * <p>With extended resolution ({@code androidHttpEngine: 'auto'} or {@code 'okhttp'}), relative prefixes:
+ * <ul>
+ *   <li>{@code cache/...} -> {@link Context#getCacheDir()}</li>
+ *   <li>{@code files/...} -> {@link Context#getFilesDir()} (app-private data)</li>
+ *   <li>{@code public-downloads/...} -> public Downloads directory (DownloadManager only)</li>
+ *   <li>other relative paths -> app external files</li>
+ * </ul>
+ */
+public final class AndroidDownloadDestination {
+
+    private AndroidDownloadDestination() {}
+
+    public static ResolvedDestination resolve(Context context, String destination, boolean extendedRoots) {
+        if (destination == null || destination.trim().isEmpty()) {
+            throw new IllegalArgumentException("Missing destination");
+        }
+
+        String trimmed = destination.trim();
+
+        if (!extendedRoots) {
+            return resolveLegacyMain(context, trimmed);
+        }
+
+        if (trimmed.startsWith("file://")) {
+            File file = new File(android.net.Uri.parse(trimmed).getPath());
+            return new ResolvedDestination(file, preferOkHttpInAutoMode(context, file));
+        }
+
+        if (trimmed.startsWith("/")) {
+            File file = new File(trimmed);
+            return new ResolvedDestination(file, preferOkHttpInAutoMode(context, file));
+        }
+
+        if (trimmed.startsWith("cache/")) {
+            File base = context.getCacheDir();
+            File file = childUnder(base, trimmed.substring("cache/".length()));
+            return new ResolvedDestination(file, true);
+        }
+
+        if (trimmed.startsWith("files/")) {
+            File base = context.getFilesDir();
+            File file = childUnder(base, trimmed.substring("files/".length()));
+            return new ResolvedDestination(file, true);
+        }
+
+        if (trimmed.startsWith("public-downloads/")) {
+            File base = android.os.Environment.getExternalStoragePublicDirectory(android.os.Environment.DIRECTORY_DOWNLOADS);
+            File file = childUnder(base, trimmed.substring("public-downloads/".length()));
+            return new ResolvedDestination(file, false);
+        }
+
+        File base = context.getExternalFilesDir(null);
+        boolean usedInternalFallback = base == null;
+        if (usedInternalFallback) {
+            base = context.getFilesDir();
+        }
+        File file = childUnder(base, trimmed);
+        boolean preferOkHttp = usedInternalFallback || preferOkHttpInAutoMode(context, file);
+        return new ResolvedDestination(file, preferOkHttp);
+    }
+
+    private static ResolvedDestination resolveLegacyMain(Context context, String trimmed) {
+        File base = context.getExternalFilesDir(null);
+        boolean usedInternalFallback = base == null;
+        if (usedInternalFallback) {
+            base = context.getFilesDir();
+        }
+        File file = new File(base, trimmed);
+        boolean preferOkHttp = usedInternalFallback;
+        return new ResolvedDestination(file, preferOkHttp);
+    }
+
+    static File childUnder(File base, String relative) {
+        if (base == null) {
+            throw new IllegalArgumentException("Storage root is unavailable");
+        }
+        File file = new File(base, relative);
+        try {
+            String canonical = file.getCanonicalPath();
+            String baseCanonical = base.getCanonicalPath();
+            if (!canonical.startsWith(baseCanonical + File.separator)) {
+                throw new IllegalArgumentException("Destination must name a file under app storage: " + relative);
+            }
+        } catch (IOException e) {
+            throw new IllegalArgumentException("Invalid destination path", e);
+        }
+        return file;
+    }
+
+    /**
+     * Whether {@link AndroidHttpEngineSelector} should pick OkHttp when {@code androidHttpEngine} is auto.
+     */
+    public static boolean preferOkHttpInAutoMode(Context context, File file) {
+        try {
+            String canonical = file.getCanonicalPath();
+            return (
+                isUnder(canonical, context.getCacheDir()) ||
+                isUnder(canonical, context.getFilesDir()) ||
+                isUnder(canonical, context.getDataDir())
+            );
+        } catch (IOException e) {
+            return false;
+        }
+    }
+
+    private static boolean isUnder(String path, File root) {
+        if (root == null) {
+            return false;
+        }
+        try {
+            String rootCanonical = root.getCanonicalPath();
+            return path.equals(rootCanonical) || path.startsWith(rootCanonical + File.separator);
+        } catch (IOException e) {
+            return false;
+        }
+    }
+
+    public static final class ResolvedDestination {
+
+        public final File file;
+        /** When true, {@code androidHttpEngine: 'auto'} selects OkHttp. */
+        public final boolean preferOkHttpInAutoMode;
+
+        ResolvedDestination(File file, boolean preferOkHttpInAutoMode) {
+            this.file = file;
+            this.preferOkHttpInAutoMode = preferOkHttpInAutoMode;
+        }
+    }
+}

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

@@ -0,0 +1,33 @@
+package ee.forgr.capacitor.plugin.downloader;
+
+/**
+ * Chooses between DownloadManager and OkHttp for Android downloads.
+ */
+public final class AndroidHttpEngineSelector {
+
+    public enum Engine {
+        DOWNLOAD_MANAGER,
+        OKHTTP
+    }
+
+    private AndroidHttpEngineSelector() {}
+
+    /**
+     * @param option explicit value from {@code androidHttpEngine}: auto, okhttp, or downloadManager (null => DownloadManager, same as main)
+     */
+    public static Engine resolve(String option, boolean preferOkHttpInAutoMode) {
+        if (option == null || option.isEmpty()) {
+            return Engine.DOWNLOAD_MANAGER;
+        }
+        if ("auto".equalsIgnoreCase(option)) {
+            return preferOkHttpInAutoMode ? Engine.OKHTTP : Engine.DOWNLOAD_MANAGER;
+        }
+        if ("okhttp".equalsIgnoreCase(option) || "native".equalsIgnoreCase(option)) {
+            return Engine.OKHTTP;
+        }
+        if ("downloadManager".equalsIgnoreCase(option) || "download_manager".equalsIgnoreCase(option)) {
+            return Engine.DOWNLOAD_MANAGER;
+        }
+        throw new IllegalArgumentException("Invalid androidHttpEngine: " + option);
+    }
+}