@capgo/capacitor-updater 7.42.9 → 7.45.10

package/dist/docs.json

@@ -343,7 +343,7 @@
           },
           {
             "name": "link",
-            "text": "ResetOptions} to control reset behavior. If `toLastSuccessful` is `false` (or omitted), resets to builtin. If `true`, resets to last successful bundle."
+            "text": "ResetOptions} to control reset behavior.\nIf `toLastSuccessful` is `false` (or omitted), resets to builtin.\nIf `true`, resets to last successful bundle.\nIf `usePendingBundle` is `true`, applies the pending bundle set via {@link next} and clears it."
           },
           {
             "name": "returns",
@@ -492,14 +492,14 @@
           },
           {
             "name": "throws",
-            "text": "{Error} Always throws when no new version is available (`error: \"no_new_version_available\"`), or when the request fails."
+            "text": "{Error} Throws for failed update checks or transport/request failures."
           },
           {
             "name": "since",
             "text": "4.0.0"
           }
         ],
-        "docs": "Check the update server for the latest available bundle version.\n\nThis queries your configured update URL (or Capgo backend) to see if a newer bundle\nis available for download. It does NOT download the bundle automatically.\n\nThe response includes:\n- `version`: The latest available version identifier\n- `url`: Download URL for the bundle (if available)\n- `breaking`: Whether this update is marked as incompatible (requires native app update)\n- `message`: Optional message from the server\n- `manifest`: File list for delta updates (if using multi-file downloads)\n\nAfter receiving the latest version info, you can:\n1. Compare it with your current version\n2. Download it using {@link download}\n3. Apply it using {@link next} or {@link set}\n\n**Important: Error handling for \"no new version available\"**\n\nWhen the device's current version matches the latest version on the server (i.e., the device is already\nup-to-date), the server returns a 200 response with `error: \"no_new_version_available\"` and\n`message: \"No new version available\"`. **This causes `getLatest()` to throw an error**, even though\nthis is a normal, expected condition.\n\nYou should catch this specific error to handle it gracefully:\n\n```typescript\ntry {\n  const latest = await CapacitorUpdater.getLatest();\n  // New version is available, proceed with download\n} catch (error) {\n  if (error.message === 'No new version available') {\n    // Device is already on the latest version - this is normal\n    console.log('Already up to date');\n  } else {\n    // Actual error occurred\n    console.error('Failed to check for updates:', error);\n  }\n}\n```\n\nIn this scenario, the server:\n- Logs the request with a \"No new version available\" message\n- Sends a \"noNew\" stat action to track that the device checked for updates but was already current (done on the backend)",
+        "docs": "Check the update server for the latest available bundle version.\n\nThis queries your configured update URL (or Capgo backend) to see if a newer bundle\nis available for download. It does NOT download the bundle automatically.\n\nThe response includes:\n- `version`: The latest available version identifier\n- `url`: Download URL for the bundle (if available)\n- `breaking`: Whether this update is marked as incompatible (requires native app update)\n- `message`: Optional message from the server\n- `manifest`: File list for delta updates (if using multi-file downloads)\n\nAfter receiving the latest version info, you can:\n1. Compare it with your current version\n2. Download it using {@link download}\n3. Apply it using {@link next} or {@link set}\n\n**Important: Handling \"no new version available\"**\n\nWhen the device's current version matches the latest version on the server (i.e., the device is already\nup-to-date), the server returns a 200 response with `error: \"no_new_version_available\"` and\n`message: \"No new version available\"`. This is a normal, expected condition and resolves with\n`kind: \"up_to_date\"` when the backend provides that classification.\n\nYou should check `kind` and `error` before attempting to download:\n\n```typescript\nconst latest = await CapacitorUpdater.getLatest();\nif (latest.kind === 'up_to_date') {\n  console.log('Already up to date');\n} else if (latest.kind === 'blocked') {\n  console.log('Update is blocked:', latest.error);\n} else if (latest.url) {\n  // New version is available, proceed with download\n}\n```\n\nIn this scenario, the server:\n- Logs the request with a \"No new version available\" message\n- Sends a \"noNew\" stat action to track that the device checked for updates but was already current (done on the backend)",
         "complexTypes": [
           "LatestVersion",
           "GetLatestOptions"
@@ -765,7 +765,7 @@
             "text": "1.0.0"
           }
         ],
-        "docs": "Remove all event listeners registered for this plugin.\n\nThis unregisters all listeners added via {@link addListener} for all event types:\n- `download`\n- `noNeedUpdate`\n- `updateAvailable`\n- `downloadComplete`\n- `downloadFailed`\n- `breakingAvailable` / `majorAvailable`\n- `updateFailed`\n- `appReloaded`\n- `appReady`\n\nUse this during cleanup (e.g., when unmounting components or closing screens)\nto prevent memory leaks from lingering event listeners.",
+        "docs": "Remove all event listeners registered for this plugin.\n\nThis unregisters all listeners added via {@link addListener} for all event types:\n- `download`\n- `noNeedUpdate`\n- `updateCheckResult`\n- `updateAvailable`\n- `downloadComplete`\n- `downloadFailed`\n- `breakingAvailable` / `majorAvailable`\n- `updateFailed`\n- `appReloaded`\n- `appReady`\n\nUse this during cleanup (e.g., when unmounting components or closing screens)\nto prevent memory leaks from lingering event listeners.",
         "complexTypes": [],
         "slug": "removealllisteners"
       },
@@ -827,6 +827,35 @@
         ],
         "slug": "addlistenernoneedupdate-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'updateCheckResult', listenerFunc: (state: UpdateCheckResultEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'updateCheckResult'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(state: UpdateCheckResultEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.45.11"
+          }
+        ],
+        "docs": "Listen for update check results before the updater decides whether to download.\nThe backend can classify the UpdateCheckResultEvent payload as `up_to_date`, `blocked`, or `failed`.\n\nThis event is emitted alongside legacy events. For `up_to_date` and `blocked`, it is emitted before\n`noNeedUpdate` and does not emit `downloadFailed`. For `failed`, it is emitted before the legacy\n`downloadFailed` event and keeps the existing failure stats behavior.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "UpdateCheckResultEvent"
+        ],
+        "slug": "addlistenerupdatecheckresult-"
+      },
       {
         "name": "addListener",
         "signature": "(eventName: 'updateAvailable', listenerFunc: (state: UpdateAvailableEvent) => void) => Promise<PluginListenerHandle>",
@@ -976,6 +1005,64 @@
         ],
         "slug": "addlistenerupdatefailed-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'set', listenerFunc: (state: SetEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'set'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(state: SetEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.43.12"
+          }
+        ],
+        "docs": "Listen for set event in the App, let you know when a bundle has been applied successfully.\nThis event is retained natively until JavaScript consumes it, so if the app reloads before your\nlistener is attached, the last pending `set` event is delivered once the listener subscribes.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "SetEvent"
+        ],
+        "slug": "addlistenerset-"
+      },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'setNext', listenerFunc: (state: SetNextEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'setNext'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "(state: SetNextEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "6.14.0"
+          }
+        ],
+        "docs": "Listen for set next event in the App, let you know when a bundle is queued as the next bundle to install.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "SetNextEvent"
+        ],
+        "slug": "addlistenersetnext-"
+      },
       {
         "name": "addListener",
         "signature": "(eventName: 'downloadFailed', listenerFunc: (state: DownloadFailedEvent) => void) => Promise<PluginListenerHandle>",
@@ -1055,7 +1142,7 @@
             "text": "5.1.0"
           }
         ],
-        "docs": "Listen for app ready event in the App, let you know when app is ready to use, this event is retain till consumed.",
+        "docs": "Listen for app ready event in the App, let you know when app is ready to use.\nThis event is retained natively until JavaScript consumes it, so it can still be delivered after\na reload even if the listener is attached later in app startup.",
         "complexTypes": [
           "PluginListenerHandle",
           "AppReadyEvent"
@@ -1255,6 +1342,70 @@
         ],
         "slug": "isshakemenuenabled"
       },
+      {
+        "name": "setShakeChannelSelector",
+        "signature": "(options: SetShakeChannelSelectorOptions) => Promise<void>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "SetShakeChannelSelectorOptions"
+          }
+        ],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options"
+          },
+          {
+            "name": "link",
+            "text": "SetShakeChannelSelectorOptions} with `enabled: true` to enable or `enabled: false` to disable."
+          },
+          {
+            "name": "returns",
+            "text": "Resolves when the setting is applied."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If the operation fails."
+          },
+          {
+            "name": "since",
+            "text": "8.43.0"
+          }
+        ],
+        "docs": "Enable or disable the shake channel selector at runtime.\n\nWhen enabled AND shakeMenu is true, shaking the device shows a channel\nselector instead of the debug menu. This allows users to switch between\nupdate channels by shaking their device.\n\nAfter selecting a channel, the app automatically checks for updates\nand downloads if available.\n\nCan also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.",
+        "complexTypes": [
+          "SetShakeChannelSelectorOptions"
+        ],
+        "slug": "setshakechannelselector"
+      },
+      {
+        "name": "isShakeChannelSelectorEnabled",
+        "signature": "() => Promise<ShakeChannelSelectorEnabled>",
+        "parameters": [],
+        "returns": "Promise<ShakeChannelSelectorEnabled>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Object with `enabled: true` or `enabled: false`."
+          },
+          {
+            "name": "throws",
+            "text": "{Error} If the operation fails."
+          },
+          {
+            "name": "since",
+            "text": "8.43.0"
+          }
+        ],
+        "docs": "Check if the shake channel selector is currently enabled.\n\nReturns the current state of the shake channel selector feature that can be toggled via\n{@link setShakeChannelSelector} or configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.",
+        "complexTypes": [
+          "ShakeChannelSelectorEnabled"
+        ],
+        "slug": "isshakechannelselectorenabled"
+      },
       {
         "name": "getAppId",
         "signature": "() => Promise<GetAppIdRes>",
@@ -1750,10 +1901,27 @@
       "properties": [
         {
           "name": "toLastSuccessful",
-          "tags": [],
-          "docs": "",
+          "tags": [
+            {
+              "text": "false",
+              "name": "default"
+            }
+          ],
+          "docs": "Reset to the last successfully loaded bundle instead of the builtin one.",
           "complexTypes": [],
-          "type": "boolean"
+          "type": "boolean | undefined"
+        },
+        {
+          "name": "usePendingBundle",
+          "tags": [
+            {
+              "text": "false",
+              "name": "default"
+            }
+          ],
+          "docs": "Apply the pending bundle set via {@link next} while resetting.\n\nWhen `true`, the plugin will switch to the pending bundle immediately and clear the pending flag.\nIf no pending bundle exists, the reset will fail.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ]
     },
@@ -1906,10 +2074,36 @@
         {
           "name": "error",
           "tags": [],
-          "docs": "Error code from the server, if any.\nCommon values:\n- `\"no_new_version_available\"`: Device is already on the latest version (not a failure)\n- Other error codes indicate actual failures in the update process",
+          "docs": "Error code from the server, if any. Use `kind` for classification instead of parsing this value.",
           "complexTypes": [],
           "type": "string | undefined"
         },
+        {
+          "name": "kind",
+          "tags": [
+            {
+              "text": "8.45.11",
+              "name": "since"
+            }
+          ],
+          "docs": "Classification for this response, provided by the backend.",
+          "complexTypes": [
+            "UpdateResponseKind"
+          ],
+          "type": "UpdateResponseKind"
+        },
+        {
+          "name": "statusCode",
+          "tags": [
+            {
+              "text": "8.45.11",
+              "name": "since"
+            }
+          ],
+          "docs": "HTTP status code returned by the update server for classified update-check responses.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
         {
           "name": "old",
           "tags": [],
@@ -2341,6 +2535,91 @@
         }
       ]
     },
+    {
+      "name": "UpdateCheckResultEvent",
+      "slug": "updatecheckresultevent",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "kind",
+          "tags": [
+            {
+              "text": "8.45.11",
+              "name": "since"
+            }
+          ],
+          "docs": "Classification for the update check result, provided by the backend.",
+          "complexTypes": [
+            "UpdateResponseKind"
+          ],
+          "type": "UpdateResponseKind"
+        },
+        {
+          "name": "error",
+          "tags": [
+            {
+              "text": "8.45.11",
+              "name": "since"
+            }
+          ],
+          "docs": "Backend error code, when provided.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "message",
+          "tags": [
+            {
+              "text": "8.45.11",
+              "name": "since"
+            }
+          ],
+          "docs": "Backend message, when provided.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "statusCode",
+          "tags": [
+            {
+              "text": "8.45.11",
+              "name": "since"
+            }
+          ],
+          "docs": "HTTP status code returned by the update endpoint.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "version",
+          "tags": [
+            {
+              "text": "8.45.11",
+              "name": "since"
+            }
+          ],
+          "docs": "Version referenced by the update check result.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "bundle",
+          "tags": [
+            {
+              "text": "8.45.11",
+              "name": "since"
+            }
+          ],
+          "docs": "Current bundle on the device.",
+          "complexTypes": [
+            "BundleInfo"
+          ],
+          "type": "BundleInfo"
+        }
+      ]
+    },
     {
       "name": "UpdateAvailableEvent",
       "slug": "updateavailableevent",
@@ -2435,6 +2714,52 @@
         }
       ]
     },
+    {
+      "name": "SetEvent",
+      "slug": "setevent",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "bundle",
+          "tags": [
+            {
+              "text": "8.43.12",
+              "name": "since"
+            }
+          ],
+          "docs": "Emit when a bundle has been applied successfully.\nThis event uses native `retainUntilConsumed` behavior.",
+          "complexTypes": [
+            "BundleInfo"
+          ],
+          "type": "BundleInfo"
+        }
+      ]
+    },
+    {
+      "name": "SetNextEvent",
+      "slug": "setnextevent",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "bundle",
+          "tags": [
+            {
+              "text": "6.14.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Emit when a bundle is queued as the next bundle to install.",
+          "complexTypes": [
+            "BundleInfo"
+          ],
+          "type": "BundleInfo"
+        }
+      ]
+    },
     {
       "name": "DownloadFailedEvent",
       "slug": "downloadfailedevent",
@@ -2471,7 +2796,7 @@
               "name": "since"
             }
           ],
-          "docs": "Emitted when the app is ready to use.",
+          "docs": "Emitted when the app is ready to use.\nThis event uses native `retainUntilConsumed` behavior.",
           "complexTypes": [
             "BundleInfo"
           ],
@@ -2614,6 +2939,38 @@
         }
       ]
     },
+    {
+      "name": "SetShakeChannelSelectorOptions",
+      "slug": "setshakechannelselectoroptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "enabled",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
+    {
+      "name": "ShakeChannelSelectorEnabled",
+      "slug": "shakechannelselectorenabled",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "enabled",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
     {
       "name": "GetAppIdRes",
       "slug": "getappidres",
@@ -3076,6 +3433,25 @@
         }
       ]
     },
+    {
+      "name": "UpdateResponseKind",
+      "slug": "updateresponsekind",
+      "docs": "Classification for update-check responses that do not provide a downloadable bundle.\nThe update backend provides this field directly. Missing or unknown values are treated as\nfailed by native clients.",
+      "types": [
+        {
+          "text": "'up_to_date'",
+          "complexTypes": []
+        },
+        {
+          "text": "'blocked'",
+          "complexTypes": []
+        },
+        {
+          "text": "'failed'",
+          "complexTypes": []
+        }
+      ]
+    },
     {
       "name": "BreakingAvailableEvent",
       "slug": "breakingavailableevent",
@@ -3658,6 +4034,22 @@
           "docs": "Enable shake gesture to show update menu for debugging/testing purposes",
           "complexTypes": [],
           "type": "boolean | undefined"
+        },
+        {
+          "name": "allowShakeChannelSelector",
+          "tags": [
+            {
+              "text": "false",
+              "name": "default"
+            },
+            {
+              "text": "8.43.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Enable the shake gesture to show a channel selector menu for switching between update channels.\nWhen enabled AND `shakeMenu` is true, the shake gesture shows a channel selector\ninstead of the default debug menu (Go Home/Reload/Close).\n\nAfter selecting a channel, the app automatically checks for updates and downloads if available.\nOnly works if channels have `allow_self_set` enabled on the backend.\n\nOnly available for Android and iOS.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ],
       "docs": "CapacitorUpdater can be configured with these options:"