@otakit/capacitor-updater 1.0.0 → 1.2.0

package/README.md

@@ -7,8 +7,10 @@ Capacitor OTA updater plugin for OtaKit.
 - checks the manifest endpoint for a newer bundle
 - downloads and verifies OTA bundles
 - stages updates safely
-- activates them on the next launch or immediately during startup
+- activates them on the next launch, next resume, or immediately
+- checks for updates on cold start and app resume (configurable interval)
 - also supports fully manual update prompts when the app wants control
+- supports optional `runtimeVersion` lanes for native compatibility boundaries
 - requires `notifyAppReady()` as the success handshake
 - rolls back automatically if the new bundle does not prove healthy
 
@@ -45,6 +47,8 @@ plugins: {
     appReadyTimeout: 10000,
     // Optional:
     // channel: "staging",
+    // runtimeVersion: "2026.04",
+    // updateMode: "next-resume",
     // updateMode: "manual",
     // updateMode: "immediate",
   }
@@ -60,6 +64,22 @@ Advanced overrides for self-hosting or custom trust only:
 Hosted OtaKit already points at `https://otakit.app/api/v1` and already trusts
 the managed manifest signing keys.
 
+## Channels vs runtimeVersion
+
+- `channel` answers "who should get this rollout?"
+- `runtimeVersion` answers "which native app shell can safely run this bundle?"
+
+Use channels for rollout tracks such as `beta`, `staging`, or `production`.
+
+Use `runtimeVersion` when a new store build creates a new compatibility boundary and you do not
+want devices on that new native shell to keep receiving older OTA bundles.
+
+When `runtimeVersion` is set:
+
+- the plugin requests bundle updates only for that runtime lane
+- bundle uploads inherit the same runtime value automatically through the CLI
+- releases stay simple: publish the bundle, and it naturally stays inside its own runtime lane
+
 ## Trust model
 
 The plugin does not just download from a URL and trust the result.
@@ -74,14 +94,32 @@ In the hosted path, managed signing keys are already built in.
 
 ## Update modes
 
+All automatic modes check for updates on **cold start** (always) and **app
+resume**.
+
+### Production modes
+
+- `next-launch` (default)
+  check and download in the background on cold start and resume.
+  activate the staged bundle only on the next cold start.
+  zero disruption during a session — the user never sees a surprise reload.
+
+- `next-resume` (more eager)
+  check and download in the background on cold start and resume.
+  activate the staged bundle on the next resume or cold start.
+
+### Manual mode
+
 - `manual`
-  no automatic startup check and no automatic staged activation
-- `next-launch`
-  automatic startup check, download in the background, activate on the next cold launch
+  no automatic checks, no automatic staged activation.
+  the app integration drives everything via `check()`, `download()`, `apply()`, or `update()`.
+
+### Dev/debug mode
+
 - `immediate`
-  automatic startup check, then download and activate during startup
+  checks, downloads, and activates in one shot as soon as possible on cold start and resume (the user may briefly see the previous version before a reload).
+  primarily for development and testing — not recommended for production.
 
-The default is `next-launch`.
 
 ## Runtime model
 
@@ -127,7 +165,8 @@ await OtaKit.notifyAppReady();
 ```
 
 The plugin handles checking, downloading, activation, and rollback based on
-`updateMode`.
+`updateMode`. It checks on cold start and every time the app comes back from
+the background (throttled by `checkInterval`).
 
 For most apps, this is the entire runtime integration.
 
@@ -154,6 +193,13 @@ await OtaKit.apply();
 Use the split flow when the app wants to download in the background and switch
 only after explicit user confirmation.
 
+## Throttle
+
+All server checks are rate-limited by `checkInterval` (default 10 min).
+This applies to automatic resume checks and to manual `check()` / `download()`
+calls. Within the interval, calls return the staged bundle if one exists, or
+null.
+
 ## Retention and deletion
 
 - the builtin, current, fallback, and staged bundles are protected

package/android/src/main/java/com/updatekit/updater/BundleInfo.java

@@ -8,6 +8,7 @@ class BundleInfo {
 
   final String id;
   final String version;
+  final String runtimeVersion;
   final BundleStatus status;
   final Long downloadedAt;
   final String sha256;
@@ -18,6 +19,7 @@ class BundleInfo {
   BundleInfo(
     String id,
     String version,
+    String runtimeVersion,
     BundleStatus status,
     Long downloadedAt,
     String sha256,
@@ -27,6 +29,7 @@ class BundleInfo {
   ) {
     this.id = id;
     this.version = version;
+    this.runtimeVersion = runtimeVersion;
     this.status = status;
     this.downloadedAt = downloadedAt;
     this.sha256 = sha256;
@@ -43,6 +46,9 @@ class BundleInfo {
     JSObject object = new JSObject();
     object.put("id", id);
     object.put("version", version);
+    if (runtimeVersion != null) {
+      object.put("runtimeVersion", runtimeVersion);
+    }
     object.put("status", status.value());
     if (downloadedAt != null) {
       object.put("downloadedAt", DateUtils.toIsoString(downloadedAt));
@@ -63,6 +69,9 @@ class BundleInfo {
     JSONObject object = new JSONObject();
     object.put("id", id);
     object.put("version", version);
+    if (runtimeVersion != null) {
+      object.put("runtimeVersion", runtimeVersion);
+    }
     object.put("status", status.value());
     if (downloadedAt != null) {
       object.put("downloadedAt", downloadedAt);
@@ -85,16 +94,39 @@ class BundleInfo {
   static BundleInfo fromJSONObject(JSONObject object) {
     String id = object.optString("id", "builtin");
     String version = object.optString("version", "0.0.0");
+    String runtimeVersion = object.has("runtimeVersion")
+      ? object.optString("runtimeVersion", null)
+      : null;
     BundleStatus status = BundleStatus.from(object.optString("status", "pending"));
     Long downloadedAt = object.has("downloadedAt") ? object.optLong("downloadedAt") : null;
     String sha256 = object.has("sha256") ? object.optString("sha256", null) : null;
     String channel = object.has("channel") ? object.optString("channel", null) : null;
     String releaseId = object.has("releaseId") ? object.optString("releaseId", null) : null;
     String path = object.has("path") ? object.optString("path", null) : null;
-    return new BundleInfo(id, version, status, downloadedAt, sha256, path, channel, releaseId);
+    return new BundleInfo(
+      id,
+      version,
+      runtimeVersion,
+      status,
+      downloadedAt,
+      sha256,
+      path,
+      channel,
+      releaseId
+    );
   }
 
   BundleInfo withStatus(BundleStatus nextStatus) {
-    return new BundleInfo(id, version, nextStatus, downloadedAt, sha256, path, channel, releaseId);
+    return new BundleInfo(
+      id,
+      version,
+      runtimeVersion,
+      nextStatus,
+      downloadedAt,
+      sha256,
+      path,
+      channel,
+      releaseId
+    );
   }
 }

package/android/src/main/java/com/updatekit/updater/BundleStore.java

@@ -27,12 +27,14 @@ final class BundleStore {
   private final File bundlesDirectory;
   private final String builtinVersion;
   private final String nativeBuild;
+  private final String appRuntimeVersion;
 
-  BundleStore(Context context, String builtinVersion, String nativeBuild) {
+  BundleStore(Context context, String builtinVersion, String nativeBuild, String appRuntimeVersion) {
     this.context = context.getApplicationContext();
     this.prefs = this.context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
     this.builtinVersion = builtinVersion;
     this.nativeBuild = nativeBuild;
+    this.appRuntimeVersion = appRuntimeVersion;
     this.bundlesDirectory = new File(this.context.getFilesDir(), "otakit_bundles");
     if (!bundlesDirectory.exists()) {
       //noinspection ResultOfMethodCallIgnored
@@ -48,10 +50,15 @@ final class BundleStore {
     return builtinVersion;
   }
 
+  SharedPreferences getPrefs() {
+    return prefs;
+  }
+
   BundleInfo builtinBundle() {
     return new BundleInfo(
       "builtin",
       builtinVersion,
+      appRuntimeVersion,
       BundleStatus.BUILTIN,
       null,
       null,
@@ -225,7 +232,7 @@ final class BundleStore {
     }
   }
 
-  synchronized JSArray listDownloadedBundles() {
+  synchronized List<BundleInfo> listDownloadedBundleInfos() {
     List<BundleInfo> result = new ArrayList<>();
     File[] entries = bundlesDirectory.listFiles();
     if (entries != null) {
@@ -237,7 +244,11 @@ final class BundleStore {
         }
       }
     }
+    return result;
+  }
 
+  synchronized JSArray listDownloadedBundles() {
+    List<BundleInfo> result = listDownloadedBundleInfos();
     JSArray array = new JSArray();
     for (BundleInfo bundle : result) {
       array.put(bundle.toJSObject());

package/android/src/main/java/com/updatekit/updater/ManifestClient.java

@@ -30,26 +30,23 @@ final class ManifestClient {
     final String url;
     final String sha256;
     final int size;
-    final Integer minNativeBuild;
+    final String runtimeVersion;
     final String releaseId;
-    final ManifestSignature signature;
 
     LatestManifest(
       String version,
       String url,
       String sha256,
       int size,
-      Integer minNativeBuild,
-      String releaseId,
-      ManifestSignature signature
+      String runtimeVersion,
+      String releaseId
     ) {
       this.version = version;
       this.url = url;
       this.sha256 = sha256;
       this.size = size;
-      this.minNativeBuild = minNativeBuild;
+      this.runtimeVersion = runtimeVersion;
       this.releaseId = releaseId;
-      this.signature = signature;
     }
   }
 
@@ -71,7 +68,7 @@ final class ManifestClient {
     String channel,
     String currentVersion,
     String currentReleaseId,
-    String nativeBuild,
+    String runtimeVersion,
     String platform,
     boolean allowInsecureUrls,
     java.util.List<ManifestVerifier.KeyEntry> manifestKeys
@@ -93,7 +90,9 @@ final class ManifestClient {
       if (currentReleaseId != null && !currentReleaseId.trim().isEmpty()) {
         connection.setRequestProperty("X-Release-Id", currentReleaseId);
       }
-      connection.setRequestProperty("X-Native-Build", nativeBuild);
+      if (runtimeVersion != null && !runtimeVersion.trim().isEmpty()) {
+        connection.setRequestProperty("X-Runtime-Version", runtimeVersion);
+      }
       connection.setConnectTimeout(15_000);
       connection.setReadTimeout(30_000);
 
@@ -118,31 +117,15 @@ final class ManifestClient {
       String sha256 = json.getString("sha256");
       int size = json.getInt("size");
 
-      Integer minNativeBuild = null;
-      if (json.has("minNativeBuild") && !json.isNull("minNativeBuild")) {
-        Object raw = json.get("minNativeBuild");
-        if (raw instanceof Number) {
-          minNativeBuild = ((Number) raw).intValue();
-        } else if (raw instanceof String) {
-          String value = ((String) raw).trim();
-          if (!value.isEmpty()) {
-            minNativeBuild = Integer.parseInt(value);
-          }
-        }
+      String responseRuntimeVersion = json.has("runtimeVersion") && !json.isNull("runtimeVersion")
+        ? json.getString("runtimeVersion").trim()
+        : null;
+      if (responseRuntimeVersion != null && responseRuntimeVersion.isEmpty()) {
+        responseRuntimeVersion = null;
       }
 
-      ManifestSignature signature = null;
-      if (json.has("signature") && !json.isNull("signature")) {
-        JSONObject sigObj = json.getJSONObject("signature");
-        if (sigObj.has("kid") && sigObj.has("sig") && sigObj.has("iat") && sigObj.has("exp")) {
-          signature = new ManifestSignature(
-            sigObj.getString("kid"),
-            sigObj.getString("sig"),
-            sigObj.getInt("iat"),
-            sigObj.getInt("exp")
-          );
-        }
-      }
+      ManifestSignature signature = parseSignature(json.optJSONObject("signature"));
+      ManifestSignature signatureV2 = parseSignature(json.optJSONObject("signatureV2"));
 
       String releaseId = null;
       if (json.has("releaseId") && !json.isNull("releaseId")) {
@@ -161,22 +144,34 @@ final class ManifestClient {
 
       // Verify manifest signature if signing keys are configured
       if (manifestKeys != null && !manifestKeys.isEmpty()) {
-        if (signature == null) {
+        if (signatureV2 != null) {
+          ManifestVerifier.verify(
+            appId,
+            channel,
+            platform,
+            version,
+            sha256,
+            size,
+            responseRuntimeVersion,
+            signatureV2,
+            manifestKeys
+          );
+        } else if (signature != null) {
+          ManifestVerifier.verifyLegacy(
+            appId,
+            channel,
+            platform,
+            version,
+            sha256,
+            size,
+            signature,
+            manifestKeys
+          );
+        } else {
           throw new IllegalStateException(
             "Manifest signature missing but signing keys are configured"
           );
         }
-        ManifestVerifier.verify(
-          appId,
-          channel,
-          platform,
-          version,
-          sha256,
-          size,
-          minNativeBuild,
-          signature,
-          manifestKeys
-        );
       }
 
       return new LatestManifest(
@@ -184,9 +179,8 @@ final class ManifestClient {
         downloadUrl,
         sha256,
         size,
-        minNativeBuild,
-        releaseId,
-        signature
+        responseRuntimeVersion,
+        releaseId
       );
     } finally {
       connection.disconnect();
@@ -206,4 +200,19 @@ final class ManifestClient {
       return new String(out.toByteArray(), StandardCharsets.UTF_8);
     }
   }
+
+  private static ManifestSignature parseSignature(JSONObject sigObj) {
+    if (sigObj == null) {
+      return null;
+    }
+    if (!sigObj.has("kid") || !sigObj.has("sig") || !sigObj.has("iat") || !sigObj.has("exp")) {
+      return null;
+    }
+    return new ManifestSignature(
+      sigObj.getString("kid"),
+      sigObj.getString("sig"),
+      sigObj.getInt("iat"),
+      sigObj.getInt("exp")
+    );
+  }
 }

package/android/src/main/java/com/updatekit/updater/ManifestVerifier.java

@@ -34,7 +34,51 @@ final class ManifestVerifier {
     String version,
     String sha256,
     int size,
-    Integer minNativeBuild,
+    String runtimeVersion,
+    ManifestClient.ManifestSignature signature,
+    List<KeyEntry> trustedKeys
+  ) throws Exception {
+    String payload = buildCanonicalPayload(
+      appId,
+      channel,
+      platform,
+      version,
+      sha256,
+      size,
+      runtimeVersion,
+      signature.kid,
+      signature.iat,
+      signature.exp
+    );
+    verifyPayload(payload, signature, trustedKeys);
+  }
+
+  static void verifyLegacy(
+    String appId,
+    String channel,
+    String platform,
+    String version,
+    String sha256,
+    int size,
+    ManifestClient.ManifestSignature signature,
+    List<KeyEntry> trustedKeys
+  ) throws Exception {
+    String payload = buildLegacyCanonicalPayload(
+      appId,
+      channel,
+      platform,
+      version,
+      sha256,
+      size,
+      signature.kid,
+      signature.iat,
+      signature.exp
+    );
+    verifyPayload(payload, signature, trustedKeys);
+  }
+
+  private static void verifyPayload(
+    String payload,
     ManifestClient.ManifestSignature signature,
     List<KeyEntry> trustedKeys
   ) throws Exception {
@@ -56,20 +100,6 @@ final class ManifestVerifier {
       throw new IllegalStateException("Unknown signing key ID: " + signature.kid);
     }
 
-    // Build canonical payload (must match server exactly)
-    String payload = buildCanonicalPayload(
-      appId,
-      channel,
-      platform,
-      version,
-      sha256,
-      size,
-      minNativeBuild,
-      signature.kid,
-      signature.iat,
-      signature.exp
-    );
-
     // Decode base64url signature
     byte[] sigBytes = base64UrlDecode(signature.sig);
 
@@ -94,12 +124,56 @@ final class ManifestVerifier {
     String version,
     String sha256,
     int size,
-    Integer minNativeBuild,
+    String runtimeVersion,
+    String kid,
+    int iat,
+    int exp
+  ) {
+    return (
+      "MANIFEST_V2\n" +
+      "appId:" +
+      appId +
+      "\n" +
+      "channel:" +
+      (channel != null ? channel : "null") +
+      "\n" +
+      "platform:" +
+      platform +
+      "\n" +
+      "version:" +
+      version +
+      "\n" +
+      "sha256:" +
+      sha256 +
+      "\n" +
+      "size:" +
+      size +
+      "\n" +
+      "runtimeVersion:" +
+      (runtimeVersion != null ? runtimeVersion : "null") +
+      "\n" +
+      "kid:" +
+      kid +
+      "\n" +
+      "iat:" +
+      iat +
+      "\n" +
+      "exp:" +
+      exp
+    );
+  }
+
+  private static String buildLegacyCanonicalPayload(
+    String appId,
+    String channel,
+    String platform,
+    String version,
+    String sha256,
+    int size,
     String kid,
     int iat,
     int exp
   ) {
-    String minBuildStr = minNativeBuild != null ? String.valueOf(minNativeBuild) : "null";
     return (
       "MANIFEST_V1\n" +
       "appId:" +
@@ -120,8 +194,7 @@ final class ManifestVerifier {
       "size:" +
       size +
       "\n" +
-      "minNativeBuild:" +
-      minBuildStr +
+      "minNativeBuild:null" +
       "\n" +
       "kid:" +
       kid +