@cabletv102/capacitor-upload-care-plugin

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

Install

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

API

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

$3

`typescript
configure(options: UploadCareConfig) => Promise
`

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

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

--------------------

$3

`typescript
openUploader(options?: UploadCareUploadOptions | undefined) => Promise
`

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

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

Returns: Promise<UploadCareUploadResult>

--------------------

$3

`typescript
uploadDataUri(options: UploadCareDataUriOptions) => Promise
`

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>

--------------------

$3

`typescript
pickMedia(options?: PickMediaOptions | undefined) => Promise
`

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

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

Returns: Promise<LocalPickedMedia>

--------------------

$3

`typescript
uploadPicked(options: UploadPickedOptions) => Promise
`

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>

--------------------

$3

`typescript
addListener(eventName: 'uploadProgress', listenerFunc: (event: UploadCareProgressEvent) => void) => Promise
`

Upload progress events while an upload is in-flight.

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

Returns: Promise<PluginListenerHandle>

--------------------

$3

`typescript
removeAllListeners() => Promise
`

--------------------

$3


#### 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' |

$3

#### UploadCareMediaType

'image' | 'video' | 'any'

capacitor-upload-care-plugin