@capgo/capacitor-updater 7.43.3 → 7.50.1

package/dist/esm/definitions.d.ts

@@ -42,14 +42,29 @@ declare module '@capacitor/cli' {
              */
             autoDeletePrevious?: boolean;
             /**
-             * Configure whether the plugin should use Auto Update via an update server.
+             * 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.
+             *
+             * Boolean values keep their existing behavior:
+             * - `true`: Same as `"atBackground"`.
+             * - `false`: Same as `"off"`.
+             *
+             * String values merge the previous Auto Update and Direct Update configuration:
+             * - `"off"`: Disable automatic update checks.
+             * - `"atBackground"`: Check and download automatically on each foreground check, then apply the update the next time the app moves to background.
+             * - `"atInstall"`: Apply immediately only after a fresh install or native app store update; otherwise use `"atBackground"` behavior.
+             * - `"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.
+             * - `"always"`: Check on every foreground transition and apply immediately whenever an update is available.
+             * - `"onlyDownload"`: Check and download automatically, emit `updateAvailable`, and never set the next bundle or apply an update automatically.
              *
              * Only available for Android and iOS.
              *
              * @default true
-             * @example false
+             * @example "onlyDownload"
              */
-            autoUpdate?: boolean;
+            autoUpdate?: boolean | 'off' | 'atBackground' | 'atInstall' | 'onLaunch' | 'always' | 'onlyDownload';
             /**
              * Automatically delete previous downloaded bundles when a newer native app bundle is installed to the device.
              * Setting this to false can broke the auto update flow if the user download from the store a native app bundle that is older than the current downloaded bundle. Upload will be prevented by channel setting downgrade_under_native.
@@ -81,6 +96,10 @@ declare module '@capacitor/cli' {
              * Configure the URL / endpoint to which update statistics are sent.
              *
              * Only available for Android and iOS. Set to "" to disable stats reporting.
+             * 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.
              *
              * @default https://plugin.capgo.app/stats
              * @example https://example.com/api/stats
@@ -107,12 +126,14 @@ declare module '@capacitor/cli' {
             version?: string;
             /**
              * Configure when the plugin should direct install updates. Only for autoUpdate mode.
+             *
+             * @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 at start, set when backgrounded)
-             * - atInstall: Direct update only when app is installed, updated from store, otherwise act as directUpdate = false
-             * - onLaunch: Direct update only on app installed, updated from store or after app kill, otherwise act as directUpdate = false
-             * - always: Direct update in all previous cases (app installed, updated from store, after app kill or app resume), never act as directUpdate = false
+             * - 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
              * - 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.
@@ -125,9 +146,9 @@ declare module '@capacitor/cli' {
             /**
              * Automatically handle splashscreen hiding when using directUpdate. When enabled, the plugin will automatically hide the splashscreen after updates are applied or when no update is needed.
              * This removes the need to manually listen for appReady events and call SplashScreen.hide().
-             * Only works when directUpdate is set to "atInstall", "always", "onLaunch", or true.
+             * Only works when autoUpdate is set to "atInstall", "always", or "onLaunch", or when the deprecated directUpdate option is set to "atInstall", "always", "onLaunch", or true.
              * Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false.
-             * Requires autoUpdate and directUpdate to be enabled.
+             * Requires Auto Update and Direct Update behavior to be enabled.
              *
              * Only available for Android and iOS.
              *
@@ -250,6 +271,16 @@ declare module '@capacitor/cli' {
              * @since 7.20.0
              */
             allowManualBundleError?: boolean;
+            /**
+             * Allow JavaScript to start a native preview session and temporarily request updates for another app id.
+             * This is intended for trusted container apps that implement Expo Go-style preview flows.
+             *
+             * Only available for Android and iOS.
+             *
+             * @default false
+             * @since 8.47.0
+             */
+            allowPreview?: boolean;
             /**
              * Persist the customId set through {@link CapacitorUpdaterPlugin.setCustomId} across app restarts.
              *
@@ -324,19 +355,30 @@ declare module '@capacitor/cli' {
              */
             osLogging?: boolean;
             /**
-             * Enable shake gesture to show update menu for debugging/testing purposes
+             * Enable the native preview menu gesture while a preview session is active.
+             * Outside preview sessions this preview menu is ignored, unless
+             * {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is enabled.
              *
              * @default false
              * @since  7.5.0
              */
             shakeMenu?: boolean;
             /**
-             * Enable the shake gesture to show a channel selector menu for switching between update channels.
-             * When enabled AND `shakeMenu` is true, the shake gesture shows a channel selector
-             * instead of the default debug menu (Go Home/Reload/Close).
+             * Choose which native gesture opens the preview/channel menu.
+             * This applies to both {@link PluginsConfig.CapacitorUpdater.shakeMenu}
+             * and {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
+             *
+             * Only available for Android and iOS.
              *
-             * After selecting a channel, the app automatically checks for updates and downloads if available.
-             * Only works if channels have `allow_self_set` enabled on the backend.
+             * @default 'shake'
+             * @since  8.48.0
+             */
+            shakeMenuGesture?: ShakeMenuGesture;
+            /**
+             * Enable the native menu gesture to show a channel selector menu for switching between update channels.
+             * If {@link PluginsConfig.CapacitorUpdater.shakeMenu} is also enabled while a preview session is active,
+             * the shake menu includes both preview actions and channel switching.
+             * The native gesture can be changed with {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.
              *
              * Only available for Android and iOS.
              *
@@ -440,6 +482,11 @@ export interface CapacitorUpdaterPlugin {
      * For encrypted bundles, provide the `sessionKey` and `checksum` parameters.
      * For multi-file delta updates, provide the `manifest` array.
      *
+     * **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.
+     *
      * @example
      * const bundle = await CapacitorUpdater.download({
      *   url: `https://example.com/versions/${version}/dist.zip`,
@@ -496,6 +543,102 @@ export interface CapacitorUpdaterPlugin {
      * @throws {Error} When there is no index.html file inside the bundle folder.
      */
     set(options: BundleId): Promise<void>;
+    /**
+     * 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.
+     * Use {@link listPreviews}, {@link setPreview}, {@link resetPreview},
+     * {@link deletePreview}, {@link checkPreviewUpdate}, and
+     * {@link updatePreview} to manage saved local previews.
+     *
+     * @param options Optional preview session options.
+     * @returns {Promise<void>} Resolves when preview session state is prepared.
+     * @since 8.47.0
+     */
+    startPreviewSession(options?: StartPreviewSessionOptions): Promise<void>;
+    /**
+     * Get every locally available preview bundle that was registered by
+     * {@link startPreviewSession} and later applied with {@link set}.
+     *
+     * This only returns previews whose bundles are still available locally. It is
+     * safe to show this in a preview switcher or native debug menu.
+     *
+     * @returns {Promise<PreviewListResult>} Locally available previews and current preview state.
+     * @throws {Error} If preview sessions are not enabled by config.
+     * @since 8.49.0
+     */
+    listPreviews(): Promise<PreviewListResult>;
+    /**
+     * Switch to a locally available preview bundle and reload the WebView.
+     *
+     * If the app is not already in a preview session, the current live bundle is
+     * saved as the fallback so {@link resetPreview} or the native shake menu can
+     * return to it later.
+     *
+     * @param options A {@link BundleId} object containing the preview bundle ID.
+     * @returns {Promise<void>} Resolves once the preview switch is staged.
+     * @throws {Error} If preview sessions are disabled or the preview is not available locally.
+     * @since 8.49.0
+     */
+    setPreview(options: BundleId): Promise<void>;
+    /**
+     * Leave the active preview session and reload the saved live bundle.
+     *
+     * This does not delete any saved previews. Use {@link deletePreview} to remove
+     * a preview from local storage.
+     *
+     * @returns {Promise<void>} Resolves once the live bundle reload is staged.
+     * @throws {Error} If there is no preview fallback bundle available.
+     * @since 8.49.0
+     */
+    resetPreview(): Promise<void>;
+    /**
+     * Delete a locally saved preview and its bundle when possible.
+     *
+     * Active previews cannot be deleted until you switch away from them or call
+     * {@link resetPreview}. If only the preview metadata can be removed, the
+     * method still resolves with `deleted: false`.
+     *
+     * @param options A {@link BundleId} object containing the preview bundle ID.
+     * @returns {Promise<DeletePreviewResult>} Whether the underlying bundle was deleted.
+     * @throws {Error} If preview sessions are disabled.
+     * @since 8.49.0
+     */
+    deletePreview(options: BundleId): Promise<DeletePreviewResult>;
+    /**
+     * Check whether a saved preview's payload URL points to a newer preview bundle.
+     *
+     * Only previews started with a `payloadUrl` can be checked natively. Direct URL
+     * previews can still be switched or deleted locally, but the updater does not
+     * know where to check for newer versions.
+     *
+     * @param options A {@link BundleId} object containing the preview bundle ID.
+     * @returns {Promise<PreviewUpdateResult>} Update status for the preview.
+     * @throws {Error} If preview sessions are disabled or the preview has no payload URL.
+     * @since 8.49.0
+     */
+    checkPreviewUpdate(options: BundleId): Promise<PreviewUpdateResult>;
+    /**
+     * Download the newest bundle for a saved preview payload URL.
+     *
+     * If the preview being updated is active, the new bundle is applied and the
+     * WebView reloads. Otherwise, the saved preview entry is moved to the newly
+     * downloaded bundle and can be selected later with {@link setPreview}.
+     *
+     * @param options A {@link BundleId} object containing the preview bundle ID.
+     * @returns {Promise<PreviewUpdateResult>} The update result and saved preview metadata.
+     * @throws {Error} If preview sessions are disabled or the preview cannot be updated.
+     * @since 8.49.0
+     */
+    updatePreview(options: BundleId): Promise<PreviewUpdateResult>;
     /**
      * Delete a bundle from local storage to free up disk space.
      *
@@ -568,7 +711,10 @@ export interface CapacitorUpdaterPlugin {
      * - Testing rollback functionality
      * - Providing users a "reset to factory" option
      *
-     * @param options {@link ResetOptions} to control reset behavior. If `toLastSuccessful` is `false` (or omitted), resets to builtin. If `true`, resets to last successful bundle.
+     * @param options {@link ResetOptions} to control reset behavior.
+     * If `toLastSuccessful` is `false` (or omitted), resets to builtin.
+     * If `true`, resets to last successful bundle.
+     * If `usePendingBundle` is `true`, applies the pending bundle set via {@link next} and clears it.
      * @returns {Promise<void>} A promise that may never resolve because the app will be reloaded.
      * @throws {Error} If the reset operation fails.
      */
@@ -674,6 +820,26 @@ export interface CapacitorUpdaterPlugin {
      * @since 4.0.0
      */
     cancelDelay(): Promise<void>;
+    /**
+     * Trigger the native auto-update check/download pipeline immediately.
+     *
+     * This starts the same background update flow used when the app moves to the
+     * foreground with auto-update enabled. It is useful for native integrations
+     * such as a silent push notification asking the app to check for a Capgo
+     * bundle without reimplementing the update protocol in JavaScript.
+     *
+     * The promise resolves after the native background work has been queued, not
+     * after the update has been downloaded or installed. Listen to updater events
+     * such as `updateAvailable`, `downloadComplete`, `downloadFailed`, and
+     * `noNeedUpdate` for the final result.
+     *
+     * Native support is available on iOS and Android. On Web, this method returns
+     * a result with `status: 'unavailable'`. Native platforms also return
+     * `unavailable` when the native auto-update system is disabled.
+     *
+     * @returns {Promise<TriggerUpdateCheckResult>} Whether a native update check was queued.
+     */
+    triggerUpdateCheck(): Promise<TriggerUpdateCheckResult>;
     /**
      * Check the update server for the latest available bundle version.
      *
@@ -692,27 +858,23 @@ export interface CapacitorUpdaterPlugin {
      * 2. Download it using {@link download}
      * 3. Apply it using {@link next} or {@link set}
      *
-     * **Important: Error handling for "no new version available"**
+     * **Important: Handling "no new version available"**
      *
      * When the device's current version matches the latest version on the server (i.e., the device is already
      * up-to-date), the server returns a 200 response with `error: "no_new_version_available"` and
-     * `message: "No new version available"`. **This causes `getLatest()` to throw an error**, even though
-     * this is a normal, expected condition.
+     * `message: "No new version available"`. This is a normal, expected condition and resolves with
+     * `kind: "up_to_date"` when the backend provides that classification.
      *
-     * You should catch this specific error to handle it gracefully:
+     * You should check `kind` and `error` before attempting to download:
      *
      * ```typescript
-     * try {
-     *   const latest = await CapacitorUpdater.getLatest();
+     * const latest = await CapacitorUpdater.getLatest();
+     * if (latest.kind === 'up_to_date') {
+     *   console.log('Already up to date');
+     * } else if (latest.kind === 'blocked') {
+     *   console.log('Update is blocked:', latest.error);
+     * } else if (latest.url) {
      *   // New version is available, proceed with download
-     * } catch (error) {
-     *   if (error.message === 'No new version available') {
-     *     // Device is already on the latest version - this is normal
-     *     console.log('Already up to date');
-     *   } else {
-     *     // Actual error occurred
-     *     console.error('Failed to check for updates:', error);
-     *   }
      * }
      * ```
      *
@@ -722,16 +884,68 @@ export interface CapacitorUpdaterPlugin {
      *
      * @param options Optional {@link GetLatestOptions} to specify which channel to check.
      * @returns {Promise<LatestVersion>} Information about the latest available bundle version.
-     * @throws {Error} Always throws when no new version is available (`error: "no_new_version_available"`), or when the request fails.
+     * @throws {Error} Throws for failed update checks or transport/request failures.
      * @since 4.0.0
      */
     getLatest(options?: GetLatestOptions): Promise<LatestVersion>;
+    /**
+     * Return the manifest entries that still need to be downloaded for a partial update.
+     *
+     * Pass the result from {@link getLatest} directly when it includes a `manifest`.
+     * The native plugin compares each manifest entry with the files already available
+     * in the builtin bundle and the local delta cache. Entries that can be reused are
+     * omitted from the returned `missing` list.
+     *
+     * For encrypted manifests, pass the `sessionKey` returned by {@link getLatest} so
+     * encrypted file hashes can be checked against local files.
+     *
+     * ```typescript
+     * const latest = await CapacitorUpdater.getLatest();
+     * const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
+     * ```
+     *
+     * @param options A {@link GetMissingBundleFilesOptions} object, or a {@link LatestVersion} response containing `manifest`.
+     * @returns {Promise<GetMissingBundleFilesResult>} The manifest entries that require network download.
+     * @throws {Error} If the manifest is missing or invalid.
+     * @since 8.47.0
+     */
+    getMissingBundleFiles(options: GetMissingBundleFilesOptions): Promise<GetMissingBundleFilesResult>;
+    /**
+     * Estimate the download size for manifest entries before downloading them.
+     *
+     * This method sends the provided manifest entries to the Capgo update endpoint
+     * once and reads the stored manifest `file_size` metadata. It does not perform
+     * per-file `HEAD` requests from the app.
+     *
+     * Use this after {@link getMissingBundleFiles} to estimate only the files this
+     * device still needs:
+     *
+     * ```typescript
+     * const latest = await CapacitorUpdater.getLatest();
+     * const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
+     * const size = await CapacitorUpdater.getBundleDownloadSize({
+     *   version: latest.version,
+     *   manifest: missing.missing,
+     * });
+     * ```
+     *
+     * @param options A {@link GetBundleDownloadSizeOptions} object containing manifest entries.
+     * @returns {Promise<GetBundleDownloadSizeResult>} Known byte totals and per-file size results.
+     * @throws {Error} If the manifest is missing or invalid.
+     * @since 8.47.0
+     */
+    getBundleDownloadSize(options: GetBundleDownloadSizeOptions): Promise<GetBundleDownloadSizeResult>;
     /**
      * Assign this device to a specific update channel at runtime.
      *
      * Channels allow you to distribute different bundle versions to different groups of users
      * (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.
+     *
      * **Requirements:**
      * - The target channel must allow self-assignment (configured in your Capgo dashboard or backend)
      * - The backend may accept or reject the request based on channel settings
@@ -758,7 +972,8 @@ export interface CapacitorUpdaterPlugin {
      * });
      * ```
      *
-     * This sends a request to the Capgo backend linking your device ID to the specified channel.
+     * This sends a request to the Capgo backend to validate the specified channel, then stores the
+     * channel locally on the device.
      *
      * @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.
@@ -767,11 +982,12 @@ export interface CapacitorUpdaterPlugin {
      */
     setChannel(options: SetChannelOptions): Promise<ChannelRes>;
     /**
-     * Remove the device's channel assignment and return to the default channel.
+     * Remove the plugin-managed local channel assignment and return to the default channel.
      *
-     * This unlinks the device from any specifically assigned channel, causing it to fall back to:
+     * This clears only the channel stored locally by {@link setChannel}; it does not delete Dashboard or Public API Device Override records. After the local assignment is cleared, normal channel precedence applies:
+     * - An existing Dashboard or Public API Device Override, if one exists
      * - The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or
-     * - Your backend's default channel for this app
+     * - Your backend default channel for this app
      *
      * Use this when:
      * - Users opt out of beta/testing programs
@@ -798,6 +1014,9 @@ 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.
+     *
      * @returns {Promise<GetChannelRes>} The current channel information.
      * @throws {Error} If the operation fails.
      * @since 4.8.0
@@ -879,7 +1098,7 @@ export interface CapacitorUpdaterPlugin {
      * **Privacy & Security characteristics:**
      * - Generated as a UUID (not based on hardware identifiers)
      * - Stored securely in platform-specific secure storage
-     * - Android: Android Keystore (persists across app reinstalls on API 23+)
+     * - Android: mirrored into backup-restorable app preferences for reinstall restore
      * - iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
      * - Not synced to cloud (iOS)
      * - Follows Apple and Google privacy best practices
@@ -887,7 +1106,9 @@ export interface CapacitorUpdaterPlugin {
      *
      * **Persistence:**
      * The device ID persists across app reinstalls to maintain consistent device identity
-     * for update tracking and analytics.
+     * for update tracking and analytics when platform storage is preserved. On Android,
+     * apps with custom backup rules must keep the plugin app preferences eligible for
+     * backup/restore; disabling Android backup or clearing app data creates a new ID.
      *
      * Use this to:
      * - Debug update delivery issues (check what ID the server sees)
@@ -938,6 +1159,7 @@ export interface CapacitorUpdaterPlugin {
      * This unregisters all listeners added via {@link addListener} for all event types:
      * - `download`
      * - `noNeedUpdate`
+     * - `updateCheckResult`
      * - `updateAvailable`
      * - `downloadComplete`
      * - `downloadFailed`
@@ -966,6 +1188,17 @@ export interface CapacitorUpdaterPlugin {
      * @since 4.0.0
      */
     addListener(eventName: 'noNeedUpdate', listenerFunc: (state: NoNeedEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for update check results before the updater decides whether to download.
+     * The backend can classify the UpdateCheckResultEvent payload as `up_to_date`, `blocked`, or `failed`.
+     *
+     * This event is emitted alongside legacy events. For `up_to_date` and `blocked`, it is emitted before
+     * `noNeedUpdate` and does not emit `downloadFailed`. For `failed`, it is emitted before the legacy
+     * `downloadFailed` event and keeps the existing failure stats behavior.
+     *
+     * @since 8.45.11
+     */
+    addListener(eventName: 'updateCheckResult', listenerFunc: (state: UpdateCheckResultEvent) => void): Promise<PluginListenerHandle>;
     /**
      * Listen for available update event, useful when you want to force check every time the app is launched
      *
@@ -998,6 +1231,20 @@ export interface CapacitorUpdaterPlugin {
      * @since 2.3.0
      */
     addListener(eventName: 'updateFailed', listenerFunc: (state: UpdateFailedEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * 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.
+     *
+     * @since 8.43.12
+     */
+    addListener(eventName: 'set', listenerFunc: (state: SetEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for set next event in the App, let you know when a bundle is queued as the next bundle to install.
+     *
+     * @since 6.14.0
+     */
+    addListener(eventName: 'setNext', listenerFunc: (state: SetNextEvent) => void): Promise<PluginListenerHandle>;
     /**
      * Listen for download fail event in the App, let you know when a bundle download has failed
      *
@@ -1011,7 +1258,9 @@ export interface CapacitorUpdaterPlugin {
      */
     addListener(eventName: 'appReloaded', listenerFunc: () => void): Promise<PluginListenerHandle>;
     /**
-     * Listen for app ready event in the App, let you know when app is ready to use, this event is retain till consumed.
+     * 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.
      *
      * @since 5.1.0
      */
@@ -1117,23 +1366,20 @@ export interface CapacitorUpdaterPlugin {
      */
     getFailedUpdate(): Promise<UpdateFailedEvent | null>;
     /**
-     * Enable or disable the shake gesture menu for debugging and testing.
+     * Enable or disable the native preview menu gesture.
      *
-     * When enabled, users can shake their device to open a debug menu that shows:
-     * - Current bundle information
-     * - Available bundles
-     * - Options to switch bundles manually
-     * - Update status
+     * During preview sessions, users can use the configured native gesture to:
+     * - Reload the current preview
+     * - Leave the test app and return to the fallback bundle
+     * - Switch update channel, when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is also enabled
      *
-     * This is useful during development and testing to:
-     * - Quickly test different bundle versions
-     * - Debug update flows
-     * - Switch between production and test bundles
-     * - Verify bundle installations
+     * Outside preview sessions, this preview menu is ignored. The channel selector can still be
+     * shown outside preview sessions when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is enabled.
      *
      * **Important:** Disable this in production builds or only enable for internal testers.
      *
-     * Can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
+     * This can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
+     * The native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.
      *
      * @param options {@link SetShakeMenuOptions} with `enabled: true` to enable or `enabled: false` to disable.
      * @returns {Promise<void>} Resolves when the setting is applied.
@@ -1142,7 +1388,7 @@ export interface CapacitorUpdaterPlugin {
      */
     setShakeMenu(options: SetShakeMenuOptions): Promise<void>;
     /**
-     * Check if the shake gesture debug menu is currently enabled.
+     * Check if the native preview menu gesture is currently enabled.
      *
      * Returns the current state of the shake menu feature that can be toggled via
      * {@link setShakeMenu} or configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
@@ -1152,22 +1398,20 @@ export interface CapacitorUpdaterPlugin {
      * - Show/hide debug settings UI
      * - Verify configuration during testing
      *
-     * @returns {Promise<ShakeMenuEnabled>} Object with `enabled: true` or `enabled: false`.
+     * @returns {Promise<ShakeMenuEnabled>} Object with the current enabled state and gesture.
      * @throws {Error} If the operation fails.
      * @since 7.5.0
      */
     isShakeMenuEnabled(): Promise<ShakeMenuEnabled>;
     /**
-     * Enable or disable the shake channel selector at runtime.
+     * Enable or disable the channel selector menu gesture at runtime.
      *
-     * When enabled AND shakeMenu is true, shaking the device shows a channel
-     * selector instead of the debug menu. This allows users to switch between
-     * update channels by shaking their device.
+     * When enabled, the configured native gesture can show a channel selector, including outside preview sessions.
+     * If {@link setShakeMenu} is also enabled while a preview session is active, the shake menu includes
+     * both preview actions and channel switching.
      *
-     * After selecting a channel, the app automatically checks for updates
-     * and downloads if available.
-     *
-     * Can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
+     * This can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
+     * The native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.
      *
      * @param options {@link SetShakeChannelSelectorOptions} with `enabled: true` to enable or `enabled: false` to disable.
      * @returns {Promise<void>} Resolves when the setting is applied.
@@ -1357,6 +1601,14 @@ export interface CapacitorUpdaterPlugin {
  */
 export type BundleStatus = 'success' | 'error' | 'pending' | 'downloading';
 export type DelayUntilNext = 'background' | 'kill' | 'nativeVersion' | 'date';
+/**
+ * Classification for update-check responses that do not provide a downloadable bundle.
+ * The update backend provides this field directly. Missing or unknown values are treated as
+ * failed by native clients.
+ *
+ * @since 8.45.11
+ */
+export type UpdateResponseKind = 'up_to_date' | 'blocked' | 'failed';
 export interface NoNeedEvent {
     /**
      * Current status of download, between 0 and 100.
@@ -1365,6 +1617,44 @@ export interface NoNeedEvent {
      */
     bundle: BundleInfo;
 }
+export interface UpdateCheckResultEvent {
+    /**
+     * Classification for the update check result, provided by the backend.
+     *
+     * @since 8.45.11
+     */
+    kind: UpdateResponseKind;
+    /**
+     * Backend error code, when provided.
+     *
+     * @since 8.45.11
+     */
+    error?: string;
+    /**
+     * Backend message, when provided.
+     *
+     * @since 8.45.11
+     */
+    message?: string;
+    /**
+     * HTTP status code returned by the update endpoint.
+     *
+     * @since 8.45.11
+     */
+    statusCode?: number;
+    /**
+     * Version referenced by the update check result.
+     *
+     * @since 8.45.11
+     */
+    version?: string;
+    /**
+     * Current bundle on the device.
+     *
+     * @since 8.45.11
+     */
+    bundle: BundleInfo;
+}
 export interface UpdateAvailableEvent {
     /**
      * Current status of download, between 0 and 100.
@@ -1401,7 +1691,7 @@ export interface ChannelInfo {
      *
      * @since 7.5.0
      */
-    id: string;
+    id: number;
     /**
      * The channel name
      *
@@ -1477,9 +1767,27 @@ export interface UpdateFailedEvent {
      */
     bundle: BundleInfo;
 }
+export interface SetEvent {
+    /**
+     * Emit when a bundle has been applied successfully.
+     * This event uses native `retainUntilConsumed` behavior.
+     *
+     * @since 8.43.12
+     */
+    bundle: BundleInfo;
+}
+export interface SetNextEvent {
+    /**
+     * Emit when a bundle is queued as the next bundle to install.
+     *
+     * @since 6.14.0
+     */
+    bundle: BundleInfo;
+}
 export interface AppReadyEvent {
     /**
      * Emitted when the app is ready to use.
+     * This event uses native `retainUntilConsumed` behavior.
      *
      * @since  5.2.0
      */
@@ -1500,6 +1808,128 @@ export interface ManifestEntry {
     file_hash: string | null;
     download_url: string | null;
 }
+export interface GetMissingBundleFilesOptions {
+    /**
+     * Manifest returned by {@link getLatest}. Passing the full {@link LatestVersion}
+     * response is supported because it contains this field.
+     *
+     * @since 8.47.0
+     */
+    manifest?: ManifestEntry[];
+    /**
+     * Target bundle version. Passing the full {@link LatestVersion} response is
+     * supported because it contains this field.
+     *
+     * @since 8.47.0
+     */
+    version?: string;
+    /**
+     * Session key returned by {@link getLatest}, required only when file hashes are encrypted.
+     *
+     * @since 8.47.0
+     */
+    sessionKey?: string;
+}
+export interface GetMissingBundleFilesResult {
+    /**
+     * Entries that are not available locally and need to be downloaded.
+     *
+     * @since 8.47.0
+     */
+    missing: ManifestEntry[];
+    /**
+     * Total entries in the provided manifest.
+     *
+     * @since 8.47.0
+     */
+    total: number;
+    /**
+     * Number of entries that need to be downloaded.
+     *
+     * @since 8.47.0
+     */
+    missingCount: number;
+    /**
+     * Number of entries that can be reused from builtin files or local cache.
+     *
+     * @since 8.47.0
+     */
+    reusableCount: number;
+}
+export interface GetBundleDownloadSizeOptions {
+    /**
+     * Manifest entries to estimate. Pass `missing.missing` from {@link getMissingBundleFiles}
+     * to estimate only the bytes this device still needs to download.
+     *
+     * @since 8.47.0
+     */
+    manifest?: ManifestEntry[];
+    /**
+     * Target bundle version. Pass `latest.version` when estimating files returned
+     * by {@link getLatest}.
+     *
+     * @since 8.47.0
+     */
+    version?: string;
+}
+export interface BundleFileSize {
+    /**
+     * File name from the manifest entry.
+     *
+     * @since 8.47.0
+     */
+    file_name: string | null;
+    /**
+     * File hash from the manifest entry.
+     *
+     * @since 8.47.0
+     */
+    file_hash: string | null;
+    /**
+     * Download URL from the manifest entry.
+     *
+     * @since 8.47.0
+     */
+    download_url: string | null;
+    /**
+     * Estimated bytes to download when the server exposes a size.
+     *
+     * @since 8.47.0
+     */
+    size?: number;
+    /**
+     * Error for this entry when the size could not be determined.
+     *
+     * @since 8.47.0
+     */
+    error?: string;
+}
+export interface GetBundleDownloadSizeResult {
+    /**
+     * Sum of all known file sizes in bytes.
+     *
+     * @since 8.47.0
+     */
+    totalSize: number;
+    /**
+     * Number of files with a known size.
+     *
+     * @since 8.47.0
+     */
+    knownFiles: number;
+    /**
+     * Number of files whose size could not be determined.
+     *
+     * @since 8.47.0
+     */
+    unknownFiles: number;
+    /**
+     * Per-file size results.
+     *
+     * @since 8.47.0
+     */
+    files: BundleFileSize[];
+}
 export interface LatestVersion {
     /**
      * Result of getLatest method
@@ -1528,12 +1958,21 @@ export interface LatestVersion {
     message?: string;
     sessionKey?: string;
     /**
-     * Error code from the server, if any.
-     * Common values:
-     * - `"no_new_version_available"`: Device is already on the latest version (not a failure)
-     * - Other error codes indicate actual failures in the update process
+     * Error code from the server, if any. Use `kind` for classification instead of parsing this value.
      */
     error?: string;
+    /**
+     * Classification for this response, provided by the backend.
+     *
+     * @since 8.45.11
+     */
+    kind?: UpdateResponseKind;
+    /**
+     * HTTP status code returned by the update server for classified update-check responses.
+     *
+     * @since 8.45.11
+     */
+    statusCode?: number;
     /**
      * The previous/current version name (provided for reference).
      */
@@ -1547,6 +1986,20 @@ export interface LatestVersion {
      * @since 6.1
      */
     manifest?: ManifestEntry[];
+    /**
+     * Missing manifest entries for this device when {@link GetLatestOptions.includeBundleSize}
+     * is enabled.
+     *
+     * @since 8.47.0
+     */
+    missing?: GetMissingBundleFilesResult;
+    /**
+     * Estimated download size for missing manifest entries when
+     * {@link GetLatestOptions.includeBundleSize} is enabled.
+     *
+     * @since 8.47.0
+     */
+    downloadSize?: GetBundleDownloadSizeResult;
     /**
      * Optional link associated with this bundle version (e.g., release notes URL, changelog, GitHub release).
      * @since 7.35.0
@@ -1594,6 +2047,193 @@ export interface GetLatestOptions {
      * @default undefined
      */
     channel?: string;
+    /**
+     * 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`.
+     * @since 8.47.0
+     * @default undefined
+     */
+    appId?: string;
+    /**
+     * 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.
+     *
+     * @since 8.47.0
+     * @default false
+     */
+    includeBundleSize?: boolean;
+}
+export interface StartPreviewSessionOptions {
+    /**
+     * App id to use while the preview session is active.
+     * The previous app id is restored when leaving the preview session.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
+     * @since 8.47.0
+     * @default undefined
+     */
+    appId?: string;
+    /**
+     * HTTP(S) URL returning a preview download payload.
+     * When provided, the native shake reload action fetches this payload again
+     * before reloading so channel previews can move to the latest bundle.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
+     * @since 8.48.0
+     * @default undefined
+     */
+    payloadUrl?: string;
+    /**
+     * Human-readable preview name stored with the next preview bundle applied by
+     * {@link set}. Native preview menus and {@link listPreviews} can display it.
+     * @since 8.49.0
+     * @default undefined
+     */
+    name?: string;
+    /**
+     * Optional source label for the preview, such as `channel`, `bundle`, `url`,
+     * or `payload`. This is stored as metadata only.
+     * @since 8.49.0
+     * @default undefined
+     */
+    source?: string;
+}
+export interface PreviewInfo {
+    /**
+     * Preview bundle id.
+     *
+     * @since 8.49.0
+     */
+    id: string;
+    /**
+     * Locally downloaded bundle backing this preview.
+     *
+     * @since 8.49.0
+     */
+    bundle: BundleInfo;
+    /**
+     * Human-readable name supplied when the preview was started.
+     *
+     * @since 8.49.0
+     */
+    name?: string;
+    /**
+     * Metadata source label supplied when the preview was started.
+     *
+     * @since 8.49.0
+     */
+    source?: string;
+    /**
+     * Preview app id, when the session uses an app id override.
+     *
+     * @since 8.49.0
+     */
+    appId?: string;
+    /**
+     * Payload URL used to refresh this preview.
+     *
+     * @since 8.49.0
+     */
+    payloadUrl?: string;
+    /**
+     * ISO timestamp for when this preview was first saved.
+     *
+     * @since 8.49.0
+     */
+    createdAt: string;
+    /**
+     * ISO timestamp for the last metadata or bundle update.
+     *
+     * @since 8.49.0
+     */
+    updatedAt: string;
+    /**
+     * ISO timestamp for the last time this preview was activated.
+     *
+     * @since 8.49.0
+     */
+    lastUsedAt: string;
+    /**
+     * Whether this preview is the currently active bundle in a preview session.
+     *
+     * @since 8.49.0
+     */
+    isActive: boolean;
+}
+export interface PreviewListResult {
+    /**
+     * Locally available preview bundles.
+     *
+     * @since 8.49.0
+     */
+    previews: PreviewInfo[];
+    /**
+     * Current preview when a preview session is active.
+     *
+     * @since 8.49.0
+     */
+    current?: PreviewInfo;
+    /**
+     * Bundle currently loaded by the WebView.
+     *
+     * @since 8.49.0
+     */
+    currentBundle: BundleInfo;
+    /**
+     * Bundle that will be restored when leaving preview mode.
+     *
+     * @since 8.49.0
+     */
+    liveBundle?: BundleInfo;
+}
+export interface DeletePreviewResult {
+    /**
+     * Whether preview metadata was removed.
+     *
+     * @since 8.49.0
+     */
+    removed: boolean;
+    /**
+     * Whether the underlying local bundle was deleted.
+     *
+     * @since 8.49.0
+     */
+    deleted: boolean;
+}
+export interface PreviewUpdateResult {
+    /**
+     * Saved preview metadata after the check or update.
+     *
+     * @since 8.49.0
+     */
+    preview: PreviewInfo;
+    /**
+     * Latest version returned by the preview payload endpoint.
+     *
+     * @since 8.49.0
+     */
+    latestVersion?: string;
+    /**
+     * Whether the saved preview already matches the latest payload version.
+     *
+     * @since 8.49.0
+     */
+    upToDate: boolean;
+    /**
+     * Whether a newer bundle was downloaded and saved.
+     *
+     * @since 8.49.0
+     */
+    updated: boolean;
+    /**
+     * New bundle when {@link updatePreview} downloaded one.
+     *
+     * @since 8.49.0
+     */
+    bundle?: BundleInfo;
 }
 export interface AppReadyResult {
     bundle: BundleInfo;
@@ -1646,7 +2286,19 @@ export interface BundleListResult {
     bundles: BundleInfo[];
 }
 export interface ResetOptions {
-    toLastSuccessful: boolean;
+    /**
+     * Reset to the last successfully loaded bundle instead of the builtin one.
+     * @default false
+     */
+    toLastSuccessful?: boolean;
+    /**
+     * Apply the pending bundle set via {@link next} while resetting.
+     *
+     * When `true`, the plugin will switch to the pending bundle immediately and clear the pending flag.
+     * If no pending bundle exists, the reset will fail.
+     * @default false
+     */
+    usePendingBundle?: boolean;
 }
 export interface ListOptions {
     /**
@@ -1678,11 +2330,48 @@ export interface AutoUpdateEnabled {
 export interface AutoUpdateAvailable {
     available: boolean;
 }
+/**
+ * Result returned after requesting an immediate native auto-update check.
+ *
+ * @property status - Native trigger state: `queued` when a check was queued,
+ * `already_running` when the native update pipeline is already active, or
+ * `unavailable` on Web or when native auto-update is disabled.
+ * @property queued - Whether a new native update check was queued. This is
+ * `true` only when `status` is `queued`; otherwise it is `false`.
+ */
+export interface TriggerUpdateCheckResult {
+    /**
+     * Native trigger state: `queued` when a check was queued, `already_running`
+     * when the native update pipeline is already active, or `unavailable` on Web
+     * or when native auto-update is disabled.
+     */
+    status: 'queued' | 'already_running' | 'unavailable';
+    /**
+     * Whether a new native update check was queued. This is `true` only when
+     * `status` is `queued`; otherwise it is `false`.
+     */
+    queued: boolean;
+}
+/**
+ * Native gesture options that open the shake menu.
+ *
+ * Supported values are `shake` and `threeFingerPinch`.
+ *
+ * @public
+ */
+export type ShakeMenuGesture = 'shake' | 'threeFingerPinch';
 export interface SetShakeMenuOptions {
     enabled: boolean;
 }
 export interface ShakeMenuEnabled {
     enabled: boolean;
+    /**
+     * The currently configured native gesture used to open the preview/channel menu.
+     * Undefined means consumers should treat the gesture as the default `shake` behavior.
+     *
+     * @since 8.48.0
+     */
+    gesture?: ShakeMenuGesture;
 }
 export interface SetShakeChannelSelectorOptions {
     enabled: boolean;