@otakit/capacitor-updater 2.1.0 → 2.1.2

package/Package.swift

@@ -0,0 +1,27 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "OtakitCapacitorUpdater",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "OtakitCapacitorUpdater",
+            targets: ["UpdaterPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", "7.0.0"..<"9.0.0"),
+        .package(url: "https://github.com/weichsel/ZIPFoundation.git", .upToNextMajor(from: "0.9.0"))
+    ],
+    targets: [
+        .target(
+            name: "UpdaterPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm"),
+                .product(name: "ZIPFoundation", package: "ZIPFoundation")
+            ],
+            path: "ios/Sources/UpdaterPlugin",
+            exclude: ["UpdaterPlugin.m"])
+    ]
+)

package/README.md

@@ -7,38 +7,17 @@ Capacitor OTA updater plugin for OtaKit.
 - 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
+- applies staged bundles on cold start, resume, or manual command
+- uses `notifyAppReady()` as the health handshake
+- rolls back automatically if a newly applied 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.
+The plugin is intentionally small:
 
-For normal app code, the main public methods are:
+- three automatic lifecycle entry points: runtime, launch, resume
+- one shared set of update primitives: check, download, apply
+- one rollback safety loop
 
-```ts
-const state = await OtaKit.getState();
-const latest = await OtaKit.check();
-
-// Low-level manual flow:
-const bundle = await OtaKit.download();
-if (bundle) {
-  await OtaKit.apply();
-}
-
-// Or the one-shot manual helper:
-await OtaKit.update();
-await OtaKit.notifyAppReady();
-```
-
-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.
+There is no built-in splash or overlay manager in this model.
 
 ## Hosted config
 
@@ -47,187 +26,244 @@ plugins: {
   OtaKit: {
     appId: "YOUR_OTAKIT_APP_ID",
     appReadyTimeout: 10000,
+
     // Optional:
     // channel: "staging",
     // runtimeVersion: "2026.04",
-    // updateMode: "next-resume",
-    // updateMode: "manual",
-    // updateMode: "immediate",
+    // launchPolicy: "apply-staged",
+    // resumePolicy: "shadow",
+    // runtimePolicy: "immediate",
+    // checkInterval: 600000,
   }
 }
 ```
 
 Advanced overrides for self-hosting or custom trust only:
 
-- `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.
+- `cdnUrl`
+- `ingestUrl`
+- `serverUrl`
 - `manifestKeys`
 - `allowInsecureUrls`
 
 Hosted OtaKit already points at the managed ingest service and CDN and already
 trusts the managed manifest signing keys.
 
-## Channels vs runtimeVersion
+## Policies
 
-- `channel` answers "who should get this rollout?"
-- `runtimeVersion` answers "which native app shell can safely run this bundle?"
+The plugin has three automatic events:
 
-Use channels for rollout tracks such as `beta`, `staging`, or `production`.
+- `runtime`
+  Cold start where the current `runtimeVersion` lane has not been resolved yet.
+- `launch`
+  Normal cold start after runtime is already resolved.
+- `resume`
+  App returning from background.
 
-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.
+Each event uses the same policy names:
 
-When `runtimeVersion` is set:
+```ts
+type OtaKitPolicy = 'off' | 'shadow' | 'apply-staged' | 'immediate';
+```
 
-- 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
+Semantics:
 
-## Trust model
+- `shadow`
+  check + download, never apply on that event
+- `apply-staged`
+  apply a staged bundle if one already exists, otherwise behave like `shadow`
+- `immediate`
+  check + download + apply
 
-The plugin does not just download from a URL and trust the result.
+Recommended defaults:
 
-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 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
+```ts
+launchPolicy = 'apply-staged';
+resumePolicy = 'shadow';
+runtimePolicy = 'immediate';
+```
 
-In the hosted path, managed signing keys are already built in.
+That means:
 
-## Update modes
+- fresh install or new `runtimeVersion`: catch up immediately
+- later cold starts: apply already staged content if present, otherwise download
+  the next update in the background
+- resumes: periodically check and stage in the background
 
-All automatic modes check for updates on **cold start** (always) and **app
-resume**.
+If an app wants full JS control:
 
-### Production modes
+```ts
+launchPolicy = 'off';
+resumePolicy = 'off';
+runtimePolicy = 'off';
+```
 
-- `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.
+## Check interval
 
-- `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.
+`checkInterval` defaults to 10 minutes and only applies to background resume
+checks:
 
-### Manual mode
+- `resumePolicy: "shadow"`
+- `resumePolicy: "apply-staged"` when there is no staged bundle to apply
 
-- `manual`
-  no automatic checks, no automatic staged activation.
-  the app integration drives everything via `check()`, `download()`, `apply()`, or `update()`.
+Set `checkInterval` to `0` or a negative value to disable resume throttling.
 
-### Development mode
+It does not throttle:
 
+- launch handling
+- runtime handling
 - `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).
-  primarily for development and testing — not recommended for production.
-
+- manual JS APIs
 
 ## Runtime model
 
-The plugin keeps three important runtime pointers:
+The plugin keeps three important pointers:
 
 - `current`
-  the bundle the WebView is currently serving
+  the bundle the WebView is serving now
 - `fallback`
   the last known-good bundle used for rollback
 - `staged`
   a downloaded bundle waiting to be activated
 
-Bundle lifecycle is intentionally small:
+Bundle lifecycle:
 
 ```text
 download -> pending -> trial -> success
                         |
-                        +-> error -> rollback -> delete failed files
+                        +-> error -> rollback
 ```
 
-In practice:
+If a bundle is applied and never calls `notifyAppReady()`:
 
-- downloads start as `pending`
-- an activated bundle becomes `trial`
-- `notifyAppReady()` promotes `trial` to `success`
-- timeout or restart during `trial` causes rollback
+- timeout triggers rollback while the app is running
+- or the next cold start detects the still-trial bundle and rolls back before
+  boot continues
 
-That gives the plugin a small but important safety model:
+The last failed applied bundle is persisted so the plugin does not immediately
+download and apply the same broken release again.
 
-- `current` is what is serving now
-- `fallback` is the last known-good bundle
-- `staged` is what can be activated next
-- rollback always goes back to `fallback`, not to an arbitrary older bundle
+## Automatic flow
 
-## Automatic and manual flows
+For the normal hosted path, most apps only need:
+
+```ts
+await OtaKit.notifyAppReady();
+```
 
-### Automatic flow
+The plugin handles checking, staging, applying, rollback, and runtime-lane
+catch-up based on the configured policies.
 
-For the normal hosted path, the app usually just needs to call:
+## Loading screen recommendation
+
+OtaKit does not manage a splash screen or loading overlay for you.
+
+Recommended startup order:
+
+1. keep a native splash screen or fullscreen loading view visible
+2. finish your normal app bootstrap
+3. call `notifyAppReady()`
+4. hide the splash screen or loading view
+
+For React and Next.js apps, treat this as part of the default setup, not an
+optional polish step.
+
+## Manual APIs
+
+The manual surface maps to the same internal engine:
 
 ```ts
+const state = await OtaKit.getState();
+const check = await OtaKit.check();
+const download = await OtaKit.download();
 await OtaKit.notifyAppReady();
 ```
 
-The plugin handles checking, downloading, activation, and rollback based on
-`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.
+`check()` returns:
 
-For most apps, this is the entire runtime integration.
+```ts
+type CheckResult =
+  | { kind: 'no_update' }
+  | { kind: 'already_staged'; latest: LatestVersion }
+  | { kind: 'update_available'; latest: LatestVersion };
+```
 
-### Manual flow
+`download()` returns:
 
-For app-driven prompts:
+```ts
+type DownloadResult = { kind: 'no_update' } | { kind: 'staged'; bundle: BundleInfo };
+```
+
+`update()` uses the same native immediate-flow operation as automatic
+`"immediate"` policies:
 
 ```ts
-const state = await OtaKit.getState();
-const latest = await OtaKit.check();
+await OtaKit.update();
+```
+
+That keeps the manual convenience path atomic inside the native plugin instead
+of splitting it into separate `download()` and `apply()` calls.
+
+`apply()` and successful `update()` are terminal operations:
 
-if (latest) {
-  await OtaKit.update();
+- on success they reload the WebView
+- they do not resolve back into the old JS context
+- call `notifyAppReady()` from normal startup after the reloaded app boots
+
+There is no listener/event API in this refactor. If an app later needs a
+smaller reactive surface, that can be added intentionally.
+
+## Example manual flow
+
+```ts
+const check = await OtaKit.check();
+
+if (check.kind === 'update_available') {
+  const result = await OtaKit.download();
+  if (result.kind === 'staged') {
+    await OtaKit.apply();
+  }
 }
 ```
 
-Or the split version:
+Or use the one-shot helper:
+
+```ts
+await OtaKit.update();
+```
+
+After the app reloads and starts again, call:
 
 ```ts
-await OtaKit.download();
-await OtaKit.apply();
+await OtaKit.notifyAppReady();
 ```
 
-Use the split flow when the app wants to download in the background and switch
-only after explicit user confirmation.
+## Compatibility lanes
 
-## Throttle
+- `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`.
 
-`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.
+Use `runtimeVersion` when a new store build creates a new compatibility
+boundary and you do not want devices on that native shell to keep receiving
+older OTA bundles.
 
-## Retention and deletion
+## Trust model
 
-- the builtin, current, fallback, and staged bundles are protected
-- superseded staged bundles are deleted automatically
-- failed trial bundles are deleted during rollback
+The plugin does not just download arbitrary zips from a URL.
+
+1. it fetches the latest manifest for the current app + channel + runtime lane
+2. it verifies the manifest signature when keys are configured
+3. it compares the manifest with current, staged, and last-failed local state
+4. it downloads only when a newer usable bundle exists
+5. it verifies the zip against the manifest `sha256`
+6. it stages and later applies the bundle
 
 ## Source areas
 
-- `src/definitions.ts`: public types and methods
+- `src/definitions.ts`: public types and config
 - `src/index.ts`: Capacitor registration and JS wrapper
 - `src/web.ts`: web fallback implementation
 - `ios/Sources/UpdaterPlugin/*`: iOS implementation
 - `android/src/main/java/com/otakit/updater/*`: Android implementation
-
-## Build locally
-
-```bash
-pnpm --filter @otakit/capacitor-updater build
-pnpm --filter @otakit/capacitor-updater typecheck
-```
-
-Repo-level verification:
-
-```bash
-npm run build
-```

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

@@ -20,7 +20,8 @@ final class BundleStore {
   private static final String KEY_CURRENT = "current_bundle_id";
   private static final String KEY_FALLBACK = "fallback_bundle_id";
   private static final String KEY_STAGED = "staged_bundle_id";
-  private static final String KEY_FAILED_INFO = "failed_bundle_info";
+  private static final String KEY_LAST_FAILED_BUNDLE_INFO = "last_failed_bundle_info";
+  private static final String KEY_LAST_RESOLVED_RUNTIME_KEY = "last_resolved_runtime_key";
 
   private final Context context;
   private final SharedPreferences prefs;
@@ -29,7 +30,12 @@ final class BundleStore {
   private final String nativeBuild;
   private final String appRuntimeVersion;
 
-  BundleStore(Context context, String builtinVersion, String nativeBuild, String appRuntimeVersion) {
+  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;
@@ -134,6 +140,10 @@ final class BundleStore {
     return current != null ? current : builtinBundle();
   }
 
+  synchronized String getCurrentBundleId() {
+    return prefs.getString(KEY_CURRENT, null);
+  }
+
   synchronized void setCurrentBundleId(String id) {
     SharedPreferences.Editor editor = prefs.edit();
     if (id == null) {
@@ -153,6 +163,10 @@ final class BundleStore {
     return fallback != null ? fallback : builtinBundle();
   }
 
+  synchronized String getFallbackBundleId() {
+    return prefs.getString(KEY_FALLBACK, null);
+  }
+
   synchronized void setFallbackBundleId(String id) {
     SharedPreferences.Editor editor = prefs.edit();
     if (id == null) {
@@ -177,22 +191,22 @@ final class BundleStore {
     editor.commit();
   }
 
-  synchronized void setFailedBundle(BundleInfo bundle) {
+  synchronized void setLastFailedBundle(BundleInfo bundle) {
     SharedPreferences.Editor editor = prefs.edit();
     if (bundle == null) {
-      editor.remove(KEY_FAILED_INFO);
+      editor.remove(KEY_LAST_FAILED_BUNDLE_INFO);
     } else {
       try {
-        editor.putString(KEY_FAILED_INFO, bundle.toJSONObject().toString());
+        editor.putString(KEY_LAST_FAILED_BUNDLE_INFO, bundle.toJSONObject().toString());
       } catch (JSONException ignored) {
-        editor.remove(KEY_FAILED_INFO);
+        editor.remove(KEY_LAST_FAILED_BUNDLE_INFO);
       }
     }
     editor.apply();
   }
 
-  synchronized BundleInfo getFailedBundle() {
-    String json = prefs.getString(KEY_FAILED_INFO, null);
+  synchronized BundleInfo getLastFailedBundle() {
+    String json = prefs.getString(KEY_LAST_FAILED_BUNDLE_INFO, null);
     if (json == null) {
       return null;
     }
@@ -203,6 +217,21 @@ final class BundleStore {
     }
   }
 
+  synchronized String getLastResolvedRuntimeKey() {
+    return prefs.getString(KEY_LAST_RESOLVED_RUNTIME_KEY, null);
+  }
+
+  synchronized void setLastResolvedRuntimeKey(String runtimeKey) {
+    SharedPreferences.Editor editor = prefs.edit();
+    if (runtimeKey == null) {
+      // null clears the key so the next cold start is treated as unresolved again
+      editor.remove(KEY_LAST_RESOLVED_RUNTIME_KEY);
+    } else {
+      editor.putString(KEY_LAST_RESOLVED_RUNTIME_KEY, runtimeKey);
+    }
+    editor.commit();
+  }
+
   synchronized void markStatus(String bundleId, BundleStatus status) {
     BundleInfo existing = getBundle(bundleId);
     if (existing == null) {

package/android/src/main/java/com/otakit/updater/DeviceEventClient.java

@@ -8,9 +8,9 @@ import java.text.SimpleDateFormat;
 import java.util.Date;
 import java.util.Locale;
 import java.util.TimeZone;
+import java.util.UUID;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
-import java.util.UUID;
 import org.json.JSONObject;
 
 final class DeviceEventClient {
@@ -52,8 +52,7 @@ final class DeviceEventClient {
         payload.put("releaseId", releaseId);
         payload.put("nativeBuild", nativeBuild);
         if (detail != null) {
-          String truncated =
-            detail.length() > 500 ? detail.substring(0, 500) : detail;
+          String truncated = detail.length() > 500 ? detail.substring(0, 500) : detail;
           payload.put("detail", truncated);
         }
 

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

@@ -1,5 +1,6 @@
 package com.otakit.updater;
 
+import android.net.Uri;
 import java.io.ByteArrayOutputStream;
 import java.io.InputStream;
 import java.net.HttpURLConnection;
@@ -74,14 +75,25 @@ final class ManifestClient {
     java.util.List<ManifestVerifier.KeyEntry> manifestKeys
   ) throws Exception {
     String base = cdnUrl.replaceAll("/+$", "");
-    String channelKey = channel != null && !channel.trim().isEmpty() ? channel.trim() : BASE_CHANNEL_KEY;
+    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"
-    );
+    Uri baseUri = Uri.parse(base);
+    if (baseUri.getScheme() == null || baseUri.getHost() == null) {
+      throw new IllegalStateException("Invalid CDN URL");
+    }
+    Uri urlUri = baseUri
+      .buildUpon()
+      .appendPath("manifests")
+      .appendPath(appId)
+      .appendPath(channelKey)
+      .appendPath(runtimeKey)
+      .appendPath("manifest.json")
+      .build();
+    URL url = new URL(urlUri.toString());
 
     requireHTTPS(url, allowInsecureUrls);
 
@@ -112,9 +124,10 @@ final class ManifestClient {
       String sha256 = json.getString("sha256");
       int size = json.getInt("size");
 
-      String responseRuntimeVersion = json.has("runtimeVersion") && !json.isNull("runtimeVersion")
-        ? json.getString("runtimeVersion").trim()
-        : null;
+      String responseRuntimeVersion =
+        json.has("runtimeVersion") && !json.isNull("runtimeVersion")
+          ? json.getString("runtimeVersion").trim()
+          : null;
       if (responseRuntimeVersion != null && responseRuntimeVersion.isEmpty()) {
         responseRuntimeVersion = null;
       }