@capgo/capacitor-updater 8.47.2 → 8.47.4

package/README.md

@@ -2200,9 +2200,10 @@ If you don't use backend, you need to provide the URL and version of the bundle.
 
 ##### StartPreviewSessionOptions
 
-| Prop        | Type                | Description                                                                                                                                                                                     | Default                | Since  |
-| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
-| **`appId`** | <code>string</code> | App id to use while the preview session is active. The previous app id is restored when leaving the preview session. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.47.0 |
+| Prop             | Type                | Description                                                                                                                                                                                                                                                               | Default                | Since  |
+| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
+| **`appId`**      | <code>string</code> | App id to use while the preview session is active. The previous app id is restored when leaving the preview session. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.                                                                           | <code>undefined</code> | 8.47.0 |
+| **`payloadUrl`** | <code>string</code> | HTTP(S) URL returning a preview download payload. When provided, the native shake reload action fetches this payload again before reloading so channel previews can move to the latest bundle. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.48.0 |
 
 
 ##### BundleListResult

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

@@ -49,9 +49,13 @@ import com.google.android.play.core.install.model.AppUpdateType;
 import com.google.android.play.core.install.model.InstallStatus;
 import com.google.android.play.core.install.model.UpdateAvailability;
 import io.github.g00fy2.versioncompare.Version;
+import java.io.ByteArrayOutputStream;
 import java.io.IOException;
+import java.io.InputStream;
+import java.net.HttpURLConnection;
 import java.net.MalformedURLException;
 import java.net.URL;
+import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.HashMap;
@@ -98,7 +102,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private static final String PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY = "CapacitorUpdater.previewPreviousShakeChannelSelector";
     private static final String PREVIEW_PREVIOUS_NEXT_BUNDLE_PREF_KEY = "CapacitorUpdater.previewPreviousNextBundle";
     private static final String PREVIEW_PREVIOUS_APP_ID_PREF_KEY = "CapacitorUpdater.previewPreviousAppId";
+    private static final String PREVIEW_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY = "CapacitorUpdater.previewPreviousDefaultChannel";
+    private static final String PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY = "CapacitorUpdater.previewPreviousDefaultChannelWasSet";
     private static final String PREVIEW_APP_ID_PREF_KEY = "CapacitorUpdater.previewAppId";
+    private static final String PREVIEW_PAYLOAD_URL_PREF_KEY = "CapacitorUpdater.previewPayloadUrl";
     private static final String[] BREAKING_EVENT_NAMES = { "breakingAvailable", "majorAvailable" };
     private static final String LAST_FAILED_BUNDLE_PREF_KEY = "CapacitorUpdater.lastFailedBundle";
     private static final String LAST_REPORTED_APP_EXIT_TIMESTAMP_PREF_KEY = "CapacitorUpdater.lastReportedAppExitTimestamp";
@@ -120,7 +127,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     static final int APPLICATION_EXIT_REASON_USER_REQUESTED = 10;
     static final int APPLICATION_EXIT_REASON_DEPENDENCY_DIED = 12;
 
-    private final String pluginVersion = "8.47.2";
+    private final String pluginVersion = "8.47.4";
     private static final String DELAY_CONDITION_PREFERENCES = "";
 
     private SharedPreferences.Editor editor;
@@ -1930,6 +1937,20 @@ public class CapacitorUpdaterPlugin extends Plugin {
         }
     }
 
+    private BundleInfo downloadBundle(
+        final String url,
+        final String version,
+        final String sessionKey,
+        final String checksum,
+        final JSONArray manifest
+    ) throws IOException {
+        if (manifest != null) {
+            return this.implementation.downloadManifest(url, version, sessionKey, checksum, manifest);
+        }
+
+        return this.implementation.download(url, version, sessionKey, checksum);
+    }
+
     @PluginMethod
     public void download(final PluginCall call) {
         final String url = call.getString("url");
@@ -1951,20 +1972,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
             logger.info("Downloading " + url);
             startNewThread(() -> {
                 try {
-                    final BundleInfo downloaded;
-                    if (manifest != null) {
-                        // For manifest downloads, we need to handle this asynchronously
-                        // to avoid automatically scheduling/applying the downloaded bundle.
-                        // Manual download must not schedule/apply the bundle automatically.
-                        CapacitorUpdaterPlugin.this.implementation.downloadBackground(url, version, sessionKey, checksum, manifest, false);
-                        // Return immediately with a pending status - the actual result will come via listeners
-                        final String id = CapacitorUpdaterPlugin.this.implementation.randomString();
-                        downloaded = new BundleInfo(id, version, BundleStatus.DOWNLOADING, new Date(System.currentTimeMillis()), "");
-                        call.resolve(InternalUtils.mapToJSObject(downloaded.toJSONMap()));
-                        return;
-                    } else {
-                        downloaded = CapacitorUpdaterPlugin.this.implementation.download(url, version, sessionKey, checksum);
-                    }
+                    final BundleInfo downloaded = this.downloadBundle(url, version, sessionKey, checksum, manifest);
                     if (downloaded.isErrorStatus()) {
                         throw new RuntimeException("Download failed: " + downloaded.getStatus());
                     } else {
@@ -2231,6 +2239,13 @@ public class CapacitorUpdaterPlugin extends Plugin {
             return;
         }
         final String previewAppId = this.normalizePreviewAppId(call.getString("appId"));
+        final String rawPayloadUrl = call.getString("payloadUrl");
+        final String previewPayloadUrl = this.normalizePreviewPayloadUrl(rawPayloadUrl);
+        if (this.hasPreviewPayloadUrl(rawPayloadUrl) && previewPayloadUrl == null) {
+            logger.error("startPreviewSession called with invalid payloadUrl");
+            call.reject("Invalid preview payloadUrl");
+            return;
+        }
         startNewThread(() -> {
             try {
                 if (!Boolean.TRUE.equals(this.previewSessionEnabled)) {
@@ -2249,6 +2264,16 @@ public class CapacitorUpdaterPlugin extends Plugin {
                     }
 
                     this.editor.putString(PREVIEW_PREVIOUS_APP_ID_PREF_KEY, this.implementation.appId);
+                    if (this.prefs.contains(DEFAULT_CHANNEL_PREF_KEY)) {
+                        this.editor.putString(
+                            PREVIEW_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY,
+                            this.prefs.getString(DEFAULT_CHANNEL_PREF_KEY, "")
+                        );
+                        this.editor.putBoolean(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY, true);
+                    } else {
+                        this.editor.remove(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY);
+                        this.editor.putBoolean(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY, false);
+                    }
                     this.editor.putBoolean(PREVIEW_PREVIOUS_SHAKE_MENU_PREF_KEY, Boolean.TRUE.equals(this.shakeMenuEnabled));
                     this.editor.putBoolean(
                         PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY,
@@ -2263,6 +2288,13 @@ public class CapacitorUpdaterPlugin extends Plugin {
                     logger.info("Preview session using appId: " + previewAppId);
                 }
 
+                if (previewPayloadUrl != null) {
+                    this.editor.putString(PREVIEW_PAYLOAD_URL_PREF_KEY, previewPayloadUrl);
+                    logger.info("Preview session using payload URL");
+                } else {
+                    this.editor.remove(PREVIEW_PAYLOAD_URL_PREF_KEY);
+                }
+
                 this.previewSessionEnabled = true;
                 this.previewSessionAlertPending = true;
                 this.implementation.previewSession = true;
@@ -2287,9 +2319,6 @@ public class CapacitorUpdaterPlugin extends Plugin {
             return false;
         }
 
-        if (!this.clearPreviewChannelOverride()) {
-            return false;
-        }
         final BundleInfo previewFallbackBundle = this.implementation.getPreviewFallbackBundle();
         this.endPreviewSession();
         final BundleInfo restoredNextBundle = this.implementation.getNextBundle();
@@ -2308,6 +2337,11 @@ public class CapacitorUpdaterPlugin extends Plugin {
     }
 
     public boolean reloadPreviewSessionFromShakeMenu() {
+        final String payloadUrl = this.storedPreviewPayloadUrl();
+        if (payloadUrl != null) {
+            return this.refreshPreviewSessionFromPayloadUrl(payloadUrl);
+        }
+
         return this._reload();
     }
 
@@ -2350,6 +2384,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
         );
         this.restorePreviewPreviousNextBundle();
         this.restorePreviewPreviousAppId();
+        this.restorePreviewPreviousDefaultChannel();
 
         this.previewSessionEnabled = false;
         this.previewSessionAlertPending = false;
@@ -2376,6 +2411,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
 
         this.restorePreviewPreviousNextBundle();
         this.restorePreviewPreviousAppId();
+        this.restorePreviewPreviousDefaultChannel();
         this.previewSessionEnabled = false;
         this.previewSessionAlertPending = false;
         this.implementation.previewSession = false;
@@ -2393,7 +2429,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.editor.remove(PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY);
         this.editor.remove(PREVIEW_PREVIOUS_NEXT_BUNDLE_PREF_KEY);
         this.editor.remove(PREVIEW_PREVIOUS_APP_ID_PREF_KEY);
+        this.editor.remove(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY);
+        this.editor.remove(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY);
         this.editor.remove(PREVIEW_APP_ID_PREF_KEY);
+        this.editor.remove(PREVIEW_PAYLOAD_URL_PREF_KEY);
         this.editor.apply();
     }
 
@@ -2413,6 +2452,23 @@ public class CapacitorUpdaterPlugin extends Plugin {
         logger.info("Restored appId after preview: " + previousAppId);
     }
 
+    private void restorePreviewPreviousDefaultChannel() {
+        final String configDefaultChannel = this.getConfig().getString("defaultChannel", "");
+        if (this.prefs.getBoolean(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_WAS_SET_PREF_KEY, false)) {
+            final String previousDefaultChannel = this.prefs.getString(PREVIEW_PREVIOUS_DEFAULT_CHANNEL_PREF_KEY, "");
+            this.editor.putString(DEFAULT_CHANNEL_PREF_KEY, previousDefaultChannel);
+            this.implementation.defaultChannel = previousDefaultChannel;
+            this.editor.apply();
+            logger.info("Restored defaultChannel after preview");
+            return;
+        }
+
+        this.editor.remove(DEFAULT_CHANNEL_PREF_KEY);
+        this.implementation.defaultChannel = configDefaultChannel;
+        this.editor.apply();
+        logger.info("Restored defaultChannel after preview to config value");
+    }
+
     private String normalizePreviewAppId(final String rawAppId) {
         if (rawAppId == null) {
             return null;
@@ -2431,6 +2487,131 @@ public class CapacitorUpdaterPlugin extends Plugin {
         return appId;
     }
 
+    private boolean hasPreviewPayloadUrl(final String rawPayloadUrl) {
+        if (rawPayloadUrl == null) {
+            return false;
+        }
+
+        final String payloadUrl = rawPayloadUrl.trim();
+        if (payloadUrl.isEmpty()) {
+            return false;
+        }
+
+        final String lowercasedPayloadUrl = payloadUrl.toLowerCase(java.util.Locale.ROOT);
+        return !"undefined".equals(lowercasedPayloadUrl) && !"null".equals(lowercasedPayloadUrl);
+    }
+
+    private String normalizePreviewPayloadUrl(final String rawPayloadUrl) {
+        if (!this.hasPreviewPayloadUrl(rawPayloadUrl)) {
+            return null;
+        }
+
+        final String payloadUrl = rawPayloadUrl.trim();
+        try {
+            final URL parsedUrl = new URL(payloadUrl);
+            final String protocol = parsedUrl.getProtocol();
+            if (!"https".equals(protocol) && !"http".equals(protocol)) {
+                return null;
+            }
+            return parsedUrl.toString();
+        } catch (final MalformedURLException ignored) {
+            return null;
+        }
+    }
+
+    private String storedPreviewPayloadUrl() {
+        return this.normalizePreviewPayloadUrl(this.prefs.getString(PREVIEW_PAYLOAD_URL_PREF_KEY, null));
+    }
+
+    private String readResponseBody(final InputStream stream) throws IOException {
+        if (stream == null) {
+            return "";
+        }
+
+        try (InputStream input = stream; ByteArrayOutputStream output = new ByteArrayOutputStream()) {
+            final byte[] buffer = new byte[8192];
+            int read;
+            while ((read = input.read(buffer)) != -1) {
+                output.write(buffer, 0, read);
+            }
+            return output.toString(StandardCharsets.UTF_8.name());
+        }
+    }
+
+    private JSONObject fetchPreviewPayload(final String payloadUrl) throws IOException, JSONException {
+        final HttpURLConnection connection = (HttpURLConnection) new URL(payloadUrl).openConnection();
+        connection.setRequestMethod("GET");
+        connection.setRequestProperty("Accept", "application/json");
+        connection.setConnectTimeout(30000);
+        connection.setReadTimeout(60000);
+
+        try {
+            final int statusCode = connection.getResponseCode();
+            final String body = this.readResponseBody(
+                statusCode >= 200 && statusCode < 300 ? connection.getInputStream() : connection.getErrorStream()
+            );
+            final JSONObject payload = new JSONObject(body);
+            if (statusCode < 200 || statusCode >= 300) {
+                throw new IOException(
+                    payload.optString("message", payload.optString("error", "Preview payload request failed with HTTP " + statusCode))
+                );
+            }
+            return payload;
+        } finally {
+            connection.disconnect();
+        }
+    }
+
+    private BundleInfo downloadPreviewPayloadBundle(final JSONObject payload) throws IOException, JSONException {
+        final String version = payload.optString("version", "").trim();
+        if (version.isEmpty()) {
+            throw new IOException("Preview payload is missing a version");
+        }
+
+        final JSONArray manifest = payload.optJSONArray("manifest");
+        final String url = payload.optString("url", "");
+        if ((url == null || url.isEmpty()) && (manifest == null || manifest.length() == 0)) {
+            throw new IOException("Preview payload is missing download information");
+        }
+
+        return this.downloadBundle(
+            url == null || url.isEmpty() ? "https://404.capgo.app/no.zip" : url,
+            version,
+            payload.optString("sessionKey", ""),
+            payload.optString("checksum", ""),
+            manifest
+        );
+    }
+
+    private boolean refreshPreviewSessionFromPayloadUrl(final String payloadUrl) {
+        try {
+            final JSONObject payload = this.fetchPreviewPayload(payloadUrl);
+            final String version = payload.optString("version", "").trim();
+            if (version.isEmpty()) {
+                throw new IOException("Preview payload is missing a version");
+            }
+
+            if (version.equals(this.implementation.getCurrentBundle().getVersionName())) {
+                logger.info("Preview payload unchanged, reloading current bundle");
+                return this._reload();
+            }
+
+            final BundleInfo next = this.downloadPreviewPayloadBundle(payload);
+            if (next.isErrorStatus()) {
+                throw new IOException("Download failed: " + next.getStatus());
+            }
+            if (!this.implementation.set(next.getId())) {
+                throw new IOException("Downloaded preview bundle cannot be applied");
+            }
+
+            this.notifyBundleSet(next);
+            return this._reload();
+        } catch (final Exception err) {
+            logger.error("Could not refresh preview session: " + err.getMessage());
+            return false;
+        }
+    }
+
     private void clearPreviewSessionForNativeBuildChange() {
         if (!Boolean.TRUE.equals(this.previewSessionEnabled) && this.implementation.getPreviewFallbackBundle() == null) {
             return;
@@ -2442,35 +2623,12 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.shakeMenuEnabled = this.getConfig().getBoolean("shakeMenu", false);
         this.shakeChannelSelectorEnabled = this.getConfig().getBoolean("allowShakeChannelSelector", false);
         this.restorePreviewPreviousAppId();
+        this.restorePreviewPreviousDefaultChannel();
         this.implementation.setPreviewFallbackBundle(null);
         this.implementation.setNextBundle(null);
-        this.clearPreviewChannelOverride();
         this.clearPreviewSessionPreferences();
     }
 
-    private boolean clearPreviewChannelOverride() {
-        final String configDefaultChannel = this.getConfig().getString("defaultChannel", "");
-        final AtomicReference<Map<String, Object>> unsetChannelResult = new AtomicReference<>();
-        try {
-            this.implementation.unsetChannel(this.editor, DEFAULT_CHANNEL_PREF_KEY, configDefaultChannel, unsetChannelResult::set);
-        } catch (final Exception err) {
-            logger.error("Could not clear preview channel override: " + err.getMessage());
-            return false;
-        }
-
-        final Map<String, Object> result = unsetChannelResult.get();
-        if (result == null) {
-            logger.error("Could not clear preview channel override: no result");
-            return false;
-        }
-        if (result.containsKey("error")) {
-            final Object message = result.getOrDefault("message", result.get("error"));
-            logger.error("Could not clear preview channel override: " + message);
-            return false;
-        }
-        return true;
-    }
-
     private void restorePreviewPreviousNextBundle() {
         final String previousNextBundleId = this.prefs.getString(PREVIEW_PREVIOUS_NEXT_BUNDLE_PREF_KEY, null);
         if (previousNextBundleId == null || previousNextBundleId.isEmpty()) {

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

@@ -193,6 +193,30 @@ public class CapgoUpdater {
         this.cachedKeyId = CryptoCipher.calcKeyId(publicKey);
     }
 
+    static File resolvePathInsideDirectory(final File baseDirectory, final String relativePath) throws IOException {
+        if (relativePath == null || relativePath.isEmpty()) {
+            throw new IOException("Invalid empty path");
+        }
+        if (relativePath.contains("\\") || relativePath.indexOf('\0') >= 0) {
+            throw new IOException("Invalid path separator");
+        }
+        if (new File(relativePath).isAbsolute()) {
+            throw new IOException("Absolute paths are not allowed");
+        }
+
+        final File canonicalBase = baseDirectory.getCanonicalFile();
+        final File canonicalTarget = new File(canonicalBase, relativePath).getCanonicalFile();
+        final String basePath = canonicalBase.getPath();
+        final String targetPath = canonicalTarget.getPath();
+        final String normalizedBasePath = basePath.endsWith(File.separator) ? basePath : basePath + File.separator;
+
+        if (!targetPath.equals(basePath) && !targetPath.startsWith(normalizedBasePath)) {
+            throw new IOException("Path escapes base directory: " + relativePath);
+        }
+
+        return canonicalTarget;
+    }
+
     public String getKeyId() {
         return this.cachedKeyId;
     }
@@ -213,23 +237,21 @@ public class CapgoUpdater {
 
             ZipEntry entry;
             while ((entry = zis.getNextEntry()) != null) {
-                if (entry.getName().contains("\\")) {
-                    logger.error("Unzip failed: Windows path not supported");
-                    logger.debug("Invalid path: " + entry.getName());
-                    this.sendStats("windows_path_fail");
+                final File file;
+                try {
+                    file = resolvePathInsideDirectory(targetDirectory, entry.getName());
+                } catch (IOException e) {
+                    if (entry.getName().contains("\\")) {
+                        logger.error("Unzip failed: Windows path not supported");
+                        logger.debug("Invalid path: " + entry.getName());
+                        this.sendStats("windows_path_fail");
+                    } else {
+                        this.sendStats("canonical_path_fail");
+                    }
+                    throw e;
                 }
-                final File file = new File(targetDirectory, entry.getName());
-                final String canonicalPath = file.getCanonicalPath();
-                final String canonicalDir = targetDirectory.getCanonicalPath();
                 final File dir = entry.isDirectory() ? file : file.getParentFile();
 
-                if (!canonicalPath.startsWith(canonicalDir)) {
-                    this.sendStats("canonical_path_fail");
-                    throw new FileNotFoundException(
-                        "SecurityException, Failed to ensure directory is the start path : " + canonicalDir + " of " + canonicalPath
-                    );
-                }
-
                 assert dir != null;
                 if (!dir.isDirectory() && !dir.mkdirs()) {
                     this.sendStats("directory_path_fail");

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

@@ -168,6 +168,16 @@ public class DownloadService extends Worker {
         return Result.success(output);
     }
 
+    static File resolveManifestTargetFile(final File destFolder, final String fileName) throws IOException {
+        final boolean isBrotli = fileName.endsWith(".br");
+        final String targetFileName = isBrotli ? fileName.substring(0, fileName.length() - 3) : fileName;
+        return CapgoUpdater.resolvePathInsideDirectory(destFolder, targetFileName);
+    }
+
+    static File resolveManifestBuiltinFile(final File builtinFolder, final String fileName) throws IOException {
+        return CapgoUpdater.resolvePathInsideDirectory(builtinFolder, fileName);
+    }
+
     private String getInputString(String key, String fallback) {
         String value = getInputData().getString(key);
         return value != null ? value : fallback;
@@ -338,11 +348,20 @@ public class DownloadService extends Worker {
                 boolean isBrotli = fileName.endsWith(".br");
                 String targetFileName = isBrotli ? fileName.substring(0, fileName.length() - 3) : fileName;
 
-                File targetFile = new File(destFolder, targetFileName);
+                File targetFile;
+                File builtinFile;
+                try {
+                    targetFile = resolveManifestTargetFile(destFolder, fileName);
+                    builtinFile = resolveManifestBuiltinFile(builtinFolder, fileName);
+                } catch (IOException e) {
+                    logger.error("Invalid manifest file path: " + fileName);
+                    sendStatsAsync("manifest_path_fail", version + ":" + fileName);
+                    hasError.set(true);
+                    continue;
+                }
                 String cacheBaseName = new File(isBrotli ? targetFileName : fileName).getName();
                 File cacheFile = new File(cacheFolder, finalFileHash + "_" + cacheBaseName);
                 final File legacyCacheFile = isBrotli ? new File(cacheFolder, finalFileHash + "_" + new File(fileName).getName()) : null;
-                File builtinFile = new File(builtinFolder, fileName);
 
                 // Ensure parent directories of the target file exist
                 if (!Objects.requireNonNull(targetFile.getParentFile()).exists() && !targetFile.getParentFile().mkdirs()) {

package/dist/docs.json

@@ -1991,6 +1991,22 @@
           "docs": "App id to use while the preview session is active.\nThe previous app id is restored when leaving the preview session.\nRequires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.",
           "complexTypes": [],
           "type": "string | undefined"
+        },
+        {
+          "name": "payloadUrl",
+          "tags": [
+            {
+              "text": "8.48.0",
+              "name": "since"
+            },
+            {
+              "text": "undefined",
+              "name": "default"
+            }
+          ],
+          "docs": "HTTP(S) URL returning a preview download payload.\nWhen provided, the native shake reload action fetches this payload again\nbefore reloading so channel previews can move to the latest bundle.\nRequires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.",
+          "complexTypes": [],
+          "type": "string | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -1973,6 +1973,15 @@ export interface StartPreviewSessionOptions {
      * @default undefined
      */
     appId?: string;
+    /**
+     * HTTP(S) URL returning a preview download payload.
+     * When provided, the native shake reload action fetches this payload again
+     * before reloading so channel previews can move to the latest bundle.
+     * Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
+     * @since 8.48.0
+     * @default undefined
+     */
+    payloadUrl?: string;
 }
 export interface AppReadyResult {
     bundle: BundleInfo;