@capacitor/filesystem 5.0.6-nightly-20230712T151609.0 → 5.1.1-nightly-20230713T150800.0

package/README.md

@@ -101,6 +101,8 @@ const readFilePath = async () => {
 * [`copy(...)`](#copy)
 * [`checkPermissions()`](#checkpermissions)
 * [`requestPermissions()`](#requestpermissions)
+* [`downloadFile(...)`](#downloadfile)
+* [`addListener('progress', ...)`](#addlistenerprogress)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
 * [Enums](#enums)
@@ -343,6 +345,45 @@ Required on Android, only when using <a href="#directory">`Directory.Documents`<
 --------------------
 
 
+### downloadFile(...)
+
+```typescript
+downloadFile(options: DownloadFileOptions) => Promise<DownloadFileResult>
+```
+
+Perform a http request to a server and download the file to the specified destination.
+
+| Param         | Type                                                                |
+| ------------- | ------------------------------------------------------------------- |
+| **`options`** | <code><a href="#downloadfileoptions">DownloadFileOptions</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#downloadfileresult">DownloadFileResult</a>&gt;</code>
+
+**Since:** 5.1.0
+
+--------------------
+
+
+### addListener('progress', ...)
+
+```typescript
+addListener(eventName: 'progress', listenerFunc: ProgressListener) => Promise<PluginListenerHandle> & PluginListenerHandle
+```
+
+Add a listener to file download progress events.
+
+| Param              | Type                                                          |
+| ------------------ | ------------------------------------------------------------- |
+| **`eventName`**    | <code>'progress'</code>                                       |
+| **`listenerFunc`** | <code><a href="#progresslistener">ProgressListener</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt; & <a href="#pluginlistenerhandle">PluginListenerHandle</a></code>
+
+**Since:** 5.1.0
+
+--------------------
+
+
 ### Interfaces
 
 
@@ -428,7 +469,7 @@ Required on Android, only when using <a href="#directory">`Directory.Documents`<
 | Prop        | Type                               | Description                                                                          | Since |
 | ----------- | ---------------------------------- | ------------------------------------------------------------------------------------ | ----- |
 | **`name`**  | <code>string</code>                | Name of the file or directory.                                                       |       |
-| **`type`**  | <code>'directory' \| 'file'</code> | Type of the file.                                                                    | 4.0.0 |
+| **`type`**  | <code>'file' \| 'directory'</code> | Type of the file.                                                                    | 4.0.0 |
 | **`size`**  | <code>number</code>                | Size of the file in bytes.                                                           | 4.0.0 |
 | **`ctime`** | <code>number</code>                | Time of creation in milliseconds. It's not available on Android 7 and older devices. | 4.0.0 |
 | **`mtime`** | <code>number</code>                | Time of last modification in milliseconds.                                           | 4.0.0 |
@@ -462,7 +503,7 @@ Required on Android, only when using <a href="#directory">`Directory.Documents`<
 
 | Prop        | Type                               | Description                                                                          | Since |
 | ----------- | ---------------------------------- | ------------------------------------------------------------------------------------ | ----- |
-| **`type`**  | <code>'directory' \| 'file'</code> | Type of the file.                                                                    | 1.0.0 |
+| **`type`**  | <code>'file' \| 'directory'</code> | Type of the file.                                                                    | 1.0.0 |
 | **`size`**  | <code>number</code>                | Size of the file in bytes.                                                           | 1.0.0 |
 | **`ctime`** | <code>number</code>                | Time of creation in milliseconds. It's not available on Android 7 and older devices. | 1.0.0 |
 | **`mtime`** | <code>number</code>                | Time of last modification in milliseconds.                                           | 1.0.0 |
@@ -501,6 +542,39 @@ Required on Android, only when using <a href="#directory">`Directory.Documents`<
 | **`publicStorage`** | <code><a href="#permissionstate">PermissionState</a></code> |
 
 
+#### DownloadFileResult
+
+| Prop       | Type                | Description                                                          | Since |
+| ---------- | ------------------- | -------------------------------------------------------------------- | ----- |
+| **`path`** | <code>string</code> | The path the file was downloaded to.                                 | 5.1.0 |
+| **`blob`** | <code>Blob</code>   | The blob data of the downloaded file. This is only available on web. | 5.1.0 |
+
+
+#### DownloadFileOptions
+
+| Prop            | Type                                            | Description                                                                                                                                                                                                                      | Since |
+| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`path`**      | <code>string</code>                             | The path the downloaded file should be moved to.                                                                                                                                                                                 | 5.1.0 |
+| **`directory`** | <code><a href="#directory">Directory</a></code> | The directory to write the file to. If this option is used, filePath can be a relative path rather than absolute. The default is the `DATA` directory.                                                                           | 5.1.0 |
+| **`progress`**  | <code>boolean</code>                            | An optional listener function to receive downloaded progress events. If this option is used, progress event should be dispatched on every chunk received. Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns. | 5.1.0 |
+
+
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+#### ProgressStatus
+
+| Prop                | Type                | Description                                          | Since |
+| ------------------- | ------------------- | ---------------------------------------------------- | ----- |
+| **`url`**           | <code>string</code> | The url of the file being downloaded.                | 5.1.0 |
+| **`bytes`**         | <code>number</code> | The number of bytes downloaded so far.               | 5.1.0 |
+| **`contentLength`** | <code>number</code> | The total number of bytes to download for this file. | 5.1.0 |
+
+
 ### Type Aliases
 
 
@@ -514,6 +588,13 @@ Required on Android, only when using <a href="#directory">`Directory.Documents`<
 <code>'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'</code>
 
 
+#### ProgressListener
+
+A listener function that receives progress events.
+
+<code>(progress: <a href="#progressstatus">ProgressStatus</a>): void</code>
+
+
 ### Enums
 
 

package/android/src/main/java/com/capacitorjs/plugins/filesystem/Filesystem.java

@@ -7,10 +7,27 @@ import android.util.Base64;
 import com.capacitorjs.plugins.filesystem.exceptions.CopyFailedException;
 import com.capacitorjs.plugins.filesystem.exceptions.DirectoryExistsException;
 import com.capacitorjs.plugins.filesystem.exceptions.DirectoryNotFoundException;
-import java.io.*;
+import com.getcapacitor.Bridge;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.plugin.util.CapacitorHttpUrlConnection;
+import com.getcapacitor.plugin.util.HttpRequestHandler;
+import java.io.BufferedWriter;
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileNotFoundException;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStreamWriter;
+import java.net.URISyntaxException;
+import java.net.URL;
 import java.nio.channels.FileChannel;
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
+import java.util.Locale;
+import org.json.JSONException;
 
 public class Filesystem {
 
@@ -285,4 +302,82 @@ public class Filesystem {
             destination.transferFrom(source, 0, source.size());
         }
     }
+
+    public JSObject downloadFile(PluginCall call, Bridge bridge, HttpRequestHandler.ProgressEmitter emitter)
+        throws IOException, URISyntaxException, JSONException {
+        String urlString = call.getString("url", "");
+        JSObject headers = call.getObject("headers", new JSObject());
+        JSObject params = call.getObject("params", new JSObject());
+        Integer connectTimeout = call.getInt("connectTimeout");
+        Integer readTimeout = call.getInt("readTimeout");
+        Boolean disableRedirects = call.getBoolean("disableRedirects");
+        Boolean shouldEncode = call.getBoolean("shouldEncodeUrlParams", true);
+        Boolean progress = call.getBoolean("progress", false);
+
+        String method = call.getString("method", "GET").toUpperCase(Locale.ROOT);
+        String path = call.getString("path");
+        String directory = call.getString("directory", Environment.DIRECTORY_DOWNLOADS);
+
+        final URL url = new URL(urlString);
+        final File file = getFileObject(path, directory);
+
+        HttpRequestHandler.HttpURLConnectionBuilder connectionBuilder = new HttpRequestHandler.HttpURLConnectionBuilder()
+            .setUrl(url)
+            .setMethod(method)
+            .setHeaders(headers)
+            .setUrlParams(params, shouldEncode)
+            .setConnectTimeout(connectTimeout)
+            .setReadTimeout(readTimeout)
+            .setDisableRedirects(disableRedirects)
+            .openConnection();
+
+        CapacitorHttpUrlConnection connection = connectionBuilder.build();
+
+        connection.setSSLSocketFactory(bridge);
+
+        InputStream connectionInputStream = connection.getInputStream();
+        FileOutputStream fileOutputStream = new FileOutputStream(file, false);
+
+        String contentLength = connection.getHeaderField("content-length");
+        int bytes = 0;
+        int maxBytes = 0;
+
+        try {
+            maxBytes = contentLength != null ? Integer.parseInt(contentLength) : 0;
+        } catch (NumberFormatException ignored) {}
+
+        byte[] buffer = new byte[1024];
+        int len;
+
+        // Throttle emitter to 100ms so it doesn't slow down app
+        long lastEmitTime = System.currentTimeMillis();
+        long minEmitIntervalMillis = 100;
+
+        while ((len = connectionInputStream.read(buffer)) > 0) {
+            fileOutputStream.write(buffer, 0, len);
+
+            bytes += len;
+
+            if (progress && null != emitter) {
+                long currentTime = System.currentTimeMillis();
+                if (currentTime - lastEmitTime > minEmitIntervalMillis) {
+                    emitter.emit(bytes, maxBytes);
+                    lastEmitTime = currentTime;
+                }
+            }
+        }
+
+        if (progress && null != emitter) {
+            emitter.emit(bytes, maxBytes);
+        }
+
+        connectionInputStream.close();
+        fileOutputStream.close();
+
+        return new JSObject() {
+            {
+                put("path", file.getAbsolutePath());
+            }
+        };
+    }
 }

package/android/src/main/java/com/capacitorjs/plugins/filesystem/FilesystemPlugin.java

@@ -4,6 +4,7 @@ import android.Manifest;
 import android.media.MediaScannerConnection;
 import android.net.Uri;
 import android.os.Build;
+import android.os.Environment;
 import com.capacitorjs.plugins.filesystem.exceptions.CopyFailedException;
 import com.capacitorjs.plugins.filesystem.exceptions.DirectoryExistsException;
 import com.capacitorjs.plugins.filesystem.exceptions.DirectoryNotFoundException;
@@ -17,7 +18,10 @@ import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
 import com.getcapacitor.annotation.Permission;
 import com.getcapacitor.annotation.PermissionCallback;
-import java.io.*;
+import com.getcapacitor.plugin.util.HttpRequestHandler;
+import java.io.File;
+import java.io.FileNotFoundException;
+import java.io.IOException;
 import java.nio.charset.Charset;
 import java.nio.file.Files;
 import java.nio.file.attribute.BasicFileAttributes;
@@ -376,6 +380,31 @@ public class FilesystemPlugin extends Plugin {
         this._copy(call, false);
     }
 
+    @PluginMethod
+    public void downloadFile(PluginCall call) {
+        try {
+            String directory = call.getString("directory", Environment.DIRECTORY_DOWNLOADS);
+
+            if (isPublicDirectory(directory) && !isStoragePermissionGranted()) {
+                requestAllPermissions(call, "permissionCallback");
+            } else {
+                HttpRequestHandler.ProgressEmitter emitter = (bytes, contentLength) -> {
+                    JSObject ret = new JSObject();
+                    ret.put("url", call.getString("url"));
+                    ret.put("bytes", bytes);
+                    ret.put("contentLength", contentLength);
+
+                    notifyListeners("progress", ret);
+                };
+
+                JSObject response = implementation.downloadFile(call, bridge, emitter);
+                call.resolve(response);
+            }
+        } catch (Exception ex) {
+            call.reject("Error downloading file: " + ex.getLocalizedMessage(), ex);
+        }
+    }
+
     private void _copy(PluginCall call, Boolean doRename) {
         String from = call.getString("from");
         String to = call.getString("to");
@@ -448,6 +477,9 @@ public class FilesystemPlugin extends Plugin {
             case "stat":
                 stat(call);
                 break;
+            case "downloadFile":
+                downloadFile(call);
+                break;
         }
     }
 

package/dist/docs.json

@@ -297,6 +297,59 @@
           "PermissionStatus"
         ],
         "slug": "requestpermissions"
+      },
+      {
+        "name": "downloadFile",
+        "signature": "(options: DownloadFileOptions) => Promise<DownloadFileResult>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "DownloadFileOptions"
+          }
+        ],
+        "returns": "Promise<DownloadFileResult>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "5.1.0"
+          }
+        ],
+        "docs": "Perform a http request to a server and download the file to the specified destination.",
+        "complexTypes": [
+          "DownloadFileResult",
+          "DownloadFileOptions"
+        ],
+        "slug": "downloadfile"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'progress', listenerFunc: ProgressListener) => Promise<PluginListenerHandle> & PluginListenerHandle",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'progress'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "ProgressListener"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle> & PluginListenerHandle",
+        "tags": [
+          {
+            "name": "since",
+            "text": "5.1.0"
+          }
+        ],
+        "docs": "Add a listener to file download progress events.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "ProgressListener"
+        ],
+        "slug": "addlistenerprogress"
       }
     ],
     "properties": []
@@ -715,7 +768,7 @@
           ],
           "docs": "Type of the file.",
           "complexTypes": [],
-          "type": "'directory' | 'file'"
+          "type": "'file' | 'directory'"
         },
         {
           "name": "size",
@@ -875,7 +928,7 @@
           ],
           "docs": "Type of the file.",
           "complexTypes": [],
-          "type": "'directory' | 'file'"
+          "type": "'file' | 'directory'"
         },
         {
           "name": "size",
@@ -1061,6 +1114,149 @@
           "type": "PermissionState"
         }
       ]
+    },
+    {
+      "name": "DownloadFileResult",
+      "slug": "downloadfileresult",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "path",
+          "tags": [
+            {
+              "text": "5.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The path the file was downloaded to.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "blob",
+          "tags": [
+            {
+              "text": "5.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The blob data of the downloaded file.\nThis is only available on web.",
+          "complexTypes": [
+            "Blob"
+          ],
+          "type": "Blob"
+        }
+      ]
+    },
+    {
+      "name": "DownloadFileOptions",
+      "slug": "downloadfileoptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "path",
+          "tags": [
+            {
+              "text": "5.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The path the downloaded file should be moved to.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "directory",
+          "tags": [
+            {
+              "text": "5.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The directory to write the file to.\nIf this option is used, filePath can be a relative path rather than absolute.\nThe default is the `DATA` directory.",
+          "complexTypes": [
+            "Directory"
+          ],
+          "type": "Directory"
+        },
+        {
+          "name": "progress",
+          "tags": [
+            {
+              "text": "5.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "An optional listener function to receive downloaded progress events.\nIf this option is used, progress event should be dispatched on every chunk received.\nChunks are throttled to every 100ms on Android/iOS to avoid slowdowns.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        }
+      ]
+    },
+    {
+      "name": "PluginListenerHandle",
+      "slug": "pluginlistenerhandle",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "remove",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "() => Promise<void>"
+        }
+      ]
+    },
+    {
+      "name": "ProgressStatus",
+      "slug": "progressstatus",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "url",
+          "tags": [
+            {
+              "text": "5.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The url of the file being downloaded.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "bytes",
+          "tags": [
+            {
+              "text": "5.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The number of bytes downloaded so far.",
+          "complexTypes": [],
+          "type": "number"
+        },
+        {
+          "name": "contentLength",
+          "tags": [
+            {
+              "text": "5.1.0",
+              "name": "since"
+            }
+          ],
+          "docs": "The total number of bytes to download for this file.",
+          "complexTypes": [],
+          "type": "number"
+        }
+      ]
     }
   ],
   "enums": [
@@ -1212,6 +1408,19 @@
           "complexTypes": []
         }
       ]
+    },
+    {
+      "name": "ProgressListener",
+      "slug": "progresslistener",
+      "docs": "A listener function that receives progress events.",
+      "types": [
+        {
+          "text": "(progress: ProgressStatus): void",
+          "complexTypes": [
+            "ProgressStatus"
+          ]
+        }
+      ]
     }
   ],
   "pluginConfigs": []

package/dist/esm/definitions.d.ts

@@ -1,4 +1,4 @@
-import type { PermissionState } from '@capacitor/core';
+import type { HttpOptions, PermissionState, PluginListenerHandle } from '@capacitor/core';
 export interface PermissionStatus {
     publicStorage: PermissionState;
 }
@@ -417,6 +417,71 @@ export interface CopyResult {
      */
     uri: string;
 }
+export interface DownloadFileOptions extends HttpOptions {
+    /**
+     * The path the downloaded file should be moved to.
+     *
+     * @since 5.1.0
+     */
+    path: string;
+    /**
+     * The directory to write the file to.
+     * If this option is used, filePath can be a relative path rather than absolute.
+     * The default is the `DATA` directory.
+     *
+     * @since 5.1.0
+     */
+    directory?: Directory;
+    /**
+     * An optional listener function to receive downloaded progress events.
+     * If this option is used, progress event should be dispatched on every chunk received.
+     * Chunks are throttled to every 100ms on Android/iOS to avoid slowdowns.
+     *
+     * @since 5.1.0
+     */
+    progress?: boolean;
+}
+export interface DownloadFileResult {
+    /**
+     * The path the file was downloaded to.
+     *
+     * @since 5.1.0
+     */
+    path?: string;
+    /**
+     * The blob data of the downloaded file.
+     * This is only available on web.
+     *
+     * @since 5.1.0
+     */
+    blob?: Blob;
+}
+export interface ProgressStatus {
+    /**
+     * The url of the file being downloaded.
+     *
+     * @since 5.1.0
+     */
+    url: string;
+    /**
+     * The number of bytes downloaded so far.
+     *
+     * @since 5.1.0
+     */
+    bytes: number;
+    /**
+     * The total number of bytes to download for this file.
+     *
+     * @since 5.1.0
+     */
+    contentLength: number;
+}
+/**
+ * A listener function that receives progress events.
+ *
+ * @since 5.1.0
+ */
+export declare type ProgressListener = (progress: ProgressStatus) => void;
 export interface FilesystemPlugin {
     /**
      * Read a file from disk
@@ -500,6 +565,18 @@ export interface FilesystemPlugin {
      * @since 1.0.0
      */
     requestPermissions(): Promise<PermissionStatus>;
+    /**
+     * Perform a http request to a server and download the file to the specified destination.
+     *
+     * @since 5.1.0
+     */
+    downloadFile(options: DownloadFileOptions): Promise<DownloadFileResult>;
+    /**
+     * Add a listener to file download progress events.
+     *
+     * @since 5.1.0
+     */
+    addListener(eventName: 'progress', listenerFunc: ProgressListener): Promise<PluginListenerHandle> & PluginListenerHandle;
 }
 /**
  * @deprecated Use `ReadFileOptions`.