@otakit/capacitor-updater 1.2.0 → 2.0.1

package/README.md

@@ -4,7 +4,7 @@ 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
@@ -14,6 +14,11 @@ Capacitor OTA updater plugin for OtaKit.
 - 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
@@ -35,9 +40,6 @@ For manual mode, `getState()` tells you if something is already staged,
 `check()` tells you whether a newer update exists, `download()` stages it, and
 `update()` is the one-shot helper that downloads and applies the newest update.
 
-Manual inspection and support methods like state inspection and reset live under
-`OtaKit.debug`.
-
 ## Hosted config
 
 ```ts
@@ -57,12 +59,14 @@ plugins: {
 
 Advanced overrides for self-hosting or custom trust only:
 
-- `serverUrl`
+- `cdnUrl` for manifest and bundle delivery
+- `ingestUrl` for event ingest requests
+- `serverUrl` for self-hosted control-plane tooling such as the CLI. The native runtime uses `cdnUrl` and `ingestUrl` instead.
 - `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 ingest service and CDN and already
+trusts the managed manifest signing keys.
 
 ## Channels vs runtimeVersion
 
@@ -84,11 +88,12 @@ When `runtimeVersion` is set:
 
 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.
 
@@ -114,7 +119,7 @@ resume**.
   no automatic checks, no automatic staged activation.
   the app integration drives everything via `check()`, `download()`, `apply()`, or `update()`.
 
-### Dev/debug mode
+### Development mode
 
 - `immediate`
   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).
@@ -165,8 +170,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.
 
@@ -195,10 +201,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/{StatsClient.java → DeviceEventClient.java}

@@ -4,52 +4,57 @@ import java.io.OutputStream;
 import java.net.HttpURLConnection;
 import java.net.URL;
 import java.nio.charset.StandardCharsets;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.Locale;
+import java.util.TimeZone;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
+import java.util.UUID;
 import org.json.JSONObject;
 
-final class StatsClient {
+final class DeviceEventClient {
 
   private static final ExecutorService executor = Executors.newSingleThreadExecutor();
 
-  private StatsClient() {}
+  private DeviceEventClient() {}
 
   static void send(
-    String updateUrl,
+    String ingestUrl,
     String appId,
     String platform,
     String action,
     String bundleVersion,
     String channel,
+    String runtimeVersion,
     String releaseId,
     String nativeBuild,
-    String errorMessage
+    String detail
   ) {
     executor.execute(() -> {
       HttpURLConnection connection = null;
       try {
-        String base = updateUrl.replaceAll("/+$", "");
-        URL url = new URL(base + "/stats");
+        String base = ingestUrl.replaceAll("/+$", "");
+        URL url = new URL(base + "/events");
 
         JSONObject payload = new JSONObject();
+        payload.put("eventId", UUID.randomUUID().toString());
+        payload.put("sentAt", iso8601Now());
         payload.put("platform", platform);
         payload.put("action", action);
-        if (bundleVersion != null) {
-          payload.put("bundleVersion", bundleVersion);
-        }
+        payload.put("bundleVersion", bundleVersion);
         if (channel != null && !channel.isEmpty()) {
           payload.put("channel", channel);
         }
-        if (releaseId != null && !releaseId.isEmpty()) {
-          payload.put("releaseId", releaseId);
-        }
-        if (nativeBuild != null) {
-          payload.put("nativeBuild", nativeBuild);
+        if (runtimeVersion != null && !runtimeVersion.isEmpty()) {
+          payload.put("runtimeVersion", runtimeVersion);
         }
-        if (errorMessage != null) {
+        payload.put("releaseId", releaseId);
+        payload.put("nativeBuild", nativeBuild);
+        if (detail != null) {
           String truncated =
-            errorMessage.length() > 500 ? errorMessage.substring(0, 500) : errorMessage;
-          payload.put("errorMessage", truncated);
+            detail.length() > 500 ? detail.substring(0, 500) : detail;
+          payload.put("detail", truncated);
         }
 
         byte[] body = payload.toString().getBytes(StandardCharsets.UTF_8);
@@ -66,10 +71,10 @@ final class StatsClient {
           output.write(body);
         }
 
-        // Fire and forget - just trigger the request
+        // Device events are best-effort and should never block the update flow.
         connection.getResponseCode();
       } catch (Exception ignored) {
-        // Stats are best-effort, don't fail on errors
+        // Device events are best-effort, don't fail on errors
       } finally {
         if (connection != null) {
           connection.disconnect();
@@ -77,4 +82,10 @@ final class StatsClient {
       }
     });
   }
+
+  private static String iso8601Now() {
+    SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US);
+    formatter.setTimeZone(TimeZone.getTimeZone("UTC"));
+    return formatter.format(new Date());
+  }
 }

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;
@@ -63,41 +66,33 @@ final class ManifestClient {
   }
 
   static LatestManifest fetchLatest(
-    String updateUrl,
+    String cdnUrl,
     String appId,
     String channel,
-    String currentVersion,
-    String currentReleaseId,
     String runtimeVersion,
-    String platform,
     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);
-      }
-      if (runtimeVersion != null && !runtimeVersion.trim().isEmpty()) {
-        connection.setRequestProperty("X-Runtime-Version", runtimeVersion);
-      }
       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) {
@@ -125,14 +120,18 @@ final class ManifestClient {
       }
 
       ManifestSignature signature = parseSignature(json.optJSONObject("signature"));
-      ManifestSignature signatureV2 = parseSignature(json.optJSONObject("signatureV2"));
 
       String releaseId = null;
       if (json.has("releaseId") && !json.isNull("releaseId")) {
-        releaseId = json.getString("releaseId");
+        releaseId = json.getString("releaseId").trim();
+      }
+      if (releaseId != null && releaseId.isEmpty()) {
+        releaseId = null;
+      }
+      if (releaseId == null) {
+        throw new IllegalStateException("Manifest response missing required releaseId");
       }
 
-      // Validate download URL scheme
       requireHTTPS(new URL(downloadUrl), allowInsecureUrls);
 
       if (manifestKeys == null || manifestKeys.isEmpty()) {
@@ -142,36 +141,23 @@ final class ManifestClient {
         );
       }
 
-      // Verify manifest signature if signing keys are configured
       if (manifestKeys != null && !manifestKeys.isEmpty()) {
-        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 {
+        if (signature == null) {
           throw new IllegalStateException(
             "Manifest signature missing but signing keys are configured"
           );
         }
+
+        ManifestVerifier.verify(
+          appId,
+          channel,
+          version,
+          sha256,
+          size,
+          responseRuntimeVersion,
+          signature,
+          manifestKeys
+        );
       }
 
       return new LatestManifest(

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

@@ -30,7 +30,6 @@ final class ManifestVerifier {
   static void verify(
     String appId,
     String channel,
-    String platform,
     String version,
     String sha256,
     int size,
@@ -41,7 +40,6 @@ final class ManifestVerifier {
     String payload = buildCanonicalPayload(
       appId,
       channel,
-      platform,
       version,
       sha256,
       size,
@@ -53,30 +51,6 @@ final class ManifestVerifier {
     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,
@@ -120,7 +94,6 @@ final class ManifestVerifier {
   private static String buildCanonicalPayload(
     String appId,
     String channel,
-    String platform,
     String version,
     String sha256,
     int size,
@@ -130,16 +103,13 @@ final class ManifestVerifier {
     int exp
   ) {
     return (
-      "MANIFEST_V2\n" +
+      "MANIFEST\n" +
       "appId:" +
       appId +
       "\n" +
       "channel:" +
       (channel != null ? channel : "null") +
       "\n" +
-      "platform:" +
-      platform +
-      "\n" +
       "version:" +
       version +
       "\n" +
@@ -163,50 +133,6 @@ final class ManifestVerifier {
     );
   }
 
-  private static String buildLegacyCanonicalPayload(
-    String appId,
-    String channel,
-    String platform,
-    String version,
-    String sha256,
-    int size,
-    String kid,
-    int iat,
-    int exp
-  ) {
-    return (
-      "MANIFEST_V1\n" +
-      "appId:" +
-      appId +
-      "\n" +
-      "channel:" +
-      (channel != null ? channel : "null") +
-      "\n" +
-      "platform:" +
-      platform +
-      "\n" +
-      "version:" +
-      version +
-      "\n" +
-      "sha256:" +
-      sha256 +
-      "\n" +
-      "size:" +
-      size +
-      "\n" +
-      "minNativeBuild:null" +
-      "\n" +
-      "kid:" +
-      kid +
-      "\n" +
-      "iat:" +
-      iat +
-      "\n" +
-      "exp:" +
-      exp
-    );
-  }
-
   private static byte[] base64UrlDecode(String input) {
     // Convert base64url to standard base64
     String base64 = input.replace('-', '+').replace('_', '/');