@capgo/capacitor-updater 5.50.2 → 5.51.15

package/dist/docs.json

@@ -156,7 +156,7 @@
             "text": "{Error} If the download fails or the bundle is invalid."
           }
         ],
-        "docs": "Download a new bundle from the provided URL for later installation.\n\nThe downloaded bundle is stored locally but not activated. To use it:\n- Call {@link next} to set it for installation on next app backgrounding/restart\n- Call {@link set} to activate it immediately (destroys current JavaScript context)\n\nThe URL should point to a zip file containing either:\n- Your app files directly in the zip root, or\n- A single folder containing all your app files\n\nThe bundle must include an `index.html` file at the root level.\n\nFor encrypted bundles, provide the `sessionKey` and `checksum` parameters.\nFor multi-file delta updates, provide the `manifest` array.\n\n**Android Background Runner note:** `@capacitor/background-runner` loads its\nconfigured runner script from native APK assets. Live updates cannot replace\nthat runner script. Keep it stable across OTA updates and ship a native app\nupdate when the runner code changes.",
+        "docs": "Download a new bundle from the provided URL for later installation.\n\nThe downloaded bundle is stored locally but not activated. To use it:\n- Call {@link next} to set it for installation on next app backgrounding/restart\n- Call {@link set} to activate it immediately (destroys current JavaScript context)\n\nThe URL should point to a zip file containing either:\n- Your app files directly in the zip root, or\n- A single folder containing all your app files\n\nThe bundle must include an `index.html` file at the root level.\n\nFor encrypted bundles, provide the `sessionKey` and `checksum` parameters.\nFor multi-file delta updates, provide the `manifest` array.\n\n**Android Background Runner note:** `@capacitor/background-runner` loads its\nconfigured runner script from native APK assets. Live updates cannot replace\nthat runner script. Keep it stable across OTA updates and ship a native app\nupdate when the runner code changes. When a bundle switch happens, Capacitor\nUpdater cancels and reschedules configured Background Runner WorkManager jobs\nand syncs the bundled runner script into native `public/` storage when present.",
         "complexTypes": [
           "BundleInfo",
           "DownloadOptions"
@@ -846,7 +846,7 @@
             "text": "4.7.0"
           }
         ],
-        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the\nselected channel locally on the device. It does not create or update a backend Device Override,\nso the device will not appear as overridden in the Capgo dashboard. Only assignments created\nfrom the dashboard or the Public API are shown in the Device Override UI.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\n**Important: Listen for the `channelPrivate` event**\n\nWhen a user attempts to set a channel that doesn't allow device self-assignment, the method will\nthrow an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event\nto provide appropriate feedback to users:\n\n```typescript\nCapacitorUpdater.addListener('channelPrivate', (data) => {\n  console.warn(`Cannot access channel \"${data.channel}\": ${data.message}`);\n  // Show user-friendly message\n});\n```\n\nThis sends a request to the Capgo backend to validate the specified channel, then stores the\nchannel locally on the device.",
+        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the\nselected channel locally on the device for future app restarts. It does not create or update\na backend Device Override, so the device will not appear as overridden in the Capgo dashboard.\nOnly assignments created from the dashboard or the Public API are shown in the Device Override UI.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\n**Important: Listen for the `channelPrivate` event**\n\nWhen a user attempts to set a channel that doesn't allow device self-assignment, the method will\nthrow an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event\nto provide appropriate feedback to users:\n\n```typescript\nCapacitorUpdater.addListener('channelPrivate', (data) => {\n  console.warn(`Cannot access channel \"${data.channel}\": ${data.message}`);\n  // Show user-friendly message\n});\n```\n\nThis sends a request to the Capgo backend to validate the specified channel, then stores the\nchannel locally on the device for future app restarts.",
         "complexTypes": [
           "ChannelRes",
           "SetChannelOptions"
@@ -911,7 +911,7 @@
             "text": "4.8.0"
           }
         ],
-        "docs": "Get the current channel assigned to this device.\n\nReturns information about:\n- `channel`: The currently assigned channel name (if any)\n- `allowSet`: Whether the channel allows self-assignment\n- `status`: Operation status\n- `error`/`message`: Additional information (if applicable)\n\nUse this to:\n- Display current channel to users (e.g., \"You're on the Beta channel\")\n- Check if a device is on a specific channel before showing features\n- Verify channel assignment after calling {@link setChannel}\n\nOn native platforms, a successful response also refreshes the locally persisted\ndefault channel used by update checks.",
+        "docs": "Get the current channel assigned to this device.\n\nReturns information about:\n- `channel`: The currently assigned channel name (if any)\n- `allowSet`: Whether the channel allows self-assignment\n- `status`: Operation status\n- `error`/`message`: Additional information (if applicable)\n\nUse this to:\n- Display current channel to users (e.g., \"You're on the Beta channel\")\n- Check if a device is on a specific channel before showing features\n- Verify channel assignment after calling {@link setChannel}\n\nOn native platforms, a successful response also refreshes the default channel used by update checks.\nThis refresh is persisted across app restarts.",
         "complexTypes": [
           "GetChannelRes"
         ],
@@ -4468,6 +4468,14 @@
         {
           "text": "'downloading'",
           "complexTypes": []
+        },
+        {
+          "text": "'deleted'",
+          "complexTypes": []
+        },
+        {
+          "text": "'deleting'",
+          "complexTypes": []
         }
       ]
     },
@@ -4575,7 +4583,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure the number of seconds the native plugin should wait before considering API timeout.\n\nOnly available for Android and iOS.",
+          "docs": "Configure the number of seconds the native plugin should wait before considering an HTTP timeout.\nApplies to update checks and file downloads. On Android these are idle connect/read/write\ntimeouts and do not cap total download time; on iOS the request timeout also bounds the\ntotal download duration.\n\nOnly available for Android and iOS.",
           "complexTypes": [],
           "type": "number | undefined"
         },
@@ -4623,7 +4631,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure how the plugin checks for, downloads, and applies live updates.\n\nThe plugin checks for updates when the app moves to the foreground and, if\n{@link periodCheckDelay} is set, on a repeating timer while the app stays open.\n\nBoolean values keep their existing behavior:\n- `true`: Same as `\"atBackground\"`.\n- `false`: Same as `\"off\"`.\n\nString values merge the previous Auto Update and Direct Update configuration:\n- `\"off\"`: Disable automatic update checks.\n- `\"atBackground\"`: Check and download automatically on each foreground check, then apply the update the next time the app moves to background.\n- `\"atInstall\"`: Apply immediately only after a fresh install or native app store update; otherwise use `\"atBackground\"` behavior.\n- `\"onLaunch\"`: Apply immediately only when the app is brought to the foreground from a killed state (cold start). After that first check, fall back to `\"atBackground\"` behavior.\n- `\"always\"`: Check on every foreground transition and apply immediately whenever an update is available.\n- `\"onlyDownload\"`: Check and download automatically, emit `updateAvailable`, and never set the next bundle or apply an update automatically.\n\nOnly available for Android and iOS.",
+          "docs": "Configure how the plugin checks for, downloads, and applies live updates.\n\nThe plugin checks for updates when the app moves to the foreground. When\n{@link periodCheckDelay} is greater than 0, it also checks on a repeating timer\nwhile the app stays open.\n\nBoolean values keep their existing behavior:\n- `true`: Same as `\"atBackground\"`.\n- `false`: Same as `\"off\"`.\n\nString values merge the previous Auto Update and Direct Update configuration:\n- `\"off\"`: Disable automatic update checks.\n- `\"atBackground\"`: Check and download automatically on each foreground check, then apply the update the next time the app moves to background.\n- `\"atInstall\"`: Apply immediately only after a fresh install or native app store update; otherwise use `\"atBackground\"` behavior.\n- `\"onLaunch\"`: Apply immediately only when the app is brought to the foreground from a killed state (cold start). After that first check, fall back to `\"atBackground\"` behavior.\n- `\"always\"`: Check on every foreground transition and apply immediately whenever an update is available.\n- `\"onlyDownload\"`: Check and download automatically, emit `updateAvailable`, and never set the next bundle or apply an update automatically.\n\nOnly available for Android and iOS.",
           "complexTypes": [],
           "type": "boolean | 'always' | 'off' | 'atBackground' | 'atInstall' | 'onLaunch' | 'onlyDownload' | undefined"
         },
@@ -4687,7 +4695,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure the URL / endpoint to which update statistics are sent.\n\nOnly available for Android and iOS. Set to \"\" to disable stats reporting.\nNative stats include update lifecycle events, app health signals such as crashes,\nAndroid ANRs, low-memory exits, iOS memory warnings, and WebView health signals\nsuch as JavaScript errors, unhandled promise rejections, resource load failures,\nWebView renderer exits, and unclean WebView restarts when available.",
+          "docs": "Configure the URL / endpoint to which update statistics are sent.\n\nOnly available for Android and iOS. Set to \"\" to disable stats reporting.\nNative stats include update lifecycle events, app health signals such as crashes,\nAndroid ANRs, low-memory exits, iOS memory warnings, and WebView health signals\nsuch as JavaScript errors, unhandled promise rejections, resource load failures,\nWebView renderer exits, unclean WebView restarts, app launch readiness timing,\nand WebView load milestones when available.",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -4727,7 +4735,7 @@
           "name": "directUpdate",
           "tags": [
             {
-              "text": "Use {@link PluginsConfig.CapacitorUpdater.autoUpdate} string modes instead.\nWorks well for apps less than 10MB and with uploads done using --delta flag.\nZip or apps more than 10MB will be relatively slow for users to update.\n- false: Never do direct updates (use default behavior: download on foreground check, apply when backgrounded)\n- atInstall: Direct update only after app install or native app store update, otherwise act as directUpdate = false\n- onLaunch: Direct update only when the app is brought to the foreground from a killed state, otherwise act as directUpdate = false\n- always: Direct update on every foreground check whenever an update is available, never act as directUpdate = false\n- true: (deprecated) Same as \"always\" for backward compatibility\n\nActivate this flag will automatically make the CLI upload delta in CICD envs and will ask for confirmation in local uploads.\nOnly available for Android and iOS.",
+              "text": "Use {@link PluginsConfig.CapacitorUpdater.autoUpdate} string modes instead.\nWorks well for apps less than 10MB and with uploads done using --delta flag.\nZip or apps more than 10MB will be relatively slow for users to update.\n- false: Never do direct updates\n- atInstall: Same as `\"atInstall\"` for {@link autoUpdate}\n- onLaunch: Same as `\"onLaunch\"` for {@link autoUpdate}\n- always: Same as `\"always\"` for {@link autoUpdate}\n- true: (deprecated) Same as \"always\" for backward compatibility\n\nActivate this flag will automatically make the CLI upload delta in CICD envs and will ask for confirmation in local uploads.\nOnly available for Android and iOS.",
               "name": "deprecated"
             },
             {
@@ -4807,7 +4815,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure the delay period for period update check. the unit is in seconds.\n\nOnly available for Android and iOS.\nCannot be less than 600 seconds (10 minutes).",
+          "docs": "Configure the interval in seconds for repeating update checks while the app stays open.\nForeground checks still run when this is 0. Values below 600 are normalized to 600.\n\nOnly available for Android and iOS.\nCannot be less than 600 seconds (10 minutes).",
           "complexTypes": [],
           "type": "number | undefined"
         },
@@ -5035,6 +5043,22 @@
           "complexTypes": [],
           "type": "boolean | undefined"
         },
+        {
+          "name": "persistDefaultChannelOnReinstall",
+          "tags": [
+            {
+              "text": "true",
+              "name": "default"
+            },
+            {
+              "text": "8.51.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Keep the default channel stored by {@link CapacitorUpdaterPlugin.setChannel} or refreshed by\n{@link CapacitorUpdaterPlugin.getChannel} when app data is restored into a new app install.\n\n`setChannel()` and a successful `getChannel()` still persist the selected channel across app\nrestarts. When this option is `false`, native startup clears that persisted channel when it\ndetects app data restored into a new installation. Native build cleanup clears the persisted\nchannel only when `persistDefaultChannelOnReinstall` is `false`, `resetWhenUpdate` is `true`,\nand the native build version has changed.\n\nOnly available for Android and iOS.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
         {
           "name": "defaultChannel",
           "tags": [

package/dist/esm/definitions.d.ts

@@ -15,7 +15,10 @@ declare module '@capacitor/cli' {
              */
             appReadyTimeout?: number;
             /**
-             * Configure the number of seconds the native plugin should wait before considering API timeout.
+             * Configure the number of seconds the native plugin should wait before considering an HTTP timeout.
+             * Applies to update checks and file downloads. On Android these are idle connect/read/write
+             * timeouts and do not cap total download time; on iOS the request timeout also bounds the
+             * total download duration.
              *
              * Only available for Android and iOS.
              *
@@ -44,8 +47,9 @@ declare module '@capacitor/cli' {
             /**
              * Configure how the plugin checks for, downloads, and applies live updates.
              *
-             * The plugin checks for updates when the app moves to the foreground and, if
-             * {@link periodCheckDelay} is set, on a repeating timer while the app stays open.
+             * The plugin checks for updates when the app moves to the foreground. When
+             * {@link periodCheckDelay} is greater than 0, it also checks on a repeating timer
+             * while the app stays open.
              *
              * Boolean values keep their existing behavior:
              * - `true`: Same as `"atBackground"`.
@@ -99,7 +103,8 @@ declare module '@capacitor/cli' {
              * Native stats include update lifecycle events, app health signals such as crashes,
              * Android ANRs, low-memory exits, iOS memory warnings, and WebView health signals
              * such as JavaScript errors, unhandled promise rejections, resource load failures,
-             * WebView renderer exits, and unclean WebView restarts when available.
+             * WebView renderer exits, unclean WebView restarts, app launch readiness timing,
+             * and WebView load milestones when available.
              *
              * @default https://plugin.capgo.app/stats
              * @example https://example.com/api/stats
@@ -130,10 +135,10 @@ declare module '@capacitor/cli' {
              * @deprecated Use {@link PluginsConfig.CapacitorUpdater.autoUpdate} string modes instead.
              * Works well for apps less than 10MB and with uploads done using --delta flag.
              * Zip or apps more than 10MB will be relatively slow for users to update.
-             * - false: Never do direct updates (use default behavior: download on foreground check, apply when backgrounded)
-             * - atInstall: Direct update only after app install or native app store update, otherwise act as directUpdate = false
-             * - onLaunch: Direct update only when the app is brought to the foreground from a killed state, otherwise act as directUpdate = false
-             * - always: Direct update on every foreground check whenever an update is available, never act as directUpdate = false
+             * - false: Never do direct updates
+             * - atInstall: Same as `"atInstall"` for {@link autoUpdate}
+             * - onLaunch: Same as `"onLaunch"` for {@link autoUpdate}
+             * - always: Same as `"always"` for {@link autoUpdate}
              * - true: (deprecated) Same as "always" for backward compatibility
              *
              * Activate this flag will automatically make the CLI upload delta in CICD envs and will ask for confirmation in local uploads.
@@ -181,7 +186,8 @@ declare module '@capacitor/cli' {
              */
             autoSplashscreenTimeout?: number;
             /**
-             * Configure the delay period for period update check. the unit is in seconds.
+             * Configure the interval in seconds for repeating update checks while the app stays open.
+             * Foreground checks still run when this is 0. Values below 600 are normalized to 600.
              *
              * Only available for Android and iOS.
              * Cannot be less than 600 seconds (10 minutes).
@@ -308,6 +314,22 @@ declare module '@capacitor/cli' {
              * @since 7.34.0
              */
             allowSetDefaultChannel?: boolean;
+            /**
+             * Keep the default channel stored by {@link CapacitorUpdaterPlugin.setChannel} or refreshed by
+             * {@link CapacitorUpdaterPlugin.getChannel} when app data is restored into a new app install.
+             *
+             * `setChannel()` and a successful `getChannel()` still persist the selected channel across app
+             * restarts. When this option is `false`, native startup clears that persisted channel when it
+             * detects app data restored into a new installation. Native build cleanup clears the persisted
+             * channel only when `persistDefaultChannelOnReinstall` is `false`, `resetWhenUpdate` is `true`,
+             * and the native build version has changed.
+             *
+             * Only available for Android and iOS.
+             *
+             * @default true
+             * @since 8.51.0
+             */
+            persistDefaultChannelOnReinstall?: boolean;
             /**
              * Set the default channel for the app in the config. Case sensitive.
              * This will setting will override the default channel set in the cloud, but will still respect overrides made in the cloud.
@@ -485,7 +507,9 @@ export interface CapacitorUpdaterPlugin {
      * **Android Background Runner note:** `@capacitor/background-runner` loads its
      * configured runner script from native APK assets. Live updates cannot replace
      * that runner script. Keep it stable across OTA updates and ship a native app
-     * update when the runner code changes.
+     * update when the runner code changes. When a bundle switch happens, Capacitor
+     * Updater cancels and reschedules configured Background Runner WorkManager jobs
+     * and syncs the bundled runner script into native `public/` storage when present.
      *
      * @example
      * const bundle = await CapacitorUpdater.download({
@@ -942,9 +966,9 @@ export interface CapacitorUpdaterPlugin {
      * (e.g., "production", "beta", "staging"). This method switches the device to a new channel.
      *
      * **Device Override UI:** `setChannel()` validates the channel with the backend, then stores the
-     * selected channel locally on the device. It does not create or update a backend Device Override,
-     * so the device will not appear as overridden in the Capgo dashboard. Only assignments created
-     * from the dashboard or the Public API are shown in the Device Override UI.
+     * selected channel locally on the device for future app restarts. It does not create or update
+     * a backend Device Override, so the device will not appear as overridden in the Capgo dashboard.
+     * Only assignments created from the dashboard or the Public API are shown in the Device Override UI.
      *
      * **Requirements:**
      * - The target channel must allow self-assignment (configured in your Capgo dashboard or backend)
@@ -973,7 +997,7 @@ export interface CapacitorUpdaterPlugin {
      * ```
      *
      * This sends a request to the Capgo backend to validate the specified channel, then stores the
-     * channel locally on the device.
+     * channel locally on the device for future app restarts.
      *
      * @param options The {@link SetChannelOptions} containing the channel name and optional auto-update trigger.
      * @returns {Promise<ChannelRes>} Channel operation result with status and optional error/message.
@@ -1014,8 +1038,8 @@ export interface CapacitorUpdaterPlugin {
      * - Check if a device is on a specific channel before showing features
      * - Verify channel assignment after calling {@link setChannel}
      *
-     * On native platforms, a successful response also refreshes the locally persisted
-     * default channel used by update checks.
+     * On native platforms, a successful response also refreshes the default channel used by update checks.
+     * This refresh is persisted across app restarts.
      *
      * @returns {Promise<GetChannelRes>} The current channel information.
      * @throws {Error} If the operation fails.
@@ -1599,7 +1623,7 @@ export interface CapacitorUpdaterPlugin {
  * success: The bundle has been downloaded and is ready to be **SET** as the next bundle.
  * error: The bundle has failed to download.
  */
-export type BundleStatus = 'success' | 'error' | 'pending' | 'downloading';
+export type BundleStatus = 'success' | 'error' | 'pending' | 'downloading' | 'deleted' | 'deleting';
 export type DelayUntilNext = 'background' | 'kill' | 'nativeVersion' | 'date';
 /**
  * Classification for update-check responses that do not provide a downloadable bundle.