@capgo/capacitor-updater 8.45.10 → 8.45.11

package/dist/docs.json

@@ -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>",
@@ -2045,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": [],
@@ -2480,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",
@@ -3293,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",

package/dist/esm/definitions.d.ts

@@ -695,27 +695,23 @@ export interface CapacitorUpdaterPlugin {
      * 2. Download it using {@link download}
      * 3. Apply it using {@link next} or {@link set}
      *
-     * **Important: Error handling for "no new version available"**
+     * **Important: Handling "no new version available"**
      *
      * When the device's current version matches the latest version on the server (i.e., the device is already
      * up-to-date), the server returns a 200 response with `error: "no_new_version_available"` and
-     * `message: "No new version available"`. **This causes `getLatest()` to throw an error**, even though
-     * this is a normal, expected condition.
+     * `message: "No new version available"`. This is a normal, expected condition and resolves with
+     * `kind: "up_to_date"` when the backend provides that classification.
      *
-     * You should catch this specific error to handle it gracefully:
+     * You should check `kind` and `error` before attempting to download:
      *
      * ```typescript
-     * try {
-     *   const latest = await CapacitorUpdater.getLatest();
+     * const latest = await CapacitorUpdater.getLatest();
+     * if (latest.kind === 'up_to_date') {
+     *   console.log('Already up to date');
+     * } else if (latest.kind === 'blocked') {
+     *   console.log('Update is blocked:', latest.error);
+     * } else if (latest.url) {
      *   // New version is available, proceed with download
-     * } catch (error) {
-     *   if (error.message === 'No new version available') {
-     *     // Device is already on the latest version - this is normal
-     *     console.log('Already up to date');
-     *   } else {
-     *     // Actual error occurred
-     *     console.error('Failed to check for updates:', error);
-     *   }
      * }
      * ```
      *
@@ -725,7 +721,7 @@ export interface CapacitorUpdaterPlugin {
      *
      * @param options Optional {@link GetLatestOptions} to specify which channel to check.
      * @returns {Promise<LatestVersion>} Information about the latest available bundle version.
-     * @throws {Error} Always throws when no new version is available (`error: "no_new_version_available"`), or when the request fails.
+     * @throws {Error} Throws for failed update checks or transport/request failures.
      * @since 4.0.0
      */
     getLatest(options?: GetLatestOptions): Promise<LatestVersion>;
@@ -941,6 +937,7 @@ export interface CapacitorUpdaterPlugin {
      * This unregisters all listeners added via {@link addListener} for all event types:
      * - `download`
      * - `noNeedUpdate`
+     * - `updateCheckResult`
      * - `updateAvailable`
      * - `downloadComplete`
      * - `downloadFailed`
@@ -969,6 +966,17 @@ export interface CapacitorUpdaterPlugin {
      * @since 4.0.0
      */
     addListener(eventName: 'noNeedUpdate', listenerFunc: (state: NoNeedEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Listen for update check results before the updater decides whether to download.
+     * The backend can classify the UpdateCheckResultEvent payload as `up_to_date`, `blocked`, or `failed`.
+     *
+     * This event is emitted alongside legacy events. For `up_to_date` and `blocked`, it is emitted before
+     * `noNeedUpdate` and does not emit `downloadFailed`. For `failed`, it is emitted before the legacy
+     * `downloadFailed` event and keeps the existing failure stats behavior.
+     *
+     * @since 8.45.11
+     */
+    addListener(eventName: 'updateCheckResult', listenerFunc: (state: UpdateCheckResultEvent) => void): Promise<PluginListenerHandle>;
     /**
      * Listen for available update event, useful when you want to force check every time the app is launched
      *
@@ -1376,6 +1384,14 @@ export interface CapacitorUpdaterPlugin {
  */
 export type BundleStatus = 'success' | 'error' | 'pending' | 'downloading';
 export type DelayUntilNext = 'background' | 'kill' | 'nativeVersion' | 'date';
+/**
+ * Classification for update-check responses that do not provide a downloadable bundle.
+ * The update backend provides this field directly. Missing or unknown values are treated as
+ * failed by native clients.
+ *
+ * @since 8.45.11
+ */
+export type UpdateResponseKind = 'up_to_date' | 'blocked' | 'failed';
 export interface NoNeedEvent {
     /**
      * Current status of download, between 0 and 100.
@@ -1384,6 +1400,44 @@ export interface NoNeedEvent {
      */
     bundle: BundleInfo;
 }
+export interface UpdateCheckResultEvent {
+    /**
+     * Classification for the update check result, provided by the backend.
+     *
+     * @since 8.45.11
+     */
+    kind: UpdateResponseKind;
+    /**
+     * Backend error code, when provided.
+     *
+     * @since 8.45.11
+     */
+    error?: string;
+    /**
+     * Backend message, when provided.
+     *
+     * @since 8.45.11
+     */
+    message?: string;
+    /**
+     * HTTP status code returned by the update endpoint.
+     *
+     * @since 8.45.11
+     */
+    statusCode?: number;
+    /**
+     * Version referenced by the update check result.
+     *
+     * @since 8.45.11
+     */
+    version?: string;
+    /**
+     * Current bundle on the device.
+     *
+     * @since 8.45.11
+     */
+    bundle: BundleInfo;
+}
 export interface UpdateAvailableEvent {
     /**
      * Current status of download, between 0 and 100.
@@ -1565,12 +1619,21 @@ export interface LatestVersion {
     message?: string;
     sessionKey?: string;
     /**
-     * Error code from the server, if any.
-     * Common values:
-     * - `"no_new_version_available"`: Device is already on the latest version (not a failure)
-     * - Other error codes indicate actual failures in the update process
+     * Error code from the server, if any. Use `kind` for classification instead of parsing this value.
      */
     error?: string;
+    /**
+     * Classification for this response, provided by the backend.
+     *
+     * @since 8.45.11
+     */
+    kind?: UpdateResponseKind;
+    /**
+     * HTTP status code returned by the update server for classified update-check responses.
+     *
+     * @since 8.45.11
+     */
+    statusCode?: number;
     /**
      * The previous/current version name (provided for reference).
      */