docs: Better documentation on File Transfer errors.

README.md

@@ -48,7 +48,12 @@ try {
         progress: true
     });
 } catch(error) {
-    // handle error - see `FileTransferError` interface for what error information is returned
+    if (error.code === 'OS-PLUG-FLTR-0010') {
+      // HTTP error - see `FileTransferError` for details on fields available in `errorData`
+      let errorData = error.data;
+    } else {
+      // other errors - use `error.code` and `error.message` for more information.
+    }
 }
 
 // Progress events
@@ -84,7 +89,12 @@ try {
     });
     // get server response and other info from result - see `UploadFileResult` interface
 } catch(error) {
-    // handle error - see `FileTransferError` interface for what error information is returned
+    if (error.code === 'OS-PLUG-FLTR-0010') {
+      // HTTP error - see `FileTransferError` for details on fields available in `errorData`
+      let errorData = error.data;
+    } else {
+      // other errors - use `error.code` and `error.message` for more information.
+    }
 }
 ```
 

packages/capacitor-plugin/README.md

@@ -31,7 +31,14 @@ try {
         progress: true
     });
 } catch(error) {
-    // handle error - see `FileTransferError` interface for what error information is returned
+    if (error.code === 'OS-PLUG-FLTR-0010') {
+      // HTTP error - see `FileTransferError` for details on fields available in `errorData`
+      let errorData = error.data;
+      this.showError('Upload failed: ' + errorData.httpStatus + '; ' + errorData.body);
+    } else {
+      // other errors - use `error.code` and `error.message` for more information.
+      this.showError('Upload failed: ' + error.code + '; ' + error.message);
+    }
 }
 
 // Progress events
@@ -67,11 +74,17 @@ try {
     });
     // get server response and other info from result - see `UploadFileResult` interface
 } catch(error) {
-    // handle error - see `FileTransferError` interface for what error information is returned
+    if (error.code === 'OS-PLUG-FLTR-0010') {
+      // HTTP error - see `FileTransferError` for details on fields available in `errorData`
+      let errorData = error.data;
+      this.showError('Upload failed: ' + errorData.httpStatus + '; ' + errorData.body);
+    } else {
+      // other errors - use `error.code` and `error.message` for more information.
+      this.showError('Upload failed: ' + error.code + '; ' + error.message);
+    }
 }
 ```
 
-
 ## API
 
 <docgen-index>
@@ -99,6 +112,9 @@ downloadFile(options: DownloadFileOptions) => Promise<DownloadFileResult>
 
 Perform an HTTP request to a server and download the file to the specified destination.
 
+If the server returns an HTTP error (e.g. 404, 500, etc.), the promise will be rejected.
+To get information about the HTTP error response when running on Android and iOS (not applicable to web), use the <a href="#filetransfererror">`FileTransferError`</a> interface available at `error.data` attribute.
+
 | Param         | Type                                                                |
 | ------------- | ------------------------------------------------------------------- |
 | **`options`** | <code><a href="#downloadfileoptions">DownloadFileOptions</a></code> |
@@ -116,7 +132,10 @@ Perform an HTTP request to a server and download the file to the specified desti
 uploadFile(options: UploadFileOptions) => Promise<UploadFileResult>
 ```
 
-Perform an HTTP request to upload a file to a server
+Perform an HTTP request to upload a file to a server.
+
+If the server returns an HTTP error (e.g. 404, 500, etc.), the promise will be rejected.
+To get information about the HTTP error response when running Android and iOS (not applicable to web), use the <a href="#filetransfererror">`FileTransferError`</a> interface available at `error.data` attribute.
 
 | Param         | Type                                                            |
 | ------------- | --------------------------------------------------------------- |
@@ -242,6 +261,20 @@ Remove all listeners for this plugin.
 | **`contentLength`**    | <code>number</code>                 | The total number of bytes associated with the file transfer.                                                                        | 1.0.0 |
 | **`lengthComputable`** | <code>boolean</code>                | Whether or not the contentLength value is relevant. In some situations, the total number of bytes may not be possible to determine. | 1.0.0 |
 
+
+#### FileTransferError
+
+| Prop             | Type                                    | Description                                                                             | Since |
+| ---------------- | --------------------------------------- | --------------------------------------------------------------------------------------- | ----- |
+| **`code`**       | <code>string</code>                     | Code identifying the error: OS-PLUG-FLTR-XXXX                                           | 1.0.0 |
+| **`message`**    | <code>string</code>                     | Message informing of what went wrong                                                    | 1.0.0 |
+| **`source`**     | <code>string</code>                     | The source for the file transfer operation (a url for download, a file path for upload) | 1.0.0 |
+| **`target`**     | <code>string</code>                     | The target of the file transfer operation (a file path for download, a url for upload)  | 1.0.0 |
+| **`httpStatus`** | <code>number</code>                     | HTTP status code of the server response (if available)                                  | 1.0.0 |
+| **`headers`**    | <code>{ [key: string]: string; }</code> | HTTP headers from the server response (if available)                                    | 1.0.0 |
+| **`body`**       | <code>string</code>                     | HTTP error response body from the server (if available)                                 | 1.0.0 |
+| **`exception`**  | <code>string</code>                     | Exception message thrown on native side (if available)                                  | 1.0.0 |
+
 </docgen-api>
 
 ### Errors

packages/capacitor-plugin/src/definitions.ts

@@ -262,6 +262,11 @@ export interface FileTransferError {
    * @since 1.0.0
    */
   httpStatus?: number;
+  /**
+   * HTTP headers from the server response (if available)
+   * @since 1.0.0
+   */
+  headers?: { [key: string]: string };
   /**
    * HTTP error response body from the server (if available)
    * @since 1.0.0
@@ -277,11 +282,19 @@ export interface FileTransferError {
 export interface FileTransferPlugin {
   /**
    * Perform an HTTP request to a server and download the file to the specified destination.
+   *
+   * If the server returns an HTTP error (e.g. 404, 500, etc.), the promise will be rejected.
+   * To get information about the HTTP error response when running on Android and iOS (not applicable to web), use the `FileTransferError` interface available at `error.data` attribute.
+   *
    * @since 1.0.0
    */
   downloadFile(options: DownloadFileOptions): Promise<DownloadFileResult>;
   /**
-   * Perform an HTTP request to upload a file to a server
+   * Perform an HTTP request to upload a file to a server.
+   *
+   * If the server returns an HTTP error (e.g. 404, 500, etc.), the promise will be rejected.
+   * To get information about the HTTP error response when running Android and iOS (not applicable to web), use the `FileTransferError` interface available at `error.data` attribute.
+   *
    * @since 1.0.0
    */
   uploadFile(options: UploadFileOptions): Promise<UploadFileResult>;
@@ -298,4 +311,7 @@ export interface FileTransferPlugin {
    * @since 1.0.0
    */
   removeAllListeners(): Promise<void>;
+
+  /** @internal used to make FileTransferError available in `@capacitor/docgen` */
+  _fileTransferErrorType?: FileTransferError;
 }

packages/capacitor-plugin/src/web.ts

@@ -471,10 +471,10 @@ export class FileTransferWeb extends WebPlugin implements FileTransferPlugin {
       const pathParts = path.split("/");
       if (pathParts.length > 1) {
         const directory = pathParts.slice(0, -1).join("/");
-        await filesystem.stat({path: directory}).catch(async ()=>{
+        await filesystem.stat({ path: directory }).catch(async () => {
           await filesystem.mkdir({
-           path: directory,
-           recursive: true,
+            path: directory,
+            recursive: true,
           });
         });
       }