@capgo/capacitor-updater 8.48.0 → 8.49.0

package/dist/docs.json

@@ -251,12 +251,203 @@
             "text": "8.47.0"
           }
         ],
-        "docs": "Start a temporary preview/testing session.\n\nThis stores the currently active bundle as the pending fallback, enables the\nnative shake menu, and makes the next applied bundle show a native notice\nexplaining that shaking the device can reload or leave the preview.\nRequires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.\nWhen `appId` is provided, the preview session temporarily uses that app id\nfor update checks until the user leaves the preview. Native updater stats are\nskipped while the preview session is active.\n\nUse this before calling {@link set} for Expo Go-style preview flows.",
+        "docs": "Start a temporary preview/testing session.\n\nThis stores the currently active bundle as the pending fallback, enables the\nnative shake menu, and makes the next applied bundle show a native notice\nexplaining that shaking the device can reload or leave the preview.\nRequires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.\nWhen `appId` is provided, the preview session temporarily uses that app id\nfor update checks until the user leaves the preview. Native updater stats are\nskipped while the preview session is active.\n\nUse this before calling {@link set} for Expo Go-style preview flows.\nUse {@link listPreviews}, {@link setPreview}, {@link resetPreview},\n{@link deletePreview}, {@link checkPreviewUpdate}, and\n{@link updatePreview} to manage saved local previews.",
         "complexTypes": [
           "StartPreviewSessionOptions"
         ],
         "slug": "startpreviewsession"
       },
+      {
+        "name": "listPreviews",
+        "signature": "() => Promise<PreviewListResult>",
+        "parameters": [],
+        "returns": "Promise<PreviewListResult>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Locally available previews and current preview state."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If preview sessions are not enabled by config."
+          },
+          {
+            "name": "since",
+            "text": "8.49.0"
+          }
+        ],
+        "docs": "Get every locally available preview bundle that was registered by\n{@link startPreviewSession} and later applied with {@link set}.\n\nThis only returns previews whose bundles are still available locally. It is\nsafe to show this in a preview switcher or native debug menu.",
+        "complexTypes": [
+          "PreviewListResult"
+        ],
+        "slug": "listpreviews"
+      },
+      {
+        "name": "setPreview",
+        "signature": "(options: BundleId) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "A {@link BundleId} object containing the preview bundle ID.",
+            "type": "BundleId"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options A {@link BundleId} object containing the preview bundle ID."
+          },
+          {
+            "name": "returns",
+            "text": "Resolves once the preview switch is staged."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If preview sessions are disabled or the preview is not available locally."
+          },
+          {
+            "name": "since",
+            "text": "8.49.0"
+          }
+        ],
+        "docs": "Switch to a locally available preview bundle and reload the WebView.\n\nIf the app is not already in a preview session, the current live bundle is\nsaved as the fallback so {@link resetPreview} or the native shake menu can\nreturn to it later.",
+        "complexTypes": [
+          "BundleId"
+        ],
+        "slug": "setpreview"
+      },
+      {
+        "name": "resetPreview",
+        "signature": "() => Promise<void>",
+        "parameters": [],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Resolves once the live bundle reload is staged."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If there is no preview fallback bundle available."
+          },
+          {
+            "name": "since",
+            "text": "8.49.0"
+          }
+        ],
+        "docs": "Leave the active preview session and reload the saved live bundle.\n\nThis does not delete any saved previews. Use {@link deletePreview} to remove\na preview from local storage.",
+        "complexTypes": [],
+        "slug": "resetpreview"
+      },
+      {
+        "name": "deletePreview",
+        "signature": "(options: BundleId) => Promise<DeletePreviewResult>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "A {@link BundleId} object containing the preview bundle ID.",
+            "type": "BundleId"
+          }
+        ],
+        "returns": "Promise<DeletePreviewResult>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options A {@link BundleId} object containing the preview bundle ID."
+          },
+          {
+            "name": "returns",
+            "text": "Whether the underlying bundle was deleted."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If preview sessions are disabled."
+          },
+          {
+            "name": "since",
+            "text": "8.49.0"
+          }
+        ],
+        "docs": "Delete a locally saved preview and its bundle when possible.\n\nActive previews cannot be deleted until you switch away from them or call\n{@link resetPreview}. If only the preview metadata can be removed, the\nmethod still resolves with `deleted: false`.",
+        "complexTypes": [
+          "DeletePreviewResult",
+          "BundleId"
+        ],
+        "slug": "deletepreview"
+      },
+      {
+        "name": "checkPreviewUpdate",
+        "signature": "(options: BundleId) => Promise<PreviewUpdateResult>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "A {@link BundleId} object containing the preview bundle ID.",
+            "type": "BundleId"
+          }
+        ],
+        "returns": "Promise<PreviewUpdateResult>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options A {@link BundleId} object containing the preview bundle ID."
+          },
+          {
+            "name": "returns",
+            "text": "Update status for the preview."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If preview sessions are disabled or the preview has no payload URL."
+          },
+          {
+            "name": "since",
+            "text": "8.49.0"
+          }
+        ],
+        "docs": "Check whether a saved preview's payload URL points to a newer preview bundle.\n\nOnly previews started with a `payloadUrl` can be checked natively. Direct URL\npreviews can still be switched or deleted locally, but the updater does not\nknow where to check for newer versions.",
+        "complexTypes": [
+          "PreviewUpdateResult",
+          "BundleId"
+        ],
+        "slug": "checkpreviewupdate"
+      },
+      {
+        "name": "updatePreview",
+        "signature": "(options: BundleId) => Promise<PreviewUpdateResult>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "A {@link BundleId} object containing the preview bundle ID.",
+            "type": "BundleId"
+          }
+        ],
+        "returns": "Promise<PreviewUpdateResult>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options A {@link BundleId} object containing the preview bundle ID."
+          },
+          {
+            "name": "returns",
+            "text": "The update result and saved preview metadata."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If preview sessions are disabled or the preview cannot be updated."
+          },
+          {
+            "name": "since",
+            "text": "8.49.0"
+          }
+        ],
+        "docs": "Download the newest bundle for a saved preview payload URL.\n\nIf the preview being updated is active, the new bundle is applied and the\nWebView reloads. Otherwise, the saved preview entry is moved to the newly\ndownloaded bundle and can be selected later with {@link setPreview}.",
+        "complexTypes": [
+          "PreviewUpdateResult",
+          "BundleId"
+        ],
+        "slug": "updatepreview"
+      },
       {
         "name": "delete",
         "signature": "(options: BundleId) => Promise<void>",
@@ -1431,7 +1622,7 @@
             "text": "7.5.0"
           }
         ],
-        "docs": "Enable or disable the native preview menu gesture.\n\nDuring preview sessions, users can use the configured native gesture to:\n- Reload the current preview\n- Leave the test app and return to the fallback bundle\n- Switch update channel, when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is also enabled\n\nOutside preview sessions, this preview menu is ignored. The channel selector can still be\nshown outside preview sessions when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is enabled.\n\n**Important:** Disable this in production builds or only enable for internal testers.\n\nThis can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.\nThe native gesture can be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}\nor `options.gesture`.",
+        "docs": "Enable or disable the native preview menu gesture.\n\nDuring preview sessions, users can use the configured native gesture to:\n- Reload the current preview\n- Leave the test app and return to the fallback bundle\n- Switch update channel, when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is also enabled\n\nOutside preview sessions, this preview menu is ignored. The channel selector can still be\nshown outside preview sessions when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is enabled.\n\n**Important:** Disable this in production builds or only enable for internal testers.\n\nThis can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.\nThe native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.",
         "complexTypes": [
           "SetShakeMenuOptions"
         ],
@@ -1495,7 +1686,7 @@
             "text": "8.43.0"
           }
         ],
-        "docs": "Enable or disable the channel selector menu gesture at runtime.\n\nWhen enabled, the configured native gesture can show a channel selector, including outside preview sessions.\nIf {@link setShakeMenu} is also enabled while a preview session is active, the shake menu includes\nboth preview actions and channel switching.\n\nThis can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.\nThe native gesture can be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}\nor {@link setShakeMenu}.",
+        "docs": "Enable or disable the channel selector menu gesture at runtime.\n\nWhen enabled, the configured native gesture can show a channel selector, including outside preview sessions.\nIf {@link setShakeMenu} is also enabled while a preview session is active, the shake menu includes\nboth preview actions and channel switching.\n\nThis can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.\nThe native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.",
         "complexTypes": [
           "SetShakeChannelSelectorOptions"
         ],
@@ -2007,6 +2198,340 @@
           "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"
+        },
+        {
+          "name": "name",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            },
+            {
+              "text": "undefined",
+              "name": "default"
+            }
+          ],
+          "docs": "Human-readable preview name stored with the next preview bundle applied by\n{@link set}. Native preview menus and {@link listPreviews} can display it.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "source",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            },
+            {
+              "text": "undefined",
+              "name": "default"
+            }
+          ],
+          "docs": "Optional source label for the preview, such as `channel`, `bundle`, `url`,\nor `payload`. This is stored as metadata only.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
+    {
+      "name": "PreviewListResult",
+      "slug": "previewlistresult",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "previews",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Locally available preview bundles.",
+          "complexTypes": [
+            "PreviewInfo"
+          ],
+          "type": "PreviewInfo[]"
+        },
+        {
+          "name": "current",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Current preview when a preview session is active.",
+          "complexTypes": [
+            "PreviewInfo"
+          ],
+          "type": "PreviewInfo"
+        },
+        {
+          "name": "currentBundle",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Bundle currently loaded by the WebView.",
+          "complexTypes": [
+            "BundleInfo"
+          ],
+          "type": "BundleInfo"
+        },
+        {
+          "name": "liveBundle",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Bundle that will be restored when leaving preview mode.",
+          "complexTypes": [
+            "BundleInfo"
+          ],
+          "type": "BundleInfo"
+        }
+      ]
+    },
+    {
+      "name": "PreviewInfo",
+      "slug": "previewinfo",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "id",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Preview bundle id.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "bundle",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Locally downloaded bundle backing this preview.",
+          "complexTypes": [
+            "BundleInfo"
+          ],
+          "type": "BundleInfo"
+        },
+        {
+          "name": "name",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Human-readable name supplied when the preview was started.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "source",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Metadata source label supplied when the preview was started.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "appId",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Preview app id, when the session uses an app id override.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "payloadUrl",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Payload URL used to refresh this preview.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "createdAt",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "ISO timestamp for when this preview was first saved.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "updatedAt",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "ISO timestamp for the last metadata or bundle update.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "lastUsedAt",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "ISO timestamp for the last time this preview was activated.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "isActive",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Whether this preview is the currently active bundle in a preview session.",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
+    {
+      "name": "DeletePreviewResult",
+      "slug": "deletepreviewresult",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "removed",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Whether preview metadata was removed.",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "deleted",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Whether the underlying local bundle was deleted.",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
+    {
+      "name": "PreviewUpdateResult",
+      "slug": "previewupdateresult",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "preview",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Saved preview metadata after the check or update.",
+          "complexTypes": [
+            "PreviewInfo"
+          ],
+          "type": "PreviewInfo"
+        },
+        {
+          "name": "latestVersion",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Latest version returned by the preview payload endpoint.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "upToDate",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Whether the saved preview already matches the latest payload version.",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "updated",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Whether a newer bundle was downloaded and saved.",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "bundle",
+          "tags": [
+            {
+              "text": "8.49.0",
+              "name": "since"
+            }
+          ],
+          "docs": "New bundle when {@link updatePreview} downloaded one.",
+          "complexTypes": [
+            "BundleInfo"
+          ],
+          "type": "BundleInfo"
         }
       ]
     },
@@ -3442,20 +3967,6 @@
           "docs": "",
           "complexTypes": [],
           "type": "boolean"
-        },
-        {
-          "name": "gesture",
-          "tags": [
-            {
-              "text": "'shake'",
-              "name": "default"
-            }
-          ],
-          "docs": "Native gesture used to open the preview/channel menu.",
-          "complexTypes": [
-            "ShakeMenuGesture"
-          ],
-          "type": "ShakeMenuGesture"
         }
       ]
     },