@otakit/capacitor-updater 1.0.0 → 1.1.0

package/README.md

@@ -7,7 +7,8 @@ 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
 - requires `notifyAppReady()` as the success handshake
 - rolls back automatically if the new bundle does not prove healthy
@@ -45,6 +46,7 @@ plugins: {
     appReadyTimeout: 10000,
     // Optional:
     // channel: "staging",
+    // updateMode: "next-resume",
     // updateMode: "manual",
     // updateMode: "immediate",
   }
@@ -74,14 +76,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 +147,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 +175,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/BundleStore.java

@@ -48,6 +48,10 @@ final class BundleStore {
     return builtinVersion;
   }
 
+  SharedPreferences getPrefs() {
+    return prefs;
+  }
+
   BundleInfo builtinBundle() {
     return new BundleInfo(
       "builtin",

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

@@ -21,6 +21,7 @@ import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicBoolean;
 
 @CapacitorPlugin(name = "OtaKit")
 public class UpdaterPlugin extends Plugin {
@@ -39,11 +40,17 @@ public class UpdaterPlugin extends Plugin {
   private String appId;
   private String channel;
   private java.util.List<ManifestVerifier.KeyEntry> manifestKeys = new java.util.ArrayList<>();
+  private long checkIntervalMs = 600_000;
+  private final AtomicBoolean checkInProgress = new AtomicBoolean(false);
   private static final String DEFAULT_UPDATE_URL = "https://www.otakit.app/api/v1";
   private static final String API_PATH_SUFFIX = "/api/v1";
   private static final String UPDATE_MODE_MANUAL = "manual";
   private static final String UPDATE_MODE_NEXT_LAUNCH = "next-launch";
+  private static final String UPDATE_MODE_NEXT_RESUME = "next-resume";
   private static final String UPDATE_MODE_IMMEDIATE = "immediate";
+  private static final String KEY_LAST_CHECK_TIMESTAMP = "last_check_timestamp";
+  private static final String TRIGGER_LAUNCH = "launch";
+  private static final String TRIGGER_RESUME = "resume";
 
   @Override
   public void load() {
@@ -112,6 +119,7 @@ public class UpdaterPlugin extends Plugin {
     }
 
     this.appReadyTimeoutMs = Math.max(1000, getConfig().getInt("appReadyTimeout", 10_000));
+    this.checkIntervalMs = Math.max(600_000, getConfig().getInt("checkInterval", 600_000));
 
     BundleInfo current = store.getCurrentBundle();
     if (current.status == BundleStatus.TRIAL) {
@@ -135,26 +143,84 @@ public class UpdaterPlugin extends Plugin {
     }
 
     if (isAutomaticUpdateMode()) {
-      startAutoUpdate();
+      runAutomaticUpdate(TRIGGER_LAUNCH);
     }
   }
 
-  private void startAutoUpdate() {
-    executor.execute(() -> {
-      try {
-        BundleInfo downloaded = performCheckAndDownload(null, true);
-        if (UPDATE_MODE_IMMEDIATE.equals(updateMode) && downloaded != null) {
+  @Override
+  protected void handleOnResume() {
+    super.handleOnResume();
+    if (isAutomaticUpdateMode()) {
+      runAutomaticUpdate(TRIGGER_RESUME);
+    }
+  }
+
+  private void runAutomaticUpdate(String trigger) {
+    // Resume-only guards
+    if (TRIGGER_RESUME.equals(trigger)) {
+      if (UPDATE_MODE_MANUAL.equals(updateMode)) return;
+
+      // next-resume and immediate: activate staged bundle on resume without server check
+      if ((UPDATE_MODE_NEXT_RESUME.equals(updateMode) || UPDATE_MODE_IMMEDIATE.equals(updateMode))) {
+        String stagedId = store.getStagedBundleId();
+        if (stagedId != null && store.getBundle(stagedId) != null) {
           activateStagedBundleForReload();
           reloadWebView();
+          return;
         }
-      } catch (Exception e) {
-        if (UPDATE_MODE_IMMEDIATE.equals(updateMode)) {
-          android.util.Log.w("UpdateKit", "immediate startup update failed", e);
+      }
+
+      if (shouldThrottleCheck()) return;
+    }
+
+    // Acquire in-flight guard (submit-time)
+    if (!checkInProgress.compareAndSet(false, true)) return;
+
+    if (UPDATE_MODE_IMMEDIATE.equals(updateMode)) {
+      // Immediate: check+download, activate if found
+      executor.execute(() -> {
+        try {
+          BundleInfo result = performCheckAndDownload(null, true);
+          recordCheckTimestamp();
+          if (result != null) {
+            activateStagedBundleForReload();
+            reloadWebView();
+          }
+        } catch (Exception e) {
+          android.util.Log.w("OtaKit", "immediate update failed (" + trigger + ")", e);
+        } finally {
+          checkInProgress.set(false);
         }
+      });
+      return;
+    }
+
+    // next-launch / next-resume: background check+download (fire-and-forget)
+    executor.execute(() -> {
+      try {
+        performCheckAndDownload(null, true);
+        recordCheckTimestamp();
+      } catch (Exception ignored) {
+        // Check failed — timestamp not recorded, will retry on next trigger
+      } finally {
+        checkInProgress.set(false);
       }
     });
   }
 
+  private boolean shouldThrottleCheck() {
+    long lastCheck = store.getPrefs().getLong(KEY_LAST_CHECK_TIMESTAMP, 0);
+    if (lastCheck <= 0) return false;
+    long elapsed = System.currentTimeMillis() - lastCheck;
+    return elapsed < checkIntervalMs;
+  }
+
+  private void recordCheckTimestamp() {
+    store.getPrefs().edit()
+      .putLong(KEY_LAST_CHECK_TIMESTAMP, System.currentTimeMillis())
+      .apply();
+  }
+
   private boolean shouldActivateStagedOnLaunch() {
     return !UPDATE_MODE_MANUAL.equals(updateMode);
   }
@@ -175,12 +241,15 @@ public class UpdaterPlugin extends Plugin {
     if (UPDATE_MODE_MANUAL.equals(raw)) {
       return UPDATE_MODE_MANUAL;
     }
+    if (UPDATE_MODE_NEXT_RESUME.equals(raw)) {
+      return UPDATE_MODE_NEXT_RESUME;
+    }
     if (UPDATE_MODE_IMMEDIATE.equals(raw)) {
       return UPDATE_MODE_IMMEDIATE;
     }
 
     android.util.Log.w(
-      "UpdateKit",
+      "OtaKit",
       "Unknown updateMode '" + raw + "', defaulting to 'next-launch'"
     );
     return UPDATE_MODE_NEXT_LAUNCH;
@@ -209,10 +278,34 @@ public class UpdaterPlugin extends Plugin {
 
   @PluginMethod
   public void check(PluginCall call) {
+    // Respect throttle — return staged bundle as a LatestVersion if available, else null
+    if (shouldThrottleCheck() || !checkInProgress.compareAndSet(false, true)) {
+      String stagedId = store.getStagedBundleId();
+      if (stagedId != null) {
+        BundleInfo staged = store.getBundle(stagedId);
+        if (staged != null) {
+          JSObject result = new JSObject();
+          result.put("version", staged.version);
+          result.put("url", "");
+          result.put("sha256", staged.sha256 != null ? staged.sha256 : "");
+          result.put("size", 0);
+          result.put("downloaded", true);
+          if (staged.releaseId != null) {
+            result.put("releaseId", staged.releaseId);
+          }
+          call.resolve(result);
+          return;
+        }
+      }
+      call.resolve((JSObject) null);
+      return;
+    }
     String targetChannel = resolveTargetChannel(null);
     executor.execute(() -> {
       try {
         ManifestClient.LatestManifest latest = fetchLatest(targetChannel);
+        // check() does NOT record timestamp — only download() and automatic paths do.
+        // This keeps check() -> download() working without the throttle blocking download().
         if (latest == null) {
           call.resolve((JSObject) null);
         } else {
@@ -221,15 +314,31 @@ public class UpdaterPlugin extends Plugin {
         }
       } catch (Exception e) {
         call.reject("check failed: " + e.getMessage());
+      } finally {
+        checkInProgress.set(false);
       }
     });
   }
 
   @PluginMethod
   public void download(PluginCall call) {
+    // Respect throttle — return staged info if available, else null
+    if (shouldThrottleCheck() || !checkInProgress.compareAndSet(false, true)) {
+      String stagedId = store.getStagedBundleId();
+      if (stagedId != null) {
+        BundleInfo staged = store.getBundle(stagedId);
+        if (staged != null) {
+          call.resolve(staged.toJSObject());
+          return;
+        }
+      }
+      call.resolve((JSObject) null);
+      return;
+    }
     executor.execute(() -> {
       try {
         BundleInfo bundle = performCheckAndDownload(null, true);
+        recordCheckTimestamp();
         if (bundle == null) {
           call.resolve((JSObject) null);
         } else {
@@ -237,6 +346,8 @@ public class UpdaterPlugin extends Plugin {
         }
       } catch (Exception e) {
         call.reject("download failed: " + e.getMessage());
+      } finally {
+        checkInProgress.set(false);
       }
     });
   }

package/dist/esm/definitions.d.ts

@@ -57,7 +57,7 @@ export interface OtaKitState {
 export interface OtaKitDebugState extends OtaKitState {
     fallback: BundleInfo;
 }
-export type OtaKitUpdateMode = 'manual' | 'next-launch' | 'immediate';
+export type OtaKitUpdateMode = 'manual' | 'next-launch' | 'next-resume' | 'immediate';
 export interface OtaKitManifestKey {
     kid: string;
     key: string;
@@ -72,6 +72,12 @@ export interface OtaKitConfig {
     channel?: string;
     /** Overall update behavior. Defaults to next-launch. */
     updateMode?: OtaKitUpdateMode;
+    /**
+     * Minimum milliseconds between automatic update checks.
+     * Applies to both resume-triggered and manual check()/download() calls.
+     * Debug APIs bypass this throttle. Defaults to 600000 (10 min).
+     */
+    checkInterval?: number;
     /** Milliseconds to wait for notifyAppReady(). Defaults to 10000. */
     appReadyTimeout?: number;
     /** Custom API base URL for self-hosted or custom servers. */

package/dist/esm/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"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"}

package/ios/Sources/UpdaterPlugin/UpdaterPlugin.swift

@@ -7,9 +7,15 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
   private enum UpdateMode: String {
     case manual
     case nextLaunch = "next-launch"
+    case nextResume = "next-resume"
     case immediate
   }
 
+  private enum Trigger {
+    case launch
+    case resume
+  }
+
   public let identifier = "UpdaterPlugin"
   public let jsName = "OtaKit"
   public let pluginMethods: [CAPPluginMethod] = [
@@ -39,8 +45,13 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
   private var channel: String?
   private var manifestKeys: [(kid: String, key: Data)] = []
   private var trialTimeoutWorkItem: DispatchWorkItem?
+  private var checkIntervalMs: Int = 600_000
+  private let isCheckInProgress = NSLock()
+  private var checkInProgress = false
+  private var foregroundObserver: NSObjectProtocol?
   private static let defaultUpdateURL = "https://www.otakit.app/api/v1"
   private static let apiPathSuffix = "/api/v1"
+  private static let lastCheckTimestampKey = "otakit_last_check_timestamp"
 
   public override func load() {
     let envUpdateUrl = ProcessInfo.processInfo.environment["OTAKIT_SERVER_URL"]
@@ -55,6 +66,7 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     updateMode = resolveUpdateMode(configured: updateModeRaw)
     downloader = Downloader(allowInsecureUrls: allowInsecureUrls)
     appReadyTimeoutMs = max(1000, getConfig().getInt("appReadyTimeout", 10_000))
+    checkIntervalMs = max(600_000, getConfig().getInt("checkInterval", 600_000))
 
     let rawKeysValue = getConfig().getArray("manifestKeys")
     if let rawKeys = rawKeysValue as? [[String: String]] {
@@ -99,31 +111,124 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     if isAutomaticUpdateMode() {
-      startAutoUpdate()
+      runAutomaticUpdate(trigger: .launch)
+    }
+
+    if isAutomaticUpdateMode() {
+      foregroundObserver = NotificationCenter.default.addObserver(
+        forName: UIApplication.willEnterForegroundNotification,
+        object: nil,
+        queue: .main
+      ) { [weak self] _ in
+        self?.handleAppWillEnterForeground()
+      }
     }
   }
 
-  private func startAutoUpdate() {
-    switch updateMode {
-    case .manual:
-      return
-    case .nextLaunch:
+  deinit {
+    if let observer = foregroundObserver {
+      NotificationCenter.default.removeObserver(observer)
+    }
+  }
+
+  private func handleAppWillEnterForeground() {
+    runAutomaticUpdate(trigger: .resume)
+  }
+
+  private func runAutomaticUpdate(trigger: Trigger) {
+    // Resume-only guards
+    if trigger == .resume {
+      if updateMode == .manual { return }
+
+      // next-resume and immediate: activate staged bundle on resume without server check
+      if (updateMode == .nextResume || updateMode == .immediate),
+         let stagedId = store.getStagedBundleId(),
+         store.getBundle(id: stagedId) != nil {
+        activateStagedBundleForReload()
+        reloadWebView()
+        return
+      }
+
+      if shouldThrottleCheck() { return }
+    }
+
+    // Acquire in-flight guard (submit-time)
+    guard claimCheckInProgress() else { return }
+
+    // Immediate mode on cold start: block until check+download+activate completes
+    if updateMode == .immediate && trigger == .launch {
       Task {
-        _ = try? await performCheckAndDownload(channel: nil, emitEvents: true)
+        defer { releaseCheckInProgress() }
+        do {
+          let result = try await performCheckAndDownload(channel: nil, emitEvents: true)
+          recordCheckTimestamp()
+          if result != nil {
+            activateStagedBundleForReload()
+            reloadWebView()
+          }
+        } catch {
+          print("[OtaKit] immediate startup update failed: \(error.localizedDescription)")
+        }
       }
-    case .immediate:
+      return
+    }
+
+    // Immediate mode on resume: background check+download, activate when done
+    if updateMode == .immediate && trigger == .resume {
       Task {
+        defer { releaseCheckInProgress() }
         do {
-          let downloaded = try await performCheckAndDownload(channel: nil, emitEvents: true)
-          if downloaded != nil {
+          let result = try await performCheckAndDownload(channel: nil, emitEvents: true)
+          recordCheckTimestamp()
+          if result != nil {
             activateStagedBundleForReload()
             reloadWebView()
           }
         } catch {
-          print("[UpdateKit] immediate startup update failed: \(error.localizedDescription)")
+          print("[OtaKit] immediate resume update failed: \(error.localizedDescription)")
         }
       }
+      return
     }
+
+    // next-launch / next-resume: background check+download (fire-and-forget)
+    Task {
+      defer { releaseCheckInProgress() }
+      do {
+        _ = try await performCheckAndDownload(channel: nil, emitEvents: true)
+        recordCheckTimestamp()
+      } catch {
+        // Check failed — timestamp not recorded, will retry on next trigger
+      }
+    }
+  }
+
+  private func shouldThrottleCheck() -> Bool {
+    let lastCheck = UserDefaults.standard.double(forKey: UpdaterPlugin.lastCheckTimestampKey)
+    guard lastCheck > 0 else { return false }
+    let elapsed = Date().timeIntervalSince1970 * 1000 - lastCheck
+    return elapsed < Double(checkIntervalMs)
+  }
+
+  private func recordCheckTimestamp() {
+    UserDefaults.standard.set(
+      Date().timeIntervalSince1970 * 1000,
+      forKey: UpdaterPlugin.lastCheckTimestampKey
+    )
+  }
+
+  private func claimCheckInProgress() -> Bool {
+    isCheckInProgress.lock()
+    defer { isCheckInProgress.unlock() }
+    if checkInProgress { return false }
+    checkInProgress = true
+    return true
+  }
+
+  private func releaseCheckInProgress() {
+    isCheckInProgress.lock()
+    defer { isCheckInProgress.unlock() }
+    checkInProgress = false
   }
 
   private func shouldActivateStagedOnLaunch() -> Bool {
@@ -141,10 +246,12 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
       return .nextLaunch
     case UpdateMode.manual.rawValue:
       return .manual
+    case UpdateMode.nextResume.rawValue:
+      return .nextResume
     case UpdateMode.immediate.rawValue:
       return .immediate
     default:
-      print("[UpdateKit] Unknown updateMode '\(raw)', defaulting to 'next-launch'")
+      print("[OtaKit] Unknown updateMode '\(raw)', defaulting to 'next-launch'")
       return .nextLaunch
     }
   }
@@ -189,10 +296,33 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
   }
 
   @objc func check(_ call: CAPPluginCall) {
+    // Respect throttle — return staged bundle as a LatestVersion if available, else null
+    if shouldThrottleCheck() || !claimCheckInProgress() {
+      if let stagedId = store.getStagedBundleId(),
+         let staged = store.getBundle(id: stagedId) {
+        var payload: [String: Any] = [
+          "version": staged.version,
+          "url": "",
+          "sha256": staged.sha256 ?? "",
+          "size": 0,
+          "downloaded": true,
+        ]
+        if let releaseId = staged.releaseId {
+          payload["releaseId"] = releaseId
+        }
+        call.resolve(payload)
+      } else {
+        call.resolve()
+      }
+      return
+    }
     let targetChannel = resolveTargetChannel(nil)
     Task {
+      defer { releaseCheckInProgress() }
       do {
         let latest = try await fetchLatest(channel: targetChannel)
+        // check() does NOT record timestamp — only download() and automatic paths do.
+        // This keeps check() -> download() working without the throttle blocking download().
         if let latest {
           let staged = findMatchingStagedBundle(latest: latest, targetChannel: targetChannel)
           call.resolve(manifestToDictionary(latest, downloaded: staged != nil))
@@ -225,9 +355,21 @@ public class UpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
   }
 
   @objc func download(_ call: CAPPluginCall) {
+    // Respect throttle — return staged info if available, else null
+    if shouldThrottleCheck() || !claimCheckInProgress() {
+      if let stagedId = store.getStagedBundleId(),
+         let staged = store.getBundle(id: stagedId) {
+        call.resolve(staged.toDictionary())
+      } else {
+        call.resolve()
+      }
+      return
+    }
     Task {
+      defer { releaseCheckInProgress() }
       do {
         let bundle = try await performCheckAndDownload(channel: nil, emitEvents: true)
+        recordCheckTimestamp()
         if let bundle {
           call.resolve(bundle.toDictionary())
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otakit/capacitor-updater",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Capacitor plugin for OTA updates",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",