From e7535273bb19d80445d907423fd2a4f69e9b77ca Mon Sep 17 00:00:00 2001 From: OS-pedrogustavobilro Date: Mon, 26 Jan 2026 16:41:00 +0000 Subject: [PATCH 1/7] docs: Make explict regarding http errors --- packages/capacitor-plugin/README.md | 8 +++++++- packages/capacitor-plugin/src/definitions.ts | 10 +++++++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/packages/capacitor-plugin/README.md b/packages/capacitor-plugin/README.md index 1025d45..2d153ce 100644 --- a/packages/capacitor-plugin/README.md +++ b/packages/capacitor-plugin/README.md @@ -99,6 +99,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 error response, use the `FileTransferError` interface available at `error.data` attribute. + | Param | Type | | ------------- | ------------------------------------------------------------------- | | **`options`** | DownloadFileOptions | @@ -116,7 +119,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 error response, use the `FileTransferError` interface available at `error.data` attribute. | Param | Type | | ------------- | --------------------------------------------------------------- | diff --git a/packages/capacitor-plugin/src/definitions.ts b/packages/capacitor-plugin/src/definitions.ts index e5b3964..25c3b55 100644 --- a/packages/capacitor-plugin/src/definitions.ts +++ b/packages/capacitor-plugin/src/definitions.ts @@ -277,11 +277,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 error response, 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 error response, use the `FileTransferError` interface available at `error.data` attribute. + * * @since 1.0.0 */ uploadFile(options: UploadFileOptions): Promise; From 782a73394fdeca464b1cb8ac1d260f833aa6cec3 Mon Sep 17 00:00:00 2001 From: OS-pedrogustavobilro Date: Mon, 26 Jan 2026 16:49:16 +0000 Subject: [PATCH 2/7] docs: FileTransferError Android / iOS only --- packages/capacitor-plugin/README.md | 4 ++-- packages/capacitor-plugin/src/definitions.ts | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/capacitor-plugin/README.md b/packages/capacitor-plugin/README.md index 2d153ce..b9e8d02 100644 --- a/packages/capacitor-plugin/README.md +++ b/packages/capacitor-plugin/README.md @@ -100,7 +100,7 @@ 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 error response, use the `FileTransferError` interface available at `error.data` attribute. +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 | | ------------- | ------------------------------------------------------------------- | @@ -122,7 +122,7 @@ uploadFile(options: UploadFileOptions) => Promise 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 error response, use the `FileTransferError` interface available at `error.data` attribute. +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 | | ------------- | --------------------------------------------------------------- | diff --git a/packages/capacitor-plugin/src/definitions.ts b/packages/capacitor-plugin/src/definitions.ts index 25c3b55..c678711 100644 --- a/packages/capacitor-plugin/src/definitions.ts +++ b/packages/capacitor-plugin/src/definitions.ts @@ -279,7 +279,7 @@ 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 error response, use the `FileTransferError` interface available at `error.data` attribute. + * 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 */ @@ -288,7 +288,7 @@ export interface FileTransferPlugin { * 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 error response, use the `FileTransferError` interface available at `error.data` attribute. + * 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 */ From 68e10a32169bb0a0f4084c133c0fda4409a3c0fa Mon Sep 17 00:00:00 2001 From: OS-pedrogustavobilro Date: Mon, 26 Jan 2026 16:57:56 +0000 Subject: [PATCH 3/7] docs: mention headers This is not a new parameter, it was already being returned by the plugin, just not available in the interface --- packages/capacitor-plugin/src/definitions.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/capacitor-plugin/src/definitions.ts b/packages/capacitor-plugin/src/definitions.ts index c678711..18a82a5 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 From 51bc8e1cb14c66dd859d9f52290ea5a161865203 Mon Sep 17 00:00:00 2001 From: OS-pedrogustavobilro Date: Mon, 26 Jan 2026 17:25:11 +0000 Subject: [PATCH 4/7] docs: Add error handling to examples --- README.md | 14 ++++++++++++-- packages/capacitor-plugin/README.md | 19 ++++++++++++++++--- 2 files changed, 28 insertions(+), 5 deletions(-) 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 b9e8d02..877bf77 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 From 12d761210818eaa8aab1a84ce4e7c2949324ad6f Mon Sep 17 00:00:00 2001 From: OS-pedrogustavobilro Date: Mon, 26 Jan 2026 17:32:46 +0000 Subject: [PATCH 5/7] chore: Make FileTransferError discoverable by docgen FileTransferError was not being used explicitly, hence why we added an internal field to the API so that docgen picks it up. --- packages/capacitor-plugin/README.md | 18 ++++++++++++++++-- packages/capacitor-plugin/src/definitions.ts | 3 +++ 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/packages/capacitor-plugin/README.md b/packages/capacitor-plugin/README.md index 877bf77..d6e6193 100644 --- a/packages/capacitor-plugin/README.md +++ b/packages/capacitor-plugin/README.md @@ -113,7 +113,7 @@ 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. +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 | | ------------- | ------------------------------------------------------------------- | @@ -135,7 +135,7 @@ uploadFile(options: UploadFileOptions) => Promise 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. +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 | | ------------- | --------------------------------------------------------------- | @@ -261,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 18a82a5..51cac86 100644 --- a/packages/capacitor-plugin/src/definitions.ts +++ b/packages/capacitor-plugin/src/definitions.ts @@ -311,4 +311,7 @@ export interface FileTransferPlugin { * @since 1.0.0 */ removeAllListeners(): Promise; + + /** @internal used to make FileTransferError available in `@capacitor/docgen` */ + _fileTransferErrorType?: FileTransferError; } From 1f1ac722810d581225f84b58218d12b7cd61f14c Mon Sep 17 00:00:00 2001 From: OS-pedrogustavobilro Date: Mon, 26 Jan 2026 17:42:26 +0000 Subject: [PATCH 6/7] chore: fix lint issues --- packages/capacitor-plugin/src/definitions.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/capacitor-plugin/src/definitions.ts b/packages/capacitor-plugin/src/definitions.ts index 51cac86..e63bc07 100644 --- a/packages/capacitor-plugin/src/definitions.ts +++ b/packages/capacitor-plugin/src/definitions.ts @@ -282,19 +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. - * + * * 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; From 80c60ffb8f42f455dbe69aeb56478c638d50bb53 Mon Sep 17 00:00:00 2001 From: OS-pedrogustavobilro Date: Mon, 26 Jan 2026 17:48:24 +0000 Subject: [PATCH 7/7] chore: fix lint issues in web.ts --- packages/capacitor-plugin/src/web.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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, }); }); }