@capgo/capacitor-updater 8.51.0 → 8.51.2

package/android/src/main/java/ee/forgr/capacitor_updater/CapgoUpdater.java

@@ -39,7 +39,9 @@ import java.security.SecureRandom;
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.Iterator;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -72,14 +74,20 @@ public class CapgoUpdater {
     private static final String FALLBACK_VERSION = "pastVersion";
     private static final String NEXT_VERSION = "nextVersion";
     private static final String PREVIEW_FALLBACK_VERSION = "previewFallbackVersion";
+    private static final String PENDING_DELETE_IDS = "pendingDeleteIds";
     private static final String bundleDirectory = "versions";
     private static final String TEMP_UNZIP_PREFIX = "capgo_unzip_";
+    private static final long DELETE_PACE_MS = 75L;
+    private final Object deleteLock = new Object();
     private static final String CAPACITOR_CONFIG_ASSET = "capacitor.config.json";
     private static final String BACKGROUND_RUNNER_CONFIG_KEY = "BackgroundRunner";
     private static final String BACKGROUND_RUNNER_WORKER_CLASS = "io.ionic.backgroundrunner.plugin.RunnerWorker";
 
     public static final String TAG = "Capacitor-updater";
     public SharedPreferences.Editor editor;
+
+    /** Optional gate run before any download touches disk (e.g. wait for launch cleanup). */
+    public Runnable downloadGate = null;
     public SharedPreferences prefs;
 
     public File documentsDir;
@@ -136,7 +144,7 @@ public class CapgoUpdater {
 
     private final FilenameFilter filter = (f, name) -> {
         // ignore directories generated by mac os x
-        return (!name.startsWith("__MACOSX") && !name.startsWith(".") && !name.startsWith(".DS_Store"));
+        return !name.startsWith("__MACOSX") && !name.startsWith(".") && !name.startsWith(".DS_Store");
     };
 
     private boolean isProd() {
@@ -927,6 +935,11 @@ public class CapgoUpdater {
 
                 try {
                     this.deleteDirectory(entry, threadToCheck);
+                    if (entry.exists()) {
+                        logger.error("Orphan bundle directory still present after delete");
+                        logger.debug("Bundle ID: " + id);
+                        continue;
+                    }
                     this.removeBundleInfo(id);
                     logger.info("Deleted orphan bundle directory");
                     logger.debug("Bundle ID: " + id);
@@ -938,6 +951,43 @@ public class CapgoUpdater {
         }
     }
 
+    public Set<String> allowedBundleIdsForCleanup() {
+        final Set<String> allowedIds = new HashSet<>();
+        for (final BundleInfo info : this.list(true)) {
+            if (info == null || info.getId() == null || info.getId().isEmpty()) {
+                continue;
+            }
+            // DELETED tombstones must not protect leftover folders.
+            // DELETING stays protected so drainPendingDeletes owns the removal.
+            if (info.isDeleted()) {
+                continue;
+            }
+            allowedIds.add(info.getId());
+        }
+        final String currentId = this.getCurrentBundleId();
+        if (currentId != null && !currentId.isEmpty()) {
+            allowedIds.add(currentId);
+        }
+        final BundleInfo fallback = this.getFallbackBundle();
+        if (fallback != null && fallback.getId() != null && !fallback.getId().isEmpty() && !fallback.isDeleting()) {
+            allowedIds.add(fallback.getId());
+        }
+        final BundleInfo next = this.getNextBundle();
+        if (next != null && next.getId() != null && !next.getId().isEmpty() && !next.isDeleting()) {
+            allowedIds.add(next.getId());
+        }
+        final BundleInfo previewFallback = this.getPreviewFallbackBundle();
+        if (
+            previewFallback != null &&
+            previewFallback.getId() != null &&
+            !previewFallback.getId().isEmpty() &&
+            !previewFallback.isDeleting()
+        ) {
+            allowedIds.add(previewFallback.getId());
+        }
+        return allowedIds;
+    }
+
     public void cleanupOrphanedTempFolders(final Thread threadToCheck) {
         if (this.documentsDir == null) {
             logger.warn("Documents directory is null, skipping temp folder cleanup");
@@ -1221,6 +1271,27 @@ public class CapgoUpdater {
         );
     }
 
+    private void runDownloadGate() throws IOException {
+        if (this.downloadGate == null) {
+            return;
+        }
+        try {
+            this.downloadGate.run();
+        } catch (final RuntimeException e) {
+            throw new IOException(e.getMessage() == null ? "Download gate failed" : e.getMessage(), e);
+        }
+    }
+
+    private boolean runDownloadGateQuiet() {
+        try {
+            this.runDownloadGate();
+            return true;
+        } catch (final IOException e) {
+            logger.error("Download blocked by cleanup gate: " + e.getMessage());
+            return false;
+        }
+    }
+
     public void downloadBackground(
         final String url,
         final String version,
@@ -1239,6 +1310,9 @@ public class CapgoUpdater {
         final JSONArray manifest,
         final boolean setNext
     ) {
+        if (!this.runDownloadGateQuiet()) {
+            return;
+        }
         final String id = this.randomString();
 
         // Check if version is already downloading, but allow retry if previous download failed
@@ -1263,9 +1337,10 @@ public class CapgoUpdater {
     }
 
     public BundleInfo download(final String url, final String version, final String sessionKey, final String checksum) throws IOException {
+        this.runDownloadGate();
         // Check for existing bundle with same version and clean up if in error state
         BundleInfo existingBundle = this.getBundleInfoByName(version);
-        if (existingBundle != null && (existingBundle.isErrorStatus() || existingBundle.isDeleted())) {
+        if (existingBundle != null && (existingBundle.isErrorStatus() || existingBundle.isDeleted() || existingBundle.isDeleting())) {
             logger.info("Found existing failed bundle for version " + version + ", deleting before retry");
             this.delete(existingBundle.getId(), true);
         }
@@ -1311,13 +1386,14 @@ public class CapgoUpdater {
         final String checksum,
         final JSONArray manifest
     ) throws IOException {
+        this.runDownloadGate();
         if (manifest == null) {
             return download(url, version, sessionKey, checksum);
         }
 
         // Check for existing bundle with same version and clean up if in error state
         BundleInfo existingBundle = this.getBundleInfoByName(version);
-        if (existingBundle != null && (existingBundle.isErrorStatus() || existingBundle.isDeleted())) {
+        if (existingBundle != null && (existingBundle.isErrorStatus() || existingBundle.isDeleted() || existingBundle.isDeleting())) {
             logger.info("Found existing failed bundle for version " + version + ", deleting before retry");
             this.delete(existingBundle.getId(), true);
         }
@@ -1384,51 +1460,93 @@ public class CapgoUpdater {
     }
 
     public Boolean delete(final String id, final Boolean removeInfo) throws IOException {
-        final BundleInfo deleted = this.getBundleInfo(id);
-        if (deleted.isBuiltin() || this.getCurrentBundleId().equals(id)) {
-            logger.error("Cannot delete current or builtin bundle");
-            logger.debug("Bundle ID: " + id);
-            return false;
-        }
-        final BundleInfo previewFallback = this.getPreviewFallbackBundle();
-        if (
-            previewFallback != null &&
-            !previewFallback.isDeleted() &&
-            !previewFallback.isErrorStatus() &&
-            previewFallback.getId().equals(id)
-        ) {
-            logger.error("Cannot delete the preview fallback bundle");
-            logger.debug("Bundle ID: " + id);
-            return false;
-        }
-        final BundleInfo next = this.getNextBundle();
-        if (next != null && !next.isDeleted() && !next.isErrorStatus() && next.getId().equals(id)) {
-            logger.error("Cannot delete the next bundle");
-            logger.debug("Bundle ID: " + id);
-            return false;
-        }
-        // Cancel download for this version if active
-        if (this.activity != null) {
-            DownloadWorkerManager.cancelVersionDownload(this.activity, deleted.getVersionName());
-        }
-        final File bundle = new File(this.documentsDir, bundleDirectory + "/" + id);
-        if (bundle.exists()) {
-            this.deleteDirectory(bundle);
-            if (!removeInfo) {
-                this.saveBundleInfo(id, deleted.setStatus(BundleStatus.DELETED));
+        return this.delete(id, removeInfo, true);
+    }
+
+    public Boolean delete(final String id, final Boolean removeInfo, final boolean cancelActiveDownload) throws IOException {
+        synchronized (this.deleteLock) {
+            final BundleInfo deleted = this.getBundleInfo(id);
+            if (deleted.isBuiltin() || this.getCurrentBundleId().equals(id)) {
+                logger.error("Cannot delete current or builtin bundle");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+            final BundleInfo previewFallback = this.getPreviewFallbackBundle();
+            if (
+                previewFallback != null &&
+                !previewFallback.isDeleted() &&
+                !previewFallback.isErrorStatus() &&
+                !previewFallback.isDeleting() &&
+                previewFallback.getId().equals(id)
+            ) {
+                logger.error("Cannot delete the preview fallback bundle");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+            final BundleInfo next = this.getNextBundle();
+            if (next != null && !next.isDeleted() && !next.isErrorStatus() && !next.isDeleting() && next.getId().equals(id)) {
+                logger.error("Cannot delete the next bundle");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+
+            final File bundle = this.getBundleDirectory(id);
+            final boolean hadRegistry = this.hasStoredBundleInfo(id);
+            final boolean hadFolder = bundle.exists();
+            if (!hadRegistry && !hadFolder) {
+                logger.error("Cannot delete unknown bundle");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+
+            // Persist DELETING before touching disk so kill/OOM can resume on next launch.
+            if (!deleted.isDeleting()) {
+                if (!this.saveBundleInfo(id, deleted.setStatus(BundleStatus.DELETING))) {
+                    logger.error("Failed to persist DELETING marker, aborting disk delete");
+                    logger.debug("Bundle ID: " + id);
+                    return false;
+                }
+            }
+
+            // Cancel download for this version if active
+            if (cancelActiveDownload && this.activity != null) {
+                DownloadWorkerManager.cancelVersionDownload(this.activity, deleted.getVersionName());
+            }
+
+            if (bundle.exists()) {
+                try {
+                    this.deleteDirectory(bundle);
+                } catch (final IOException e) {
+                    logger.error("Failed to delete bundle folder, will retry later");
+                    logger.debug("Bundle ID: " + id + ", Error: " + e.getMessage());
+                    return false;
+                }
+            }
+
+            // Only drop registry after the folder is confirmed gone.
+            if (bundle.exists()) {
+                logger.error("Bundle folder still present after delete, will retry later");
+                logger.debug("Bundle ID: " + id);
+                return false;
+            }
+
+            final boolean finalized;
+            if (Boolean.FALSE.equals(removeInfo)) {
+                finalized = this.saveBundleInfo(id, deleted.setStatus(BundleStatus.DELETED));
             } else {
-                this.removeBundleInfo(id);
+                finalized = this.saveBundleInfo(id, null);
+            }
+            if (!finalized) {
+                logger.error("Failed to finalize delete registry update, will retry later");
+                logger.debug("Bundle ID: " + id);
+                return false;
             }
+            this.sendStats("delete", deleted.getVersionName());
+            this.dequeuePendingDelete(id);
+            logger.info("Bundle deleted and confirmed gone");
+            logger.debug("Bundle ID: " + id);
             return true;
         }
-        logger.info("Bundle not found on disk");
-        logger.debug("Version: " + deleted.getVersionName());
-        // perhaps we did not find the bundle in the files, but if the user requested a delete, we delete
-        if (removeInfo) {
-            this.removeBundleInfo(id);
-        }
-        this.sendStats("delete", deleted.getVersionName());
-        return false;
     }
 
     public Boolean delete(final String id) {
@@ -1441,6 +1559,82 @@ public class CapgoUpdater {
         }
     }
 
+    /**
+     * Resume incomplete deletes one-by-one. Safe across app kill / OOM because
+     * delete() marks DELETING before disk work and only clears registry after confirm.
+     */
+    public void drainPendingDeletes() {
+        final LinkedHashSet<String> pendingIds = new LinkedHashSet<>();
+        for (final BundleInfo info : this.list(true)) {
+            if (info != null && info.isDeleting() && info.getId() != null && !info.getId().isEmpty()) {
+                pendingIds.add(info.getId());
+            }
+        }
+        pendingIds.addAll(this.getPendingDeleteIds());
+        for (final String id : pendingIds) {
+            try {
+                logger.info("Resuming pending delete for bundle: " + id);
+                if (Boolean.TRUE.equals(this.delete(id, true))) {
+                    this.dequeuePendingDelete(id);
+                }
+            } catch (final Exception e) {
+                logger.error("Pending delete failed, will retry next launch");
+                logger.debug("Bundle ID: " + id + ", Error: " + e.getMessage());
+            }
+            try {
+                Thread.sleep(DELETE_PACE_MS);
+            } catch (final InterruptedException ie) {
+                Thread.currentThread().interrupt();
+                return;
+            }
+        }
+    }
+
+    private Set<String> getPendingDeleteIds() {
+        final Set<String> ids = new LinkedHashSet<>();
+        if (this.prefs == null) {
+            return ids;
+        }
+        final String raw = this.prefs.getString(PENDING_DELETE_IDS, "");
+        if (raw == null || raw.isEmpty()) {
+            return ids;
+        }
+        for (final String part : raw.split(",")) {
+            if (part != null && !part.isEmpty()) {
+                ids.add(part);
+            }
+        }
+        return ids;
+    }
+
+    private void enqueuePendingDelete(final String id) {
+        if (id == null || id.isEmpty() || this.editor == null || this.prefs == null) {
+            return;
+        }
+        final Set<String> ids = this.getPendingDeleteIds();
+        if (!ids.add(id)) {
+            return;
+        }
+        this.editor.putString(PENDING_DELETE_IDS, String.join(",", ids));
+        this.editor.commit();
+    }
+
+    private void dequeuePendingDelete(final String id) {
+        if (id == null || id.isEmpty() || this.editor == null || this.prefs == null) {
+            return;
+        }
+        final Set<String> ids = this.getPendingDeleteIds();
+        if (!ids.remove(id)) {
+            return;
+        }
+        if (ids.isEmpty()) {
+            this.editor.remove(PENDING_DELETE_IDS);
+        } else {
+            this.editor.putString(PENDING_DELETE_IDS, String.join(",", ids));
+        }
+        this.editor.commit();
+    }
+
     private File getBundleDirectory(final String id) {
         return new File(this.documentsDir, bundleDirectory + "/" + id);
     }
@@ -1448,7 +1642,13 @@ public class CapgoUpdater {
     private boolean bundleExists(final String id) {
         final File bundle = this.getBundleDirectory(id);
         final BundleInfo bundleInfo = this.getBundleInfo(id);
-        return (bundle.isDirectory() && bundle.exists() && new File(bundle.getPath(), "/index.html").exists() && !bundleInfo.isDeleted());
+        return (
+            bundle.isDirectory() &&
+            bundle.exists() &&
+            new File(bundle.getPath(), "/index.html").exists() &&
+            !bundleInfo.isDeleted() &&
+            !bundleInfo.isDeleting()
+        );
     }
 
     static final class ResetState {
@@ -1627,21 +1827,51 @@ public class CapgoUpdater {
         // Only attempt to delete when the fallback is a different bundle than the
         // currently loaded one. Otherwise we spam logs with "Cannot delete <id>"
         // because delete() protects the current bundle from removal.
-        if (
-            autoDeletePrevious &&
+        final String previousFallbackId = fallback.getId();
+        final String previousFallbackVersion = fallback.getVersionName();
+        final BundleInfo nextBundle = this.getNextBundle();
+        final boolean previousIsNext =
+            nextBundle != null &&
+            previousFallbackId != null &&
+            previousFallbackId.equals(nextBundle.getId()) &&
+            !nextBundle.isDeleted() &&
+            !nextBundle.isErrorStatus() &&
+            !nextBundle.isDeleting();
+        final boolean shouldDeletePrevious =
+            Boolean.TRUE.equals(autoDeletePrevious) &&
             !fallback.isBuiltin() &&
-            fallback.getId() != null &&
-            !fallback.getId().equals(bundle.getId()) &&
-            !fallbackIsPreviewFallback
-        ) {
-            final Boolean res = this.delete(fallback.getId());
-            if (res) {
-                logger.info("Deleted previous bundle: " + fallback.getVersionName());
-            } else {
-                logger.debug("Skip deleting previous bundle (same as current or protected): " + fallback.getId());
+            previousFallbackId != null &&
+            !previousFallbackId.equals(bundle.getId()) &&
+            !fallbackIsPreviewFallback &&
+            !previousIsNext;
+        if (shouldDeletePrevious) {
+            // Cancel any in-flight download for the old version before the async boundary
+            // so a later download of the same version name is not cancelled mid-flight.
+            if (this.activity != null) {
+                DownloadWorkerManager.cancelVersionDownload(this.activity, previousFallbackVersion);
+            }
+            // Mark durable intent before fallback switch so a kill mid-flight still retries.
+            if (!this.saveBundleInfo(previousFallbackId, fallback.setStatus(BundleStatus.DELETING))) {
+                logger.error("Failed to persist DELETING for previous bundle; queueing durable retry");
+                logger.debug("Bundle ID: " + previousFallbackId);
+                this.enqueuePendingDelete(previousFallbackId);
             }
         }
         this.setFallbackBundle(bundle);
+        if (shouldDeletePrevious) {
+            new Thread(() -> {
+                try {
+                    final Boolean res = this.delete(previousFallbackId, true, false);
+                    if (Boolean.TRUE.equals(res)) {
+                        logger.info("Deleted previous bundle: " + previousFallbackVersion);
+                    } else {
+                        logger.debug("Previous bundle delete incomplete, will retry: " + previousFallbackId);
+                    }
+                } catch (final IOException e) {
+                    logger.error("Failed to delete previous bundle: " + previousFallbackId + " " + e.getMessage());
+                }
+            }, "CapgoUpdater-autoDeletePrevious").start();
+        }
     }
 
     public void setError(final BundleInfo bundle) {
@@ -1964,7 +2194,6 @@ public class CapgoUpdater {
                 logger.info("Public channel requested, channel override removed");
                 callback.callback(res);
             } else {
-                // Success - persist defaultChannel
                 this.defaultChannel = channel;
                 editor.putString(defaultChannelKey, channel);
                 editor.apply();
@@ -2484,10 +2713,10 @@ public class CapgoUpdater {
         this.saveBundleInfo(id, null);
     }
 
-    public void saveBundleInfo(final String id, final BundleInfo info) {
+    public boolean saveBundleInfo(final String id, final BundleInfo info) {
         if (id == null || (info != null && (info.isBuiltin() || info.isUnknown()))) {
             logger.debug("Not saving info for bundle: [" + id + "] " + info);
-            return;
+            return false;
         }
 
         if (info == null) {
@@ -2499,7 +2728,7 @@ public class CapgoUpdater {
             logger.debug("Storing info for bundle [" + id + "] " + update.getClass().getName() + " -> " + jsonString);
             this.editor.putString(id + INFO_SUFFIX, jsonString);
         }
-        this.editor.commit();
+        return this.editor.commit();
     }
 
     private void setBundleStatus(final String id, final BundleStatus status) {

package/android/src/main/java/ee/forgr/capacitor_updater/DelayCondition.java

@@ -40,7 +40,7 @@ public class DelayCondition {
     public boolean equals(Object o) {
         if (this == o) return true;
         if (!(o instanceof DelayCondition that)) return false;
-        return (getKind() == that.getKind() && Objects.equals(getValue(), that.getValue()));
+        return getKind() == that.getKind() && Objects.equals(getValue(), that.getValue());
     }
 
     @Override
@@ -51,6 +51,6 @@ public class DelayCondition {
     @NonNull
     @Override
     public String toString() {
-        return ("DelayCondition{" + "kind=" + kind + ", value='" + value + '\'' + '}');
+        return "DelayCondition{" + "kind=" + kind + ", value='" + value + '\'' + '}';
     }
 }

package/android/src/main/java/ee/forgr/capacitor_updater/InternalUtils.java

@@ -22,7 +22,7 @@ public class InternalUtils {
     public static String getPackageName(PackageManager pm, String packageName) {
         try {
             PackageInfo pInfo = getPackageInfoInternal(pm, packageName);
-            return (pInfo != null) ? pInfo.packageName : null;
+            return pInfo != null ? pInfo.packageName : null;
         } catch (PackageManager.NameNotFoundException e) {
             // Exception is handled internally, and null is returned to indicate the package name could not be retrieved
             return null;

package/android/src/main/java/ee/forgr/capacitor_updater/ShakeMenu.java

@@ -273,7 +273,7 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
         String name = preview.optString("name", "");
         JSObject bundle = preview.getJSObject("bundle");
         String version = bundle == null ? "" : bundle.optString("version", "");
-        String label = !name.isEmpty() ? name : (!version.isEmpty() ? version : preview.optString("id", "Preview"));
+        String label = !name.isEmpty() ? name : !version.isEmpty() ? version : preview.optString("id", "Preview");
         if (preview.optBoolean("isActive", false)) {
             label += " (current)";
         }

package/dist/docs.json

@@ -846,7 +846,7 @@
             "text": "4.7.0"
           }
         ],
-        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the\nselected channel locally on the device. It does not create or update a backend Device Override,\nso the device will not appear as overridden in the Capgo dashboard. Only assignments created\nfrom the dashboard or the Public API are shown in the Device Override UI.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\n**Important: Listen for the `channelPrivate` event**\n\nWhen a user attempts to set a channel that doesn't allow device self-assignment, the method will\nthrow an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event\nto provide appropriate feedback to users:\n\n```typescript\nCapacitorUpdater.addListener('channelPrivate', (data) => {\n  console.warn(`Cannot access channel \"${data.channel}\": ${data.message}`);\n  // Show user-friendly message\n});\n```\n\nThis sends a request to the Capgo backend to validate the specified channel, then stores the\nchannel locally on the device.",
+        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the\nselected channel locally on the device for future app restarts. It does not create or update\na backend Device Override, so the device will not appear as overridden in the Capgo dashboard.\nOnly assignments created from the dashboard or the Public API are shown in the Device Override UI.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\n**Important: Listen for the `channelPrivate` event**\n\nWhen a user attempts to set a channel that doesn't allow device self-assignment, the method will\nthrow an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event\nto provide appropriate feedback to users:\n\n```typescript\nCapacitorUpdater.addListener('channelPrivate', (data) => {\n  console.warn(`Cannot access channel \"${data.channel}\": ${data.message}`);\n  // Show user-friendly message\n});\n```\n\nThis sends a request to the Capgo backend to validate the specified channel, then stores the\nchannel locally on the device for future app restarts.",
         "complexTypes": [
           "ChannelRes",
           "SetChannelOptions"
@@ -911,7 +911,7 @@
             "text": "4.8.0"
           }
         ],
-        "docs": "Get the current channel assigned to this device.\n\nReturns information about:\n- `channel`: The currently assigned channel name (if any)\n- `allowSet`: Whether the channel allows self-assignment\n- `status`: Operation status\n- `error`/`message`: Additional information (if applicable)\n\nUse this to:\n- Display current channel to users (e.g., \"You're on the Beta channel\")\n- Check if a device is on a specific channel before showing features\n- Verify channel assignment after calling {@link setChannel}\n\nOn native platforms, a successful response also refreshes the locally persisted\ndefault channel used by update checks.",
+        "docs": "Get the current channel assigned to this device.\n\nReturns information about:\n- `channel`: The currently assigned channel name (if any)\n- `allowSet`: Whether the channel allows self-assignment\n- `status`: Operation status\n- `error`/`message`: Additional information (if applicable)\n\nUse this to:\n- Display current channel to users (e.g., \"You're on the Beta channel\")\n- Check if a device is on a specific channel before showing features\n- Verify channel assignment after calling {@link setChannel}\n\nOn native platforms, a successful response also refreshes the default channel used by update checks.\nThis refresh is persisted across app restarts.",
         "complexTypes": [
           "GetChannelRes"
         ],
@@ -4468,6 +4468,14 @@
         {
           "text": "'downloading'",
           "complexTypes": []
+        },
+        {
+          "text": "'deleted'",
+          "complexTypes": []
+        },
+        {
+          "text": "'deleting'",
+          "complexTypes": []
         }
       ]
     },
@@ -5035,6 +5043,22 @@
           "complexTypes": [],
           "type": "boolean | undefined"
         },
+        {
+          "name": "persistDefaultChannelOnReinstall",
+          "tags": [
+            {
+              "text": "true",
+              "name": "default"
+            },
+            {
+              "text": "8.51.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Keep the default channel stored by {@link CapacitorUpdaterPlugin.setChannel} or refreshed by\n{@link CapacitorUpdaterPlugin.getChannel} when app data is restored into a new app install.\n\n`setChannel()` and a successful `getChannel()` still persist the selected channel across app\nrestarts. When this option is `false`, native startup clears that persisted channel when it\ndetects app data restored into a new installation. Native build cleanup clears the persisted\nchannel only when `persistDefaultChannelOnReinstall` is `false`, `resetWhenUpdate` is `true`,\nand the native build version has changed.\n\nOnly available for Android and iOS.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
         {
           "name": "defaultChannel",
           "tags": [

package/dist/esm/definitions.d.ts

@@ -311,6 +311,22 @@ declare module '@capacitor/cli' {
              * @since 7.34.0
              */
             allowSetDefaultChannel?: boolean;
+            /**
+             * Keep the default channel stored by {@link CapacitorUpdaterPlugin.setChannel} or refreshed by
+             * {@link CapacitorUpdaterPlugin.getChannel} when app data is restored into a new app install.
+             *
+             * `setChannel()` and a successful `getChannel()` still persist the selected channel across app
+             * restarts. When this option is `false`, native startup clears that persisted channel when it
+             * detects app data restored into a new installation. Native build cleanup clears the persisted
+             * channel only when `persistDefaultChannelOnReinstall` is `false`, `resetWhenUpdate` is `true`,
+             * and the native build version has changed.
+             *
+             * Only available for Android and iOS.
+             *
+             * @default true
+             * @since 8.51.0
+             */
+            persistDefaultChannelOnReinstall?: boolean;
             /**
              * Set the default channel for the app in the config. Case sensitive.
              * This will setting will override the default channel set in the cloud, but will still respect overrides made in the cloud.
@@ -947,9 +963,9 @@ export interface CapacitorUpdaterPlugin {
      * (e.g., "production", "beta", "staging"). This method switches the device to a new channel.
      *
      * **Device Override UI:** `setChannel()` validates the channel with the backend, then stores the
-     * selected channel locally on the device. It does not create or update a backend Device Override,
-     * so the device will not appear as overridden in the Capgo dashboard. Only assignments created
-     * from the dashboard or the Public API are shown in the Device Override UI.
+     * selected channel locally on the device for future app restarts. It does not create or update
+     * a backend Device Override, so the device will not appear as overridden in the Capgo dashboard.
+     * Only assignments created from the dashboard or the Public API are shown in the Device Override UI.
      *
      * **Requirements:**
      * - The target channel must allow self-assignment (configured in your Capgo dashboard or backend)
@@ -978,7 +994,7 @@ export interface CapacitorUpdaterPlugin {
      * ```
      *
      * This sends a request to the Capgo backend to validate the specified channel, then stores the
-     * channel locally on the device.
+     * channel locally on the device for future app restarts.
      *
      * @param options The {@link SetChannelOptions} containing the channel name and optional auto-update trigger.
      * @returns {Promise<ChannelRes>} Channel operation result with status and optional error/message.
@@ -1019,8 +1035,8 @@ export interface CapacitorUpdaterPlugin {
      * - Check if a device is on a specific channel before showing features
      * - Verify channel assignment after calling {@link setChannel}
      *
-     * On native platforms, a successful response also refreshes the locally persisted
-     * default channel used by update checks.
+     * On native platforms, a successful response also refreshes the default channel used by update checks.
+     * This refresh is persisted across app restarts.
      *
      * @returns {Promise<GetChannelRes>} The current channel information.
      * @throws {Error} If the operation fails.
@@ -1604,7 +1620,7 @@ export interface CapacitorUpdaterPlugin {
  * success: The bundle has been downloaded and is ready to be **SET** as the next bundle.
  * error: The bundle has failed to download.
  */
-export type BundleStatus = 'success' | 'error' | 'pending' | 'downloading';
+export type BundleStatus = 'success' | 'error' | 'pending' | 'downloading' | 'deleted' | 'deleting';
 export type DelayUntilNext = 'background' | 'kill' | 'nativeVersion' | 'date';
 /**
  * Classification for update-check responses that do not provide a downloadable bundle.