@capgo/capacitor-updater 7.42.9 → 7.45.10

package/dist/esm/definitions.d.ts

@@ -330,6 +330,20 @@ declare module '@capacitor/cli' {
              * @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).
+             *
+             * 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.
+             *
+             * Only available for Android and iOS.
+             *
+             * @default false
+             * @since 8.43.0
+             */
+            allowShakeChannelSelector?: boolean;
         };
     }
 }
@@ -554,7 +568,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.
      */
@@ -678,27 +695,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);
-     *   }
      * }
      * ```
      *
@@ -708,7 +721,7 @@ 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>;
@@ -924,6 +937,7 @@ export interface CapacitorUpdaterPlugin {
      * This unregisters all listeners added via {@link addListener} for all event types:
      * - `download`
      * - `noNeedUpdate`
+     * - `updateCheckResult`
      * - `updateAvailable`
      * - `downloadComplete`
      * - `downloadFailed`
@@ -952,6 +966,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
      *
@@ -984,6 +1009,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
      *
@@ -997,7 +1036,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
      */
@@ -1143,6 +1184,35 @@ export interface CapacitorUpdaterPlugin {
      * @since 7.5.0
      */
     isShakeMenuEnabled(): Promise<ShakeMenuEnabled>;
+    /**
+     * Enable or disable the shake channel selector 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.
+     *
+     * After selecting a channel, the app automatically checks for updates
+     * and downloads if available.
+     *
+     * Can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
+     *
+     * @param options {@link SetShakeChannelSelectorOptions} 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 8.43.0
+     */
+    setShakeChannelSelector(options: SetShakeChannelSelectorOptions): Promise<void>;
+    /**
+     * Check if the shake channel selector is currently enabled.
+     *
+     * Returns the current state of the shake channel selector feature that can be toggled via
+     * {@link setShakeChannelSelector} or configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
+     *
+     * @returns {Promise<ShakeChannelSelectorEnabled>} Object with `enabled: true` or `enabled: false`.
+     * @throws {Error} If the operation fails.
+     * @since 8.43.0
+     */
+    isShakeChannelSelectorEnabled(): Promise<ShakeChannelSelectorEnabled>;
     /**
      * Get the currently configured App ID used for update server communication.
      *
@@ -1314,6 +1384,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.
@@ -1322,6 +1400,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.
@@ -1434,9 +1550,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
      */
@@ -1485,12 +1619,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).
      */
@@ -1603,7 +1746,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 {
     /**
@@ -1641,6 +1796,12 @@ export interface SetShakeMenuOptions {
 export interface ShakeMenuEnabled {
     enabled: boolean;
 }
+export interface SetShakeChannelSelectorOptions {
+    enabled: boolean;
+}
+export interface ShakeChannelSelectorEnabled {
+    enabled: boolean;
+}
 export interface GetAppIdRes {
     appId: string;
 }