diff --git a/README.md b/README.md index df062a8..2874019 100644 --- a/README.md +++ b/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. + } } ``` diff --git a/packages/capacitor-plugin/README.md b/packages/capacitor-plugin/README.md index 1025d45..d6e6193 100644 --- a/packages/capacitor-plugin/README.md +++ b/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 @@ -99,6 +112,9 @@ downloadFile(options: DownloadFileOptions) => Promise 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. + | Param | Type | | ------------- | ------------------------------------------------------------------- | | **`options`** | DownloadFileOptions | @@ -116,7 +132,10 @@ Perform an HTTP request to a server and download the file to the specified desti uploadFile(options: UploadFileOptions) => Promise ``` -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. | Param | Type | | ------------- | --------------------------------------------------------------- | @@ -242,6 +261,20 @@ Remove all listeners for this plugin. | **`contentLength`** | number | The total number of bytes associated with the file transfer. | 1.0.0 | | **`lengthComputable`** | boolean | 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`** | string | Code identifying the error: OS-PLUG-FLTR-XXXX | 1.0.0 | +| **`message`** | string | Message informing of what went wrong | 1.0.0 | +| **`source`** | string | The source for the file transfer operation (a url for download, a file path for upload) | 1.0.0 | +| **`target`** | string | The target of the file transfer operation (a file path for download, a url for upload) | 1.0.0 | +| **`httpStatus`** | number | HTTP status code of the server response (if available) | 1.0.0 | +| **`headers`** | { [key: string]: string; } | HTTP headers from the server response (if available) | 1.0.0 | +| **`body`** | string | HTTP error response body from the server (if available) | 1.0.0 | +| **`exception`** | string | Exception message thrown on native side (if available) | 1.0.0 | + ### Errors diff --git a/packages/capacitor-plugin/src/definitions.ts b/packages/capacitor-plugin/src/definitions.ts index e5b3964..e63bc07 100644 --- a/packages/capacitor-plugin/src/definitions.ts +++ b/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; /** - * 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; @@ -298,4 +311,7 @@ export interface FileTransferPlugin { * @since 1.0.0 */ removeAllListeners(): Promise; + + /** @internal used to make FileTransferError available in `@capacitor/docgen` */ + _fileTransferErrorType?: FileTransferError; } diff --git a/packages/capacitor-plugin/src/web.ts b/packages/capacitor-plugin/src/web.ts index 8029ec5..cf0de7e 100644 --- a/packages/capacitor-plugin/src/web.ts +++ b/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, }); }); }