@capgo/capacitor-updater 6.25.6 → 6.25.8

package/dist/esm/definitions.d.ts

@@ -322,243 +322,566 @@ declare module '@capacitor/cli' {
 }
 export interface CapacitorUpdaterPlugin {
     /**
-     * Notify Capacitor Updater that the current bundle is working (a rollback will occur if this method is not called on every app launch)
-     * By default this method should be called in the first 10 sec after app launch, otherwise a rollback will occur.
-     * Change this behaviour with {@link appReadyTimeout}
+     * Notify the native layer that JavaScript initialized successfully.
      *
-     * @returns {Promise<AppReadyResult>} an Promise resolved directly
-     * @throws {Error}
+     * **CRITICAL: You must call this method on every app launch to prevent automatic rollback.**
+     *
+     * This is a simple notification to confirm that your bundle's JavaScript loaded and executed.
+     * The native web server successfully served the bundle files and your JS runtime started.
+     * That's all it checks - nothing more complex.
+     *
+     * **What triggers rollback:**
+     * - NOT calling this method within the timeout (default: 10 seconds)
+     * - Complete JavaScript failure (bundle won't load at all)
+     *
+     * **What does NOT trigger rollback:**
+     * - Runtime errors after initialization (API failures, crashes, etc.)
+     * - Network request failures
+     * - Application logic errors
+     *
+     * **IMPORTANT: Call this BEFORE any network requests.**
+     * Don't wait for APIs, data loading, or async operations. Call it as soon as your
+     * JavaScript bundle starts executing to confirm the bundle itself is valid.
+     *
+     * Best practices:
+     * - Call immediately in your app entry point (main.js, app component mount, etc.)
+     * - Don't put it after network calls or heavy initialization
+     * - Don't wrap it in try/catch with conditions
+     * - Adjust {@link PluginsConfig.CapacitorUpdater.appReadyTimeout} if you need more time
+     *
+     * @returns {Promise<AppReadyResult>} Always resolves successfully with current bundle info. This method never fails.
      */
     notifyAppReady(): Promise<AppReadyResult>;
     /**
-     * Set the updateUrl for the app, this will be used to check for updates.
+     * Set the update URL for the app dynamically at runtime.
+     *
+     * This overrides the {@link PluginsConfig.CapacitorUpdater.updateUrl} config value.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowModifyUrl} to be set to `true`.
      *
-     * @param options contains the URL to use for checking for updates.
-     * @returns {Promise<void>}
-     * @throws {Error}
+     * Use {@link PluginsConfig.CapacitorUpdater.persistModifyUrl} to persist this value across app restarts.
+     * Otherwise, the URL will reset to the config value on next app launch.
+     *
+     * @param options Contains the URL to use for checking for updates.
+     * @returns {Promise<void>} Resolves when the URL is successfully updated.
+     * @throws {Error} If `allowModifyUrl` is false or if the operation fails.
      * @since 5.4.0
      */
     setUpdateUrl(options: UpdateUrl): Promise<void>;
     /**
-     * Set the statsUrl for the app, this will be used to send statistics. Passing an empty string will disable statistics gathering.
+     * Set the statistics URL for the app dynamically at runtime.
+     *
+     * This overrides the {@link PluginsConfig.CapacitorUpdater.statsUrl} config value.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowModifyUrl} to be set to `true`.
+     *
+     * Pass an empty string to disable statistics gathering entirely.
+     * Use {@link PluginsConfig.CapacitorUpdater.persistModifyUrl} to persist this value across app restarts.
      *
-     * @param options contains the URL to use for sending statistics.
-     * @returns {Promise<void>}
-     * @throws {Error}
+     * @param options Contains the URL to use for sending statistics, or an empty string to disable.
+     * @returns {Promise<void>} Resolves when the URL is successfully updated.
+     * @throws {Error} If `allowModifyUrl` is false or if the operation fails.
      * @since 5.4.0
      */
     setStatsUrl(options: StatsUrl): Promise<void>;
     /**
-     * Set the channelUrl for the app, this will be used to set the channel.
+     * Set the channel URL for the app dynamically at runtime.
      *
-     * @param options contains the URL to use for setting the channel.
-     * @returns {Promise<void>}
-     * @throws {Error}
+     * This overrides the {@link PluginsConfig.CapacitorUpdater.channelUrl} config value.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowModifyUrl} to be set to `true`.
+     *
+     * Use {@link PluginsConfig.CapacitorUpdater.persistModifyUrl} to persist this value across app restarts.
+     * Otherwise, the URL will reset to the config value on next app launch.
+     *
+     * @param options Contains the URL to use for channel operations.
+     * @returns {Promise<void>} Resolves when the URL is successfully updated.
+     * @throws {Error} If `allowModifyUrl` is false or if the operation fails.
      * @since 5.4.0
      */
     setChannelUrl(options: ChannelUrl): Promise<void>;
     /**
-     * Download a new bundle from the provided URL, it should be a zip file, with files inside or with a unique id inside with all your files
+     * Download a new bundle from the provided URL for later installation.
+     *
+     * The downloaded bundle is stored locally but not activated. To use it:
+     * - Call {@link next} to set it for installation on next app backgrounding/restart
+     * - Call {@link set} to activate it immediately (destroys current JavaScript context)
+     *
+     * The URL should point to a zip file containing either:
+     * - Your app files directly in the zip root, or
+     * - A single folder containing all your app files
+     *
+     * The bundle must include an `index.html` file at the root level.
+     *
+     * For encrypted bundles, provide the `sessionKey` and `checksum` parameters.
+     * For multi-file partial updates, provide the `manifest` array.
+     *
+     * @example
+     * const bundle = await CapacitorUpdater.download({
+     *   url: `https://example.com/versions/${version}/dist.zip`,
+     *   version: version
+     * });
+     * // Bundle is downloaded but not active yet
+     * await CapacitorUpdater.next({ id: bundle.id }); // Will activate on next background
      *
-     * @example const bundle = await CapacitorUpdater.download({ url: `https://example.com/versions/${version}/dist.zip`, version });
-     * @returns {Promise<BundleInfo>} The {@link BundleInfo} for the specified bundle.
      * @param options The {@link DownloadOptions} for downloading a new bundle zip.
+     * @returns {Promise<BundleInfo>} The {@link BundleInfo} for the downloaded bundle.
+     * @throws {Error} If the download fails or the bundle is invalid.
      */
     download(options: DownloadOptions): Promise<BundleInfo>;
     /**
-     * Set the next bundle to be used when the app is reloaded.
+     * Set the next bundle to be activated when the app backgrounds or restarts.
      *
-     * @param options Contains the ID of the next Bundle to set on next app launch. {@link BundleInfo.id}
-     * @returns {Promise<BundleInfo>} The {@link BundleInfo} for the specified bundle id.
-     * @throws {Error} When there is no index.html file inside the bundle folder.
+     * This is the recommended way to apply updates as it doesn't interrupt the user's current session.
+     * The bundle will be activated when:
+     * - The app is backgrounded (user switches away), or
+     * - The app is killed and relaunched, or
+     * - {@link reload} is called manually
+     *
+     * Unlike {@link set}, this method does NOT destroy the current JavaScript context immediately.
+     * Your app continues running normally until one of the above events occurs.
+     *
+     * Use {@link setMultiDelay} to add additional conditions before the update is applied.
+     *
+     * @param options Contains the ID of the bundle to set as next. Use {@link BundleInfo.id} from a downloaded bundle.
+     * @returns {Promise<BundleInfo>} The {@link BundleInfo} for the specified bundle.
+     * @throws {Error} When there is no index.html file inside the bundle folder or the bundle doesn't exist.
      */
     next(options: BundleId): Promise<BundleInfo>;
     /**
      * Set the current bundle and immediately reloads the app.
      *
+     * **IMPORTANT: This is a terminal operation that destroys the current JavaScript context.**
+     *
+     * When you call this method:
+     * - The entire JavaScript context is immediately destroyed
+     * - The app reloads from a different folder with different files
+     * - NO code after this call will execute
+     * - NO promises will resolve
+     * - NO callbacks will fire
+     * - Event listeners registered after this call are unreliable and may never fire
+     *
+     * The reload happens automatically - you don't need to do anything else.
+     * If you need to preserve state like the current URL path, use the {@link PluginsConfig.CapacitorUpdater.keepUrlPathAfterReload} config option.
+     * For other state preservation needs, save your data before calling this method (e.g., to localStorage).
+     *
+     * **Do not** try to execute additional logic after calling `set()` - it won't work as expected.
+     *
      * @param options A {@link BundleId} object containing the new bundle id to set as current.
-     * @returns {Promise<void>}
-     * @throws {Error} When there are is no index.html file inside the bundle folder.
+     * @returns {Promise<void>} A promise that will never resolve because the JavaScript context is destroyed.
+     * @throws {Error} When there is no index.html file inside the bundle folder.
      */
     set(options: BundleId): Promise<void>;
     /**
-     * Deletes the specified bundle from the native app storage. Use with {@link list} to get the stored Bundle IDs.
+     * Delete a bundle from local storage to free up disk space.
+     *
+     * You cannot delete:
+     * - The currently active bundle
+     * - The `builtin` bundle (the version shipped with your app)
+     * - The bundle set as `next` (call {@link next} with a different bundle first)
      *
-     * @param options A {@link BundleId} object containing the ID of a bundle to delete (note, this is the bundle id, NOT the version name)
-     * @returns {Promise<void>} When the bundle is deleted
-     * @throws {Error}
+     * Use {@link list} to get all available bundle IDs.
+     *
+     * **Note:** The bundle ID is NOT the same as the version name.
+     * Use the `id` field from {@link BundleInfo}, not the `version` field.
+     *
+     * @param options A {@link BundleId} object containing the bundle ID to delete.
+     * @returns {Promise<void>} Resolves when the bundle is successfully deleted.
+     * @throws {Error} If the bundle is currently in use or doesn't exist.
      */
     delete(options: BundleId): Promise<void>;
     /**
-     * Mark an installed bundle as errored. Only available when {@link PluginsConfig.CapacitorUpdater.allowManualBundleError} is true.
+     * Manually mark a bundle as failed/errored in manual update mode.
+     *
+     * This is useful when you detect that a bundle has critical issues and want to prevent
+     * it from being used again. The bundle status will be changed to `error` and the plugin
+     * will avoid using this bundle in the future.
      *
-     * @param options A {@link BundleId} object containing the bundle id to mark as errored.
-     * @returns {Promise<BundleInfo>} The updated {@link BundleInfo} for the bundle.
-     * @throws {Error} When the bundle does not exist or the feature is disabled.
+     * **Requirements:**
+     * - {@link PluginsConfig.CapacitorUpdater.allowManualBundleError} must be set to `true`
+     * - Only works in manual update mode (when autoUpdate is disabled)
+     *
+     * Common use case: After downloading and testing a bundle, you discover it has critical
+     * bugs and want to mark it as failed so it won't be retried.
+     *
+     * @param options A {@link BundleId} object containing the bundle ID to mark as errored.
+     * @returns {Promise<BundleInfo>} The updated {@link BundleInfo} with status set to `error`.
+     * @throws {Error} When the bundle does not exist or `allowManualBundleError` is false.
      * @since 7.20.0
      */
     setBundleError(options: BundleId): Promise<BundleInfo>;
     /**
-     * Get all locally downloaded bundles in your app
+     * Get all locally downloaded bundles stored in your app.
+     *
+     * This returns all bundles that have been downloaded and are available locally, including:
+     * - The currently active bundle
+     * - The `builtin` bundle (shipped with your app)
+     * - Any downloaded bundles waiting to be activated
+     * - Failed bundles (with `error` status)
      *
-     * @returns {Promise<BundleListResult>} A Promise containing the {@link BundleListResult.bundles}
-     * @param options The {@link ListOptions} for listing bundles
-     * @throws {Error}
+     * Use this to:
+     * - Check available disk space by counting bundles
+     * - Delete old bundles with {@link delete}
+     * - Monitor bundle download status
+     *
+     * @param options The {@link ListOptions} for customizing the bundle list output.
+     * @returns {Promise<BundleListResult>} A promise containing the array of {@link BundleInfo} objects.
+     * @throws {Error} If the operation fails.
      */
     list(options?: ListOptions): Promise<BundleListResult>;
     /**
-     * Reset the app to the `builtin` bundle (the one sent to Apple App Store / Google Play Store ) or the last successfully loaded bundle.
+     * Reset the app to a known good bundle.
+     *
+     * This method helps recover from problematic updates by reverting to either:
+     * - The `builtin` bundle (the original version shipped with your app to App Store/Play Store)
+     * - The last successfully loaded bundle (most recent bundle that worked correctly)
+     *
+     * **IMPORTANT: This triggers an immediate app reload, destroying the current JavaScript context.**
+     * See {@link set} for details on the implications of this operation.
      *
-     * @param options Containing {@link ResetOptions.toLastSuccessful}, `true` resets to the builtin bundle and `false` will reset to the last successfully loaded bundle.
-     * @returns {Promise<void>}
-     * @throws {Error}
+     * Use cases:
+     * - Emergency recovery when an update causes critical issues
+     * - 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.
+     * @returns {Promise<void>} A promise that may never resolve because the app will be reloaded.
+     * @throws {Error} If the reset operation fails.
      */
     reset(options?: ResetOptions): Promise<void>;
     /**
-     * Get the current bundle, if none are set it returns `builtin`. currentNative is the original bundle installed on the device
+     * Get information about the currently active bundle.
+     *
+     * Returns:
+     * - `bundle`: The currently active bundle information
+     * - `native`: The version of the builtin bundle (the original app version from App/Play Store)
+     *
+     * If no updates have been applied, `bundle.id` will be `"builtin"`, indicating the app
+     * is running the original version shipped with the native app.
      *
-     * @returns {Promise<CurrentBundleResult>} A Promise evaluating to the {@link CurrentBundleResult}
-     * @throws {Error}
+     * Use this to:
+     * - Display the current version to users
+     * - Check if an update is currently active
+     * - Compare against available updates
+     * - Log the active bundle for debugging
+     *
+     * @returns {Promise<CurrentBundleResult>} A promise with the current bundle and native version info.
+     * @throws {Error} If the operation fails.
      */
     current(): Promise<CurrentBundleResult>;
     /**
-     * Reload the view
+     * Manually reload the app to apply a pending update.
+     *
+     * This triggers the same reload behavior that happens automatically when the app backgrounds.
+     * If you've called {@link next} to queue an update, calling `reload()` will apply it immediately.
+     *
+     * **IMPORTANT: This destroys the current JavaScript context immediately.**
+     * See {@link set} for details on the implications of this operation.
      *
-     * @returns {Promise<void>} A Promise which is resolved when the view is reloaded
-     * @throws {Error}
+     * Common use cases:
+     * - Applying an update immediately after download instead of waiting for backgrounding
+     * - Providing a "Restart now" button to users after an update is ready
+     * - Testing update flows during development
+     *
+     * If no update is pending (no call to {@link next}), this simply reloads the current bundle.
+     *
+     * @returns {Promise<void>} A promise that may never resolve because the app will be reloaded.
+     * @throws {Error} If the reload operation fails.
      */
     reload(): Promise<void>;
     /**
-     * Sets a {@link DelayCondition} array containing conditions that the Plugin will use to delay the update.
-     * After all conditions are met, the update process will run start again as usual, so update will be installed after a backgrounding or killing the app.
-     * For the `date` kind, the value should be an iso8601 date string.
-     * For the `background` kind, the value should be a number in milliseconds.
-     * For the `nativeVersion` kind, the value should be the version number.
-     * For the `kill` kind, the value is not used.
-     * The function has inconsistent behavior the option kill do trigger the update after the first kill and not after the next background like other options. This will be fixed in a future major release.
+     * Configure conditions that must be met before a pending update is applied.
+     *
+     * After calling {@link next} to queue an update, use this method to control when it gets applied.
+     * The update will only be installed after ALL specified conditions are satisfied.
+     *
+     * Available condition types:
+     * - `background`: Wait for the app to be backgrounded. Optionally specify duration in milliseconds.
+     * - `kill`: Wait for the app to be killed and relaunched (**Note:** Current behavior triggers update immediately on kill, not on next background. This will be fixed in v8.)
+     * - `date`: Wait until a specific date/time (ISO 8601 format)
+     * - `nativeVersion`: Wait until the native app is updated to a specific version
+     *
+     * Condition value formats:
+     * - `background`: Number in milliseconds (e.g., `"300000"` for 5 minutes), or omit for immediate
+     * - `kill`: No value needed
+     * - `date`: ISO 8601 date string (e.g., `"2025-12-31T23:59:59Z"`)
+     * - `nativeVersion`: Version string (e.g., `"2.0.0"`)
      *
      * @example
-     * // Delay the update after the user kills the app or after a background of 300000 ms (5 minutes)
-     * await CapacitorUpdater.setMultiDelay({ delayConditions: [{ kind: 'kill' }, { kind: 'background', value: '300000' }] })
+     * // Update after user kills app OR after 5 minutes in background
+     * await CapacitorUpdater.setMultiDelay({
+     *   delayConditions: [
+     *     { kind: 'kill' },
+     *     { kind: 'background', value: '300000' }
+     *   ]
+     * });
+     *
      * @example
-     * // Delay the update after the specific iso8601 date is expired
-     * await CapacitorUpdater.setMultiDelay({ delayConditions: [{ kind: 'date', value: '2022-09-14T06:14:11.920Z' }] })
+     * // Update after a specific date
+     * await CapacitorUpdater.setMultiDelay({
+     *   delayConditions: [{ kind: 'date', value: '2025-12-31T23:59:59Z' }]
+     * });
+     *
      * @example
-     * // Delay the update after the first background (default behaviour without setting delay)
-     * await CapacitorUpdater.setMultiDelay({ delayConditions: [{ kind: 'background' }] })
-     * @param options Containing the {@link MultiDelayConditions} array of conditions to set
-     * @returns {Promise<void>}
-     * @throws {Error}
+     * // Default behavior: update on next background
+     * await CapacitorUpdater.setMultiDelay({
+     *   delayConditions: [{ kind: 'background' }]
+     * });
+     *
+     * @param options Contains the {@link MultiDelayConditions} array of conditions.
+     * @returns {Promise<void>} Resolves when the delay conditions are set.
+     * @throws {Error} If the operation fails or conditions are invalid.
      * @since 4.3.0
      */
     setMultiDelay(options: MultiDelayConditions): Promise<void>;
     /**
-     * Cancels a {@link DelayCondition} to process an update immediately.
+     * Cancel all delay conditions and apply the pending update immediately.
+     *
+     * If you've set delay conditions with {@link setMultiDelay}, this method clears them
+     * and triggers the pending update to be applied on the next app background or restart.
      *
-     * @returns {Promise<void>}
-     * @throws {Error}
+     * This is useful when:
+     * - User manually requests to update now (e.g., clicks "Update now" button)
+     * - Your app detects it's a good time to update (e.g., user finished critical task)
+     * - You want to override a time-based delay early
+     *
+     * @returns {Promise<void>} Resolves when the delay conditions are cleared.
+     * @throws {Error} If the operation fails.
      * @since 4.0.0
      */
     cancelDelay(): Promise<void>;
     /**
-     * Get Latest bundle available from update Url
+     * Check the update server for the latest available bundle version.
+     *
+     * This queries your configured update URL (or Capgo backend) to see if a newer bundle
+     * is available for download. It does NOT download the bundle automatically.
      *
-     * @returns {Promise<LatestVersion>} A Promise resolved when url is loaded
-     * @throws {Error}
+     * The response includes:
+     * - `version`: The latest available version identifier
+     * - `url`: Download URL for the bundle (if available)
+     * - `breaking`: Whether this update is marked as incompatible (requires native app update)
+     * - `message`: Optional message from the server
+     * - `manifest`: File list for partial updates (if using multi-file downloads)
+     *
+     * After receiving the latest version info, you can:
+     * 1. Compare it with your current version
+     * 2. Download it using {@link download}
+     * 3. Apply it using {@link next} or {@link set}
+     *
+     * @param options Optional {@link GetLatestOptions} to specify which channel to check.
+     * @returns {Promise<LatestVersion>} Information about the latest available bundle version.
+     * @throws {Error} If the request fails or the server returns an error.
      * @since 4.0.0
      */
     getLatest(options?: GetLatestOptions): Promise<LatestVersion>;
     /**
-     * Sets the channel for this device. The channel has to allow for self assignment for this to work.
-     * Do not use this method to set the channel at boot.
-     * This method is to set the channel after the app is ready, and user interacted.
-     * If you want to set the channel at boot, use the {@link PluginsConfig} to set the default channel.
-     * This methods send to Capgo backend a request to link the device ID to the channel. Capgo can accept or refuse depending of the setting of your channel.
+     * 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.
      *
+     * **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
      *
+     * **When to use:**
+     * - After the app is ready and the user has interacted (e.g., opted into beta program)
+     * - To implement in-app channel switching (beta toggle, tester access, etc.)
+     * - For user-driven channel changes
      *
-     * @param options Is the {@link SetChannelOptions} channel to set
-     * @returns {Promise<ChannelRes>} A Promise which is resolved when the new channel is set
-     * @throws {Error}
+     * **When NOT to use:**
+     * - At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead
+     * - Before user interaction
+     *
+     * This sends a request to the Capgo backend linking your device ID to the specified channel.
+     *
+     * @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.
+     * @throws {Error} If the channel doesn't exist or doesn't allow self-assignment.
      * @since 4.7.0
      */
     setChannel(options: SetChannelOptions): Promise<ChannelRes>;
     /**
-     * Unset the channel for this device. The device will then return to the default channel
+     * Remove the device's channel assignment and return to the default channel.
+     *
+     * This unlinks the device from any specifically assigned channel, causing it to fall back to:
+     * - The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or
+     * - Your backend's default channel for this app
      *
-     * @returns {Promise<ChannelRes>} A Promise resolved when channel is set
-     * @throws {Error}
+     * Use this when:
+     * - Users opt out of beta/testing programs
+     * - You want to reset a device to standard update distribution
+     * - Testing channel switching behavior
+     *
+     * @param options {@link UnsetChannelOptions} containing optional auto-update trigger.
+     * @returns {Promise<void>} Resolves when the channel is successfully unset.
+     * @throws {Error} If the operation fails.
      * @since 4.7.0
      */
     unsetChannel(options: UnsetChannelOptions): Promise<void>;
     /**
-     * Get the channel for this device
+     * Get the current channel assigned to this device.
+     *
+     * Returns information about:
+     * - `channel`: The currently assigned channel name (if any)
+     * - `allowSet`: Whether the channel allows self-assignment
+     * - `status`: Operation status
+     * - `error`/`message`: Additional information (if applicable)
+     *
+     * Use this to:
+     * - Display current channel to users (e.g., "You're on the Beta channel")
+     * - Check if a device is on a specific channel before showing features
+     * - Verify channel assignment after calling {@link setChannel}
      *
-     * @returns {Promise<ChannelRes>} A Promise that resolves with the channel info
-     * @throws {Error}
+     * @returns {Promise<GetChannelRes>} The current channel information.
+     * @throws {Error} If the operation fails.
      * @since 4.8.0
      */
     getChannel(): Promise<GetChannelRes>;
     /**
-     * List all channels available for this device that allow self-assignment
+     * Get a list of all channels available for this device to self-assign to.
      *
-     * @returns {Promise<ListChannelsResult>} A Promise that resolves with the available channels
-     * @throws {Error}
+     * Only returns channels where `allow_self_set` is `true`. These are channels that
+     * users can switch to using {@link setChannel} without backend administrator intervention.
+     *
+     * Each channel includes:
+     * - `id`: Unique channel identifier
+     * - `name`: Human-readable channel name
+     * - `public`: Whether the channel is publicly visible
+     * - `allow_self_set`: Always `true` in results (filtered to only self-assignable channels)
+     *
+     * Use this to:
+     * - Build a channel selector UI for users (e.g., "Join Beta" button)
+     * - Show available testing/preview channels
+     * - Implement channel discovery features
+     *
+     * @returns {Promise<ListChannelsResult>} List of channels the device can self-assign to.
+     * @throws {Error} If the operation fails or the request to the backend fails.
      * @since 7.5.0
      */
     listChannels(): Promise<ListChannelsResult>;
     /**
-     * Set a custom ID for this device
+     * Set a custom identifier for this device.
+     *
+     * This allows you to identify devices by your own custom ID (user ID, account ID, etc.)
+     * instead of or in addition to the device's unique hardware ID. The custom ID is sent
+     * to your update server and can be used for:
+     * - Targeting specific users for updates
+     * - Analytics and user tracking
+     * - Debugging and support (correlating devices with users)
+     * - A/B testing or feature flagging
      *
-     * When {@link PluginsConfig.CapacitorUpdater.persistCustomId} is true, the value will be stored natively and restored on the next app launch.
-     * Pass an empty string to remove any previously stored customId.
+     * **Persistence:**
+     * - When {@link PluginsConfig.CapacitorUpdater.persistCustomId} is `true`, the ID persists across app restarts
+     * - When `false`, the ID is only kept for the current session
      *
-     * @param options is the {@link SetCustomIdOptions} customId to set
-     * @returns {Promise<void>} an Promise resolved instantly
-     * @throws {Error}
+     * **Clearing the custom ID:**
+     * - Pass an empty string `""` to remove any stored custom ID
+     *
+     * @param options The {@link SetCustomIdOptions} containing the custom identifier string.
+     * @returns {Promise<void>} Resolves immediately (synchronous operation).
+     * @throws {Error} If the operation fails.
      * @since 4.9.0
      */
     setCustomId(options: SetCustomIdOptions): Promise<void>;
     /**
-     * Get the native app version or the builtin version if set in config
+     * Get the builtin bundle version (the original version shipped with your native app).
+     *
+     * This returns the version of the bundle that was included when the app was installed
+     * from the App Store or Play Store. This is NOT the currently active bundle version -
+     * use {@link current} for that.
+     *
+     * Returns:
+     * - The {@link PluginsConfig.CapacitorUpdater.version} config value if set, or
+     * - The native app version from platform configs (package.json, Info.plist, build.gradle)
      *
-     * @returns {Promise<BuiltinVersion>} A Promise with version for this device
+     * Use this to:
+     * - Display the "factory" version to users
+     * - Compare against downloaded bundle versions
+     * - Determine if any updates have been applied
+     * - Debugging version mismatches
+     *
+     * @returns {Promise<BuiltinVersion>} The builtin bundle version string.
      * @since 5.2.0
      */
     getBuiltinVersion(): Promise<BuiltinVersion>;
     /**
-     * Get unique ID used to identify device (sent to auto update server).
+     * Get the unique, privacy-friendly identifier for this device.
+     *
+     * This ID is used to identify the device when communicating with update servers.
+     * It's automatically generated and stored securely by the plugin.
+     *
+     * **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+)
+     * - iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
+     * - Not synced to cloud (iOS)
+     * - Follows Apple and Google privacy best practices
+     * - Users can clear it via system settings (Android) or keychain access (iOS)
      *
-     * This ID is privacy-friendly and follows Apple and Google best practices:
-     * - Generated as a UUID and stored securely
-     * - Android: Uses Android Keystore (persists across reinstalls on API 23+)
-     * - iOS: Uses Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly (persists across reinstalls)
-     * - Data stays on device (not synced to cloud on iOS)
-     * - Can be cleared by user via system settings (Android) or keychain access (iOS)
+     * **Persistence:**
+     * The device ID persists across app reinstalls to maintain consistent device identity
+     * for update tracking and analytics.
      *
-     * The device ID now persists between app reinstalls to maintain consistent device identity.
+     * Use this to:
+     * - Debug update delivery issues (check what ID the server sees)
+     * - Implement device-specific features
+     * - Correlate server logs with specific devices
      *
-     * @returns {Promise<DeviceId>} A Promise with id for this device
-     * @throws {Error}
+     * @returns {Promise<DeviceId>} The unique device identifier string.
+     * @throws {Error} If the operation fails.
      */
     getDeviceId(): Promise<DeviceId>;
     /**
-     * Get the native Capacitor Updater plugin version (sent to auto update server)
+     * Get the version of the Capacitor Updater plugin installed in your app.
      *
-     * @returns {Promise<PluginVersion>} A Promise with Plugin version
-     * @throws {Error}
+     * This returns the version of the native plugin code (Android/iOS), which is sent
+     * to the update server with each request. This is NOT your app version or bundle version.
+     *
+     * Use this to:
+     * - Debug plugin-specific issues (when reporting bugs)
+     * - Verify plugin installation and version
+     * - Check compatibility with backend features
+     * - Display in debug/about screens
+     *
+     * @returns {Promise<PluginVersion>} The Capacitor Updater plugin version string.
+     * @throws {Error} If the operation fails.
      */
     getPluginVersion(): Promise<PluginVersion>;
     /**
-     * Get the state of auto update config.
+     * Check if automatic updates are currently enabled.
+     *
+     * Returns `true` if {@link PluginsConfig.CapacitorUpdater.autoUpdate} is enabled,
+     * meaning the plugin will automatically check for, download, and apply updates.
      *
-     * @returns {Promise<AutoUpdateEnabled>} The status for auto update. Evaluates to `false` in manual mode.
-     * @throws {Error}
+     * Returns `false` if in manual mode, where you control the update flow using
+     * {@link getLatest}, {@link download}, {@link next}, and {@link set}.
+     *
+     * Use this to:
+     * - Determine which update flow your app is using
+     * - Show/hide manual update UI based on mode
+     * - Debug update behavior
+     *
+     * @returns {Promise<AutoUpdateEnabled>} `true` if auto-update is enabled, `false` if in manual mode.
+     * @throws {Error} If the operation fails.
      */
     isAutoUpdateEnabled(): Promise<AutoUpdateEnabled>;
     /**
-     * Remove all listeners for this plugin.
+     * Remove all event listeners registered for this plugin.
+     *
+     * This unregisters all listeners added via {@link addListener} for all event types:
+     * - `download`
+     * - `noNeedUpdate`
+     * - `updateAvailable`
+     * - `downloadComplete`
+     * - `downloadFailed`
+     * - `breakingAvailable` / `majorAvailable`
+     * - `updateFailed`
+     * - `appReloaded`
+     * - `appReady`
+     *
+     * Use this during cleanup (e.g., when unmounting components or closing screens)
+     * to prevent memory leaks from lingering event listeners.
      *
+     * @returns {Promise<void>} Resolves when all listeners are removed.
      * @since 1.0.0
      */
     removeAllListeners(): Promise<void>;
@@ -626,60 +949,150 @@ export interface CapacitorUpdaterPlugin {
      */
     addListener(eventName: 'appReady', listenerFunc: (state: AppReadyEvent) => void): Promise<PluginListenerHandle>;
     /**
-     * Get if auto update is available (not disabled by serverUrl).
+     * Check if the auto-update feature is available (not disabled by custom server configuration).
+     *
+     * Returns `false` when a custom `updateUrl` is configured, as this typically indicates
+     * you're using a self-hosted update server that may not support all auto-update features.
+     *
+     * Returns `true` when using the default Capgo backend or when the feature is available.
+     *
+     * This is different from {@link isAutoUpdateEnabled}:
+     * - `isAutoUpdateEnabled()`: Checks if auto-update MODE is turned on/off
+     * - `isAutoUpdateAvailable()`: Checks if auto-update is SUPPORTED with your current configuration
      *
-     * @returns {Promise<AutoUpdateAvailable>} The availability status for auto update. Evaluates to `false` when serverUrl is set.
-     * @throws {Error}
+     * @returns {Promise<AutoUpdateAvailable>} `false` when custom updateUrl is set, `true` otherwise.
+     * @throws {Error} If the operation fails.
      */
     isAutoUpdateAvailable(): Promise<AutoUpdateAvailable>;
     /**
-     * Get the next bundle that will be used when the app reloads.
-     * Returns null if no next bundle is set.
+     * Get information about the bundle queued to be activated on next reload.
      *
-     * @returns {Promise<BundleInfo | null>} A Promise that resolves with the next bundle information or null
-     * @throws {Error}
+     * Returns:
+     * - {@link BundleInfo} object if a bundle has been queued via {@link next}
+     * - `null` if no update is pending
+     *
+     * This is useful to:
+     * - Check if an update is waiting to be applied
+     * - Display "Update pending" status to users
+     * - Show version info of the queued update
+     * - Decide whether to show a "Restart to update" prompt
+     *
+     * The queued bundle will be activated when:
+     * - The app is backgrounded (default behavior)
+     * - The app is killed and restarted
+     * - {@link reload} is called manually
+     * - Delay conditions set by {@link setMultiDelay} are met
+     *
+     * @returns {Promise<BundleInfo | null>} The pending bundle info, or `null` if none is queued.
+     * @throws {Error} If the operation fails.
      * @since 6.8.0
      */
     getNextBundle(): Promise<BundleInfo | null>;
     /**
-     * Get the most recent update that failed to install, if any. The stored value is cleared after it is retrieved once.
+     * Retrieve information about the most recent bundle that failed to load.
+     *
+     * When a bundle fails to load (e.g., JavaScript errors prevent initialization, missing files),
+     * the plugin automatically rolls back and stores information about the failure. This method
+     * retrieves that failure information.
+     *
+     * **IMPORTANT: The stored value is cleared after being retrieved once.**
+     * Calling this method multiple times will only return the failure info on the first call,
+     * then `null` on subsequent calls until another failure occurs.
+     *
+     * Returns:
+     * - {@link UpdateFailedEvent} with bundle info if a failure was recorded
+     * - `null` if no failure has occurred or if it was already retrieved
      *
-     * @returns {Promise<UpdateFailedEvent | null>} The last failed update or null when no failure has been recorded. Value is cleared after it is returned once.
-     * @throws {Error}
+     * Use this to:
+     * - Show users why an update failed
+     * - Log failure information for debugging
+     * - Implement custom error handling/reporting
+     * - Display rollback notifications
+     *
+     * @returns {Promise<UpdateFailedEvent | null>} The failed update info (cleared after first retrieval), or `null`.
+     * @throws {Error} If the operation fails.
      * @since 7.22.0
      */
     getFailedUpdate(): Promise<UpdateFailedEvent | null>;
     /**
-     * Enable or disable the shake menu for debugging/testing purposes
+     * Enable or disable the shake gesture menu for debugging and testing.
+     *
+     * 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
+     *
+     * 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
      *
-     * @param options Contains enabled boolean to enable or disable shake menu
-     * @returns {Promise<void>}
-     * @throws {Error}
+     * **Important:** Disable this in production builds or only enable for internal testers.
+     *
+     * Can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
+     *
+     * @param options {@link SetShakeMenuOptions} with `enabled: true` to enable or `enabled: false` to disable.
+     * @returns {Promise<void>} Resolves when the setting is applied.
+     * @throws {Error} If the operation fails.
      * @since 7.5.0
      */
     setShakeMenu(options: SetShakeMenuOptions): Promise<void>;
     /**
-     * Get the current state of the shake menu
+     * Check if the shake gesture debug menu 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}.
      *
-     * @returns {Promise<ShakeMenuEnabled>} The current state of shake menu
-     * @throws {Error}
+     * Use this to:
+     * - Check if debug features are enabled
+     * - Show/hide debug settings UI
+     * - Verify configuration during testing
+     *
+     * @returns {Promise<ShakeMenuEnabled>} Object with `enabled: true` or `enabled: false`.
+     * @throws {Error} If the operation fails.
      * @since 7.5.0
      */
     isShakeMenuEnabled(): Promise<ShakeMenuEnabled>;
     /**
-     * Get the configured App ID
+     * Get the currently configured App ID used for update server communication.
+     *
+     * Returns the App ID that identifies this app to the update server. This can be:
+     * - The value set via {@link setAppId}, or
+     * - The {@link PluginsConfig.CapacitorUpdater.appId} config value, or
+     * - The default app identifier from your native app configuration
+     *
+     * Use this to:
+     * - Verify which App ID is being used for updates
+     * - Debug update delivery issues
+     * - Display app configuration in debug screens
+     * - Confirm App ID after calling {@link setAppId}
      *
-     * @returns {Promise<GetAppIdRes>} The current App ID
-     * @throws {Error}
+     * @returns {Promise<GetAppIdRes>} Object containing the current `appId` string.
+     * @throws {Error} If the operation fails.
      * @since 7.14.0
      */
     getAppId(): Promise<GetAppIdRes>;
     /**
-     * Set the App ID for the app (requires allowModifyAppId to be true in config)
+     * Dynamically change the App ID used for update server communication.
+     *
+     * This overrides the App ID used to identify your app to the update server, allowing you
+     * to switch between different app configurations at runtime (e.g., production vs staging
+     * app IDs, or multi-tenant configurations).
+     *
+     * **Requirements:**
+     * - {@link PluginsConfig.CapacitorUpdater.allowModifyAppId} must be set to `true`
+     *
+     * **Important considerations:**
+     * - Changing the App ID will affect which updates this device receives
+     * - The new App ID must exist on your update server
+     * - This is primarily for advanced use cases (multi-tenancy, environment switching)
+     * - Most apps should use the config-based {@link PluginsConfig.CapacitorUpdater.appId} instead
      *
-     * @param options The new App ID to set
-     * @returns {Promise<void>}
-     * @throws {Error} If allowModifyAppId is false or if the operation fails
+     * @param options {@link SetAppIdOptions} containing the new App ID string.
+     * @returns {Promise<void>} Resolves when the App ID is successfully changed.
+     * @throws {Error} If `allowModifyAppId` is false or the operation fails.
      * @since 7.14.0
      */
     setAppId(options: SetAppIdOptions): Promise<void>;