deprecate(filesystem): deprecate downloadFile and add migration steps for file transfer plugin (#2360)

Author: ItsChaceD

filesystem/README.md

@@ -42,6 +42,64 @@ For detailed steps on how to do this, please see the [Capacitor Docs](https://ca
 </plist>
 ```
 
+## Migrating from downloadFile to File Transfer plugin
+
+As of version 7.1.0, the `downloadFile` functionality in the Filesystem plugin has been deprecated in favor of the new [@capacitor/file-transfer](https://capacitorjs.com/docs/apis/file-transfer) plugin.
+
+### Installing the File Transfer plugin
+
+```bash
+npm install @capacitor/file-transfer
+npx cap sync
+```
+
+### Migration example
+
+Before (using Filesystem plugin):
+
+```typescript
+import { Filesystem, Directory } from '@capacitor/filesystem';
+
+await Filesystem.downloadFile({
+  url: 'https://example.com/file.pdf',
+  path: 'downloaded-file.pdf',
+  directory: Directory.Documents,
+  progress: true
+});
+
+// Progress events
+Filesystem.addListener('progress', (progress) => {
+  console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`);
+});
+```
+
+After (using File Transfer plugin):
+
+```typescript
+import { FileTransfer } from '@capacitor/file-transfer';
+import { Filesystem, Directory } from '@capacitor/filesystem';
+
+// First get the full file path using Filesystem
+const fileInfo = await Filesystem.getUri({
+  directory: Directory.Documents,
+  path: 'downloaded-file.pdf'
+});
+
+// Then use the FileTransfer plugin to download
+await FileTransfer.downloadFile({
+  url: 'https://example.com/file.pdf',
+  path: fileInfo.uri,
+  progress: true
+});
+
+// Progress events
+FileTransfer.addListener('progress', (progress) => {
+  console.log(`Downloaded ${progress.bytes} of ${progress.contentLength}`);
+});
+```
+
+The File Transfer plugin offers improved reliability, better error handling with specific error codes, and also adds upload functionality.
+
 ## iOS
 
 To have files appear in the Files app, you must also set the following keys to `YES` in `Info.plist`:

filesystem/src/definitions.ts

@@ -486,6 +486,7 @@ export interface DownloadFileOptions extends HttpOptions {
   /**
    * The path the downloaded file should be moved to.
    *
+   * @deprecated Use @capacitor/file-transfer instead.
    * @since 5.1.0
    */
   path: string;
@@ -494,6 +495,7 @@ export interface DownloadFileOptions extends HttpOptions {
    * If this option is used, filePath can be a relative path rather than absolute.
    * The default is the `DATA` directory.
    *
+   * @deprecated Use @capacitor/file-transfer instead.
    * @since 5.1.0
    */
   directory?: Directory;
@@ -502,13 +504,15 @@ export interface DownloadFileOptions extends HttpOptions {
    * 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.
    *
+   * @deprecated Use @capacitor/file-transfer instead.
    * @since 5.1.0
    */
   progress?: boolean;
   /**
    * Whether to create any missing parent directories.
    *
    * @default false
+   * @deprecated Use @capacitor/file-transfer instead.
    * @since 5.1.2
    */
   recursive?: boolean;
@@ -518,13 +522,15 @@ export interface DownloadFileResult {
   /**
    * The path the file was downloaded to.
    *
+   * @deprecated Use @capacitor/file-transfer instead.
    * @since 5.1.0
    */
   path?: string;
   /**
    * The blob data of the downloaded file.
    * This is only available on web.
    *
+   * @deprecated Use @capacitor/file-transfer instead.
    * @since 5.1.0
    */
   blob?: Blob;
@@ -533,18 +539,21 @@ export interface ProgressStatus {
   /**
    * The url of the file being downloaded.
    *
+   * @deprecated Use @capacitor/file-transfer instead.
    * @since 5.1.0
    */
   url: string;
   /**
    * The number of bytes downloaded so far.
    *
+   * @deprecated Use @capacitor/file-transfer instead.
    * @since 5.1.0
    */
   bytes: number;
   /**
    * The total number of bytes to download for this file.
    *
+   * @deprecated Use @capacitor/file-transfer instead.
    * @since 5.1.0
    */
   contentLength: number;
@@ -553,6 +562,7 @@ export interface ProgressStatus {
 /**
  * A listener function that receives progress events.
  *
+ * @deprecated Use @capacitor/file-transfer instead.
  * @since 5.1.0
  */
 export type ProgressListener = (progress: ProgressStatus) => void;
@@ -656,13 +666,15 @@ export interface FilesystemPlugin {
   /**
    * Perform a http request to a server and download the file to the specified destination.
    *
+   * @deprecated Use @capacitor/file-transfer plugin instead.
    * @since 5.1.0
    */
   downloadFile(options: DownloadFileOptions): Promise<DownloadFileResult>;
 
   /**
    * Add a listener to file download progress events.
    *
+   * @deprecated Use @capacitor/file-transfer plugin instead.
    * @since 5.1.0
    */
   addListener(
@@ -672,6 +684,7 @@ export interface FilesystemPlugin {
   /**
    * Remove all listeners for this plugin.
    *
+   * @deprecated Use @capacitor/file-transfer plugin instead.
    * @since 5.2.0
    */
   removeAllListeners(): Promise<void>;