@otakit/capacitor-updater 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OtaKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# @otakit/capacitor-updater
+
+Capacitor OTA updater plugin for OtaKit.
+
+## What it does
+
+- 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
+- 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
+
+For normal app code, the main public methods are:
+
+```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.
+
+Manual inspection and support methods like state inspection and reset live under
+`OtaKit.debug`.
+
+## Hosted config
+
+```ts
+plugins: {
+  OtaKit: {
+    appId: "YOUR_OTAKIT_APP_ID",
+    appReadyTimeout: 10000,
+    // Optional:
+    // channel: "staging",
+    // updateMode: "manual",
+    // updateMode: "immediate",
+  }
+}
+```
+
+Advanced overrides for self-hosting or custom trust only:
+
+- `serverUrl`
+- `manifestKeys`
+- `allowInsecureUrls`
+
+Hosted OtaKit already points at `https://otakit.app/api/v1` and already trusts
+the managed manifest signing keys.
+
+## Trust model
+
+The plugin does not just download from a URL and trust the result.
+
+1. it fetches a manifest from the server
+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
+
+In the hosted path, managed signing keys are already built in.
+
+## Update modes
+
+- `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
+- `immediate`
+  automatic startup check, then download and activate during startup
+
+The default is `next-launch`.
+
+## Runtime model
+
+The plugin keeps three important runtime pointers:
+
+- `current`
+  the bundle the WebView is currently serving
+- `fallback`
+  the last known-good bundle used for rollback
+- `staged`
+  a downloaded bundle waiting to be activated
+
+Bundle lifecycle is intentionally small:
+
+```text
+download -> pending -> trial -> success
+                        |
+                        +-> error -> rollback -> delete failed files
+```
+
+In practice:
+
+- downloads start as `pending`
+- an activated bundle becomes `trial`
+- `notifyAppReady()` promotes `trial` to `success`
+- timeout or restart during `trial` causes rollback
+
+That gives the plugin a small but important safety model:
+
+- `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 and manual flows
+
+### Automatic flow
+
+For the normal hosted path, the app usually just needs to call:
+
+```ts
+await OtaKit.notifyAppReady();
+```
+
+The plugin handles checking, downloading, activation, and rollback based on
+`updateMode`.
+
+For most apps, this is the entire runtime integration.
+
+### Manual flow
+
+For app-driven prompts:
+
+```ts
+const state = await OtaKit.getState();
+const latest = await OtaKit.check();
+
+if (latest) {
+  await OtaKit.update();
+}
+```
+
+Or the split version:
+
+```ts
+await OtaKit.download();
+await OtaKit.apply();
+```
+
+Use the split flow when the app wants to download in the background and switch
+only after explicit user confirmation.
+
+## Retention and deletion
+
+- the builtin, current, fallback, and staged bundles are protected
+- superseded staged bundles are deleted automatically
+- failed trial bundles are deleted during rollback
+- `debug.deleteBundle()` only works for downloaded bundles outside runtime state
+
+## Source areas
+
+- `src/definitions.ts`: public types and methods
+- `src/index.ts`: Capacitor registration and JS wrapper
+- `src/web.ts`: web fallback implementation
+- `ios/Sources/UpdaterPlugin/*`: iOS implementation
+- `android/src/main/java/com/updatekit/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/UpdatekitUpdater.podspec

@@ -0,0 +1,18 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'UpdatekitUpdater'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.dependency 'ZIPFoundation', '~> 0.9'
+  s.swift_version = '5.9'
+end

package/android/build.gradle

@@ -0,0 +1,49 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.1.5'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.5.1'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.2.2'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace "com.updatekit.updater"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+    defaultConfig {
+        minSdk project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdk project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+        versionCode 1
+        versionName "0.0.1"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    lintOptions {
+        abortOnError false
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

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

@@ -0,0 +1,100 @@
+package com.updatekit.updater;
+
+import com.getcapacitor.JSObject;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+class BundleInfo {
+
+  final String id;
+  final String version;
+  final BundleStatus status;
+  final Long downloadedAt;
+  final String sha256;
+  final String path;
+  final String channel;
+  final String releaseId;
+
+  BundleInfo(
+    String id,
+    String version,
+    BundleStatus status,
+    Long downloadedAt,
+    String sha256,
+    String path,
+    String channel,
+    String releaseId
+  ) {
+    this.id = id;
+    this.version = version;
+    this.status = status;
+    this.downloadedAt = downloadedAt;
+    this.sha256 = sha256;
+    this.path = path;
+    this.channel = channel;
+    this.releaseId = releaseId;
+  }
+
+  boolean isBuiltin() {
+    return "builtin".equals(id);
+  }
+
+  JSObject toJSObject() {
+    JSObject object = new JSObject();
+    object.put("id", id);
+    object.put("version", version);
+    object.put("status", status.value());
+    if (downloadedAt != null) {
+      object.put("downloadedAt", DateUtils.toIsoString(downloadedAt));
+    }
+    if (sha256 != null) {
+      object.put("sha256", sha256);
+    }
+    if (channel != null) {
+      object.put("channel", channel);
+    }
+    if (releaseId != null) {
+      object.put("releaseId", releaseId);
+    }
+    return object;
+  }
+
+  JSONObject toJSONObject() throws JSONException {
+    JSONObject object = new JSONObject();
+    object.put("id", id);
+    object.put("version", version);
+    object.put("status", status.value());
+    if (downloadedAt != null) {
+      object.put("downloadedAt", downloadedAt);
+    }
+    if (sha256 != null) {
+      object.put("sha256", sha256);
+    }
+    if (channel != null) {
+      object.put("channel", channel);
+    }
+    if (releaseId != null) {
+      object.put("releaseId", releaseId);
+    }
+    if (path != null) {
+      object.put("path", path);
+    }
+    return object;
+  }
+
+  static BundleInfo fromJSONObject(JSONObject object) {
+    String id = object.optString("id", "builtin");
+    String version = object.optString("version", "0.0.0");
+    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);
+  }
+
+  BundleInfo withStatus(BundleStatus nextStatus) {
+    return new BundleInfo(id, version, nextStatus, downloadedAt, sha256, path, channel, releaseId);
+  }
+}

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

@@ -0,0 +1,28 @@
+package com.updatekit.updater;
+
+enum BundleStatus {
+  BUILTIN("builtin"),
+  PENDING("pending"),
+  TRIAL("trial"),
+  SUCCESS("success"),
+  ERROR("error");
+
+  private final String value;
+
+  BundleStatus(String value) {
+    this.value = value;
+  }
+
+  public String value() {
+    return value;
+  }
+
+  public static BundleStatus from(String raw) {
+    for (BundleStatus status : values()) {
+      if (status.value.equals(raw)) {
+        return status;
+      }
+    }
+    return PENDING;
+  }
+}

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

@@ -0,0 +1,264 @@
+package com.updatekit.updater;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import com.getcapacitor.JSArray;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Comparator;
+import java.util.List;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+final class BundleStore {
+
+  private static final String PREFS_NAME = "otakit_updater_state";
+  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 final Context context;
+  private final SharedPreferences prefs;
+  private final File bundlesDirectory;
+  private final String builtinVersion;
+  private final String nativeBuild;
+
+  BundleStore(Context context, String builtinVersion, String nativeBuild) {
+    this.context = context.getApplicationContext();
+    this.prefs = this.context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+    this.builtinVersion = builtinVersion;
+    this.nativeBuild = nativeBuild;
+    this.bundlesDirectory = new File(this.context.getFilesDir(), "otakit_bundles");
+    if (!bundlesDirectory.exists()) {
+      //noinspection ResultOfMethodCallIgnored
+      bundlesDirectory.mkdirs();
+    }
+  }
+
+  String getNativeBuild() {
+    return nativeBuild;
+  }
+
+  String getBuiltinVersion() {
+    return builtinVersion;
+  }
+
+  BundleInfo builtinBundle() {
+    return new BundleInfo(
+      "builtin",
+      builtinVersion,
+      BundleStatus.BUILTIN,
+      null,
+      null,
+      null,
+      null,
+      null
+    );
+  }
+
+  File bundleDirectory(String id) {
+    return new File(bundlesDirectory, id);
+  }
+
+  private File metadataFile(String id) {
+    return new File(bundleDirectory(id), "bundle.json");
+  }
+
+  synchronized void saveBundle(BundleInfo bundle) throws Exception {
+    if (bundle.isBuiltin()) {
+      return;
+    }
+
+    File directory = bundleDirectory(bundle.id);
+    if (!directory.exists() && !directory.mkdirs()) {
+      throw new IllegalStateException("Failed to create bundle directory");
+    }
+
+    byte[] bytes = bundle.toJSONObject().toString().getBytes(StandardCharsets.UTF_8);
+    try (FileOutputStream output = new FileOutputStream(metadataFile(bundle.id), false)) {
+      output.write(bytes);
+    }
+  }
+
+  synchronized BundleInfo getBundle(String id) {
+    if ("builtin".equals(id)) {
+      return builtinBundle();
+    }
+
+    File metadata = metadataFile(id);
+    if (!metadata.exists()) {
+      return null;
+    }
+
+    try (FileInputStream input = new FileInputStream(metadata)) {
+      byte[] bytes = readAllBytes(input);
+      JSONObject json = new JSONObject(new String(bytes, StandardCharsets.UTF_8));
+      return BundleInfo.fromJSONObject(json);
+    } catch (Exception ignored) {
+      return null;
+    }
+  }
+
+  private static byte[] readAllBytes(FileInputStream input) throws Exception {
+    java.io.ByteArrayOutputStream buffer = new java.io.ByteArrayOutputStream();
+    byte[] chunk = new byte[8192];
+    int read;
+    while ((read = input.read(chunk)) != -1) {
+      buffer.write(chunk, 0, read);
+    }
+    return buffer.toByteArray();
+  }
+
+  synchronized boolean bundleExists(String id) {
+    return getBundle(id) != null;
+  }
+
+  synchronized BundleInfo getCurrentBundle() {
+    String currentId = prefs.getString(KEY_CURRENT, null);
+    if (currentId == null) {
+      return builtinBundle();
+    }
+    BundleInfo current = getBundle(currentId);
+    return current != null ? current : builtinBundle();
+  }
+
+  synchronized void setCurrentBundleId(String id) {
+    SharedPreferences.Editor editor = prefs.edit();
+    if (id == null) {
+      editor.remove(KEY_CURRENT);
+    } else {
+      editor.putString(KEY_CURRENT, id);
+    }
+    editor.commit();
+  }
+
+  synchronized BundleInfo getFallbackBundle() {
+    String fallbackId = prefs.getString(KEY_FALLBACK, null);
+    if (fallbackId == null) {
+      return builtinBundle();
+    }
+    BundleInfo fallback = getBundle(fallbackId);
+    return fallback != null ? fallback : builtinBundle();
+  }
+
+  synchronized void setFallbackBundleId(String id) {
+    SharedPreferences.Editor editor = prefs.edit();
+    if (id == null) {
+      editor.remove(KEY_FALLBACK);
+    } else {
+      editor.putString(KEY_FALLBACK, id);
+    }
+    editor.commit();
+  }
+
+  synchronized String getStagedBundleId() {
+    return prefs.getString(KEY_STAGED, null);
+  }
+
+  synchronized void setStagedBundleId(String id) {
+    SharedPreferences.Editor editor = prefs.edit();
+    if (id == null) {
+      editor.remove(KEY_STAGED);
+    } else {
+      editor.putString(KEY_STAGED, id);
+    }
+    editor.commit();
+  }
+
+  synchronized void setFailedBundle(BundleInfo bundle) {
+    SharedPreferences.Editor editor = prefs.edit();
+    if (bundle == null) {
+      editor.remove(KEY_FAILED_INFO);
+    } else {
+      try {
+        editor.putString(KEY_FAILED_INFO, bundle.toJSONObject().toString());
+      } catch (JSONException ignored) {
+        editor.remove(KEY_FAILED_INFO);
+      }
+    }
+    editor.apply();
+  }
+
+  synchronized BundleInfo getFailedBundle() {
+    String json = prefs.getString(KEY_FAILED_INFO, null);
+    if (json == null) {
+      return null;
+    }
+    try {
+      return BundleInfo.fromJSONObject(new JSONObject(json));
+    } catch (Exception e) {
+      return null;
+    }
+  }
+
+  synchronized void markStatus(String bundleId, BundleStatus status) {
+    BundleInfo existing = getBundle(bundleId);
+    if (existing == null) {
+      return;
+    }
+    try {
+      saveBundle(existing.withStatus(status));
+    } catch (Exception ignored) {}
+  }
+
+  synchronized void deleteBundle(String id) throws Exception {
+    if ("builtin".equals(id)) {
+      return;
+    }
+
+    File directory = bundleDirectory(id);
+    deleteRecursively(directory);
+
+    if (id.equals(getStagedBundleId())) {
+      setStagedBundleId(null);
+    }
+    if (id.equals(prefs.getString(KEY_CURRENT, null))) {
+      setCurrentBundleId(null);
+    }
+    if (id.equals(prefs.getString(KEY_FALLBACK, null))) {
+      setFallbackBundleId(null);
+    }
+  }
+
+  synchronized JSArray listDownloadedBundles() {
+    List<BundleInfo> result = new ArrayList<>();
+    File[] entries = bundlesDirectory.listFiles();
+    if (entries != null) {
+      Arrays.sort(entries, Comparator.comparing(File::getName));
+      for (File entry : entries) {
+        BundleInfo bundle = getBundle(entry.getName());
+        if (bundle != null) {
+          result.add(bundle);
+        }
+      }
+    }
+
+    JSArray array = new JSArray();
+    for (BundleInfo bundle : result) {
+      array.put(bundle.toJSObject());
+    }
+    return array;
+  }
+
+  private void deleteRecursively(File target) throws Exception {
+    if (!target.exists()) {
+      return;
+    }
+    if (target.isDirectory()) {
+      File[] children = target.listFiles();
+      if (children != null) {
+        for (File child : children) {
+          deleteRecursively(child);
+        }
+      }
+    }
+    if (!target.delete()) {
+      throw new IllegalStateException("Failed to delete " + target.getAbsolutePath());
+    }
+  }
+}

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

@@ -0,0 +1,17 @@
+package com.updatekit.updater;
+
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.Locale;
+import java.util.TimeZone;
+
+final class DateUtils {
+
+  private DateUtils() {}
+
+  static String toIsoString(long timestampMs) {
+    SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US);
+    format.setTimeZone(TimeZone.getTimeZone("UTC"));
+    return format.format(new Date(timestampMs));
+  }
+}