@capgo/capacitor-uploader/dist/docs.json

Upload file natively

{
  "api": {
    "name": "UploaderPlugin",
    "slug": "uploaderplugin",
    "docs": "Capacitor Uploader Plugin for uploading files with background support and progress tracking.\n\n### iOS setup\n\nOn iOS the native layer uses a background `URLSession` with the identifier\n`CapacitorUploaderBackgroundSession`. Many apps can upload without adding\n`UIBackgroundModes`; add `fetch` when you need uploads to continue after the app\nis suspended.\n\nApp Store Connect rejects builds that declare `UIBackgroundModes` → `processing`\nwithout `BGTaskSchedulerPermittedIdentifiers`. This plugin does not schedule\n`BGTaskScheduler` work, so avoid `processing` unless another feature needs it.\nIf `processing` is present (for example from older setup guides), include\n`CapacitorUploaderBackgroundSession` in `BGTaskSchedulerPermittedIdentifiers`\nin your app's `Info.plist`.",
    "tags": [
      {
        "text": "```xml\n<key>UIBackgroundModes</key>\n<array>\n  <string>fetch</string>\n</array>\n<key>BGTaskSchedulerPermittedIdentifiers</key>\n<array>\n  <string>CapacitorUploaderBackgroundSession</string>\n</array>\n```",
        "name": "example"
      },
      {
        "text": "0.0.1",
        "name": "since"
      }
    ],
    "methods": [
      {
        "name": "startUpload",
        "signature": "(options: uploadOption) => Promise<{ id: string; }>",
        "parameters": [
          {
            "name": "options",
            "docs": "- Configuration for the upload",
            "type": "uploadOption"
          }
        ],
        "returns": "Promise<{ id: string; }>",
        "tags": [
          {
            "name": "param",
            "text": "options - Configuration for the upload"
          },
          {
            "name": "returns",
            "text": "Promise that resolves with the upload ID"
          },
          {
            "name": "throws",
            "text": "Error if the upload fails to start"
          },
          {
            "name": "since",
            "text": "0.0.1"
          },
          {
            "name": "example",
            "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```"
          },
          {
            "name": "example",
            "text": "```typescript\nconst { id } = await Uploader.startUpload({\n  serverUrl: 'https://api.example.com/upload',\n  method: 'POST',\n  uploadType: 'multipart',\n  files: [\n    { filePath: 'file:///...photo1.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },\n    { filePath: 'file:///...photo2.jpg', fieldName: 'images[]', mimeType: 'image/jpeg' },\n  ],\n  parameters: { albumId: '7' },\n  headers: { Authorization: 'Bearer token' },\n});\nconsole.log('Upload started with ID:', id);\n```"
          }
        ],
        "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.",
        "complexTypes": [
          "uploadOption"
        ],
        "slug": "startupload"
      },
      {
        "name": "uploadMultipart",
        "signature": "(options: UploadMultipartOptions) => Promise<{ id: string; }>",
        "parameters": [
          {
            "name": "options",
            "docs": "- Configuration for the multipart upload",
            "type": "UploadMultipartOptions"
          }
        ],
        "returns": "Promise<{ id: string; }>",
        "tags": [
          {
            "name": "param",
            "text": "options - Configuration for the multipart upload"
          },
          {
            "name": "returns",
            "text": "Promise that resolves with the upload ID"
          },
          {
            "name": "throws",
            "text": "Error if the upload fails to start"
          },
          {
            "name": "since",
            "text": "8.3.2"
          },
          {
            "name": "example",
            "text": "```typescript\nconst { id } = await Uploader.uploadMultipart({\n  url: 'https://example.com/upload',\n  filePath: 'file:///path/to/file.jpg',\n  fieldName: 'photo',\n  fields: { albumId: '7' },\n  headers: { Authorization: 'Bearer token' },\n});\nconsole.log('Upload started with ID:', id);\n```"
          }
        ],
        "docs": "Start uploading a single file as multipart/form-data.\n\nThis is a convenience API for backends that expect a named file field and\nadditional form fields. Existing `startUpload` binary uploads are unchanged.",
        "complexTypes": [
          "UploadMultipartOptions"
        ],
        "slug": "uploadmultipart"
      },
      {
        "name": "removeUpload",
        "signature": "(options: { id: string; }) => Promise<void>",
        "parameters": [
          {
            "name": "options",
            "docs": "- Object containing the upload ID to remove",
            "type": "{ id: string; }"
          }
        ],
        "returns": "Promise<void>",
        "tags": [
          {
            "name": "param",
            "text": "options - Object containing the upload ID to remove"
          },
          {
            "name": "returns",
            "text": "Promise that resolves when the upload is removed"
          },
          {
            "name": "throws",
            "text": "Error if the upload ID is not found"
          },
          {
            "name": "since",
            "text": "0.0.1"
          },
          {
            "name": "example",
            "text": "```typescript\nawait Uploader.removeUpload({ id: 'upload-123' });\n```"
          }
        ],
        "docs": "Cancel and remove an ongoing upload.\n\nThis will stop the upload if it's in progress and clean up resources.",
        "complexTypes": [],
        "slug": "removeupload"
      },
      {
        "name": "addListener",
        "signature": "(eventName: 'events', listenerFunc: (state: UploadEvent) => void) => Promise<PluginListenerHandle>",
        "parameters": [
          {
            "name": "eventName",
            "docs": "- Must be 'events'",
            "type": "'events'"
          },
          {
            "name": "listenerFunc",
            "docs": "- Callback function to handle upload events",
            "type": "(state: UploadEvent) => void"
          }
        ],
        "returns": "Promise<PluginListenerHandle>",
        "tags": [
          {
            "name": "param",
            "text": "eventName - Must be 'events'"
          },
          {
            "name": "param",
            "text": "listenerFunc - Callback function to handle upload events"
          },
          {
            "name": "returns",
            "text": "Promise that resolves with a listener handle for removal"
          },
          {
            "name": "since",
            "text": "0.0.1"
          },
          {
            "name": "example",
            "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```"
          }
        ],
        "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)",
        "complexTypes": [
          "PluginListenerHandle",
          "UploadEvent"
        ],
        "slug": "addlistenerevents-"
      },
      {
        "name": "acknowledgeEvent",
        "signature": "(options: { eventId: string; }) => Promise<void>",
        "parameters": [
          {
            "name": "options",
            "docs": "- Object containing the eventId to acknowledge",
            "type": "{ eventId: string; }"
          }
        ],
        "returns": "Promise<void>",
        "tags": [
          {
            "name": "param",
            "text": "options - Object containing the eventId to acknowledge"
          },
          {
            "name": "returns",
            "text": "Promise that resolves when the event has been removed from the cache"
          },
          {
            "name": "since",
            "text": "0.0.2"
          },
          {
            "name": "example",
            "text": "```typescript\nconst listener = await Uploader.addListener('events', async (event) => {\n  if (event.name === 'completed' || event.name === 'failed') {\n    handleUploadResult(event);\n    if (event.eventId) {\n      await Uploader.acknowledgeEvent({ eventId: event.eventId });\n    }\n  }\n});\n```"
          }
        ],
        "docs": "Acknowledge receipt of an upload event and remove it from the plugin cache.\n\nCompleted and failed events are stored in the plugin's persistent cache so they can be\nre-delivered if the app is closed or backgrounded before the event is processed.\nCall this method after successfully handling a 'completed' or 'failed' event to prevent\nit from being re-broadcast the next time the plugin initialises.\n\nProgress ('uploading') events do not have an eventId and do not need to be acknowledged.",
        "complexTypes": [],
        "slug": "acknowledgeevent"
      },
      {
        "name": "getPluginVersion",
        "signature": "() => Promise<{ version: string; }>",
        "parameters": [],
        "returns": "Promise<{ version: string; }>",
        "tags": [
          {
            "name": "returns",
            "text": "Promise that resolves with the plugin version"
          },
          {
            "name": "throws",
            "text": "Error if getting the version fails"
          },
          {
            "name": "since",
            "text": "0.0.1"
          },
          {
            "name": "example",
            "text": "```typescript\nconst { version } = await Uploader.getPluginVersion();\nconsole.log('Plugin version:', version);\n```"
          }
        ],
        "docs": "Get the native Capacitor plugin version.",
        "complexTypes": [],
        "slug": "getpluginversion"
      }
    ],
    "properties": []
  },
  "interfaces": [
    {
      "name": "uploadOption",
      "slug": "uploadoption",
      "docs": "",
      "tags": [],
      "methods": [],
      "properties": [
        {
          "name": "filePath",
          "tags": [
            {
              "text": "0.0.1",
              "name": "since"
            }
          ],
          "docs": "The local file path of the file to upload.\nCan be a file:// URL or an absolute path.\n\nIf you need to upload multiple files in a single multipart request, use `files`.",
          "complexTypes": [],
          "type": "string | undefined"
        },
        {
          "name": "files",
          "tags": [
            {
              "text": "0.0.3",
              "name": "since"
            }
          ],
          "docs": "Multiple files to upload in a single request.\n\nWhen provided, uploads are sent as `multipart/form-data` with one part per file.\nUse `fieldName` to control each part name (e.g. `images[]`).\n\nNote: `PUT` uploads (e.g. presigned S3 URLs) only support a single file.",
          "complexTypes": [
            "UploadFileOption"
          ],
          "type": "UploadFileOption[] | undefined"
        },
        {
          "name": "serverUrl",
          "tags": [
            {
              "text": "0.0.1",
              "name": "since"
            }
          ],
          "docs": "The server URL endpoint where the file should be uploaded.",
          "complexTypes": [],
          "type": "string"
        },
        {
          "name": "notificationTitle",
          "tags": [
            {
              "text": "'Uploading'",
              "name": "default"
            },
            {
              "text": "0.0.1",
              "name": "since"
            }
          ],
          "docs": "The title of the upload notification shown to the user.\nAndroid only.",
          "complexTypes": [],
          "type": "string | undefined"
        },
        {
          "name": "headers",
          "tags": [
            {
              "text": "0.0.1",
              "name": "since"
            },
            {
              "text": "```typescript\nheaders: {\n  'Authorization': 'Bearer token123',\n  'X-Custom-Header': 'value'\n}\n```",
              "name": "example"
            }
          ],
          "docs": "HTTP headers to send with the upload request.\nUseful for authentication tokens, content types, etc.",
          "complexTypes": [],
          "type": "{ [key: string]: string; }"
        },
        {
          "name": "method",
          "tags": [
            {
              "text": "'POST'",
              "name": "default"
            },
            {
              "text": "0.0.1",
              "name": "since"
            }
          ],
          "docs": "The HTTP method to use for the upload request.",
          "complexTypes": [],
          "type": "'PUT' | 'POST' | undefined"
        },
        {
          "name": "mimeType",
          "tags": [
            {
              "text": "0.0.1",
              "name": "since"
            },
            {
              "text": "'image/jpeg', 'application/pdf', 'video/mp4'",
              "name": "example"
            }
          ],
          "docs": "The MIME type of the file being uploaded.\nIf not specified, the plugin will attempt to determine it automatically.",
          "complexTypes": [],
          "type": "string | undefined"
        },
        {
          "name": "parameters",
          "tags": [
            {
              "text": "0.0.1",
              "name": "since"
            }
          ],
          "docs": "Additional form parameters to send with the upload request.\nThese will be included as form data in multipart uploads.",
          "complexTypes": [],
          "type": "{ [key: string]: string; } | undefined"
        },
        {
          "name": "maxRetries",
          "tags": [
            {
              "text": "0.0.1",
              "name": "since"
            },
            {
              "text": "0",
              "name": "default"
            }
          ],
          "docs": "The maximum number of times to retry the upload if it fails.",
          "complexTypes": [],
          "type": "number | undefined"
        },
        {
          "name": "uploadType",
          "tags": [
            {
              "text": "'binary' when `method` is `'PUT'`, otherwise `'multipart'`",
              "name": "default"
            },
            {
              "text": "0.0.2",
              "name": "since"
            }
          ],
          "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",
          "complexTypes": [],
          "type": "'binary' | 'multipart' | undefined"
        },
        {
          "name": "fileField",
          "tags": [
            {
              "text": "'file'",
              "name": "default"
            },
            {
              "text": "0.0.2",
              "name": "since"
            }
          ],
          "docs": "The form field name for the file when using multipart upload type.\nOnly used when uploadType is 'multipart'.\n\nFor multi-file uploads via `files`, this is used as the default field name\nwhen a file entry does not specify `fieldName`.",
          "complexTypes": [],
          "type": "string | undefined"
        }
      ]
    },
    {
      "name": "UploadFileOption",
      "slug": "uploadfileoption",
      "docs": "Configuration options for uploading a file.",
      "tags": [
        {
          "text": "0.0.1",
          "name": "since"
        }
      ],
      "methods": [],
      "properties": [
        {
          "name": "filePath",
          "tags": [
            {
              "text": "0.0.3",
              "name": "since"
            }
          ],
          "docs": "The local file path of the file to upload.\nCan be a file:// URL or an absolute path.",
          "complexTypes": [],
          "type": "string"
        },
        {
          "name": "fieldName",
          "tags": [
            {
              "text": "0.0.3",
              "name": "since"
            }
          ],
          "docs": "The form field name for the file part when using multipart upload.\n\nIf omitted, `uploadOption.fileField` is used (defaults to `'file'`).",
          "complexTypes": [],
          "type": "string | undefined"
        },
        {
          "name": "mimeType",
          "tags": [
            {
              "text": "0.0.3",
              "name": "since"
            }
          ],
          "docs": "The MIME type of this file.\nIf not specified, the plugin will attempt to determine it automatically.",
          "complexTypes": [],
          "type": "string | undefined"
        }
      ]
    },
    {
      "name": "UploadMultipartOptions",
      "slug": "uploadmultipartoptions",
      "docs": "Options for starting a single-file multipart upload.",
      "tags": [
        {
          "text": "8.3.2",
          "name": "since"
        }
      ],
      "methods": [],
      "properties": [
        {
          "name": "url",
          "tags": [
            {
              "text": "8.3.2",
              "name": "since"
            }
          ],
          "docs": "The server URL endpoint where the multipart request should be sent.",
          "complexTypes": [],
          "type": "string"
        },
        {
          "name": "filePath",
          "tags": [
            {
              "text": "8.3.2",
              "name": "since"
            }
          ],
          "docs": "The local file path of the file to upload.\nCan be a file:// URL or an absolute path.",
          "complexTypes": [],
          "type": "string"
        },
        {
          "name": "fieldName",
          "tags": [
            {
              "text": "8.3.2",
              "name": "since"
            }
          ],
          "docs": "The form field name for the uploaded file part.",
          "complexTypes": [],
          "type": "string"
        },
        {
          "name": "fields",
          "tags": [
            {
              "text": "8.3.2",
              "name": "since"
            }
          ],
          "docs": "Additional form fields to include in the multipart request.",
          "complexTypes": [],
          "type": "{ [key: string]: string; } | undefined"
        },
        {
          "name": "headers",
          "tags": [
            {
              "text": "8.3.2",
              "name": "since"
            }
          ],
          "docs": "HTTP headers to send with the upload request.",
          "complexTypes": [],
          "type": "{ [key: string]: string; } | undefined"
        }
      ]
    },
    {
      "name": "PluginListenerHandle",
      "slug": "pluginlistenerhandle",
      "docs": "",
      "tags": [],
      "methods": [],
      "properties": [
        {
          "name": "remove",
          "tags": [],
          "docs": "",
          "complexTypes": [],
          "type": "() => Promise<void>"
        }
      ]
    },
    {
      "name": "UploadEvent",
      "slug": "uploadevent",
      "docs": "Event emitted during the upload lifecycle.",
      "tags": [
        {
          "text": "0.0.1",
          "name": "since"
        }
      ],
      "methods": [],
      "properties": [
        {
          "name": "name",
          "tags": [
            {
              "text": "0.0.1",
              "name": "since"
            }
          ],
          "docs": "The current status of the upload.\n- 'uploading': Upload is in progress\n- 'completed': Upload finished successfully\n- 'failed': Upload encountered an error",
          "complexTypes": [],
          "type": "'uploading' | 'completed' | 'failed'"
        },
        {
          "name": "payload",
          "tags": [
            {
              "text": "0.0.1",
              "name": "since"
            }
          ],
          "docs": "Additional data about the upload event.",
          "complexTypes": [],
          "type": "{ percent?: number | undefined; error?: string | undefined; statusCode?: number | undefined; }"
        },
        {
          "name": "id",
          "tags": [
            {
              "text": "0.0.1",
              "name": "since"
            }
          ],
          "docs": "Unique identifier for this upload task.",
          "complexTypes": [],
          "type": "string"
        },
        {
          "name": "eventId",
          "tags": [
            {
              "text": "0.0.2",
              "name": "since"
            }
          ],
          "docs": "Unique identifier for this specific event instance.\nOnly present on 'completed' and 'failed' events.\nUsed with acknowledgeEvent() to confirm receipt and remove the event from the plugin cache.\nProgress ('uploading') events do not have an eventId and are not persisted.",
          "complexTypes": [],
          "type": "string | undefined"
        }
      ]
    }
  ],
  "enums": [],
  "typeAliases": [],
  "pluginConfigs": []
}