@capgo/capacitor-uploader 7.2.8 → 7.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -192,15 +192,22 @@ Documentation for the [Capacitor Camera preview](https://github.com/Cap-go/camer
192
192
  <docgen-api>
193
193
  <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
194
194
 
195
+ Capacitor Uploader Plugin for uploading files with background support and progress tracking.
196
+
195
197
  ### startUpload(...)
196
198
 
197
199
  ```typescript
198
200
  startUpload(options: uploadOption) => Promise<{ id: string; }>
199
201
  ```
200
202
 
201
- | Param | Type | Description |
202
- | ------------- | ----------------------------------------------------- | ---------------------------------------- |
203
- | **`options`** | <code><a href="#uploadoption">uploadOption</a></code> | <a href="#uploadoption">uploadOption</a> |
203
+ Start uploading a file to a server.
204
+
205
+ The upload will continue in the background even if the app is closed or backgrounded.
206
+ Listen to upload events to track progress, completion, or failure.
207
+
208
+ | Param | Type | Description |
209
+ | ------------- | ----------------------------------------------------- | ------------------------------ |
210
+ | **`options`** | <code><a href="#uploadoption">uploadOption</a></code> | - Configuration for the upload |
204
211
 
205
212
  **Returns:** <code>Promise&lt;{ id: string; }&gt;</code>
206
213
 
@@ -215,9 +222,13 @@ startUpload(options: uploadOption) => Promise<{ id: string; }>
215
222
  removeUpload(options: { id: string; }) => Promise<void>
216
223
  ```
217
224
 
218
- | Param | Type |
219
- | ------------- | ---------------------------- |
220
- | **`options`** | <code>{ id: string; }</code> |
225
+ Cancel and remove an ongoing upload.
226
+
227
+ This will stop the upload if it's in progress and clean up resources.
228
+
229
+ | Param | Type | Description |
230
+ | ------------- | ---------------------------- | ------------------------------------------- |
231
+ | **`options`** | <code>{ id: string; }</code> | - Object containing the upload ID to remove |
221
232
 
222
233
  **Since:** 0.0.1
223
234
 
@@ -230,10 +241,17 @@ removeUpload(options: { id: string; }) => Promise<void>
230
241
  addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void) => Promise<PluginListenerHandle>
231
242
  ```
232
243
 
233
- | Param | Type |
234
- | ------------------ | ----------------------------------------------------------------------- |
235
- | **`eventName`** | <code>'events'</code> |
236
- | **`listenerFunc`** | <code>(state: <a href="#uploadevent">UploadEvent</a>) =&gt; void</code> |
244
+ Listen for upload progress and status events.
245
+
246
+ Events are fired for:
247
+ - Upload progress updates (with percent)
248
+ - Upload completion (with statusCode)
249
+ - Upload failure (with error and statusCode)
250
+
251
+ | Param | Type | Description |
252
+ | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------- |
253
+ | **`eventName`** | <code>'events'</code> | - Must be 'events' |
254
+ | **`listenerFunc`** | <code>(state: <a href="#uploadevent">UploadEvent</a>) =&gt; void</code> | - Callback function to handle upload events |
237
255
 
238
256
  **Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
239
257
 
@@ -248,10 +266,12 @@ addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void) =>
248
266
  getPluginVersion() => Promise<{ version: string; }>
249
267
  ```
250
268
 
251
- Get the native Capacitor plugin version
269
+ Get the native Capacitor plugin version.
252
270
 
253
271
  **Returns:** <code>Promise&lt;{ version: string; }&gt;</code>
254
272
 
273
+ **Since:** 0.0.1
274
+
255
275
  --------------------
256
276
 
257
277
 
@@ -260,18 +280,20 @@ Get the native Capacitor plugin version
260
280
 
261
281
  #### uploadOption
262
282
 
263
- | Prop | Type | Default | Since |
264
- | ----------------------- | --------------------------------------- | ------------------------ | ----- |
265
- | **`filePath`** | <code>string</code> | | 0.0.1 |
266
- | **`serverUrl`** | <code>string</code> | | 0.0.1 |
267
- | **`notificationTitle`** | <code>number</code> | <code>'Uploading'</code> | 0.0.1 |
268
- | **`headers`** | <code>{ [key: string]: string; }</code> | | 0.0.1 |
269
- | **`method`** | <code>'PUT' \| 'POST'</code> | <code>'POST'</code> | 0.0.1 |
270
- | **`mimeType`** | <code>string</code> | | 0.0.1 |
271
- | **`parameters`** | <code>{ [key: string]: string; }</code> | | 0.0.1 |
272
- | **`maxRetries`** | <code>number</code> | | 0.0.1 |
273
- | **`uploadType`** | <code>'binary' \| 'multipart'</code> | <code>'binary'</code> | 0.0.2 |
274
- | **`fileField`** | <code>string</code> | <code>'file'</code> | 0.0.2 |
283
+ Configuration options for uploading a file.
284
+
285
+ | Prop | Type | Description | Default | Since |
286
+ | ----------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----- |
287
+ | **`filePath`** | <code>string</code> | The local file path of the file to upload. Can be a file:// URL or an absolute path. | | 0.0.1 |
288
+ | **`serverUrl`** | <code>string</code> | The server URL endpoint where the file should be uploaded. | | 0.0.1 |
289
+ | **`notificationTitle`** | <code>number</code> | The title of the upload notification shown to the user. Android only. | <code>'Uploading'</code> | 0.0.1 |
290
+ | **`headers`** | <code>{ [key: string]: string; }</code> | HTTP headers to send with the upload request. Useful for authentication tokens, content types, etc. | | 0.0.1 |
291
+ | **`method`** | <code>'PUT' \| 'POST'</code> | The HTTP method to use for the upload request. | <code>'POST'</code> | 0.0.1 |
292
+ | **`mimeType`** | <code>string</code> | The MIME type of the file being uploaded. If not specified, the plugin will attempt to determine it automatically. | | 0.0.1 |
293
+ | **`parameters`** | <code>{ [key: string]: string; }</code> | Additional form parameters to send with the upload request. These will be included as form data in multipart uploads. | | 0.0.1 |
294
+ | **`maxRetries`** | <code>number</code> | The maximum number of times to retry the upload if it fails. | <code>0</code> | 0.0.1 |
295
+ | **`uploadType`** | <code>'binary' \| 'multipart'</code> | The type of upload to perform. - 'binary': Uploads the file as raw binary data in the request body - 'multipart': Uploads the file as multipart/form-data | <code>'binary'</code> | 0.0.2 |
296
+ | **`fileField`** | <code>string</code> | The form field name for the file when using multipart upload type. Only used when uploadType is 'multipart'. | <code>'file'</code> | 0.0.2 |
275
297
 
276
298
 
277
299
  #### PluginListenerHandle
@@ -283,11 +305,13 @@ Get the native Capacitor plugin version
283
305
 
284
306
  #### UploadEvent
285
307
 
286
- | Prop | Type | Description | Default | Since |
287
- | ------------- | ----------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------- | ----- |
288
- | **`name`** | <code>'uploading' \| 'completed' \| 'failed'</code> | Current status of upload, between 0 and 100. | | 0.0.1 |
289
- | **`payload`** | <code>{ percent?: number; error?: string; statusCode?: number; }</code> | | <code>{ percent: 0, error: '', statusCode: 0 }</code> | 0.0.1 |
290
- | **`id`** | <code>string</code> | | | 0.0.1 |
308
+ Event emitted during the upload lifecycle.
309
+
310
+ | Prop | Type | Description | Since |
311
+ | ------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
312
+ | **`name`** | <code>'uploading' \| 'completed' \| 'failed'</code> | The current status of the upload. - 'uploading': Upload is in progress - 'completed': Upload finished successfully - 'failed': Upload encountered an error | 0.0.1 |
313
+ | **`payload`** | <code>{ percent?: number; error?: string; statusCode?: number; }</code> | Additional data about the upload event. | 0.0.1 |
314
+ | **`id`** | <code>string</code> | Unique identifier for this upload task. | 0.0.1 |
291
315
 
292
316
  </docgen-api>
293
317
 
@@ -21,7 +21,7 @@ import net.gotev.uploadservice.observer.request.RequestObserverDelegate;
21
21
  @CapacitorPlugin(name = "Uploader")
22
22
  public class UploaderPlugin extends Plugin {
23
23
 
24
- private final String PLUGIN_VERSION = "7.2.8";
24
+ private final String pluginVersion = "7.3.1";
25
25
 
26
26
  private Uploader implementation;
27
27
 
@@ -173,7 +173,7 @@ public class UploaderPlugin extends Plugin {
173
173
  public void getPluginVersion(final PluginCall call) {
174
174
  try {
175
175
  final JSObject ret = new JSObject();
176
- ret.put("version", this.PLUGIN_VERSION);
176
+ ret.put("version", this.pluginVersion);
177
177
  call.resolve(ret);
178
178
  } catch (final Exception e) {
179
179
  call.reject("Could not get plugin version", e);
package/dist/docs.json CHANGED
@@ -2,8 +2,13 @@
2
2
  "api": {
3
3
  "name": "UploaderPlugin",
4
4
  "slug": "uploaderplugin",
5
- "docs": "",
6
- "tags": [],
5
+ "docs": "Capacitor Uploader Plugin for uploading files with background support and progress tracking.",
6
+ "tags": [
7
+ {
8
+ "text": "0.0.1",
9
+ "name": "since"
10
+ }
11
+ ],
7
12
  "methods": [
8
13
  {
9
14
  "name": "startUpload",
@@ -11,30 +16,34 @@
11
16
  "parameters": [
12
17
  {
13
18
  "name": "options",
14
- "docs": "uploadOption",
19
+ "docs": "- Configuration for the upload",
15
20
  "type": "uploadOption"
16
21
  }
17
22
  ],
18
23
  "returns": "Promise<{ id: string; }>",
19
24
  "tags": [
20
25
  {
21
- "name": "since",
22
- "text": "0.0.1"
26
+ "name": "param",
27
+ "text": "options - Configuration for the upload"
28
+ },
29
+ {
30
+ "name": "returns",
31
+ "text": "Promise that resolves with the upload ID"
23
32
  },
24
33
  {
25
- "name": "description",
26
- "text": "Start the upload"
34
+ "name": "throws",
35
+ "text": "Error if the upload fails to start"
27
36
  },
28
37
  {
29
- "name": "param",
30
- "text": "options uploadOption"
38
+ "name": "since",
39
+ "text": "0.0.1"
31
40
  },
32
41
  {
33
- "name": "returns",
34
- "text": ": string }"
42
+ "name": "example",
43
+ "text": "```typescript\nconst { id } = await Uploader.startUpload({\n filePath: 'file:///path/to/file.jpg',\n serverUrl: 'https://example.com/upload',\n headers: {\n 'Authorization': 'Bearer token'\n },\n method: 'POST',\n uploadType: 'multipart',\n fileField: 'photo'\n});\nconsole.log('Upload started with ID:', id);\n```"
35
44
  }
36
45
  ],
37
- "docs": "",
46
+ "docs": "Start uploading a file to a server.\n\nThe upload will continue in the background even if the app is closed or backgrounded.\nListen to upload events to track progress, completion, or failure.",
38
47
  "complexTypes": [
39
48
  "uploadOption"
40
49
  ],
@@ -46,29 +55,34 @@
46
55
  "parameters": [
47
56
  {
48
57
  "name": "options",
49
- "docs": "",
58
+ "docs": "- Object containing the upload ID to remove",
50
59
  "type": "{ id: string; }"
51
60
  }
52
61
  ],
53
62
  "returns": "Promise<void>",
54
63
  "tags": [
55
64
  {
56
- "name": "since",
57
- "text": "0.0.1"
65
+ "name": "param",
66
+ "text": "options - Object containing the upload ID to remove"
58
67
  },
59
68
  {
60
- "name": "description",
61
- "text": "Remove the upload"
69
+ "name": "returns",
70
+ "text": "Promise that resolves when the upload is removed"
62
71
  },
63
72
  {
64
- "name": "param",
65
- "text": "options"
73
+ "name": "throws",
74
+ "text": "Error if the upload ID is not found"
75
+ },
76
+ {
77
+ "name": "since",
78
+ "text": "0.0.1"
66
79
  },
67
80
  {
68
- "name": "returns"
81
+ "name": "example",
82
+ "text": "```typescript\nawait Uploader.removeUpload({ id: 'upload-123' });\n```"
69
83
  }
70
84
  ],
71
- "docs": "",
85
+ "docs": "Cancel and remove an ongoing upload.\n\nThis will stop the upload if it's in progress and clean up resources.",
72
86
  "complexTypes": [],
73
87
  "slug": "removeupload"
74
88
  },
@@ -78,38 +92,39 @@
78
92
  "parameters": [
79
93
  {
80
94
  "name": "eventName",
81
- "docs": "",
95
+ "docs": "- Must be 'events'",
82
96
  "type": "'events'"
83
97
  },
84
98
  {
85
99
  "name": "listenerFunc",
86
- "docs": "",
100
+ "docs": "- Callback function to handle upload events",
87
101
  "type": "(state: UploadEvent) => void"
88
102
  }
89
103
  ],
90
104
  "returns": "Promise<PluginListenerHandle>",
91
105
  "tags": [
92
106
  {
93
- "name": "since",
94
- "text": "0.0.1"
107
+ "name": "param",
108
+ "text": "eventName - Must be 'events'"
95
109
  },
96
110
  {
97
- "name": "description",
98
- "text": "Add a listener for the upload events"
111
+ "name": "param",
112
+ "text": "listenerFunc - Callback function to handle upload events"
99
113
  },
100
114
  {
101
- "name": "param",
102
- "text": "eventName"
115
+ "name": "returns",
116
+ "text": "Promise that resolves with a listener handle for removal"
103
117
  },
104
118
  {
105
- "name": "param",
106
- "text": "listenerFunc"
119
+ "name": "since",
120
+ "text": "0.0.1"
107
121
  },
108
122
  {
109
- "name": "returns"
123
+ "name": "example",
124
+ "text": "```typescript\nconst listener = await Uploader.addListener('events', (event) => {\n if (event.name === 'uploading') {\n console.log(`Upload ${event.id}: ${event.payload.percent}%`);\n } else if (event.name === 'completed') {\n console.log(`Upload ${event.id} completed`);\n } else if (event.name === 'failed') {\n console.error(`Upload ${event.id} failed:`, event.payload.error);\n }\n});\n\n// Remove listener when done\nawait listener.remove();\n```"
110
125
  }
111
126
  ],
112
- "docs": "",
127
+ "docs": "Listen for upload progress and status events.\n\nEvents are fired for:\n- Upload progress updates (with percent)\n- Upload completion (with statusCode)\n- Upload failure (with error and statusCode)",
113
128
  "complexTypes": [
114
129
  "PluginListenerHandle",
115
130
  "UploadEvent"
@@ -124,14 +139,22 @@
124
139
  "tags": [
125
140
  {
126
141
  "name": "returns",
127
- "text": "an Promise with version for this device"
142
+ "text": "Promise that resolves with the plugin version"
128
143
  },
129
144
  {
130
145
  "name": "throws",
131
- "text": "An error if the something went wrong"
146
+ "text": "Error if getting the version fails"
147
+ },
148
+ {
149
+ "name": "since",
150
+ "text": "0.0.1"
151
+ },
152
+ {
153
+ "name": "example",
154
+ "text": "```typescript\nconst { version } = await Uploader.getPluginVersion();\nconsole.log('Plugin version:', version);\n```"
132
155
  }
133
156
  ],
134
- "docs": "Get the native Capacitor plugin version",
157
+ "docs": "Get the native Capacitor plugin version.",
135
158
  "complexTypes": [],
136
159
  "slug": "getpluginversion"
137
160
  }
@@ -142,8 +165,13 @@
142
165
  {
143
166
  "name": "uploadOption",
144
167
  "slug": "uploadoption",
145
- "docs": "",
146
- "tags": [],
168
+ "docs": "Configuration options for uploading a file.",
169
+ "tags": [
170
+ {
171
+ "text": "0.0.1",
172
+ "name": "since"
173
+ }
174
+ ],
147
175
  "methods": [],
148
176
  "properties": [
149
177
  {
@@ -152,13 +180,9 @@
152
180
  {
153
181
  "text": "0.0.1",
154
182
  "name": "since"
155
- },
156
- {
157
- "text": "The file path of the file to upload",
158
- "name": "description"
159
183
  }
160
184
  ],
161
- "docs": "",
185
+ "docs": "The local file path of the file to upload.\nCan be a file:// URL or an absolute path.",
162
186
  "complexTypes": [],
163
187
  "type": "string"
164
188
  },
@@ -168,33 +192,25 @@
168
192
  {
169
193
  "text": "0.0.1",
170
194
  "name": "since"
171
- },
172
- {
173
- "text": "The url of the server",
174
- "name": "description"
175
195
  }
176
196
  ],
177
- "docs": "",
197
+ "docs": "The server URL endpoint where the file should be uploaded.",
178
198
  "complexTypes": [],
179
199
  "type": "string"
180
200
  },
181
201
  {
182
202
  "name": "notificationTitle",
183
203
  "tags": [
184
- {
185
- "text": "0.0.1",
186
- "name": "since"
187
- },
188
204
  {
189
205
  "text": "'Uploading'",
190
206
  "name": "default"
191
207
  },
192
208
  {
193
- "text": "The title of the notification\nAndroid only",
194
- "name": "description"
209
+ "text": "0.0.1",
210
+ "name": "since"
195
211
  }
196
212
  ],
197
- "docs": "",
213
+ "docs": "The title of the upload notification shown to the user.\nAndroid only.",
198
214
  "complexTypes": [],
199
215
  "type": "number | undefined"
200
216
  },
@@ -206,31 +222,27 @@
206
222
  "name": "since"
207
223
  },
208
224
  {
209
- "text": "The headers to send with the request",
210
- "name": "description"
225
+ "text": "```typescript\nheaders: {\n 'Authorization': 'Bearer token123',\n 'X-Custom-Header': 'value'\n}\n```",
226
+ "name": "example"
211
227
  }
212
228
  ],
213
- "docs": "",
229
+ "docs": "HTTP headers to send with the upload request.\nUseful for authentication tokens, content types, etc.",
214
230
  "complexTypes": [],
215
231
  "type": "{ [key: string]: string; }"
216
232
  },
217
233
  {
218
234
  "name": "method",
219
235
  "tags": [
220
- {
221
- "text": "0.0.1",
222
- "name": "since"
223
- },
224
- {
225
- "text": "The method to use for the request",
226
- "name": "description"
227
- },
228
236
  {
229
237
  "text": "'POST'",
230
238
  "name": "default"
239
+ },
240
+ {
241
+ "text": "0.0.1",
242
+ "name": "since"
231
243
  }
232
244
  ],
233
- "docs": "",
245
+ "docs": "The HTTP method to use for the upload request.",
234
246
  "complexTypes": [],
235
247
  "type": "'PUT' | 'POST' | undefined"
236
248
  },
@@ -242,11 +254,11 @@
242
254
  "name": "since"
243
255
  },
244
256
  {
245
- "text": "The mime type to use for the request",
246
- "name": "description"
257
+ "text": "'image/jpeg', 'application/pdf', 'video/mp4'",
258
+ "name": "example"
247
259
  }
248
260
  ],
249
- "docs": "",
261
+ "docs": "The MIME type of the file being uploaded.\nIf not specified, the plugin will attempt to determine it automatically.",
250
262
  "complexTypes": [],
251
263
  "type": "string | undefined"
252
264
  },
@@ -256,13 +268,9 @@
256
268
  {
257
269
  "text": "0.0.1",
258
270
  "name": "since"
259
- },
260
- {
261
- "text": "The parameters to send with the request",
262
- "name": "description"
263
271
  }
264
272
  ],
265
- "docs": "",
273
+ "docs": "Additional form parameters to send with the upload request.\nThese will be included as form data in multipart uploads.",
266
274
  "complexTypes": [],
267
275
  "type": "{ [key: string]: string; } | undefined"
268
276
  },
@@ -274,51 +282,43 @@
274
282
  "name": "since"
275
283
  },
276
284
  {
277
- "text": "The maximum number of retries",
278
- "name": "description"
285
+ "text": "0",
286
+ "name": "default"
279
287
  }
280
288
  ],
281
- "docs": "",
289
+ "docs": "The maximum number of times to retry the upload if it fails.",
282
290
  "complexTypes": [],
283
291
  "type": "number | undefined"
284
292
  },
285
293
  {
286
294
  "name": "uploadType",
287
295
  "tags": [
288
- {
289
- "text": "0.0.2",
290
- "name": "since"
291
- },
292
- {
293
- "text": "The type of upload to use",
294
- "name": "description"
295
- },
296
296
  {
297
297
  "text": "'binary'",
298
298
  "name": "default"
299
+ },
300
+ {
301
+ "text": "0.0.2",
302
+ "name": "since"
299
303
  }
300
304
  ],
301
- "docs": "",
305
+ "docs": "The type of upload to perform.\n- 'binary': Uploads the file as raw binary data in the request body\n- 'multipart': Uploads the file as multipart/form-data",
302
306
  "complexTypes": [],
303
307
  "type": "'binary' | 'multipart' | undefined"
304
308
  },
305
309
  {
306
310
  "name": "fileField",
307
311
  "tags": [
308
- {
309
- "text": "0.0.2",
310
- "name": "since"
311
- },
312
- {
313
- "text": "The form field name for the file when using multipart",
314
- "name": "description"
315
- },
316
312
  {
317
313
  "text": "'file'",
318
314
  "name": "default"
315
+ },
316
+ {
317
+ "text": "0.0.2",
318
+ "name": "since"
319
319
  }
320
320
  ],
321
- "docs": "",
321
+ "docs": "The form field name for the file when using multipart upload type.\nOnly used when uploadType is 'multipart'.",
322
322
  "complexTypes": [],
323
323
  "type": "string | undefined"
324
324
  }
@@ -343,8 +343,13 @@
343
343
  {
344
344
  "name": "UploadEvent",
345
345
  "slug": "uploadevent",
346
- "docs": "",
347
- "tags": [],
346
+ "docs": "Event emitted during the upload lifecycle.",
347
+ "tags": [
348
+ {
349
+ "text": "0.0.1",
350
+ "name": "since"
351
+ }
352
+ ],
348
353
  "methods": [],
349
354
  "properties": [
350
355
  {
@@ -355,7 +360,7 @@
355
360
  "name": "since"
356
361
  }
357
362
  ],
358
- "docs": "Current status of upload, between 0 and 100.",
363
+ "docs": "The current status of the upload.\n- 'uploading': Upload is in progress\n- 'completed': Upload finished successfully\n- 'failed': Upload encountered an error",
359
364
  "complexTypes": [],
360
365
  "type": "'uploading' | 'completed' | 'failed'"
361
366
  },
@@ -365,17 +370,9 @@
365
370
  {
366
371
  "text": "0.0.1",
367
372
  "name": "since"
368
- },
369
- {
370
- "text": "The payload of the event",
371
- "name": "description"
372
- },
373
- {
374
- "text": "{ percent: 0, error: '', statusCode: 0 }",
375
- "name": "default"
376
373
  }
377
374
  ],
378
- "docs": "",
375
+ "docs": "Additional data about the upload event.",
379
376
  "complexTypes": [],
380
377
  "type": "{ percent?: number | undefined; error?: string | undefined; statusCode?: number | undefined; }"
381
378
  },
@@ -385,13 +382,9 @@
385
382
  {
386
383
  "text": "0.0.1",
387
384
  "name": "since"
388
- },
389
- {
390
- "text": "The id of the upload",
391
- "name": "description"
392
385
  }
393
386
  ],
394
- "docs": "",
387
+ "docs": "Unique identifier for this upload task.",
395
388
  "complexTypes": [],
396
389
  "type": "string"
397
390
  }
@@ -1,132 +1,237 @@
1
1
  import type { PluginListenerHandle } from '@capacitor/core';
2
+ /**
3
+ * Configuration options for uploading a file.
4
+ *
5
+ * @since 0.0.1
6
+ */
2
7
  export interface uploadOption {
3
8
  /**
9
+ * The local file path of the file to upload.
10
+ * Can be a file:// URL or an absolute path.
11
+ *
4
12
  * @since 0.0.1
5
- * @description The file path of the file to upload
6
13
  */
7
14
  filePath: string;
8
15
  /**
16
+ * The server URL endpoint where the file should be uploaded.
17
+ *
9
18
  * @since 0.0.1
10
- * @description The url of the server
11
19
  */
12
20
  serverUrl: string;
13
21
  /**
14
- * @since 0.0.1
22
+ * The title of the upload notification shown to the user.
23
+ * Android only.
24
+ *
15
25
  * @default 'Uploading'
16
- * @description The title of the notification
17
- * Android only
26
+ * @since 0.0.1
18
27
  */
19
28
  notificationTitle?: number;
20
29
  /**
30
+ * HTTP headers to send with the upload request.
31
+ * Useful for authentication tokens, content types, etc.
32
+ *
21
33
  * @since 0.0.1
22
- * @description The headers to send with the request
34
+ * @example
35
+ * ```typescript
36
+ * headers: {
37
+ * 'Authorization': 'Bearer token123',
38
+ * 'X-Custom-Header': 'value'
39
+ * }
40
+ * ```
23
41
  */
24
42
  headers: {
25
43
  [key: string]: string;
26
44
  };
27
45
  /**
28
- * @since 0.0.1
29
- * @description The method to use for the request
46
+ * The HTTP method to use for the upload request.
47
+ *
30
48
  * @default 'POST'
49
+ * @since 0.0.1
31
50
  */
32
51
  method?: 'PUT' | 'POST';
33
52
  /**
53
+ * The MIME type of the file being uploaded.
54
+ * If not specified, the plugin will attempt to determine it automatically.
55
+ *
34
56
  * @since 0.0.1
35
- * @description The mime type to use for the request
57
+ * @example 'image/jpeg', 'application/pdf', 'video/mp4'
36
58
  */
37
59
  mimeType?: string;
38
60
  /**
61
+ * Additional form parameters to send with the upload request.
62
+ * These will be included as form data in multipart uploads.
63
+ *
39
64
  * @since 0.0.1
40
- * @description The parameters to send with the request
41
65
  */
42
66
  parameters?: {
43
67
  [key: string]: string;
44
68
  };
45
69
  /**
70
+ * The maximum number of times to retry the upload if it fails.
71
+ *
46
72
  * @since 0.0.1
47
- * @description The maximum number of retries
73
+ * @default 0
48
74
  */
49
75
  maxRetries?: number;
50
76
  /**
51
- * @since 0.0.2
52
- * @description The type of upload to use
77
+ * The type of upload to perform.
78
+ * - 'binary': Uploads the file as raw binary data in the request body
79
+ * - 'multipart': Uploads the file as multipart/form-data
80
+ *
53
81
  * @default 'binary'
82
+ * @since 0.0.2
54
83
  */
55
84
  uploadType?: 'binary' | 'multipart';
56
85
  /**
57
- * @since 0.0.2
58
- * @description The form field name for the file when using multipart
86
+ * The form field name for the file when using multipart upload type.
87
+ * Only used when uploadType is 'multipart'.
88
+ *
59
89
  * @default 'file'
90
+ * @since 0.0.2
60
91
  */
61
92
  fileField?: string;
62
93
  }
94
+ /**
95
+ * Event emitted during the upload lifecycle.
96
+ *
97
+ * @since 0.0.1
98
+ */
63
99
  export interface UploadEvent {
64
100
  /**
65
- * Current status of upload, between 0 and 100.
101
+ * The current status of the upload.
102
+ * - 'uploading': Upload is in progress
103
+ * - 'completed': Upload finished successfully
104
+ * - 'failed': Upload encountered an error
66
105
  *
67
106
  * @since 0.0.1
68
107
  */
69
108
  name: 'uploading' | 'completed' | 'failed';
70
109
  /**
110
+ * Additional data about the upload event.
111
+ *
71
112
  * @since 0.0.1
72
- * @description The payload of the event
73
- * @default { percent: 0, error: '', statusCode: 0 }
74
113
  */
75
114
  payload: {
76
115
  /**
116
+ * Upload progress percentage from 0 to 100.
117
+ * Only present during 'uploading' events.
118
+ *
77
119
  * @since 0.0.1
78
- * @description The percent of the upload
79
120
  */
80
121
  percent?: number;
81
122
  /**
123
+ * Error message if the upload failed.
124
+ * Only present during 'failed' events.
125
+ *
82
126
  * @since 0.0.1
83
- * @description The error of the upload
84
127
  */
85
128
  error?: string;
86
129
  /**
130
+ * HTTP status code returned by the server.
131
+ * Present during 'completed' and 'failed' events.
132
+ *
87
133
  * @since 0.0.1
88
- * @description The status code of the upload
89
134
  */
90
135
  statusCode?: number;
91
136
  };
92
137
  /**
138
+ * Unique identifier for this upload task.
139
+ *
93
140
  * @since 0.0.1
94
- * @description The id of the upload
95
141
  */
96
142
  id: string;
97
143
  }
144
+ /**
145
+ * Capacitor Uploader Plugin for uploading files with background support and progress tracking.
146
+ *
147
+ * @since 0.0.1
148
+ */
98
149
  export interface UploaderPlugin {
99
150
  /**
151
+ * Start uploading a file to a server.
152
+ *
153
+ * The upload will continue in the background even if the app is closed or backgrounded.
154
+ * Listen to upload events to track progress, completion, or failure.
155
+ *
156
+ * @param options - Configuration for the upload
157
+ * @returns Promise that resolves with the upload ID
158
+ * @throws Error if the upload fails to start
100
159
  * @since 0.0.1
101
- * @description Start the upload
102
- * @param options uploadOption
103
- * @returns { id: string }
160
+ * @example
161
+ * ```typescript
162
+ * const { id } = await Uploader.startUpload({
163
+ * filePath: 'file:///path/to/file.jpg',
164
+ * serverUrl: 'https://example.com/upload',
165
+ * headers: {
166
+ * 'Authorization': 'Bearer token'
167
+ * },
168
+ * method: 'POST',
169
+ * uploadType: 'multipart',
170
+ * fileField: 'photo'
171
+ * });
172
+ * console.log('Upload started with ID:', id);
173
+ * ```
104
174
  */
105
175
  startUpload(options: uploadOption): Promise<{
106
176
  id: string;
107
177
  }>;
108
178
  /**
179
+ * Cancel and remove an ongoing upload.
180
+ *
181
+ * This will stop the upload if it's in progress and clean up resources.
182
+ *
183
+ * @param options - Object containing the upload ID to remove
184
+ * @returns Promise that resolves when the upload is removed
185
+ * @throws Error if the upload ID is not found
109
186
  * @since 0.0.1
110
- * @description Remove the upload
111
- * @param options
112
- * @returns { void }
187
+ * @example
188
+ * ```typescript
189
+ * await Uploader.removeUpload({ id: 'upload-123' });
190
+ * ```
113
191
  */
114
192
  removeUpload(options: {
115
193
  id: string;
116
194
  }): Promise<void>;
117
195
  /**
196
+ * Listen for upload progress and status events.
197
+ *
198
+ * Events are fired for:
199
+ * - Upload progress updates (with percent)
200
+ * - Upload completion (with statusCode)
201
+ * - Upload failure (with error and statusCode)
202
+ *
203
+ * @param eventName - Must be 'events'
204
+ * @param listenerFunc - Callback function to handle upload events
205
+ * @returns Promise that resolves with a listener handle for removal
118
206
  * @since 0.0.1
119
- * @description Add a listener for the upload events
120
- * @param eventName
121
- * @param listenerFunc
122
- * @returns { PluginListenerHandle }
207
+ * @example
208
+ * ```typescript
209
+ * const listener = await Uploader.addListener('events', (event) => {
210
+ * if (event.name === 'uploading') {
211
+ * console.log(`Upload ${event.id}: ${event.payload.percent}%`);
212
+ * } else if (event.name === 'completed') {
213
+ * console.log(`Upload ${event.id} completed`);
214
+ * } else if (event.name === 'failed') {
215
+ * console.error(`Upload ${event.id} failed:`, event.payload.error);
216
+ * }
217
+ * });
218
+ *
219
+ * // Remove listener when done
220
+ * await listener.remove();
221
+ * ```
123
222
  */
124
223
  addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void): Promise<PluginListenerHandle>;
125
224
  /**
126
- * Get the native Capacitor plugin version
225
+ * Get the native Capacitor plugin version.
127
226
  *
128
- * @returns {Promise<{ id: string }>} an Promise with version for this device
129
- * @throws An error if the something went wrong
227
+ * @returns Promise that resolves with the plugin version
228
+ * @throws Error if getting the version fails
229
+ * @since 0.0.1
230
+ * @example
231
+ * ```typescript
232
+ * const { version } = await Uploader.getPluginVersion();
233
+ * console.log('Plugin version:', version);
234
+ * ```
130
235
  */
131
236
  getPluginVersion(): Promise<{
132
237
  version: string;
@@ -1 +1 @@
1
- {"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\nexport interface uploadOption {\n /**\n * @since 0.0.1\n * @description The file path of the file to upload\n */\n filePath: string;\n /**\n * @since 0.0.1\n * @description The url of the server\n */\n serverUrl: string;\n /**\n * @since 0.0.1\n * @default 'Uploading'\n * @description The title of the notification\n * Android only\n */\n notificationTitle?: number;\n /**\n * @since 0.0.1\n * @description The headers to send with the request\n */\n headers: {\n [key: string]: string;\n };\n /**\n * @since 0.0.1\n * @description The method to use for the request\n * @default 'POST'\n */\n method?: 'PUT' | 'POST';\n /**\n * @since 0.0.1\n * @description The mime type to use for the request\n */\n mimeType?: string;\n /**\n * @since 0.0.1\n * @description The parameters to send with the request\n */\n parameters?: { [key: string]: string };\n /**\n * @since 0.0.1\n * @description The maximum number of retries\n */\n maxRetries?: number;\n /**\n * @since 0.0.2\n * @description The type of upload to use\n * @default 'binary'\n */\n uploadType?: 'binary' | 'multipart';\n /**\n * @since 0.0.2\n * @description The form field name for the file when using multipart\n * @default 'file'\n */\n fileField?: string;\n}\nexport interface UploadEvent {\n /**\n * Current status of upload, between 0 and 100.\n *\n * @since 0.0.1\n */\n name: 'uploading' | 'completed' | 'failed';\n /**\n * @since 0.0.1\n * @description The payload of the event\n * @default { percent: 0, error: '', statusCode: 0 }\n */\n payload: {\n /**\n * @since 0.0.1\n * @description The percent of the upload\n */\n percent?: number;\n /**\n * @since 0.0.1\n * @description The error of the upload\n */\n error?: string;\n /**\n * @since 0.0.1\n * @description The status code of the upload\n */\n statusCode?: number;\n };\n /**\n * @since 0.0.1\n * @description The id of the upload\n */\n id: string;\n}\n\nexport interface UploaderPlugin {\n /**\n * @since 0.0.1\n * @description Start the upload\n * @param options uploadOption\n * @returns { id: string }\n */\n startUpload(options: uploadOption): Promise<{ id: string }>;\n /**\n * @since 0.0.1\n * @description Remove the upload\n * @param options\n * @returns { void }\n */\n removeUpload(options: { id: string }): Promise<void>;\n /**\n * @since 0.0.1\n * @description Add a listener for the upload events\n * @param eventName\n * @param listenerFunc\n * @returns { PluginListenerHandle }\n */\n addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void): Promise<PluginListenerHandle>;\n\n /**\n * Get the native Capacitor plugin version\n *\n * @returns {Promise<{ id: string }>} an Promise with version for this device\n * @throws An error if the something went wrong\n */\n getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
1
+ {"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Configuration options for uploading a file.\n *\n * @since 0.0.1\n */\nexport interface uploadOption {\n /**\n * The local file path of the file to upload.\n * Can be a file:// URL or an absolute path.\n *\n * @since 0.0.1\n */\n filePath: string;\n\n /**\n * The server URL endpoint where the file should be uploaded.\n *\n * @since 0.0.1\n */\n serverUrl: string;\n\n /**\n * The title of the upload notification shown to the user.\n * Android only.\n *\n * @default 'Uploading'\n * @since 0.0.1\n */\n notificationTitle?: number;\n\n /**\n * HTTP headers to send with the upload request.\n * Useful for authentication tokens, content types, etc.\n *\n * @since 0.0.1\n * @example\n * ```typescript\n * headers: {\n * 'Authorization': 'Bearer token123',\n * 'X-Custom-Header': 'value'\n * }\n * ```\n */\n headers: {\n [key: string]: string;\n };\n\n /**\n * The HTTP method to use for the upload request.\n *\n * @default 'POST'\n * @since 0.0.1\n */\n method?: 'PUT' | 'POST';\n\n /**\n * The MIME type of the file being uploaded.\n * If not specified, the plugin will attempt to determine it automatically.\n *\n * @since 0.0.1\n * @example 'image/jpeg', 'application/pdf', 'video/mp4'\n */\n mimeType?: string;\n\n /**\n * Additional form parameters to send with the upload request.\n * These will be included as form data in multipart uploads.\n *\n * @since 0.0.1\n */\n parameters?: { [key: string]: string };\n\n /**\n * The maximum number of times to retry the upload if it fails.\n *\n * @since 0.0.1\n * @default 0\n */\n maxRetries?: number;\n\n /**\n * The type of upload to perform.\n * - 'binary': Uploads the file as raw binary data in the request body\n * - 'multipart': Uploads the file as multipart/form-data\n *\n * @default 'binary'\n * @since 0.0.2\n */\n uploadType?: 'binary' | 'multipart';\n\n /**\n * The form field name for the file when using multipart upload type.\n * Only used when uploadType is 'multipart'.\n *\n * @default 'file'\n * @since 0.0.2\n */\n fileField?: string;\n}\n\n/**\n * Event emitted during the upload lifecycle.\n *\n * @since 0.0.1\n */\nexport interface UploadEvent {\n /**\n * The current status of the upload.\n * - 'uploading': Upload is in progress\n * - 'completed': Upload finished successfully\n * - 'failed': Upload encountered an error\n *\n * @since 0.0.1\n */\n name: 'uploading' | 'completed' | 'failed';\n\n /**\n * Additional data about the upload event.\n *\n * @since 0.0.1\n */\n payload: {\n /**\n * Upload progress percentage from 0 to 100.\n * Only present during 'uploading' events.\n *\n * @since 0.0.1\n */\n percent?: number;\n\n /**\n * Error message if the upload failed.\n * Only present during 'failed' events.\n *\n * @since 0.0.1\n */\n error?: string;\n\n /**\n * HTTP status code returned by the server.\n * Present during 'completed' and 'failed' events.\n *\n * @since 0.0.1\n */\n statusCode?: number;\n };\n\n /**\n * Unique identifier for this upload task.\n *\n * @since 0.0.1\n */\n id: string;\n}\n\n/**\n * Capacitor Uploader Plugin for uploading files with background support and progress tracking.\n *\n * @since 0.0.1\n */\nexport interface UploaderPlugin {\n /**\n * Start uploading a file to a server.\n *\n * The upload will continue in the background even if the app is closed or backgrounded.\n * Listen to upload events to track progress, completion, or failure.\n *\n * @param options - Configuration for the upload\n * @returns Promise that resolves with the upload ID\n * @throws Error if the upload fails to start\n * @since 0.0.1\n * @example\n * ```typescript\n * const { id } = await Uploader.startUpload({\n * filePath: 'file:///path/to/file.jpg',\n * serverUrl: 'https://example.com/upload',\n * headers: {\n * 'Authorization': 'Bearer token'\n * },\n * method: 'POST',\n * uploadType: 'multipart',\n * fileField: 'photo'\n * });\n * console.log('Upload started with ID:', id);\n * ```\n */\n startUpload(options: uploadOption): Promise<{ id: string }>;\n\n /**\n * Cancel and remove an ongoing upload.\n *\n * This will stop the upload if it's in progress and clean up resources.\n *\n * @param options - Object containing the upload ID to remove\n * @returns Promise that resolves when the upload is removed\n * @throws Error if the upload ID is not found\n * @since 0.0.1\n * @example\n * ```typescript\n * await Uploader.removeUpload({ id: 'upload-123' });\n * ```\n */\n removeUpload(options: { id: string }): Promise<void>;\n\n /**\n * Listen for upload progress and status events.\n *\n * Events are fired for:\n * - Upload progress updates (with percent)\n * - Upload completion (with statusCode)\n * - Upload failure (with error and statusCode)\n *\n * @param eventName - Must be 'events'\n * @param listenerFunc - Callback function to handle upload events\n * @returns Promise that resolves with a listener handle for removal\n * @since 0.0.1\n * @example\n * ```typescript\n * const listener = await Uploader.addListener('events', (event) => {\n * if (event.name === 'uploading') {\n * console.log(`Upload ${event.id}: ${event.payload.percent}%`);\n * } else if (event.name === 'completed') {\n * console.log(`Upload ${event.id} completed`);\n * } else if (event.name === 'failed') {\n * console.error(`Upload ${event.id} failed:`, event.payload.error);\n * }\n * });\n *\n * // Remove listener when done\n * await listener.remove();\n * ```\n */\n addListener(eventName: 'events', listenerFunc: (state: UploadEvent) => void): Promise<PluginListenerHandle>;\n\n /**\n * Get the native Capacitor plugin version.\n *\n * @returns Promise that resolves with the plugin version\n * @throws Error if getting the version fails\n * @since 0.0.1\n * @example\n * ```typescript\n * const { version } = await Uploader.getPluginVersion();\n * console.log('Plugin version:', version);\n * ```\n */\n getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
@@ -3,7 +3,7 @@ import Capacitor
3
3
 
4
4
  @objc(UploaderPlugin)
5
5
  public class UploaderPlugin: CAPPlugin, CAPBridgedPlugin {
6
- private let PLUGIN_VERSION: String = "7.2.8"
6
+ private let pluginVersion: String = "7.3.1"
7
7
  public let identifier = "UploaderPlugin"
8
8
  public let jsName = "Uploader"
9
9
  public let pluginMethods: [CAPPluginMethod] = [
@@ -62,7 +62,7 @@ public class UploaderPlugin: CAPPlugin, CAPBridgedPlugin {
62
62
  }
63
63
 
64
64
  @objc func getPluginVersion(_ call: CAPPluginCall) {
65
- call.resolve(["version": self.PLUGIN_VERSION])
65
+ call.resolve(["version": self.pluginVersion])
66
66
  }
67
67
 
68
68
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@capgo/capacitor-uploader",
3
- "version": "7.2.8",
3
+ "version": "7.3.1",
4
4
  "description": "Upload file natively",
5
5
  "main": "dist/plugin.cjs.js",
6
6
  "module": "dist/esm/index.js",