@capgo/capacitor-updater 7.38.0 → 7.40.0

package/dist/esm/definitions.d.ts

@@ -1,323 +1,4 @@
 import type { PluginListenerHandle } from '@capacitor/core';
-declare module '@capacitor/cli' {
-    interface PluginsConfig {
-        /**
-         * CapacitorUpdater can be configured with these options:
-         */
-        CapacitorUpdater?: {
-            /**
-             * Configure the number of milliseconds the native plugin should wait before considering an update 'failed'.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default 10000 // (10 seconds)
-             * @example 1000 // (1 second, minimum 1000)
-             */
-            appReadyTimeout?: number;
-            /**
-             * Configure the number of seconds the native plugin should wait before considering API timeout.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default 20 // (20 second)
-             * @example 10 // (10 second)
-             */
-            responseTimeout?: number;
-            /**
-             * Configure whether the plugin should use automatically delete failed bundles.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default true
-             * @example false
-             */
-            autoDeleteFailed?: boolean;
-            /**
-             * Configure whether the plugin should use automatically delete previous bundles after a successful update.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default true
-             * @example false
-             */
-            autoDeletePrevious?: boolean;
-            /**
-             * Configure whether the plugin should use Auto Update via an update server.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default true
-             * @example false
-             */
-            autoUpdate?: boolean;
-            /**
-             * 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.
-             * Only available for Android and iOS.
-             *
-             * @default true
-             * @example false
-             */
-            resetWhenUpdate?: boolean;
-            /**
-             * Configure the URL / endpoint to which update checks are sent.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default https://plugin.capgo.app/updates
-             * @example https://example.com/api/auto_update
-             */
-            updateUrl?: string;
-            /**
-             * Configure the URL / endpoint for channel operations.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default https://plugin.capgo.app/channel_self
-             * @example https://example.com/api/channel
-             */
-            channelUrl?: string;
-            /**
-             * Configure the URL / endpoint to which update statistics are sent.
-             *
-             * Only available for Android and iOS. Set to "" to disable stats reporting.
-             *
-             * @default https://plugin.capgo.app/stats
-             * @example https://example.com/api/stats
-             */
-            statsUrl?: string;
-            /**
-             * Configure the public key for end to end live update encryption Version 2
-             *
-             * Only available for Android and iOS.
-             *
-             * @default undefined
-             * @since 6.2.0
-             */
-            publicKey?: string;
-            /**
-             * Configure the current version of the app. This will be used for the first update request.
-             * If not set, the plugin will get the version from the native code.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default undefined
-             * @since  4.17.48
-             */
-            version?: string;
-            /**
-             * Configure when the plugin should direct install updates. Only for autoUpdate mode.
-             * Works well for apps less than 10MB and with uploads done using --partial 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
-             * - true: (deprecated) Same as "always" for backward compatibility
-             *
-             * Only available for Android and iOS.
-             *
-             * @default false
-             * @since  5.1.0
-             */
-            directUpdate?: boolean | 'atInstall' | 'always' | 'onLaunch';
-            /**
-             * 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.
-             * Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false.
-             * Requires autoUpdate and directUpdate to be enabled.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default false
-             * @since  7.6.0
-             */
-            autoSplashscreen?: boolean;
-            /**
-             * Display a native loading indicator on top of the splashscreen while automatic direct updates are running.
-             * Only takes effect when {@link autoSplashscreen} is enabled.
-             * Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default false
-             * @since  7.19.0
-             */
-            autoSplashscreenLoader?: boolean;
-            /**
-             * Automatically hide the splashscreen after the specified number of milliseconds when using automatic direct updates.
-             * If the timeout elapses, the update continues to download in the background while the splashscreen is dismissed.
-             * Set to `0` (zero) to disable the timeout.
-             * When the timeout fires, the direct update flow is skipped and the downloaded bundle is installed on the next background/launch.
-             * Requires {@link autoSplashscreen} to be enabled.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default 10000 // (10 seconds)
-             * @since  7.19.0
-             */
-            autoSplashscreenTimeout?: number;
-            /**
-             * Configure the delay period for period update check. the unit is in seconds.
-             *
-             * Only available for Android and iOS.
-             * Cannot be less than 600 seconds (10 minutes).
-             *
-             * @default 0 (disabled)
-             * @example 3600 (1 hour)
-             * @example 86400 (24 hours)
-             */
-            periodCheckDelay?: number;
-            /**
-             * Configure the CLI to use a local server for testing or self-hosted update server.
-             *
-             *
-             * @default undefined
-             * @since  4.17.48
-             */
-            localS3?: boolean;
-            /**
-             * Configure the CLI to use a local server for testing or self-hosted update server.
-             *
-             *
-             * @default undefined
-             * @since  4.17.48
-             */
-            localHost?: string;
-            /**
-             * Configure the CLI to use a local server for testing or self-hosted update server.
-             *
-             *
-             * @default undefined
-             * @since  4.17.48
-             */
-            localWebHost?: string;
-            /**
-             * Configure the CLI to use a local server for testing or self-hosted update server.
-             *
-             *
-             * @default undefined
-             * @since  4.17.48
-             */
-            localSupa?: string;
-            /**
-             * Configure the CLI to use a local server for testing.
-             *
-             *
-             * @default undefined
-             * @since  4.17.48
-             */
-            localSupaAnon?: string;
-            /**
-             * Configure the CLI to use a local api for testing.
-             *
-             *
-             * @default undefined
-             * @since  6.3.3
-             */
-            localApi?: string;
-            /**
-             * Configure the CLI to use a local file api for testing.
-             *
-             *
-             * @default undefined
-             * @since  6.3.3
-             */
-            localApiFiles?: string;
-            /**
-             * Allow the plugin to modify the updateUrl, statsUrl and channelUrl dynamically from the JavaScript side.
-             *
-             *
-             * @default false
-             * @since  5.4.0
-             */
-            allowModifyUrl?: boolean;
-            /**
-             * Allow the plugin to modify the appId dynamically from the JavaScript side.
-             *
-             *
-             * @default false
-             * @since  7.14.0
-             */
-            allowModifyAppId?: boolean;
-            /**
-             * Allow marking bundles as errored from JavaScript while using manual update flows.
-             * When enabled, {@link CapacitorUpdaterPlugin.setBundleError} can change a bundle status to `error`.
-             *
-             * @default false
-             * @since 7.20.0
-             */
-            allowManualBundleError?: boolean;
-            /**
-             * Persist the customId set through {@link CapacitorUpdaterPlugin.setCustomId} across app restarts.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default false (will be true by default in a future major release v8.x.x)
-             * @since  7.17.3
-             */
-            persistCustomId?: boolean;
-            /**
-             * Persist the updateUrl, statsUrl and channelUrl set through {@link CapacitorUpdaterPlugin.setUpdateUrl},
-             * {@link CapacitorUpdaterPlugin.setStatsUrl} and {@link CapacitorUpdaterPlugin.setChannelUrl} across app restarts.
-             *
-             * Only available for Android and iOS.
-             *
-             * @default false
-             * @since  7.20.0
-             */
-            persistModifyUrl?: boolean;
-            /**
-             * Allow or disallow the {@link CapacitorUpdaterPlugin.setChannel} method to modify the defaultChannel.
-             * When set to `false`, calling `setChannel()` will return an error with code `disabled_by_config`.
-             *
-             * @default true
-             * @since 7.34.0
-             */
-            allowSetDefaultChannel?: boolean;
-            /**
-             * Set the default channel for the app in the config. Case sensitive.
-             * This will setting will override the default channel set in the cloud, but will still respect overrides made in the cloud.
-             * This requires the channel to allow devices to self dissociate/associate in the channel settings. https://capgo.app/docs/public-api/channels/#channel-configuration-options
-             *
-             *
-             * @default undefined
-             * @since  5.5.0
-             */
-            defaultChannel?: string;
-            /**
-             * Configure the app id for the app in the config.
-             *
-             * @default undefined
-             * @since  6.0.0
-             */
-            appId?: string;
-            /**
-             * Configure the plugin to keep the URL path after a reload.
-             * WARNING: When a reload is triggered, 'window.history' will be cleared.
-             *
-             * @default false
-             * @since  6.8.0
-             */
-            keepUrlPathAfterReload?: boolean;
-            /**
-             * Disable the JavaScript logging of the plugin. if true, the plugin will not log to the JavaScript console. only the native log will be done
-             *
-             * @default false
-             * @since  7.3.0
-             */
-            disableJSLogging?: boolean;
-            /**
-             * Enable shake gesture to show update menu for debugging/testing purposes
-             *
-             * @default false
-             * @since  7.5.0
-             */
-            shakeMenu?: boolean;
-        };
-    }
-}
 export interface CapacitorUpdaterPlugin {
     /**
      * Notify the native layer that JavaScript initialized successfully.
@@ -998,6 +679,29 @@ export interface CapacitorUpdaterPlugin {
      * @since 7.34.0
      */
     addListener(eventName: 'channelPrivate', listenerFunc: (state: ChannelPrivateEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for flexible update state changes on Android.
+     *
+     * This event fires during the flexible update download process, providing:
+     * - Download progress (bytes downloaded / total bytes)
+     * - Installation status changes
+     *
+     * **Install status values:**
+     * - `UNKNOWN` (0): Unknown status
+     * - `PENDING` (1): Download pending
+     * - `DOWNLOADING` (2): Download in progress
+     * - `INSTALLING` (3): Installing the update
+     * - `INSTALLED` (4): Update installed (app restart needed)
+     * - `FAILED` (5): Update failed
+     * - `CANCELED` (6): Update was canceled
+     * - `DOWNLOADED` (11): Download complete, ready to install
+     *
+     * When status is `DOWNLOADED`, you should prompt the user and call
+     * {@link completeFlexibleUpdate} to finish the installation.
+     *
+     * @since 8.0.0
+     */
+    addListener(eventName: 'onFlexibleUpdateStateChange', listenerFunc: (state: FlexibleUpdateState) => void): Promise<PluginListenerHandle>;
     /**
      * Check if the auto-update feature is available (not disabled by custom server configuration).
      *
@@ -1146,6 +850,127 @@ export interface CapacitorUpdaterPlugin {
      * @since 7.14.0
      */
     setAppId(options: SetAppIdOptions): Promise<void>;
+    /**
+     * Get information about the app's availability in the App Store or Play Store.
+     *
+     * This method checks the native app stores to see if a newer version of the app
+     * is available for download. This is different from Capgo's OTA updates - this
+     * checks for native app updates that require going through the app stores.
+     *
+     * **Platform differences:**
+     * - **Android**: Uses Play Store's In-App Updates API for accurate update information
+     * - **iOS**: Queries the App Store lookup API (requires country code for accurate results)
+     *
+     * **Returns information about:**
+     * - Current installed version
+     * - Available version in the store (if any)
+     * - Whether an update is available
+     * - Update priority (Android only)
+     * - Whether immediate/flexible updates are allowed (Android only)
+     *
+     * Use this to:
+     * - Check if users need to update from the app store
+     * - Show "Update Available" prompts for native updates
+     * - Implement version gating (require minimum native version)
+     * - Combine with Capgo OTA updates for a complete update strategy
+     *
+     * @param options Optional {@link GetAppUpdateInfoOptions} with country code for iOS.
+     * @returns {Promise<AppUpdateInfo>} Information about the current and available app versions.
+     * @throws {Error} If the operation fails or store information is unavailable.
+     * @since 8.0.0
+     */
+    getAppUpdateInfo(options?: GetAppUpdateInfoOptions): Promise<AppUpdateInfo>;
+    /**
+     * Open the app's page in the App Store or Play Store.
+     *
+     * This navigates the user to your app's store listing where they can manually
+     * update the app. Use this as a fallback when in-app updates are not available
+     * or when the user needs to update on iOS.
+     *
+     * **Platform behavior:**
+     * - **Android**: Opens Play Store to the app's page
+     * - **iOS**: Opens App Store to the app's page
+     *
+     * **Customization options:**
+     * - `appId`: Specify a custom App Store ID (iOS) - useful for opening a different app's page
+     * - `packageName`: Specify a custom package name (Android) - useful for opening a different app's page
+     *
+     * @param options Optional {@link OpenAppStoreOptions} to customize which app's store page to open.
+     * @returns {Promise<void>} Resolves when the store is opened.
+     * @throws {Error} If the store cannot be opened.
+     * @since 8.0.0
+     */
+    openAppStore(options?: OpenAppStoreOptions): Promise<void>;
+    /**
+     * Perform an immediate in-app update on Android.
+     *
+     * This triggers Google Play's immediate update flow, which:
+     * 1. Shows a full-screen update UI
+     * 2. Downloads and installs the update
+     * 3. Restarts the app automatically
+     *
+     * The user cannot continue using the app until the update is complete.
+     * This is ideal for critical updates that must be installed immediately.
+     *
+     * **Requirements:**
+     * - Android only (throws error on iOS)
+     * - An update must be available (check with {@link getAppUpdateInfo} first)
+     * - The update must allow immediate updates (`immediateUpdateAllowed: true`)
+     *
+     * **User experience:**
+     * - Full-screen blocking UI
+     * - Progress shown during download
+     * - App automatically restarts after installation
+     *
+     * @returns {Promise<AppUpdateResult>} Result indicating success, cancellation, or failure.
+     * @throws {Error} If not on Android, no update is available, or immediate updates not allowed.
+     * @since 8.0.0
+     */
+    performImmediateUpdate(): Promise<AppUpdateResult>;
+    /**
+     * Start a flexible in-app update on Android.
+     *
+     * This triggers Google Play's flexible update flow, which:
+     * 1. Downloads the update in the background
+     * 2. Allows the user to continue using the app
+     * 3. Notifies when download is complete
+     * 4. Requires calling {@link completeFlexibleUpdate} to install
+     *
+     * Monitor the download progress using the `onFlexibleUpdateStateChange` listener.
+     *
+     * **Requirements:**
+     * - Android only (throws error on iOS)
+     * - An update must be available (check with {@link getAppUpdateInfo} first)
+     * - The update must allow flexible updates (`flexibleUpdateAllowed: true`)
+     *
+     * **Typical flow:**
+     * 1. Call `startFlexibleUpdate()` to begin download
+     * 2. Listen to `onFlexibleUpdateStateChange` for progress
+     * 3. When status is `DOWNLOADED`, prompt user to restart
+     * 4. Call `completeFlexibleUpdate()` to install and restart
+     *
+     * @returns {Promise<AppUpdateResult>} Result indicating the update was started, cancelled, or failed.
+     * @throws {Error} If not on Android, no update is available, or flexible updates not allowed.
+     * @since 8.0.0
+     */
+    startFlexibleUpdate(): Promise<AppUpdateResult>;
+    /**
+     * Complete a flexible in-app update on Android.
+     *
+     * After a flexible update has been downloaded (status `DOWNLOADED` in
+     * `onFlexibleUpdateStateChange`), call this method to install the update
+     * and restart the app.
+     *
+     * **Important:** This will immediately restart the app. Make sure to:
+     * - Save any user data before calling
+     * - Prompt the user before restarting
+     * - Only call when the download status is `DOWNLOADED`
+     *
+     * @returns {Promise<void>} Resolves when the update installation begins (app will restart).
+     * @throws {Error} If not on Android or no downloaded update is pending.
+     * @since 8.0.0
+     */
+    completeFlexibleUpdate(): Promise<void>;
 }
 /**
  * pending: The bundle is pending to be **SET** as the next bundle.
@@ -1488,3 +1313,285 @@ export interface GetAppIdRes {
 export interface SetAppIdOptions {
     appId: string;
 }
+/**
+ * Options for {@link CapacitorUpdaterPlugin.getAppUpdateInfo}.
+ *
+ * @since 8.0.0
+ */
+export interface GetAppUpdateInfoOptions {
+    /**
+     * Two-letter country code (ISO 3166-1 alpha-2) for the App Store lookup.
+     *
+     * This is required on iOS to get accurate App Store information, as app
+     * availability and versions can vary by country.
+     *
+     * Examples: "US", "GB", "DE", "JP", "FR"
+     *
+     * On Android, this option is ignored as the Play Store handles region
+     * detection automatically.
+     *
+     * @since 8.0.0
+     */
+    country?: string;
+}
+/**
+ * Information about app updates available in the App Store or Play Store.
+ *
+ * @since 8.0.0
+ */
+export interface AppUpdateInfo {
+    /**
+     * The currently installed version name (e.g., "1.2.3").
+     *
+     * @since 8.0.0
+     */
+    currentVersionName: string;
+    /**
+     * The version name available in the store, if an update is available.
+     * May be undefined if no update information is available.
+     *
+     * @since 8.0.0
+     */
+    availableVersionName?: string;
+    /**
+     * The currently installed version code (Android) or build number (iOS).
+     *
+     * @since 8.0.0
+     */
+    currentVersionCode: string;
+    /**
+     * The version code available in the store (Android only).
+     * On iOS, this will be the same as `availableVersionName`.
+     *
+     * @since 8.0.0
+     */
+    availableVersionCode?: string;
+    /**
+     * The release date of the available version (iOS only).
+     * Format: ISO 8601 date string.
+     *
+     * @since 8.0.0
+     */
+    availableVersionReleaseDate?: string;
+    /**
+     * The current update availability status.
+     *
+     * @since 8.0.0
+     */
+    updateAvailability: AppUpdateAvailability;
+    /**
+     * The priority of the update as set by the developer in Play Console (Android only).
+     * Values range from 0 (default/lowest) to 5 (highest priority).
+     *
+     * Use this to decide whether to show an update prompt or force an update.
+     *
+     * @since 8.0.0
+     */
+    updatePriority?: number;
+    /**
+     * Whether an immediate update is allowed (Android only).
+     *
+     * If `true`, you can call {@link CapacitorUpdaterPlugin.performImmediateUpdate}.
+     *
+     * @since 8.0.0
+     */
+    immediateUpdateAllowed?: boolean;
+    /**
+     * Whether a flexible update is allowed (Android only).
+     *
+     * If `true`, you can call {@link CapacitorUpdaterPlugin.startFlexibleUpdate}.
+     *
+     * @since 8.0.0
+     */
+    flexibleUpdateAllowed?: boolean;
+    /**
+     * Number of days since the update became available (Android only).
+     *
+     * Use this to implement "update nagging" - remind users more frequently
+     * as the update ages.
+     *
+     * @since 8.0.0
+     */
+    clientVersionStalenessDays?: number;
+    /**
+     * The current install status of a flexible update (Android only).
+     *
+     * @since 8.0.0
+     */
+    installStatus?: FlexibleUpdateInstallStatus;
+    /**
+     * The minimum OS version required for the available update (iOS only).
+     *
+     * @since 8.0.0
+     */
+    minimumOsVersion?: string;
+}
+/**
+ * Options for {@link CapacitorUpdaterPlugin.openAppStore}.
+ *
+ * @since 8.0.0
+ */
+export interface OpenAppStoreOptions {
+    /**
+     * The Android package name to open in the Play Store.
+     *
+     * If not specified, uses the current app's package name.
+     * Use this to open a different app's store page.
+     *
+     * Only used on Android.
+     *
+     * @since 8.0.0
+     */
+    packageName?: string;
+    /**
+     * The iOS App Store ID to open.
+     *
+     * If not specified, uses the current app's bundle identifier to look up the app.
+     * Use this to open a different app's store page or when automatic lookup fails.
+     *
+     * Only used on iOS.
+     *
+     * @since 8.0.0
+     */
+    appId?: string;
+}
+/**
+ * State information for flexible update progress (Android only).
+ *
+ * @since 8.0.0
+ */
+export interface FlexibleUpdateState {
+    /**
+     * The current installation status.
+     *
+     * @since 8.0.0
+     */
+    installStatus: FlexibleUpdateInstallStatus;
+    /**
+     * Number of bytes downloaded so far.
+     * Only available during the `DOWNLOADING` status.
+     *
+     * @since 8.0.0
+     */
+    bytesDownloaded?: number;
+    /**
+     * Total number of bytes to download.
+     * Only available during the `DOWNLOADING` status.
+     *
+     * @since 8.0.0
+     */
+    totalBytesToDownload?: number;
+}
+/**
+ * Result of an app update operation.
+ *
+ * @since 8.0.0
+ */
+export interface AppUpdateResult {
+    /**
+     * The result code of the update operation.
+     *
+     * @since 8.0.0
+     */
+    code: AppUpdateResultCode;
+}
+/**
+ * Update availability status.
+ *
+ * @since 8.0.0
+ */
+export declare enum AppUpdateAvailability {
+    /**
+     * Update availability is unknown.
+     * This typically means the check hasn't completed or failed.
+     */
+    UNKNOWN = 0,
+    /**
+     * No update is available.
+     * The installed version is the latest.
+     */
+    UPDATE_NOT_AVAILABLE = 1,
+    /**
+     * An update is available for download.
+     */
+    UPDATE_AVAILABLE = 2,
+    /**
+     * An update is currently being downloaded or installed.
+     */
+    UPDATE_IN_PROGRESS = 3
+}
+/**
+ * Installation status for flexible updates (Android only).
+ *
+ * @since 8.0.0
+ */
+export declare enum FlexibleUpdateInstallStatus {
+    /**
+     * Unknown install status.
+     */
+    UNKNOWN = 0,
+    /**
+     * Download is pending and will start soon.
+     */
+    PENDING = 1,
+    /**
+     * Download is in progress.
+     * Check `bytesDownloaded` and `totalBytesToDownload` for progress.
+     */
+    DOWNLOADING = 2,
+    /**
+     * The update is being installed.
+     */
+    INSTALLING = 3,
+    /**
+     * The update has been installed.
+     * The app needs to be restarted to use the new version.
+     */
+    INSTALLED = 4,
+    /**
+     * The update failed to download or install.
+     */
+    FAILED = 5,
+    /**
+     * The update was canceled by the user.
+     */
+    CANCELED = 6,
+    /**
+     * The update has been downloaded and is ready to install.
+     * Call {@link CapacitorUpdaterPlugin.completeFlexibleUpdate} to install.
+     */
+    DOWNLOADED = 11
+}
+/**
+ * Result codes for app update operations.
+ *
+ * @since 8.0.0
+ */
+export declare enum AppUpdateResultCode {
+    /**
+     * The update completed successfully.
+     */
+    OK = 0,
+    /**
+     * The user canceled the update.
+     */
+    CANCELED = 1,
+    /**
+     * The update failed.
+     */
+    FAILED = 2,
+    /**
+     * No update is available.
+     */
+    NOT_AVAILABLE = 3,
+    /**
+     * The requested update type is not allowed.
+     * For example, trying to perform an immediate update when only flexible is allowed.
+     */
+    NOT_ALLOWED = 4,
+    /**
+     * Required information is missing.
+     * This can happen if {@link CapacitorUpdaterPlugin.getAppUpdateInfo} wasn't called first.
+     */
+    INFO_MISSING = 5
+}