@otakit/capacitor-updater 1.1.0 → 2.0.0

package/README.md

@@ -4,15 +4,21 @@ Capacitor OTA updater plugin for OtaKit.
 
 ## What it does
 
-- checks the manifest endpoint for a newer bundle
+- fetches the latest manifest for its release lane from the CDN
 - downloads and verifies OTA bundles
 - stages updates safely
 - 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
 
+OtaKit publishes signed static manifests into object storage behind a CDN. The
+plugin fetches the manifest for its `appId + channel + runtimeVersion` lane,
+verifies it, compares it against the current and staged bundle locally, and
+only downloads when the manifest actually points at something newer.
+
 For normal app code, the main public methods are:
 
 ```ts
@@ -46,6 +52,7 @@ plugins: {
     appReadyTimeout: 10000,
     // Optional:
     // channel: "staging",
+    // runtimeVersion: "2026.04",
     // updateMode: "next-resume",
     // updateMode: "manual",
     // updateMode: "immediate",
@@ -55,22 +62,40 @@ plugins: {
 
 Advanced overrides for self-hosting or custom trust only:
 
-- `serverUrl`
+- `cdnUrl` for manifest and bundle delivery
+- `serverUrl` for stats and control-plane requests
 - `manifestKeys`
 - `allowInsecureUrls`
 
-Hosted OtaKit already points at `https://otakit.app/api/v1` and already trusts
-the managed manifest signing keys.
+Hosted OtaKit already points at the managed control-plane API and CDN 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.
 
-1. it fetches a manifest from the server
+1. it fetches the latest manifest from the CDN for its app + channel + runtimeVersion lane
 2. it verifies the manifest signature when manifest keys are configured
-3. it downloads the bundle zip
-4. it verifies the zip against the manifest `sha256`
-5. it stages and activates the bundle
+3. it compares that manifest against the current and staged bundle already on the device
+4. if the manifest is newer, it downloads the bundle zip
+5. it verifies the zip against the manifest `sha256`
+6. it stages and activates the bundle
 
 In the hosted path, managed signing keys are already built in.
 
@@ -147,8 +172,9 @@ await OtaKit.notifyAppReady();
 ```
 
 The plugin handles checking, downloading, activation, and rollback based on
-`updateMode`. It checks on cold start and every time the app comes back from
-the background (throttled by `checkInterval`).
+`updateMode`. In `next-launch` and `next-resume`, it checks on cold start and
+every time the app comes back from the background, throttled by `checkInterval`.
+`immediate` bypasses that throttle.
 
 For most apps, this is the entire runtime integration.
 
@@ -177,10 +203,9 @@ 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.
+`checkInterval` (default 10 min) only applies to automatic checks in
+`next-launch` and `next-resume`. Manual `check()` / `download()` calls are
+always live, and `immediate` mode ignores the interval entirely.
 
 ## Retention and deletion
 

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
@@ -56,6 +58,7 @@ final class BundleStore {
     return new BundleInfo(
       "builtin",
       builtinVersion,
+      appRuntimeVersion,
       BundleStatus.BUILTIN,
       null,
       null,
@@ -229,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) {
@@ -241,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/HostedManifestKeys.java

@@ -7,18 +7,17 @@ import java.util.Locale;
 
 final class HostedManifestKeys {
 
-  private static final String MANAGED_SERVER_URL = "https://www.otakit.app/api/v1";
+  private static final String MANAGED_CDN_URL = "https://cdn.otakit.app";
 
   private HostedManifestKeys() {}
 
-  static boolean matchesManagedServer(String updateUrl) {
-    if (updateUrl == null) {
+  static boolean matchesManagedManifestUrl(String cdnUrl) {
+    if (cdnUrl == null) {
       return false;
     }
 
-    String normalized = updateUrl.trim().replaceAll("/+$", "").toLowerCase(Locale.ROOT);
-    return normalized.equals(MANAGED_SERVER_URL)
-        || normalized.equals("https://otakit.app/api/v1");
+    String normalized = cdnUrl.trim().replaceAll("/+$", "").toLowerCase(Locale.ROOT);
+    return normalized.equals(MANAGED_CDN_URL) || normalized.equals("https://www.otakit.app");
   }
 
   static List<ManifestVerifier.KeyEntry> createDefaultKeys() {

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

@@ -9,6 +9,9 @@ import org.json.JSONObject;
 
 final class ManifestClient {
 
+  private static final String BASE_CHANNEL_KEY = "__base__";
+  private static final String DEFAULT_RUNTIME_KEY = "__default__";
+
   static final class ManifestSignature {
 
     final String kid;
@@ -30,26 +33,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;
     }
   }
 
@@ -66,39 +66,33 @@ final class ManifestClient {
   }
 
   static LatestManifest fetchLatest(
-    String updateUrl,
+    String cdnUrl,
     String appId,
     String channel,
-    String currentVersion,
-    String currentReleaseId,
-    String nativeBuild,
-    String platform,
+    String runtimeVersion,
     boolean allowInsecureUrls,
     java.util.List<ManifestVerifier.KeyEntry> manifestKeys
   ) throws Exception {
-    String base = updateUrl.replaceAll("/+$", "");
-    URL url = new URL(base + "/manifest");
+    String base = cdnUrl.replaceAll("/+$", "");
+    String channelKey = channel != null && !channel.trim().isEmpty() ? channel.trim() : BASE_CHANNEL_KEY;
+    String runtimeKey =
+      runtimeVersion != null && !runtimeVersion.trim().isEmpty()
+        ? runtimeVersion.trim()
+        : DEFAULT_RUNTIME_KEY;
+    URL url = new URL(
+      base + "/manifests/" + appId + "/" + channelKey + "/" + runtimeKey + "/manifest.json"
+    );
 
     requireHTTPS(url, allowInsecureUrls);
 
     HttpURLConnection connection = (HttpURLConnection) url.openConnection();
     try {
       connection.setRequestMethod("GET");
-      connection.setRequestProperty("X-App-Id", appId);
-      connection.setRequestProperty("X-Platform", platform);
-      if (channel != null && !channel.trim().isEmpty()) {
-        connection.setRequestProperty("X-Channel", channel);
-      }
-      connection.setRequestProperty("X-Current-Version", currentVersion);
-      if (currentReleaseId != null && !currentReleaseId.trim().isEmpty()) {
-        connection.setRequestProperty("X-Release-Id", currentReleaseId);
-      }
-      connection.setRequestProperty("X-Native-Build", nativeBuild);
       connection.setConnectTimeout(15_000);
       connection.setReadTimeout(30_000);
 
       int status = connection.getResponseCode();
-      if (status == 204) {
+      if (status == 404 || status == 204) {
         return null;
       }
       if (status != 200) {
@@ -118,38 +112,20 @@ 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"));
 
       String releaseId = null;
       if (json.has("releaseId") && !json.isNull("releaseId")) {
         releaseId = json.getString("releaseId");
       }
 
-      // Validate download URL scheme
       requireHTTPS(new URL(downloadUrl), allowInsecureUrls);
 
       if (manifestKeys == null || manifestKeys.isEmpty()) {
@@ -159,21 +135,20 @@ final class ManifestClient {
         );
       }
 
-      // Verify manifest signature if signing keys are configured
       if (manifestKeys != null && !manifestKeys.isEmpty()) {
         if (signature == null) {
           throw new IllegalStateException(
             "Manifest signature missing but signing keys are configured"
           );
         }
+
         ManifestVerifier.verify(
           appId,
           channel,
-          platform,
           version,
           sha256,
           size,
-          minNativeBuild,
+          responseRuntimeVersion,
           signature,
           manifestKeys
         );
@@ -184,9 +159,8 @@ final class ManifestClient {
         downloadUrl,
         sha256,
         size,
-        minNativeBuild,
-        releaseId,
-        signature
+        responseRuntimeVersion,
+        releaseId
       );
     } finally {
       connection.disconnect();
@@ -206,4 +180,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

@@ -30,11 +30,29 @@ final class ManifestVerifier {
   static void verify(
     String appId,
     String channel,
-    String platform,
     String version,
     String sha256,
     int size,
-    Integer minNativeBuild,
+    String runtimeVersion,
+    ManifestClient.ManifestSignature signature,
+    List<KeyEntry> trustedKeys
+  ) throws Exception {
+    String payload = buildCanonicalPayload(
+      appId,
+      channel,
+      version,
+      sha256,
+      size,
+      runtimeVersion,
+      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 +74,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);
 
@@ -90,27 +94,22 @@ final class ManifestVerifier {
   private static String buildCanonicalPayload(
     String appId,
     String channel,
-    String platform,
     String version,
     String sha256,
     int size,
-    Integer minNativeBuild,
+    String runtimeVersion,
     String kid,
     int iat,
     int exp
   ) {
-    String minBuildStr = minNativeBuild != null ? String.valueOf(minNativeBuild) : "null";
     return (
-      "MANIFEST_V1\n" +
+      "MANIFEST\n" +
       "appId:" +
       appId +
       "\n" +
       "channel:" +
       (channel != null ? channel : "null") +
       "\n" +
-      "platform:" +
-      platform +
-      "\n" +
       "version:" +
       version +
       "\n" +
@@ -120,8 +119,8 @@ final class ManifestVerifier {
       "size:" +
       size +
       "\n" +
-      "minNativeBuild:" +
-      minBuildStr +
+      "runtimeVersion:" +
+      (runtimeVersion != null ? runtimeVersion : "null") +
       "\n" +
       "kid:" +
       kid +