### Example App Local Testing

Source: https://github.com/cap-go/capacitor-updater/blob/main/AGENTS.md

Sets up and runs the example application locally to test the plugin. Navigate to the example app directory, install dependencies, and start the app.

```bash
cd example-app
bun install
bun run start
```

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

### Install Dependencies and Start Server

Source: https://github.com/cap-go/capacitor-updater/blob/main/example-app/README.md

Use these commands to install project dependencies and start the Vite development server. This is the initial setup step for running the example app.

```bash
bun install
bun run start
```

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

### Install Dependencies and Build Plugin

Source: https://github.com/cap-go/capacitor-updater/blob/main/AGENTS.md

Installs project dependencies and builds the plugin using Bun. Always use 'bun install' and 'bun run build' for development.

```bash
bun install

bun run build
```

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

### Install Project Dependencies

Source: https://github.com/cap-go/capacitor-updater/blob/main/CONTRIBUTING.md

Run this command to install all necessary Node.js dependencies for the project.

```shell
npm install
```

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

### Capacitor Configuration Example

Source: https://github.com/cap-go/capacitor-updater/wiki/Capgo-CLI

Example of capacitor.config.json showing appId and appName, which are used to identify your application.

```json
{
  "appId": 'ee.forgr.capacitor_go',
  "appName": 'Capgo',
  "webDir": 'dist'
}
```

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

### Install Capacitor Updater

Source: https://github.com/cap-go/capacitor-updater/wiki/Auto-update

Install the capacitor-updater package and sync Capacitor.

```bash
npm install @capgo/capacitor-updater
npx cap sync
```

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

### Package.json Version Example

Source: https://github.com/cap-go/capacitor-updater/wiki/Capgo-CLI

Example of package.json showing the version field, which is used by the CLI if not explicitly provided during upload.

```json
{
 "version": "1.0.2"
}
```

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

### addListener('updateAvailable', ...)

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Listens for update events. Notifies when an update is ready to be installed at the next app start.

```APIDOC
## addListener('updateAvailable', ...)

### Description
Listen for update event in the App, let you know when update is ready to install at next app start.

### Method
POST (assumed)

### Endpoint
/addListener

### Parameters
#### Query Parameters
- **eventName** (string) - Required - Must be 'updateAvailable'.
- **listenerFunc** (UpdateAvailableListener) - Required - The callback function to handle update available events.

### Returns
- **PluginListenerHandle** - An object with a `remove` method to unregister the listener.

### Response Example
```json
{
  "__listenerId": "some-unique-id"
}
```
```

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

### Start Preview Session

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Starts a temporary preview session, enabling the native shake menu and preparing for a previewed bundle. Requires `allowPreview` to be true. Use this before calling `set` for Expo Go-style preview flows.

```typescript
startPreviewSession(options?: StartPreviewSessionOptions | undefined) => Promise<void>
```

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

### Start Flexible In-App Update (Android)

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Initiates a flexible in-app update on Android, downloading the update in the background while the user continues to use the app. This requires monitoring download progress and calling `completeFlexibleUpdate` to install.

```typescript
startFlexibleUpdate() => Promise<AppUpdateResult>
```

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

### addListener('setNext', ...)

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Listen for the 'setNext' event, which signals that a bundle is queued as the next one to be installed. This allows developers to be aware of the upcoming bundle installation.

```APIDOC
## addListener('setNext', ...)

### Description
Listen for set next event in the App, let you know when a bundle is queued as the next bundle to install.

### Method
POST

### Endpoint
/addListener

### Parameters
#### Request Body
- **eventName** (string) - Required - `'setNext'`
- **listenerFunc** (function) - Required - A callback function that receives a `SetNextEvent` object.

### Request Example
```json
{
  "eventName": "setNext",
  "listenerFunc": "(state: SetNextEvent) => void"
}
```

### Response
#### Success Response (200)
- **value** (PluginListenerHandle) - A handle to the registered listener.

### Response Example
```json
{
  "value": "PluginListenerHandle"
}
```
```

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

### addListener('updateFailed')

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Listen for update fail event in the App, let you know when update has fail to install at next app start.

```APIDOC
## addListener('updateFailed')

### Description
Listen for update fail event in the App, let you know when update has fail to install at next app start.

### Method
POST

### Endpoint
/addListener

### Parameters
#### Query Parameters
- **eventName** (string) - Required - 'updateFailed'
- **listenerFunc** (function) - Required - A callback function that receives an UpdateFailedEvent object.

### Response
#### Success Response (200)
- **value** (PluginListenerHandle) - A handle to the listener that can be used to remove it.

### Response Example
```json
{
  "value": "some-listener-handle"
}
```
```

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

### Migrate to New Tooling

Source: https://github.com/cap-go/capacitor-updater/wiki/Upgrade-from-version-2-to-3

Remove old global and local installations of capgo and capacitor-updater, then install the new @capgo/cli and @capgo/capacitor-updater packages. Finally, sync your project.

```bash
npm remove -g capgo
npm remove capacitor-updater

npm i @capgo/cli
npm i @capgo/capacitor-updater
npx cap sync
```

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

### addListener('updateFailed', ...)

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Listen for update fail events. This informs you when an update has failed to install at the next app start.

```APIDOC
## addListener('updateFailed', ...)

### Description
Listens for events indicating that an application update has failed. This notification is triggered when an update encounters an error during its installation process, typically detected upon the next application launch.

### Method
`addListener`

### Parameters
#### Event Name
- **`eventName`** (string) - Must be `'updateFailed'`.

#### Listener Function
- **`listenerFunc`** (function) - A callback function that receives an `UpdateFailedEvent` object when an update failure is detected.

### Returns
- `Promise<PluginListenerHandle>` - A promise that resolves with a `PluginListenerHandle` object for listener management.

### Since
2.3.0
```

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

### Install SwiftLint on macOS

Source: https://github.com/cap-go/capacitor-updater/blob/main/CONTRIBUTING.md

If you are developing on macOS, install SwiftLint for Swift code linting.

```shell
brew install swiftlint
```

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

### startPreviewSession

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Starts a temporary preview/testing session. This stores the currently active bundle as the pending fallback, enables the native shake menu, and makes the next applied bundle show a native notice. Requires `allowPreview` to be true.

```APIDOC
## startPreviewSession

### Description
Starts a temporary preview/testing session. This stores the currently active bundle as the pending fallback, enables the native shake menu, and makes the next applied bundle show a native notice explaining that shaking the device can reload or leave the preview. Requires `allowPreview` to be true.

### Method
startPreviewSession

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **options** (StartPreviewSessionOptions | undefined) - Optional - Optional preview session options.

### Request Example
```json
{
  "appId": "your-app-id"
}
```

### Response
#### Success Response (200)
- **None** - Resolves when preview session state is prepared.

#### Response Example
```json
// No response body is returned.
```

### Since
8.47.0
```

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

### Install Capacitor Updater for Capacitor 5

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Install the LTS version of Capacitor Updater for Capacitor 5.

```bash
npm install @capgo/capacitor-updater@lts-v5
```

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

### startPreviewSession(...) - Start Preview Session

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Starts a temporary preview/testing session. This stores the currently active bundle as the pending fallback, enables the native shake menu, and makes the next applied bundle show a native notice explaining that shaking the device can reload or leave the preview. Requires `allowPreview` to be `true`. When `appId` is provided, the preview session temporarily uses that app id for update checks until the user leaves the preview. Native updater stats are skipped while the preview session is active. Use this before calling `set()` for Expo Go-style preview flows.

```APIDOC
## startPreviewSession(...)

### Description
Start a temporary preview/testing session.

This stores the currently active bundle as the pending fallback, enables the
native shake menu, and makes the next applied bundle show a native notice
explaining that shaking the device can reload or leave the preview.
Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
When `appId` is provided, the preview session temporarily uses that app id
for update checks until the user leaves the preview. Native updater stats are
skipped while the preview session is active.

Use this before calling {@link set} for Expo Go-style preview flows.

### Parameters
#### Path Parameters
- **options** (StartPreviewSessionOptions | undefined) - Optional - Optional preview session options.

### Returns
#### Success Response (Promise<void>)
- This method does not return a value upon successful execution.

**Since:** 8.47.0
```

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

### addListener('setNext')

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Listen for set next event in the App, let you know when a bundle is queued as the next bundle to install.

```APIDOC
## addListener('setNext')

### Description
Listen for set next event in the App, let you know when a bundle is queued as the next bundle to install.

### Method
POST

### Endpoint
/addListener

### Parameters
#### Query Parameters
- **eventName** (string) - Required - 'setNext'
- **listenerFunc** (function) - Required - A callback function that receives a SetNextEvent object.

### Response
#### Success Response (200)
- **value** (PluginListenerHandle) - A handle to the listener that can be used to remove it.

### Response Example
```json
{
  "value": "some-listener-handle"
}
```
```

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

### Install Capacitor Updater for Capacitor 7

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Install the LTS version of Capacitor Updater for Capacitor 7.

```bash
npm install @capgo/capacitor-updater@lts-v7
```

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

### Install Capacitor Updater for Capacitor 6

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Install the LTS version of Capacitor Updater for Capacitor 6.

```bash
npm install @capgo/capacitor-updater@lts-v6
```

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

### Handle Updates with App State and Splash Screen

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

This example demonstrates how to manage app updates based on application state changes, using the Splash Screen to enhance user experience during the update process. It downloads the update when the app becomes active and applies it when the app is sent to the background.

```javascript
import { CapacitorUpdater, VersionInfo } from '@capgo/capacitor-updater'
import { SplashScreen } from '@capacitor/splash-screen'
import { App } from '@capacitor/app'

let version: VersionInfo;
App.addListener('appStateChange', async (state) => {
    if (state.isActive) {
      // Ensure download occurs while the app is active, or download may fail
      version = await CapacitorUpdater.download({
        version: '0.0.4',
        url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
      })
    }

    if (!state.isActive && version) {
      // Activate the update when the application is sent to background
      SplashScreen.show()
      try {
        await CapacitorUpdater.set(version);
        // At this point, the new version should be active, and will need to hide the splash screen
      } catch () {
        SplashScreen.hide() // Hide the splash screen again if something went wrong
      }
    }
})

```

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

### addListener('download', ...)

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Listens for download events in the app, providing status updates on download progress (started, loading, finished).

```APIDOC
## addListener('download', ...)

### Description
Listen for download event in the App, let you know when the download is started, loading and finished.

### Method
POST (assumed)

### Endpoint
/addListener

### Parameters
#### Query Parameters
- **eventName** (string) - Required - Must be 'download'.
- **listenerFunc** (DownloadChangeListener) - Required - The callback function to handle download events.

### Returns
- **PluginListenerHandle** - An object with a `remove` method to unregister the listener.

### Response Example
```json
{
  "__listenerId": "some-unique-id"
}
```
```

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

### current()

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Retrieves the current installed app version and the native version. Returns 'builtin' if no version is set.

```APIDOC
## current()

### Description
Get the current version, if none are set it returns `builtin`, currentNative is the original version install on the device.

### Method
GET (assumed)

### Endpoint
/current

### Returns
- **current** (string) - The current app version.
- **currentNative** (string) - The native version installed on the device.

### Response Example
```json
{
  "current": "1.0.0",
  "currentNative": "1.0.0"
}
```
```

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

### Install Capacitor Updater for Capacitor 4

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Install the LTS version of Capacitor Updater for Capacitor 4.

```bash
npm install @capgo/capacitor-updater@lts-v4
```

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

### addListener('download')

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Listens for bundle download events in the App. This event fires when a download starts, progresses, and completes, providing download progress percentages.

```APIDOC
## addListener('download')

### Description
Listen for bundle download event in the App. Fires once a download has started, during downloading and when finished.
This will return you all download percent during the download

### Parameters
#### Path Parameters
- **eventName** (`'download'`) - Required - The name of the event to listen for.
- **listenerFunc** (`(state: DownloadEvent) => void`) - Required - The function to call when the event is fired.

### Returns
`Promise<PluginListenerHandle>`

### Since
2.0.11
```

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

### GET /versions

Source: https://github.com/cap-go/capacitor-updater/wiki/Capgo-API

Retrieves a list of all versions associated with an application.

```APIDOC
## GET /versions

### Description
Retrieves a list of all versions associated with an application.

### Method
GET

### Endpoint
`https://api.capgo.app/versions`

### Parameters
#### Query Parameters
- **app_id** (string) - Required - The ID of the application.

### Response
#### Success Response (200)
- **Array of version objects** - Returns an array of version objects, each containing details like `id`, `created_at`, `name`, `app_id`, `version`, `created_by`, `updated_at`, `public`, `disableAutoUpdateUnderNative`, and `disableAutoUpdateToMajor`.

### Response Example
```json
[
  {
    "id": 1,
    "created_at": "string",
    "name": "string",
    "app_id": "string",
    "version": 1,
    "created_by": "string",
    "updated_at": "string",
    "public": true,
    "disableAutoUpdateUnderNative": false,
    "disableAutoUpdateToMajor": false
  }
]
```
```

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

### Response for GET /device (multiple devices)

Source: https://github.com/cap-go/capacitor-updater/wiki/Capgo-API

Returns an array of device objects when querying the GET /device endpoint with an app_id.

```javascript
{
    created_at?: string | undefined;
    updated_at?: string | undefined;
    device_id: string;
    version: number;
    app_id: string;
    platform?: "ios" | "android" | undefined;
    plugin_version: string;
    os_version?: string | undefined;
}[]
```

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

### Install Capacitor Updater for Capacitor 8

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Install the latest version of Capacitor Updater for Capacitor 8.

```bash
npm install @capgo/capacitor-updater@latest
```

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

### Add Native Shells

Source: https://github.com/cap-go/capacitor-updater/blob/main/example-app/README.md

Add native shells for iOS or Android to test the plugin's behavior on a physical device or simulator. Run this command from the example app's root folder.

```bash
bunx cap add ios
# or
bunx cap add android
```

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

### Set Multiple Delay Conditions for Updates

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Configure conditions that must be met before a pending update is applied. Use this to control when an update is installed after queuing it with `next()`. The update installs only after ALL specified conditions are satisfied.

```typescript
await CapacitorUpdater.setMultiDelay({
  delayConditions: [
    { kind: 'kill' },
    { kind: 'background', value: '300000' }
  ]
});
```

```typescript
await CapacitorUpdater.setMultiDelay({
  delayConditions: [{ kind: 'date', value: '2025-12-31T23:59:59Z' }]
});
```

```typescript
await CapacitorUpdater.setMultiDelay({
  delayConditions: [{ kind: 'background' }]
});
```

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

### GET /device

Source: https://github.com/cap-go/capacitor-updater/wiki/Capgo-API

Retrieves a list of all devices linked to an application, or a specific device if a channel name is provided.

```APIDOC
## GET /device

### Description
Retrieves a list of all devices linked to an application, or a specific device if a channel name is provided.

### Method
GET

### Endpoint
`https://api.capgo.app/device`

### Parameters
#### Query Parameters
- **appid** (string) - Required - The ID of the application.
- **channel** (string) - Optional - The name of the channel to filter devices by.

### Response
#### Success Response (200)
- **Array of device objects** - Returns an array of device objects, each containing details like `created_at`, `updated_at`, `device_id`, `version`, `app_id`, `platform`, `plugin_version`, and `os_version`.

### Response Example
```json
[
  {
    "created_at": "string",
    "updated_at": "string",
    "device_id": "string",
    "version": 1,
    "app_id": "string",
    "platform": "ios" | "android",
    "plugin_version": "string",
    "os_version": "string"
  }
]
```
```

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

### Response for GET /channel (multiple channels)

Source: https://github.com/cap-go/capacitor-updater/wiki/Capgo-API

Returns an array of channel objects when querying the GET /channel endpoint with an app_id.

```javascript
{
    id: number;
    created_at: string;
    name: string;
    app_id: string;
    version: number;
    created_by: string;
    updated_at: string;
    public: boolean;
    disableAutoUpdateUnderNative: boolean;
    disableAutoUpdateToMajor: boolean;
}[]
```

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

### Listen for Flexible Update State Changes

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Listen for changes in the flexible update download and installation process on Android. This event provides download progress and installation status updates.

```typescript
addListener(eventName: 'onFlexibleUpdateStateChange', listenerFunc: (state: FlexibleUpdateState) => void) => Promise<PluginListenerHandle>
```

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

### Listen for Queued Bundle Event

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Use this listener to be notified when a bundle is queued as the next one to install. This helps in managing and tracking upcoming updates.

```typescript
addListener(eventName: 'setNext', listenerFunc: (state: SetNextEvent) => void) => Promise<PluginListenerHandle>
```

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

### SetNextEvent

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Emits an event when a bundle is queued as the next one to be installed.

```APIDOC
## SetNextEvent

### Description
Emit when a bundle is queued as the next bundle to install.

### Parameters
#### Request Body
- **`bundle`** (BundleInfo) - Required - Information about the bundle queued for installation.
```

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

### startFlexibleUpdate

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Initiates a flexible in-app update on Android, downloading the update in the background while the user continues to use the app. A subsequent call to `completeFlexibleUpdate` is required to install the update.

```APIDOC
## startFlexibleUpdate

### Description
Start a flexible in-app update on Android. This triggers Google Play's flexible update flow, which downloads the update in the background, allows the user to continue using the app, notifies when the download is complete, and requires calling `completeFlexibleUpdate` to install. Monitor download progress using the `onFlexibleUpdateStateChange` listener.

**Requirements:**
- Android only (throws error on iOS)
- An update must be available (check with `getAppUpdateInfo` first)
- The update must allow flexible updates (`flexibleUpdateAllowed: true`)

**Typical flow:**
1. Call `startFlexibleUpdate()` to begin download
2. Listen to `onFlexibleUpdateStateChange` for progress
3. When status is `DOWNLOADED`, prompt user to restart
4. Call `completeFlexibleUpdate()` to install and restart

### Method
`startFlexibleUpdate`

### Response
#### Success Response
`Promise<AppUpdateResult>` — Result indicating the update was started, cancelled, or failed.

### Throws
`{Error}` - If not on Android, no update is available, or flexible updates not allowed.
```

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

### Listen for Download Events

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Listens for download events within the app, providing status updates on download progress (started, loading, finished).

```typescript
addListener(eventName: 'download', listenerFunc: DownloadChangeListener) => Promise<PluginListenerHandle> & PluginListenerHandle
```

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

### download

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Downloads a new app bundle from a provided URL for later installation. The bundle can be encrypted or a multi-file delta update. It is stored locally but not activated until next() or set() is called.

```APIDOC
## download

### Description
Downloads a new app bundle from a provided URL for later installation. The bundle can be encrypted or a multi-file delta update. It is stored locally but not activated until next() or set() is called.

### Method
POST

### Endpoint
/download

### Parameters
#### Request Body
- **options** (DownloadOptions) - Required - The options for downloading a new bundle zip, including url, version, and optionally sessionKey, checksum, and manifest.

### Request Example
```json
{
  "url": "https://example.com/versions/1.0.0/dist.zip",
  "version": "1.0.0"
}
```

### Response
#### Success Response (200)
- **BundleInfo** - The BundleInfo for the downloaded bundle, including id, version, and info.

#### Error Response (400)
- **Error** - If the download fails or the bundle is invalid.
```

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

### addListener('onFlexibleUpdateStateChange')

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Listen for flexible update state changes on Android. This event fires during the flexible update download process, providing download progress and installation status changes.

```APIDOC
## addListener('onFlexibleUpdateStateChange')

### Description
Listen for flexible update state changes on Android. This event fires during the flexible update download process, providing download progress and installation status changes.

### Method
addListener

### Parameters
#### Listener Parameters
- **eventName** (string) - Required - 'onFlexibleUpdateStateChange'
- **listenerFunc** ((state: FlexibleUpdateState) => void) - Required - Callback function to handle state changes.

### Returns
`Promise<PluginListenerHandle>` - A promise that resolves with a PluginListenerHandle.

### Event Details
**Install status values:**
- `UNKNOWN` (0): Unknown status
- `PENDING` (1): Download pending
- `DOWNLOADING` (2): Download in progress
- `INSTALLING` (3): Installing the update
- `INSTALLED` (4): Update installed (app restart needed)
- `FAILED` (5): Update failed
- `CANCELED` (6): Update was canceled
- `DOWNLOADED` (11): Download complete, ready to install

When status is `DOWNLOADED`, you should prompt the user and call `completeFlexibleUpdate` to finish the installation.
```

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

### Get Current App Version

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Retrieves the current installed version of the app. If no version is explicitly set, it defaults to 'builtin'. `currentNative` reflects the original version installed on the device.

```typescript
current() => Promise<{ current: string; currentNative: string; }>
```

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

### Download App Bundle

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Download a new app bundle from a provided URL for later installation. The bundle can be activated immediately or on the next app background/restart. Supports encrypted bundles and multi-file delta updates.

```typescript
download(options: DownloadOptions) => Promise<BundleInfo>
```

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

### setMultiDelay(options)

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Configures conditions that must be met before a pending update is applied. This method allows control over when an update is installed after it has been queued using `next()`, ensuring all specified conditions are satisfied.

```APIDOC
## setMultiDelay(options)

### Description
Configure conditions that must be met before a pending update is applied.

### Method
N/A (SDK Method)

### Endpoint
N/A (SDK Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **options** (MultiDelayConditions) - Required - Contains the `MultiDelayConditions` array of conditions.

### Request Example
```json
{
  "options": {
    "background": 300000,
    "date": "2025-12-31T23:59:59Z",
    "nativeVersion": "2.0.0"
  }
}
```

### Response
#### Success Response (200)
- **void**

#### Response Example
(No response body for success)
```

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

### Get App Version Name

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Retrieves the version name of the app, if it was set during the application's setup phase.

```typescript
versionName() => Promise<{ versionName: string; }>
```

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

### Listen for Update Failed Event

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Use this listener to be notified when an update has failed to install at the next app start. This is useful for error handling and informing the user.

```typescript
addListener(eventName: 'updateFailed', listenerFunc: (state: UpdateFailedEvent) => void) => Promise<PluginListenerHandle>
```

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

### Get Capacitor Updater Plugin Version

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Retrieves the version of the native Capacitor Updater plugin installed in the app. This information is sent to the update server with each request and is useful for debugging.

```typescript
getPluginVersion() => Promise<PluginVersion>
```

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

### Trigger Immediate Update Check

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Trigger the native auto-update check/download pipeline immediately. This starts the background update flow. The promise resolves after the native background work has been queued, not after the update is downloaded or installed.

```typescript
await CapacitorUpdater.triggerUpdateCheck();
```

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

### addListener('appReady', ...)

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Listen for the 'appReady' event, indicating that the application is ready for use. This event is retained natively and can be delivered after a reload, even if the listener is attached later in the app startup.

```APIDOC
## addListener('appReady', ...)

### Description
Listen for app ready event in the App, let you know when app is ready to use. This event is retained natively until JavaScript consumes it, so it can still be delivered after a reload even if the listener is attached later in app startup.

### Method
POST

### Endpoint
/addListener

### Parameters
#### Request Body
- **eventName** (string) - Required - `'appReady'`
- **listenerFunc** (function) - Required - A callback function that receives an `AppReadyEvent` object.

### Request Example
```json
{
  "eventName": "appReady",
  "listenerFunc": "(state: AppReadyEvent) => void"
}
```

### Response
#### Success Response (200)
- **value** (PluginListenerHandle) - A handle to the registered listener.

### Response Example
```json
{
  "value": "PluginListenerHandle"
}
```
```

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

### addListener('appReady')

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Listen for app ready event in the App, let you know when app is ready to use. This event is retained natively until JavaScript consumes it, so it can still be delivered after a reload even if the listener is attached later in app startup.

```APIDOC
## addListener('appReady')

### Description
Listen for app ready event in the App, let you know when app is ready to use. This event is retained natively until JavaScript consumes it, so it can still be delivered after a reload even if the listener is attached later in app startup.

### Method
POST

### Endpoint
/addListener

### Parameters
#### Query Parameters
- **eventName** (string) - Required - 'appReady'
- **listenerFunc** (function) - Required - A callback function that receives an AppReadyEvent object.

### Response
#### Success Response (200)
- **value** (PluginListenerHandle) - A handle to the listener that can be used to remove it.

### Response Example
```json
{
  "value": "some-listener-handle"
}
```
```

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

### Initialize Capgo CLI

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Initialize the Capgo CLI with your API key to set up auto-updates.

```bash
npx @capgo/cli@latest init API_KEY
```

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

### addListener('download', ...)

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Listens for the 'download' event, which fires during the app bundle download process. It provides progress updates throughout the download.

```APIDOC
## addListener('download', ...)

### Description
Listen for bundle download event in the App. Fires once a download has started, during downloading and when finished. This will return you all download percent during the download.

### Parameters
#### Event Name
- **`eventName`** (`'download'`) - Required - The name of the event to listen for.
#### Listener Function
- **`listenerFunc`** (`(state: DownloadEvent) => void`) - Required - The callback function to execute when the event is fired.

### Returns
`Promise<PluginListenerHandle>`

### Since
2.0.11
```

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

### addListener('downloadComplete', ...)

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Listen for downloadComplete events, indicating that an update has finished downloading.

```APIDOC
## addListener('downloadComplete', ...)

### Description
Listens for an event that signals an update has been successfully downloaded. This allows the application to prepare for the update or notify the user.

### Method
`addListener`

### Parameters
#### Event Name
- **`eventName`** (string) - Must be `'downloadComplete'`.

#### Listener Function
- **`listenerFunc`** (function) - A callback function that receives a `DownloadCompleteEvent` object upon completion of the download.

### Returns
- `Promise<PluginListenerHandle>` - A promise that resolves with a `PluginListenerHandle` object for listener management.

### Since
4.0.0
```

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

### Download and Set New Version

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Download a new version of the app from a specified URL and then set it as the active version, which reloads the app.

```javascript
const version = await CapacitorUpdater.download({
    version: '0.0.4',
    url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
  })
  await CapacitorUpdater.set(version); // sets the new version, and reloads the app
```

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

### Install Capacitor Updater v4 Alpha

Source: https://github.com/cap-go/capacitor-updater/wiki/Upgrade-from-v3-to-v4-alpha

Install the next version of the Capacitor Updater package using npm.

```bash
npm i @capgo/capacitor-updater@next
```

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

### Build and Copy Assets

Source: https://github.com/cap-go/capacitor-updater/wiki/Upgrade-from-version-2-to-3

After updating the import statements, rebuild your project using 'npm run build' and then copy the assets using 'npx cap copy'.

```bash
npm run build
npx cap copy
```

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

### Publish Plugin

Source: https://github.com/cap-go/capacitor-updater/blob/main/CONTRIBUTING.md

Use this command to publish the plugin to the npm registry. A pre-publish hook ensures the plugin is prepared before publishing.

```shell
npm publish
```

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

### addListener('downloadComplete')

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Listens for 'downloadComplete' events.

```APIDOC
## addListener('downloadComplete')

### Description
Listen for downloadComplete events.

### Parameters
#### Path Parameters
- **eventName** (`'downloadComplete'`) - Required - The name of the event to listen for.
- **listenerFunc** (`(state: DownloadCompleteEvent) => void`) - Required - The function to call when the event is fired.

### Returns
`Promise<PluginListenerHandle>`

### Since
4.0.0
```

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

### Response for GET /device (single device)

Source: https://github.com/cap-go/capacitor-updater/wiki/Capgo-API

Returns a single device object when querying the GET /device endpoint with both app_id and channel name.

```javascript
{
    created_at?: string | undefined;
    updated_at?: string | undefined;
    device_id: string;
    version: number;
    app_id: string;
    platform?: "ios" | "android" | undefined;
    plugin_version: string;
    os_version?: string | undefined;
}
```

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

### Format and Lint Code

Source: https://github.com/cap-go/capacitor-updater/blob/main/AGENTS.md

Formats the code using ESLint, Prettier, and SwiftLint, and also lints the code without making changes. Use 'bun run fmt' for formatting and 'bun run lint' for linting.

```bash
bun run fmt

bun run lint
```

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

### Response for GET /channel (single channel)

Source: https://github.com/cap-go/capacitor-updater/wiki/Capgo-API

Returns a single channel object when querying the GET /channel endpoint with both app_id and channel name.

```javascript
{
    id: number;
    created_at: string;
    name: string;
    app_id: string;
    version: number;
    created_by: string;
    updated_at: string;
    public: boolean;
    disableAutoUpdateUnderNative: boolean;
    disableAutoUpdateToMajor: boolean;
}
```

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

### Install Specific Capacitor Updater Version

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Install a specific version of the Capacitor Updater plugin that matches your Capacitor version using npm tags.

```bash
npm install @capgo/capacitor-updater@<version>
```

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

### Manual Download and Update on App State Change

Source: https://github.com/cap-go/capacitor-updater/wiki/Manual-mode

This snippet demonstrates how to manually download and apply updates based on the application's active state. It listens for app state changes to initiate downloads when the app is active and applies the update when the app goes into the background. Ensure necessary imports are included.

```jsx
import { CapacitorUpdater } from '@capgo/capacitor-updater'
import { SplashScreen } from '@capacitor/splash-screen'
import { App } from '@capacitor/app'
let data = {version: ""}
App.addListener('appStateChange', async(state) => {
     if (state.isActive) {
       // Do the download during user active app time to prevent failed download
       data = await CapacitorUpdater.download({
       url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
       })
     }
     if (!state.isActive && data.version !== "") {
       // Do the switch when user leave app
       SplashScreen.show()
       try {
         await CapacitorUpdater.set(data)
       } catch (err) {
         console.log(err)
         SplashScreen.hide() // in case the set fail, otherwise the new app will have to hide it
       }
     }
 })
```

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

### addListener('set', ...)

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Listen for the 'set' event, which indicates that a bundle has been successfully applied. This event is retained natively and delivered upon listener subscription, even if the app reloads before the listener is attached.

```APIDOC
## addListener('set', ...)

### Description
Listen for set event in the App, let you know when a bundle has been applied successfully. This event is retained natively until JavaScript consumes it, so if the app reloads before your listener is attached, the last pending `set` event is delivered once the listener subscribes.

### Method
POST

### Endpoint
/addListener

### Parameters
#### Request Body
- **eventName** (string) - Required - `'set'`
- **listenerFunc** (function) - Required - A callback function that receives a `SetEvent` object.

### Request Example
```json
{
  "eventName": "set",
  "listenerFunc": "(state: SetEvent) => void"
}
```

### Response
#### Success Response (200)
- **value** (PluginListenerHandle) - A handle to the registered listener.

### Response Example
```json
{
  "value": "PluginListenerHandle"
}
```
```

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

### GetLatestOptions

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Configuration options for checking the latest available update. Allows specifying a channel, app ID, and whether to include bundle size information.

```APIDOC
## GetLatestOptions

### Description
Configuration options for checking the latest available update. Allows specifying a channel, app ID, and whether to include bundle size information.

### Properties

- **`channel`** (string) - Optional - The channel to get the latest version for. The channel must allow 'self_assign' for this to work.
- **`appId`** (string) - Optional - Temporarily use another app id for this update check while using a trusted preview container. This only changes the app id sent by this request; it does not persist a preview session. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
- **`includeBundleSize`** (boolean) - Optional - When true, the native plugin computes which manifest files are missing on this device and asks the Capgo update endpoint for their stored sizes before resolving {@link getLatest}. This adds one backend request only when the update response contains a manifest. It does not perform per-file network checks. Defaults to `false`.
```

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

### set

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Sets a downloaded version as the current active version of the application. An error will be returned if the specified version does not contain an index.html file. An optional custom versionName can also be provided.

```APIDOC
## set

### Description
Sets a downloaded version as the current version. Returns an error if the version folder lacks an index.html. An optional custom versionName can be provided.

### Method
POST

### Endpoint
/set

### Parameters
#### Request Body
- **options** (object) - Required - An object containing version information.
  - **version** (string) - Required - The identifier of the version to set as current.
  - **versionName** (string) - Optional - A custom name for the version.

### Response
#### Success Response (200)
- (void) - Indicates successful setting of the version.

### Request Example
{
  "version": "1.0.0",
  "versionName": "Release Candidate 1"
}

### Response Example
(No content on success)
```

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

### GetChannelRes

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Response structure for getting the current channel information.

```APIDOC
## GetChannelRes

### Description
Response structure for getting the current channel information.

### Response
#### Success Response (200)
- **`channel`** (string) - Current status of get channel
- **`error`** (string) - Error message, if any
- **`message`** (string) - Additional message details.
- **`status`** (string) - Status of the channel operation.
- **`allowSet`** (boolean) - Indicates if setting a channel is allowed.
```

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

### list

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Retrieves a list of all available app versions currently stored on the device.

```APIDOC
## list

### Description
Gets a list of all available versions stored on the device.

### Method
GET

### Endpoint
/list

### Response
#### Success Response (200)
- **versions** (array of strings) - An array containing the identifiers of all available versions.

### Response Example
{
  "versions": ["1.0.0", "1.0.1"]
}
```

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

### Get Device Update ID

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Retrieves the unique device identifier used by the auto-update server.

```typescript
getId() => Promise<{ id: string; }>
```

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

### AppReadyEvent

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Emitted when the application is ready for use, utilizing native `retainUntilConsumed` behavior.

```APIDOC
## AppReadyEvent

### Description
Emitted when the app is ready to use. This event uses native `retainUntilConsumed` behavior.

### Parameters
#### Request Body
- **`bundle`** (BundleInfo) - Required - Information about the bundle that the app is ready to use.
- **`status`** (string) - Required - The status of the app readiness.
```

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

### getNextBundle()

Source: https://github.com/cap-go/capacitor-updater/blob/main/README.md

Get information about the bundle that is queued to be activated on the next reload. Returns null if no update is pending.

```APIDOC
## getNextBundle()

### Description
Get information about the bundle queued to be activated on next reload.

Returns:
- {@link BundleInfo} object if a bundle has been queued via {@link next}
- `null` if no update is pending

This is useful to:
- Check if an update is waiting to be applied
- Display "Update pending" status to users
- Show version info of the queued update
- Decide whether to show a "Restart to update" prompt

The queued bundle will be activated when:
- The app is backgrounded (default behavior)
- The app is killed and restarted
- {@link reload} is called manually
- Delay conditions set by {@link setMultiDelay} are met

### Method
`getNextBundle`

### Returns
- `Promise<BundleInfo | null>` - A promise that resolves with a `BundleInfo` object if an update is queued, or `null` if no update is pending.

### Since
6.8.0
```

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

### Initialize Live Update Probe and Error Handling

Source: https://github.com/cap-go/capacitor-updater/blob/main/example-app/index.html

Initializes a global probe object to capture live update events and sets up global error listeners for 'error' and 'unhandledrejection' events. This is useful for debugging and monitoring update processes.

```javascript
const probe = (globalThis.__capgoProbe = {
  htmlLoadedAt: new Date().toISOString(),
  moduleLoadedAt: null,
  errors: [],
});
globalThis.addEventListener('error', (event) => {
  const detail = `${event.message} @ ${event.filename || 'inline'}:${event.lineno || 0}:${event.colno || 0}`;
  probe.errors.push(detail);
  console.log('[Harness] window.error', detail);
});
globalThis.addEventListener('unhandledrejection', (event) => {
  const detail = event.reason?.stack || event.reason?.message || String(event.reason);
  probe.errors.push(detail);
  console.log('[Harness] window.unhandledrejection', detail);
});
console.log('[Harness] inline boot', probe.htmlLoadedAt);
```

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

### GET /channel

Source: https://github.com/cap-go/capacitor-updater/wiki/Capgo-API

Retrieves a list of all channels for a given application ID, or a specific channel if a channel name is provided.

```APIDOC
## GET /channel

### Description
Retrieves a list of all channels for a given application ID, or a specific channel if a channel name is provided.

### Method
GET

### Endpoint
`https://api.capgo.app/channel`

### Parameters
#### Query Parameters
- **appid** (string) - Required - The ID of the application.
- **channel** (string) - Optional - The name of the channel to retrieve.

### Response
#### Success Response (200)
- **Array of channel objects** - Returns an array of channel objects, each containing details like `id`, `created_at`, `name`, `app_id`, `version`, `created_by`, `updated_at`, `public`, `disableAutoUpdateUnderNative`, and `disableAutoUpdateToMajor`.

### Response Example
```json
[
  {
    "id": 1,
    "created_at": "string",
    "name": "string",
    "app_id": "string",
    "version": 1,
    "created_by": "string",
    "updated_at": "string",
    "public": true,
    "disableAutoUpdateUnderNative": false,
    "disableAutoUpdateToMajor": false
  }
]
```
```

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

### download

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Downloads a new version of the app from a provided URL. The URL should point to a zip file containing the app's assets, either directly or within a unique folder.

```APIDOC
## download

### Description
Downloads a new version from the provided URL. The URL should be a zip file containing the app's assets.

### Method
POST

### Endpoint
/download

### Parameters
#### Request Body
- **options** (object) - Required - An object containing the download URL.
  - **url** (string) - Required - The URL of the zip file to download.

### Response
#### Success Response (200)
- **version** (string) - The version identifier of the downloaded update.

### Request Example
{
  "url": "https://github.com/Cap-go/demo-app/releases/download/0.0.2/dist.zip"
}

### Response Example
{
  "version": "1.0.0"
}
```

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

### list

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Retrieves all locally downloaded bundles, including the active, builtin, pending, and failed bundles. Useful for checking disk space, deleting old bundles, and monitoring download status.

```APIDOC
## list

### Description
Get all locally downloaded bundles stored in your app. This returns all bundles that have been downloaded and are available locally, including the currently active bundle, the `builtin` bundle, any downloaded bundles waiting to be activated, and failed bundles (with `error` status).

Use this to check available disk space by counting bundles, delete old bundles with {@link delete}, or monitor bundle download status.

### Method
list

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
list(options?: ListOptions | undefined)
```

### Response
#### Success Response (200)
`Promise<BundleListResult>` — A promise containing the array of {@link BundleInfo} objects.

#### Response Example
```typescript
// Example response structure (actual structure may vary based on BundleListResult definition)
{
  "bundles": [
    {
      "id": "bundle-123",
      "version": "1.0.0",
      "status": "active",
      "createdAt": "2023-10-27T10:00:00Z"
    },
    {
      "id": "builtin",
      "version": "1.0.0",
      "status": "active",
      "createdAt": "2023-10-27T09:00:00Z"
    }
  ]
}
```

### Throws
{Error} If the operation fails.
```

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

### Listen for Update Availability

Source: https://github.com/cap-go/capacitor-updater/wiki/Capacitor-updater-plugin

Listens for general update events, indicating that an update is ready to be installed upon the next app launch.

```typescript
addListener(eventName: 'updateAvailable', listenerFunc: UpdateAvailableListener) => Promise<PluginListenerHandle> & PluginListenerHandle
```

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

### Listen for Bundle Download Events

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Listen for bundle download events. This will return download progress during the download process. Use this to track download status.

```typescript
addListener(eventName: 'download', listenerFunc: (state: DownloadEvent) => void) => Promise<PluginListenerHandle>
```

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

### Get Failed Update Information

Source: https://github.com/cap-go/capacitor-updater/blob/main/api.md

Retrieve information about the most recent bundle that failed to load. The stored failure information is cleared after being retrieved once.

```typescript
getFailedUpdate() => Promise<UpdateFailedEvent | null>
```