@capawesome/capacitor-live-update 6.7.2 → 7.0.0-dev.1765885034

package/dist/esm/definitions.d.ts

@@ -1,8 +1,9 @@
+import type { PluginListenerHandle } from '@capacitor/core';
 declare module '@capacitor/cli' {
     interface PluginsConfig {
         LiveUpdate?: {
             /**
-             * The app ID is used to identify the app when using [Capawesome Cloud](https://capawesome.io/cloud).
+             * The app ID is used to identify the app when using [Capawesome Cloud](https://capawesome.io/cloud/).
              *
              * This is **NOT** the same as the app identifier (e.g. `com.example.app`).
              * This is a unique identifier generated by Capawesome Cloud (e.g. `6e351b4f-69a7-415e-a057-4567df7ffe94`).
@@ -11,6 +12,21 @@ declare module '@capacitor/cli' {
              * @example '6e351b4f-69a7-415e-a057-4567df7ffe94'
              */
             appId?: string;
+            /**
+             * Whether or not to automatically block bundles that have been rolled back.
+             *
+             * When enabled, the plugin will automatically block bundles that caused a rollback
+             * (up to 100 bundles). When the limit is reached, the oldest blocked bundle is unblocked.
+             * Blocked bundles will be skipped in future sync operations.
+             *
+             * **Attention**: This option has no effect if `readyTimeout` is set to `0`.
+             *
+             * Only available on Android and iOS.
+             *
+             * @since 7.3.0
+             * @default false
+             */
+            autoBlockRolledBackBundles?: boolean;
             /**
              * Whether or not to automatically delete unused bundles.
              *
@@ -20,6 +36,21 @@ declare module '@capacitor/cli' {
              * @default false
              */
             autoDeleteBundles?: boolean;
+            /**
+             * The auto-update strategy for live updates.
+             *
+             * - `none`: Live updates will not be applied automatically.
+             * - `background`: Live updates will be automatically downloaded
+             * and applied in the background at app startup and when the app resumes
+             * (if the last check was more than 15 minutes ago).
+             *
+             * Only available on Android and iOS.
+             *
+             * @since 7.3.0
+             * @default 'none'
+             * @example 'background'
+             */
+            autoUpdateStrategy?: 'none' | 'background';
             /**
              * The default channel of the app.
              *
@@ -27,13 +58,6 @@ declare module '@capacitor/cli' {
              * @example 'production'
              */
             defaultChannel?: string;
-            /**
-             * Whether or not the plugin is enabled.
-             *
-             * @since 5.0.0
-             * @default true
-             */
-            enabled?: boolean;
             /**
              * The timeout in milliseconds for HTTP requests.
              *
@@ -41,15 +65,6 @@ declare module '@capacitor/cli' {
              * @default 60000
              */
             httpTimeout?: number;
-            /**
-             * The location of the server to use when using [Capawesome Cloud](https://capawesome.io/cloud).
-             *
-             * @since 6.2.0
-             * @default 'us'
-             * @example 'eu'
-             * @deprecated This option will be removed in the future.
-             */
-            location?: 'us' | 'eu';
             /**
              * The public key to verify the integrity of the bundle.
              *
@@ -60,23 +75,44 @@ declare module '@capacitor/cli' {
              */
             publicKey?: string;
             /**
-             * The timeout in milliseconds to wait for the app to be ready before resetting to the default bundle.
+             * The timeout in milliseconds to wait for the app to be ready
+             * before resetting to the default bundle.
+             *
+             * It is strongly **recommended** to configure this option (e.g. `10000` ms)
+             * so that the plugin can roll back to the default bundle in case of problems.
+             * If configured, the plugin will wait for the app to call the `ready()`
+             * method before resetting to the default bundle.
+             *
+             * Set to `0` to disable the timeout.
              *
              * @since 5.0.0
-             * @default 10000
+             * @default 0
+             * @example 10000
              */
             readyTimeout?: number;
             /**
-             * Whether or not the app should be reset to the default bundle during an update.
+             * The API domain of the [Capawesome Cloud](https://cloud.capawesome.io) server **without** scheme or path.
              *
-             * @since 5.0.0
-             * @default true
+             * @since 7.0.0
+             * @default 'api.cloud.capawesome.io'
+             * @example 'api.cloud.capawesome.eu'
              */
-            resetOnUpdate?: boolean;
+            serverDomain?: string;
         };
     }
 }
 export interface LiveUpdatePlugin {
+    /**
+     * Clear all blocked bundles from the blocked list.
+     *
+     * This removes all bundle identifiers that were automatically blocked
+     * due to rollbacks when `autoBlockRolledBackBundles` is enabled.
+     *
+     * Only available on Android and iOS.
+     *
+     * @since 7.4.0
+     */
+    clearBlockedBundles(): Promise<void>;
     /**
      * Delete a bundle from the app.
      *
@@ -102,20 +138,23 @@ export interface LiveUpdatePlugin {
      */
     fetchLatestBundle(options?: FetchLatestBundleOptions): Promise<FetchLatestBundleResult>;
     /**
-     * Get the active bundle identifier.
+     * Get all blocked bundle identifiers.
+     *
+     * Returns the list of bundle identifiers that were automatically blocked
+     * due to rollbacks when `autoBlockRolledBackBundles` is enabled.
      *
      * Only available on Android and iOS.
      *
-     * @since 5.0.0
-     * @deprecated Use `getCurrentBundle()` instead.
+     * @since 7.4.0
      */
-    getBundle(): Promise<GetBundleResult>;
+    getBlockedBundles(): Promise<GetBlockedBundlesResult>;
     /**
      * Get all identifiers of bundles that have been downloaded.
      *
      * Only available on Android and iOS.
      *
      * @since 5.0.0
+     * @deprecated Use `getDownloadedBundles()` instead.
      */
     getBundles(): Promise<GetBundlesResult>;
     /**
@@ -126,6 +165,25 @@ export interface LiveUpdatePlugin {
      * @since 5.0.0
      */
     getChannel(): Promise<GetChannelResult>;
+    /**
+     * Get the runtime configuration.
+     *
+     * Returns the current plugin configuration including any runtime
+     * overrides set via `setConfig()`.
+     *
+     * Only available on Android and iOS.
+     *
+     * @since 7.4.0
+     */
+    getConfig(): Promise<GetConfigResult>;
+    /**
+     * Get all identifiers of bundles that have been downloaded.
+     *
+     * Only available on Android and iOS.
+     *
+     * @since 7.4.0
+     */
+    getDownloadedBundles(): Promise<GetDownloadedBundlesResult>;
     /**
      * Get the bundle identifier of the current bundle.
      * The current bundle is the bundle that is currently used by the app.
@@ -151,6 +209,14 @@ export interface LiveUpdatePlugin {
      * @since 5.0.0
      */
     getDeviceId(): Promise<GetDeviceIdResult>;
+    /**
+     * Check whether a sync operation is currently in progress.
+     *
+     * Only available on Android and iOS.
+     *
+     * @since 7.4.0
+     */
+    isSyncing(): Promise<IsSyncingResult>;
     /**
      * Get the bundle identifier of the next bundle.
      * The next bundle is the bundle that will be used after calling `reload()`
@@ -164,6 +230,9 @@ export interface LiveUpdatePlugin {
     /**
      * Get the version code of the app.
      *
+     * On **Android**, this is the `versionCode` from the `android/app/build.gradle` file.
+     * On **iOS**, this is the `CFBundleVersion` from the `Info.plist` file.
+     *
      * Only available on Android and iOS.
      *
      * @since 5.0.0
@@ -172,6 +241,9 @@ export interface LiveUpdatePlugin {
     /**
      * Get the version name of the app.
      *
+     * On **Android**, this is the `versionName` from the `android/app/build.gradle` file.
+     * On **iOS**, this is the `CFBundleShortVersionString` from the `Info.plist` file.
+     *
      * Only available on Android and iOS.
      *
      * @since 5.0.0
@@ -187,7 +259,7 @@ export interface LiveUpdatePlugin {
      *
      * @since 5.0.0
      */
-    ready(): Promise<void>;
+    ready(): Promise<ReadyResult>;
     /**
      * Reload the app to apply the new bundle.
      *
@@ -207,16 +279,16 @@ export interface LiveUpdatePlugin {
      */
     reset(): Promise<void>;
     /**
-     * Set the next bundle to use for the app.
+     * Reset the runtime configuration to the values from the Capacitor config file.
      *
-     * Call `reload()` or restart the app to apply the changes.
+     * This clears any runtime configuration set via `setConfig()`.
+     * The changes take effect immediately.
      *
      * Only available on Android and iOS.
      *
-     * @since 5.0.0
-     * @deprecated Use `setNextBundle()` instead.
+     * @since 7.4.0
      */
-    setBundle(options: SetBundleOptions): Promise<void>;
+    resetConfig(): Promise<void>;
     /**
      * Set the channel to use for the update.
      *
@@ -225,6 +297,21 @@ export interface LiveUpdatePlugin {
      * @since 5.0.0
      */
     setChannel(options: SetChannelOptions): Promise<void>;
+    /**
+     * Set the runtime configuration.
+     *
+     * This allows updating plugin configuration options at runtime.
+     * The changes are persisted across app restarts and take effect immediately.
+     *
+     * **Important:** Runtime configuration is automatically reset to default values
+     * whenever the native app is updated to a new version. This ensures that
+     * configuration from previous versions doesn't persist after an app update.
+     *
+     * Only available on Android and iOS.
+     *
+     * @since 7.4.0
+     */
+    setConfig(options: SetConfigOptions): Promise<void>;
     /**
      * Set the custom identifier of the device.
      *
@@ -253,6 +340,46 @@ export interface LiveUpdatePlugin {
      * @since 5.0.0
      */
     sync(options?: SyncOptions): Promise<SyncResult>;
+    /**
+     * Listen for the download progress of a bundle.
+     *
+     * Only available on Android and iOS.
+     *
+     * @since 7.0.0
+     */
+    addListener(eventName: 'downloadBundleProgress', listenerFunc: DownloadBundleProgressListener): Promise<PluginListenerHandle>;
+    /**
+     * Listen for when a bundle is set as the next bundle.
+     *
+     * This event is triggered whenever a bundle is set to be used on the next app restart,
+     * either through automatic updates or manual calls to `setNextBundle()`.
+     *
+     * Only available on Android and iOS.
+     *
+     * @since 7.3.0
+     */
+    addListener(eventName: 'nextBundleSet', listenerFunc: NextBundleSetListener): Promise<PluginListenerHandle>;
+    /**
+     * Listen for when the app is reloaded.
+     *
+     * This event is triggered after the `reload()` method is called
+     * and the app has been reloaded.
+     *
+     * **Note:** To verify whether an update was successfully applied after a reload,
+     * use the `ready()` method instead. The `ready()` method provides detailed information
+     * about the current bundle, previous bundle, and whether a rollback occurred.
+     *
+     * Only available on Android and iOS.
+     *
+     * @since 7.4.0
+     */
+    addListener(eventName: 'reloaded', listenerFunc: ReloadedListener): Promise<PluginListenerHandle>;
+    /**
+     * Remove all listeners for this plugin.
+     *
+     * @since 7.2.0
+     */
+    removeAllListeners(): Promise<void>;
 }
 /**
  * @since 5.0.0
@@ -278,19 +405,30 @@ export interface DownloadBundleOptions {
     /**
      * The unique identifier of the bundle.
      *
+     * **Attention**: The value `public` is reserved and cannot be used as a bundle identifier.
+     *
      * @since 5.0.0
      * @example '1.0.0'
      */
     bundleId: string;
     /**
-     * The checksum of the bundle to verify the integrity of the ZIP file.
+     * The checksum of the self-hosted bundle as a SHA-256 hash
+     * in base64 format to verify the integrity of the bundle.
      *
-     * Must be a SHA-256 hash in base64 format.
+     * **Attention**: Only supported for the `zip` artifact type.
      *
-     * @since 6.1.0
-     * @deprecated The server should return a `X-Checksum` header instead.
+     * @since 7.1.0
      */
     checksum?: string;
+    /**
+     * The signature of the self-hosted bundle as a signed SHA-256 hash
+     * in base64 format to verify the integrity of the bundle.
+     *
+     * **Attention**: Only supported for the `zip` artifact type.
+     *
+     * @since 7.1.0
+     */
+    signature?: string;
     /**
      * The URL of the bundle to download.
      *
@@ -300,10 +438,10 @@ export interface DownloadBundleOptions {
      * `https://example.com/download`, the plugin will download the file
      * with the href `index.html` from `https://example.com/download?href=index.html`.
      *
-     * To **verify the integrity** of the file, the server must return
+     * To **verify the integrity** of the file, the server should return
      * a `X-Checksum` header with the SHA-256 hash in base64 format.
      *
-     * To **verify the signature** of the file, the server must return
+     * To **verify the signature** of the file, the server should return
      * a `X-Signature` header with the signed SHA-256 hash in base64 format.
      *
      * @since 5.0.0
@@ -340,6 +478,24 @@ export interface FetchLatestBundleResult {
      * @since 6.6.0
      */
     bundleId: string | null;
+    /**
+     * The checksum of the latest bundle if the bundle is self-hosted.
+     *
+     * If the bundle is hosted on Capawesome Cloud, the checksum will be
+     * returned as response header when downloading the bundle.
+     *
+     * @since 7.1.0
+     */
+    checksum?: string;
+    /**
+     * Custom properties that are associated with the latest bundle.
+     *
+     * @since 7.0.0
+     * @example { "key": "value" }
+     */
+    customProperties?: {
+        [key: string]: string;
+    };
     /**
      * The URL of the latest bundle to download.
      * Pass this URL to the `downloadBundle(...)` method to download the bundle.
@@ -347,6 +503,15 @@ export interface FetchLatestBundleResult {
      * @since 6.7.0
      */
     downloadUrl?: string;
+    /**
+     * The signature of the latest bundle if the bundle is self-hosted.
+     *
+     * If the bundle is hosted on Capawesome Cloud, the signature will be
+     * returned as response header when downloading the bundle.
+     *
+     * @since 7.1.0
+     */
+    signature?: string;
 }
 /**
  * @since 5.0.0
@@ -362,6 +527,17 @@ export interface GetBundleResult {
      */
     bundleId: string | null;
 }
+/**
+ * @since 7.4.0
+ */
+export interface GetBlockedBundlesResult {
+    /**
+     * An array of unique identifiers of all blocked bundles.
+     *
+     * @since 7.4.0
+     */
+    bundleIds: string[];
+}
 /**
  * @since 5.0.0
  */
@@ -373,6 +549,17 @@ export interface GetBundlesResult {
      */
     bundleIds: string[];
 }
+/**
+ * @since 7.4.0
+ */
+export interface GetDownloadedBundlesResult {
+    /**
+     * An array of unique identifiers of all downloaded bundles.
+     *
+     * @since 7.4.0
+     */
+    bundleIds: string[];
+}
 /**
  * @since 5.0.0
  */
@@ -387,6 +574,27 @@ export interface GetChannelResult {
      */
     channel: string | null;
 }
+/**
+ * @since 7.4.0
+ */
+export interface GetConfigResult {
+    /**
+     * The app ID used to identify the app.
+     *
+     * If `null`, no app ID is configured.
+     *
+     * @since 7.4.0
+     * @example '6e351b4f-69a7-415e-a057-4567df7ffe94'
+     */
+    appId: string | null;
+    /**
+     * The auto-update strategy for live updates.
+     *
+     * @since 7.4.0
+     * @example 'background'
+     */
+    autoUpdateStrategy: 'none' | 'background';
+}
 /**
  * @since 6.7.0
  */
@@ -416,6 +624,17 @@ export interface GetDeviceIdResult {
      */
     deviceId: string;
 }
+/**
+ * @since 7.4.0
+ */
+export interface IsSyncingResult {
+    /**
+     * Whether a sync operation is currently in progress.
+     *
+     * @since 7.4.0
+     */
+    syncing: boolean;
+}
 /**
  * @since 6.7.0
  */
@@ -473,6 +692,33 @@ export interface GetCustomIdResult {
      */
     customId: string | null;
 }
+/**
+ * @since 7.0.0
+ */
+export interface ReadyResult {
+    /**
+     * The identifier of the previous bundle used.
+     *
+     * If `null`, the default bundle was used.
+     *
+     * @since 7.0.0
+     */
+    previousBundleId: string | null;
+    /**
+     * The identifier of the current bundle used.
+     *
+     * If `null`, the default bundle is being used.
+     *
+     * @since 7.0.0
+     */
+    currentBundleId: string | null;
+    /**
+     * Whether or not the app was reset to the default bundle.
+     *
+     * @since 7.0.0
+     */
+    rollback: boolean;
+}
 /**
  * @since 5.0.0
  */
@@ -498,6 +744,20 @@ export interface SetChannelOptions {
      */
     channel: string | null;
 }
+/**
+ * @since 7.4.0
+ */
+export interface SetConfigOptions {
+    /**
+     * The app ID used to identify the app.
+     *
+     * Set `null` to reset to the value from the Capacitor config file.
+     *
+     * @since 7.4.0
+     * @example '6e351b4f-69a7-415e-a057-4567df7ffe94'
+     */
+    appId?: string | null;
+}
 /**
  * @since 5.0.0
  */
@@ -549,3 +809,69 @@ export interface SyncResult {
      */
     nextBundleId: string | null;
 }
+/**
+ * Listener for the download progress of a bundle.
+ *
+ * @since 7.0.0
+ */
+export type DownloadBundleProgressListener = (event: DownloadBundleProgressEvent) => void;
+/**
+ * Event that is triggered when the download progress of a bundle changes.
+ *
+ * @since 7.0.0
+ */
+export interface DownloadBundleProgressEvent {
+    /**
+     * The unique identifier of the bundle that is being downloaded.
+     *
+     * @since 7.0.0
+     */
+    bundleId: string;
+    /**
+     * The number of bytes that have been downloaded.
+     *
+     * @since 7.0.0
+     */
+    downloadedBytes: number;
+    /**
+     * The progress of the download in percent as a value between `0` and `1`.
+     *
+     * @since 7.0.0
+     * @example 0.5
+     */
+    progress: number;
+    /**
+     * The total number of bytes to download.
+     *
+     * @since 7.0.0
+     */
+    totalBytes: number;
+}
+/**
+ * Listener for when a bundle is set as the next bundle.
+ *
+ * @since 7.3.0
+ */
+export type NextBundleSetListener = (event: NextBundleSetEvent) => void;
+/**
+ * Event that is triggered when a bundle is set as the next bundle.
+ *
+ * @since 7.3.0
+ */
+export interface NextBundleSetEvent {
+    /**
+     * The unique identifier of the bundle that is set as the next bundle.
+     *
+     * If `null`, the default bundle will be used.
+     *
+     * @since 7.3.0
+     * @example '1.0.0'
+     */
+    bundleId: string | null;
+}
+/**
+ * Listener for when the app is reloaded.
+ *
+ * @since 7.4.0
+ */
+export type ReloadedListener = () => void;