@cabletv102/capacitor-upload-care-plugin

Utilizes UploadCare's mobile SDK with Ionic/Capacitor/React

Install

npm install @cabletv102/capacitor-upload-care-plugin
npx cap sync

API

• configure(...)
• openUploader(...)
• uploadDataUri(...)
• pickMedia(...)
• uploadPicked(...)
• addListener('uploadProgress', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

configure(...)

configure(options: UploadCareConfig) => Promise<void>

Configure the Uploadcare SDK. Call this early in your app (e.g., app initialization).

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | UploadCareConfig |

openUploader(...)

openUploader(options?: UploadCareUploadOptions | undefined) => Promise<UploadCareUploadResult>

Open the native Uploadcare picker/uploader. You will call this from Ionic components (IonButton, IonItem, etc.).

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | UploadCareUploadOptions |

Returns: Promise<UploadCareUploadResult>

uploadDataUri(...)

uploadDataUri(options: UploadCareDataUriOptions) => Promise<UploadCareUploadResult>

Upload a base64 data URI directly (no native picker). Expects a full data URI like: data:image/jpeg;base64,/9j/4AAQSk...

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | UploadCareDataUriOptions |

Returns: Promise<UploadCareUploadResult>

pickMedia(...)

pickMedia(options?: PickMediaOptions | undefined) => Promise<LocalPickedMedia>

Pick without upload. Expects a full data URI like: data:image/jpeg;base64,/9j/4AAQSk...

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | PickMediaOptions |

Returns: Promise<LocalPickedMedia>

uploadPicked(...)

uploadPicked(options: UploadPickedOptions) => Promise<UploadCareUploadResult>

upload later using the previously picked item. Expects a full data URI like: data:image/jpeg;base64,/9j/4AAQSk...

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | UploadPickedOptions |

Returns: Promise<UploadCareUploadResult>

addListener('uploadProgress', ...)

addListener(eventName: 'uploadProgress', listenerFunc: (event: UploadCareProgressEvent) => void) => Promise<PluginListenerHandle>

Upload progress events while an upload is in-flight.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------- | | eventName | 'uploadProgress' | | listenerFunc | (event: UploadCareProgressEvent) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Interfaces

UploadCareConfig

Configuration options for Uploadcare SDK. These map to the public/private (secret) keys you will pass from the host app.

| Prop | Type | Description | | --------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | publicKey | string | Your Uploadcare public key (required for client-side uploading). Example: 'demopublickey' | | secretKey | string | Optional: Secret key if your mobile SDK usage requires it. Usually used for signed uploads / secure operations. Handle with care and never expose this in web builds. | | cdnBase | string | Optional: custom CDN base or API base if your Uploadcare project uses them. | | apiBase | string | | | debug | boolean | Whether to enable console logging on native side for debugging. |

UploadCareUploadResult

Result from an Uploadcare upload session.

| Prop | Type | Description | | ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------- | | success | boolean | Whether the upload interaction completed successfully. | | cancelled | boolean | If the user cancelled the picker. | | errorMessage | string | Error message, if any. | | uploadId | string | Optional: the id used for progress events. | | files | UploadCareFile[] | Array of uploaded file descriptors. Even when multiple is false, we’ll return an array of length 1. |

UploadCareFile

Metadata about a single uploaded file as returned by Uploadcare.

| Prop | Type | Description | | --------------- | ------------------- | --------------------------------------------------------------------- | | uuid | string | Uploadcare file UUID. | | cdnUrl | string | Uploadcare CDN URL for this file (what you probably care about most). | | filename | string | Original filename, if available. | | sizeBytes | number | File size in bytes. | | mimeType | string | MIME type, e.g. 'image/jpeg'. | | width | number | Width & height if it’s an image (when available). | | height | number | |

UploadCareUploadOptions

Options for an individual upload interaction.

| Prop | Type | Description | | ---------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | mediaType | UploadCareMediaType | image | video | any (default: any) | | multiple | boolean | Allow selecting multiple files. | | allowedMimeTypes | string[] | Restrict to images, videos, etc. If omitted, use Uploadcare defaults. We’ll map this to native Uploadcare type restrictions. | | maxFiles | number | Max number of files when multiple is true. | | enableCrop | boolean | Whether to enable cropping UI (if supported by the SDK). | | cropRatio | string | Preferred crop aspect ratio, like '3:2', '1:1', etc. We’ll parse and map this on native side if Uploadcare supports it. | | maxFileSizeBytes | number | Max file size in bytes (we can enforce in native before uploading). | | uploadId | string | Let's UI pre-assign uploadId for old openUploader flow. |

UploadCareDataUriOptions

Options for uploading a pre-existing base64 data URI. The dataUri must be a full data URI string: data:<mime>;base64,<payload>

| Prop | Type | | -------------- | ------------------- | | dataUri | string | | fileName | string | | uploadId | string |

LocalPickedMedia

| Prop | Type | | ----------------- | ------------------------------- | | localId | string | | uri | string | | mediaType | 'image' | 'video' | | mimeType | string | | displayName | string | | sizeBytes | number | | width | number | | height | number | | durationMs | number |

PickMediaOptions

| Prop | Type | | --------------- | ------------------------------------------------------------------- | | mediaType | UploadCareMediaType |

UploadPickedOptions

| Prop | Type | | -------------- | ------------------- | | localId | string | | fileName | string | | uploadId | string |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

UploadCareProgressEvent

| Prop | Type | | ------------------- | ------------------------------- | | uploadId | string | | progress | number | | bytesWritten | number | | contentLength | number | | mediaType | 'image' | 'video' |

Type Aliases

UploadCareMediaType

'image' | 'video' | 'any'