@capgo/capacitor-updater 8.45.10 → 8.46.0

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

@@ -1088,7 +1088,16 @@ public class CapgoUpdater {
         this.sendStats("set", bundle.getVersionName(), previousBundleName);
     }
 
+    @Deprecated
     public void autoReset() {
+        this.autoReset(this.versionCode == null ? "" : this.versionCode);
+    }
+
+    public void autoReset(final String currentNativeBuildVersion) {
+        this.autoReset(currentNativeBuildVersion, true);
+    }
+
+    public void autoReset(final String currentNativeBuildVersion, final boolean resetWhenNativeVersionChanged) {
         final BundleInfo currentBundle = this.getCurrentBundle();
         if (!currentBundle.isBuiltin() && !this.bundleExists(currentBundle.getId())) {
             logger.info("Folder at bundle path does not exist. Triggering reset.");
@@ -1099,7 +1108,36 @@ public class CapgoUpdater {
         if (shouldResetForForeignBundle(bundlePath, currentBundle.isBuiltin(), this.hasStoredBundleInfo(currentBundle.getId()))) {
             logger.info("Current bundle id is not one of the bundle ids stored by this plugin. Triggering reset.");
             this.reset();
+            return;
+        }
+        final String previousNativeBuildVersion = this.getStoredNativeBuildVersion();
+        if (
+            resetWhenNativeVersionChanged &&
+            !previousNativeBuildVersion.isEmpty() &&
+            currentNativeBuildVersion != null &&
+            !currentNativeBuildVersion.isEmpty() &&
+            !Objects.equals(previousNativeBuildVersion, currentNativeBuildVersion)
+        ) {
+            logger.info(
+                "Stored native build version " +
+                    previousNativeBuildVersion +
+                    " does not match current native build version " +
+                    currentNativeBuildVersion +
+                    ". Triggering reset."
+            );
+            this.reset();
+        }
+    }
+
+    private String getStoredNativeBuildVersion() {
+        if (this.prefs == null) {
+            return "";
+        }
+        String previousNativeBuildVersion = this.prefs.getString("LatestNativeBuildVersion", "");
+        if (previousNativeBuildVersion == null || previousNativeBuildVersion.isEmpty()) {
+            previousNativeBuildVersion = this.prefs.getString("LatestVersionNative", "");
         }
+        return previousNativeBuildVersion == null ? "" : previousNativeBuildVersion;
     }
 
     public void reset() {
@@ -1229,6 +1267,7 @@ public class CapgoUpdater {
                         Map<String, Object> retError = new HashMap<>();
                         retError.put("message", "Request failed: " + e.getMessage());
                         retError.put("error", "network_error");
+                        retError.put("kind", "failed");
                         callback.callback(retError);
                     }
 
@@ -1236,11 +1275,46 @@ public class CapgoUpdater {
                     public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException {
                         try (ResponseBody responseBody = response.body()) {
                             final int statusCode = response.code();
+                            final String responseData = responseBody != null ? responseBody.string() : "";
+                            JSONObject jsonResponse = null;
+                            if (!responseData.isEmpty()) {
+                                try {
+                                    jsonResponse = new JSONObject(responseData);
+                                } catch (JSONException ignored) {
+                                    // Non-JSON responses are handled as response or parse errors below.
+                                }
+                            }
+
+                            if (jsonResponse != null && (jsonResponse.has("error") || jsonResponse.has("kind"))) {
+                                if (statusCode == 429) {
+                                    checkAndHandleRateLimitResponse(response);
+                                }
+                                Map<String, Object> retError = new HashMap<>();
+                                if (jsonResponse.has("error") && !jsonResponse.isNull("error")) {
+                                    retError.put("error", jsonResponse.getString("error"));
+                                }
+                                if (jsonResponse.has("kind") && !jsonResponse.isNull("kind")) {
+                                    retError.put("kind", jsonResponse.getString("kind"));
+                                }
+                                if (jsonResponse.has("message") && !jsonResponse.isNull("message")) {
+                                    retError.put("message", jsonResponse.getString("message"));
+                                } else {
+                                    retError.put("message", "server did not provide a message");
+                                }
+                                if (jsonResponse.has("version") && !jsonResponse.isNull("version")) {
+                                    retError.put("version", jsonResponse.getString("version"));
+                                }
+                                retError.put("statusCode", statusCode);
+                                callback.callback(retError);
+                                return;
+                            }
+
                             // Check for 429 rate limit
                             if (checkAndHandleRateLimitResponse(response)) {
                                 Map<String, Object> retError = new HashMap<>();
                                 retError.put("message", "Rate limit exceeded");
                                 retError.put("error", "rate_limit_exceeded");
+                                retError.put("kind", "failed");
                                 retError.put("statusCode", statusCode);
                                 callback.callback(retError);
                                 return;
@@ -1250,27 +1324,14 @@ public class CapgoUpdater {
                                 Map<String, Object> retError = new HashMap<>();
                                 retError.put("message", "Server error: " + response.code());
                                 retError.put("error", "response_error");
+                                retError.put("kind", "failed");
                                 retError.put("statusCode", statusCode);
                                 callback.callback(retError);
                                 return;
                             }
 
-                            assert responseBody != null;
-                            String responseData = responseBody.string();
-                            JSONObject jsonResponse = new JSONObject(responseData);
-
-                            // Check for server-side errors first
-                            if (jsonResponse.has("error")) {
-                                Map<String, Object> retError = new HashMap<>();
-                                retError.put("error", jsonResponse.getString("error"));
-                                if (jsonResponse.has("message")) {
-                                    retError.put("message", jsonResponse.getString("message"));
-                                } else {
-                                    retError.put("message", "server did not provide a message");
-                                }
-                                retError.put("statusCode", statusCode);
-                                callback.callback(retError);
-                                return;
+                            if (jsonResponse == null) {
+                                throw new JSONException("Response is not a JSON object");
                             }
 
                             Map<String, Object> ret = new HashMap<>();
@@ -1292,6 +1353,7 @@ public class CapgoUpdater {
                             Map<String, Object> retError = new HashMap<>();
                             retError.put("message", "JSON parse error: " + e.getMessage());
                             retError.put("error", "parse_error");
+                            retError.put("kind", "failed");
                             callback.callback(retError);
                         }
                     }
@@ -1683,6 +1745,10 @@ public class CapgoUpdater {
     }
 
     public void sendStats(final String action, final String versionName, final String oldVersionName) {
+        this.sendStats(action, versionName, oldVersionName, null);
+    }
+
+    public void sendStats(final String action, final String versionName, final String oldVersionName, final Map<String, String> metadata) {
         // Check if rate limit was exceeded
         if (rateLimitExceeded) {
             logger.debug("Skipping sendStats due to rate limit (429). Stats will resume after app restart.");
@@ -1701,6 +1767,9 @@ public class CapgoUpdater {
             json.put("old_version_name", oldVersionName);
             json.put("action", action);
             json.put("timestamp", System.currentTimeMillis());
+            if (metadata != null && !metadata.isEmpty()) {
+                json.put("metadata", new JSONObject(metadata));
+            }
         } catch (JSONException e) {
             logger.error("Error preparing stats");
             logger.debug("JSONException: " + e.getMessage());

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

@@ -448,12 +448,36 @@ public class ShakeMenu implements ShakeDetector.Listener {
                                 }
 
                                 String latestError = getString(latestRes, "error");
+                                String latestKind = getString(latestRes, "kind");
+                                String latestMessage = getString(latestRes, "message");
+
+                                String detail = latestMessage != null && !latestMessage.isEmpty()
+                                    ? latestMessage
+                                    : latestError != null && !latestError.isEmpty()
+                                        ? latestError
+                                        : latestKind != null && !latestKind.isEmpty()
+                                            ? latestKind
+                                            : "server did not provide a message";
 
                                 // Handle update errors first (before "no new version" check)
-                                if (latestError != null && !latestError.isEmpty() && !"no_new_version_available".equals(latestError)) {
+                                if (
+                                    "failed".equals(latestKind) ||
+                                    (latestError != null &&
+                                        !latestError.isEmpty() &&
+                                        !"up_to_date".equals(latestKind) &&
+                                        !"blocked".equals(latestKind))
+                                ) {
+                                    activity.runOnUiThread(() -> {
+                                        progressDialog.dismiss();
+                                        showError("Channel set to " + channelName + ". Update check failed: " + detail);
+                                    });
+                                    return;
+                                }
+
+                                if ("blocked".equals(latestKind)) {
                                     activity.runOnUiThread(() -> {
                                         progressDialog.dismiss();
-                                        showError("Channel set to " + channelName + ". Update check failed: " + latestError);
+                                        showError("Channel set to " + channelName + ". Update check blocked: " + detail);
                                     });
                                     return;
                                 }
@@ -461,7 +485,7 @@ public class ShakeMenu implements ShakeDetector.Listener {
                                 String latestUrl = getString(latestRes, "url");
 
                                 // Check if there's an actual update available
-                                if ("no_new_version_available".equals(latestError) || latestUrl == null || latestUrl.isEmpty()) {
+                                if ("up_to_date".equals(latestKind) || latestUrl == null || latestUrl.isEmpty()) {
                                     activity.runOnUiThread(() -> {
                                         progressDialog.dismiss();
                                         showSuccess("Channel set to " + channelName + ". Already on latest version.");

package/dist/docs.json

@@ -470,6 +470,23 @@
         "complexTypes": [],
         "slug": "canceldelay"
       },
+      {
+        "name": "triggerUpdateCheck",
+        "signature": "() => Promise<TriggerUpdateCheckResult>",
+        "parameters": [],
+        "returns": "Promise<TriggerUpdateCheckResult>",
+        "tags": [
+          {
+            "name": "returns",
+            "text": "Whether a native update check was queued."
+          }
+        ],
+        "docs": "Trigger the native auto-update check/download pipeline immediately.\n\nThis starts the same background update flow used when the app moves to the\nforeground with auto-update enabled. It is useful for native integrations\nsuch as a silent push notification asking the app to check for a Capgo\nbundle without reimplementing the update protocol in JavaScript.\n\nThe promise resolves after the native background work has been queued, not\nafter the update has been downloaded or installed. Listen to updater events\nsuch as `updateAvailable`, `downloadComplete`, `downloadFailed`, and\n`noNeedUpdate` for the final result.\n\nNative support is available on iOS and Android. On Web, this method returns\na result with `status: 'unavailable'`. Native platforms also return\n`unavailable` when the native auto-update system is disabled.",
+        "complexTypes": [
+          "TriggerUpdateCheckResult"
+        ],
+        "slug": "triggerupdatecheck"
+      },
       {
         "name": "getLatest",
         "signature": "(options?: GetLatestOptions | undefined) => Promise<LatestVersion>",
@@ -492,14 +509,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 +782,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 +844,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>",
@@ -1973,6 +2019,38 @@
         }
       ]
     },
+    {
+      "name": "TriggerUpdateCheckResult",
+      "slug": "triggerupdatecheckresult",
+      "docs": "Result returned after requesting an immediate native auto-update check.",
+      "tags": [
+        {
+          "text": "status - Native trigger state: `queued` when a check was queued,\n`already_running` when the native update pipeline is already active, or\n`unavailable` on Web or when native auto-update is disabled.",
+          "name": "property"
+        },
+        {
+          "text": "queued - Whether a new native update check was queued. This is\n`true` only when `status` is `queued`; otherwise it is `false`.",
+          "name": "property"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "status",
+          "tags": [],
+          "docs": "Native trigger state: `queued` when a check was queued, `already_running`\nwhen the native update pipeline is already active, or `unavailable` on Web\nor when native auto-update is disabled.",
+          "complexTypes": [],
+          "type": "'queued' | 'already_running' | 'unavailable'"
+        },
+        {
+          "name": "queued",
+          "tags": [],
+          "docs": "Whether a new native update check was queued. This is `true` only when\n`status` is `queued`; otherwise it is `false`.",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
     {
       "name": "LatestVersion",
       "slug": "latestversion",
@@ -2045,10 +2123,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 +2584,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 +3482,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",
@@ -3452,7 +3660,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure the URL / endpoint to which update statistics are sent.\n\nOnly available for Android and iOS. Set to \"\" to disable stats reporting.",
+          "docs": "Configure the URL / endpoint to which update statistics are sent.\n\nOnly available for Android and iOS. Set to \"\" to disable stats reporting.\nNative stats include update lifecycle events, app health signals such as crashes,\nAndroid ANRs, low-memory exits, iOS memory warnings, and WebView health signals\nsuch as JavaScript errors, unhandled promise rejections, resource load failures,\nWebView renderer exits, and unclean WebView restarts when available.",
           "complexTypes": [],
           "type": "string | undefined"
         },