@fireota/react-native 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FireOTA
+
+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

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @fireota/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Over-the-air JavaScript updates for React Native, served from **your own Firebase project** by [FireOTA](https://www.npmjs.com/package/@fireota/cli).
+
+- SHA-256 verified downloads, straight from your Firebase Storage bucket
+- Staged rollouts, pause and rollback from the FireOTA dashboard
+- Automatic rollback when a new bundle crashes before it starts
+- Old updates are discarded when a new store build is installed
+- No third-party native dependencies
+
+> **Beta (0.x).** Verified on Android with React Native 0.87. iOS support is implemented but not yet device-tested.
+
+## Install
+
+```sh
+npm install @fireota/react-native
+npm install --save-dev @fireota/cli
+cd ios && pod install
+```
+
+Requires a bare React Native app, 0.73 or newer (Expo: run `npx expo prebuild`).
+
+## Android
+
+In `MainApplication.kt` (React Native 0.76+ template):
+
+```kotlin
+import dev.fireota.reactnative.FireOTA
+
+override val reactHost: ReactHost by lazy {
+  getDefaultReactHost(
+    context = applicationContext,
+    packageList = PackageList(this).packages,
+    jsBundleFilePath = if (BuildConfig.DEBUG) null else FireOTA.getJSBundleFile(applicationContext),
+  )
+}
+```
+
+Older templates that override `reactNativeHost`:
+
+```kotlin
+override fun getJSBundleFile(): String? =
+  if (BuildConfig.DEBUG) super.getJSBundleFile()
+  else FireOTA.getJSBundleFile(applicationContext) ?: super.getJSBundleFile()
+```
+
+## iOS
+
+```objc
+// AppDelegate.mm
+#import <FireOTA.h>
+
+- (NSURL *)bundleURL
+{
+#if DEBUG
+  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
+#else
+  return [FireOTA bundleURL] ?: [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+#endif
+}
+```
+
+Swift: add `#import <FireOTA.h>` to the bridging header and return `FireOTA.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")` from `bundleURL()` in release builds.
+
+## Configure
+
+Call once, early and unconditionally (e.g. `index.js`). Reaching this call confirms a new bundle starts; a bundle that never reaches it is rolled back on the next launch.
+
+```js
+import FireOTA from "@fireota/react-native";
+
+if (!__DEV__) {
+  FireOTA.configure({
+    appId: "YOUR_APP_ID",
+    serverUrl: "https://ota.example.com",
+    runtimeVersion: "1.3.0", // must equal this store build; bump when native code changes
+    channel: "production",
+  });
+}
+```
+
+By default updates download silently and apply on the next cold start; mandatory updates restart immediately. To show your own prompt, set `checkOnAppStart: false` and use the API:
+
+```js
+const result = await FireOTA.checkForUpdate();
+if (result.updateAvailable) {
+  // show your UI with result.release.version / result.release.notes, then:
+  await FireOTA.downloadUpdate(result.release);
+  await FireOTA.installUpdate(result.release, "immediate");
+}
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `configure(options)` | Initialize once at startup (required). |
+| `sync()` | Check, download and install, honouring install modes. |
+| `checkForUpdate()` | `{ updateAvailable, reason?, release? }` |
+| `downloadUpdate(release)` | Download and verify; the running bundle is untouched. |
+| `installUpdate(release, mode)` | `"nextRestart"` or `"immediate"`. |
+| `reload()` | Restart now to apply a pending update. |
+| `clearPendingUpdate()` | Drop a downloaded update that is not applied yet. |
+| `getCurrentRelease()` | `{ releaseId, pendingReleaseId, installationId }` |
+| `getUpdateStatus()` | Current status string. |
+
+Options: `appId`, `serverUrl`, `runtimeVersion` (required), `channel`, `checkOnAppStart`, `installMode`, `mandatoryInstallMode`, `onStatusChange(status, detail)`.
+
+## Publishing updates
+
+Use [`@fireota/cli`](https://www.npmjs.com/package/@fireota/cli):
+
+```sh
+npx fireota publish --app YOUR_APP_ID --platform android --version 1.3.1 --runtime 1.3.0 --channel production --rollout 10
+```
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,51 @@
+buildscript {
+  ext.safeExtGet = { prop, fallback -> rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback }
+  repositories { google(); mavenCentral() }
+  dependencies {
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${safeExtGet('kotlinVersion', '2.1.20')}"
+  }
+}
+
+apply plugin: "com.android.library"
+
+/**
+ * AGP 9 compiles Kotlin itself ("built-in Kotlin", on by default) and registers the `kotlin`
+ * extension; applying kotlin-android on top fails with "Cannot add extension with name 'kotlin'".
+ * Only apply it on AGP 8 or when the app turned built-in Kotlin off (android.builtInKotlin=false).
+ */
+def needsKotlinPlugin() {
+  def agpMajor = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')[0].toInteger()
+  if (agpMajor <= 8) return true
+  def builtIn = providers.gradleProperty("android.builtInKotlin").orNull
+  return builtIn != null && !builtIn.toBoolean()
+}
+
+def useKotlinPlugin = needsKotlinPlugin()
+if (useKotlinPlugin) {
+  apply plugin: "kotlin-android"
+}
+
+android {
+  namespace "dev.fireota.reactnative"
+  compileSdk safeExtGet("compileSdkVersion", 35)
+  defaultConfig {
+    minSdk safeExtGet("minSdkVersion", 24)
+  }
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+if (useKotlinPlugin) {
+  // Built-in Kotlin derives this from compileOptions; the standalone plugin needs it explicitly.
+  tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
+    kotlinOptions.jvmTarget = "17"
+  }
+}
+
+repositories { google(); mavenCentral() }
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,10 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET" />
+  <application>
+    <activity
+      android:name="dev.fireota.reactnative.FireOTARestartActivity"
+      android:exported="false"
+      android:process=":fireota_restart"
+      android:theme="@android:style/Theme.Translucent.NoTitleBar" />
+  </application>
+</manifest>

package/android/src/main/java/dev/fireota/reactnative/FireOTA.kt

@@ -0,0 +1,33 @@
+package dev.fireota.reactnative
+
+import android.content.Context
+
+/**
+ * Entry point for MainApplication. Returns the path of the OTA bundle to load, or null to
+ * fall back to the bundle shipped inside the APK/AAB.
+ *
+ *   override fun getJSBundleFile(): String? =
+ *       FireOTA.getJSBundleFile(applicationContext) ?: super.getJSBundleFile()
+ */
+object FireOTA {
+  @Volatile private var resolved = false
+  @Volatile private var bundlePath: String? = null
+
+  @JvmStatic
+  fun getJSBundleFile(context: Context): String? {
+    // Resolve once per process: launch attempts are counted per process start.
+    if (!resolved) {
+      synchronized(this) {
+        if (!resolved) {
+          bundlePath = try {
+            FireOTAStore(context.applicationContext).resolveLaunchBundle()
+          } catch (_: Throwable) {
+            null // never block startup: fall back to the embedded bundle
+          }
+          resolved = true
+        }
+      }
+    }
+    return bundlePath
+  }
+}

package/android/src/main/java/dev/fireota/reactnative/FireOTAModule.kt

@@ -0,0 +1,105 @@
+package dev.fireota.reactnative
+
+import android.content.Intent
+import android.os.Process
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import java.util.concurrent.Executors
+
+class FireOTAModule(private val reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
+  private val store = FireOTAStore(reactContext)
+  private val io = Executors.newSingleThreadExecutor()
+
+  override fun getName() = "FireOTA"
+
+  @ReactMethod
+  fun getState(promise: Promise) {
+    try {
+      val map = Arguments.createMap()
+      map.putString("installationId", store.installationId)
+      map.putString("nativeVersion", store.nativeVersion())
+      map.putString("appVersion", store.nativeVersion())
+      map.putString("currentReleaseId", store.get(FireOTAStore.KEY_CURRENT))
+      map.putString("pendingReleaseId", store.get(FireOTAStore.KEY_PENDING))
+      map.putString("previousReleaseId", store.get(FireOTAStore.KEY_PREVIOUS))
+      map.putString("failedReleaseId", store.get(FireOTAStore.KEY_FAILED))
+      map.putBoolean("isFirstRun", store.isUnconfirmed())
+      promise.resolve(map)
+    } catch (e: Throwable) {
+      promise.reject("FIREOTA_STATE", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun downloadUpdate(url: String, sha256: String, releaseId: String, promise: Promise) {
+    io.execute {
+      try {
+        store.download(url, sha256, releaseId)
+        promise.resolve(null)
+      } catch (e: SecurityException) {
+        promise.reject("FIREOTA_CHECKSUM", e.message, e)
+      } catch (e: Throwable) {
+        promise.reject("FIREOTA_DOWNLOAD", e.message, e)
+      }
+    }
+  }
+
+  @ReactMethod
+  fun installUpdate(releaseId: String, promise: Promise) {
+    try {
+      store.setPending(releaseId)
+      promise.resolve(null)
+    } catch (e: Throwable) {
+      promise.reject("FIREOTA_INSTALL", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  fun markSuccess(promise: Promise) {
+    io.execute {
+      try {
+        store.markSuccess()
+        promise.resolve(null)
+      } catch (e: Throwable) {
+        promise.reject("FIREOTA_CONFIRM", e.message, e)
+      }
+    }
+  }
+
+  @ReactMethod
+  fun clearPending(promise: Promise) {
+    store.clear(FireOTAStore.KEY_PENDING)
+    store.clear(FireOTAStore.KEY_DOWNLOADED)
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  fun clearFailed(promise: Promise) {
+    store.clear(FireOTAStore.KEY_FAILED)
+    promise.resolve(null)
+  }
+
+  /**
+   * Restarts the process so the pending bundle loads. React Native reuses its bundle loader on
+   * a JS reload, so a cold restart is the reliable way to switch bundles on Android.
+   */
+  @ReactMethod
+  fun restartApp(promise: Promise) {
+    val launch = reactContext.packageManager.getLaunchIntentForPackage(reactContext.packageName)
+    if (launch == null) {
+      promise.reject("FIREOTA_RESTART", "No launch activity found.")
+      return
+    }
+    promise.resolve(null)
+    val intent = Intent(reactContext, FireOTARestartActivity::class.java)
+      .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+      .putExtra(FireOTARestartActivity.EXTRA_LAUNCH, launch.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK))
+      .putExtra(FireOTARestartActivity.EXTRA_PID, Process.myPid())
+    reactContext.startActivity(intent)
+    reactContext.currentActivity?.finishAffinity()
+    Runtime.getRuntime().exit(0)
+  }
+}

package/android/src/main/java/dev/fireota/reactnative/FireOTAPackage.kt

@@ -0,0 +1,13 @@
+package dev.fireota.reactnative
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+// The classic ReactPackage API is deprecated in RN 0.87 but still supported through the interop layer.
+@Suppress("OVERRIDE_DEPRECATION", "DEPRECATION")
+class FireOTAPackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> = listOf(FireOTAModule(reactContext))
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> = emptyList()
+}

package/android/src/main/java/dev/fireota/reactnative/FireOTARestartActivity.kt

@@ -0,0 +1,28 @@
+package dev.fireota.reactnative
+
+import android.app.Activity
+import android.content.Intent
+import android.os.Build
+import android.os.Bundle
+import android.os.Process
+
+/** Runs in its own process (":fireota_restart"): kills the app process, then relaunches it. */
+class FireOTARestartActivity : Activity() {
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    Process.killProcess(intent.getIntExtra(EXTRA_PID, -1))
+    val launch: Intent? = if (Build.VERSION.SDK_INT >= 33) {
+      intent.getParcelableExtra(EXTRA_LAUNCH, Intent::class.java)
+    } else {
+      @Suppress("DEPRECATION") intent.getParcelableExtra(EXTRA_LAUNCH)
+    }
+    launch?.let { startActivity(it) }
+    finish()
+    Runtime.getRuntime().exit(0)
+  }
+
+  companion object {
+    const val EXTRA_LAUNCH = "dev.fireota.launch"
+    const val EXTRA_PID = "dev.fireota.pid"
+  }
+}

package/android/src/main/java/dev/fireota/reactnative/FireOTAStore.kt

@@ -0,0 +1,207 @@
+package dev.fireota.reactnative
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.content.pm.PackageManager
+import android.os.Build
+import java.io.DataInputStream
+import java.io.File
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.security.MessageDigest
+import java.util.UUID
+import java.util.zip.GZIPInputStream
+import org.json.JSONObject
+
+/**
+ * On-device OTA state. Bundles live in app-private storage:
+ *   filesDir/fireota/releases/<releaseId>/index.android.bundle (+ drawable-* assets)
+ *
+ * Launch rules (resolveLaunchBundle, once per process):
+ *  - a new native binary (store update / reinstall) discards every OTA bundle;
+ *  - a pending release is promoted to current and must confirm (markSuccess) during this launch;
+ *  - a current release that reaches a second launch unconfirmed is rolled back to the previous one.
+ */
+internal class FireOTAStore(private val context: Context) {
+  private val prefs: SharedPreferences = context.getSharedPreferences("dev.fireota", Context.MODE_PRIVATE)
+  private val root = File(context.filesDir, "fireota/releases")
+
+  fun releaseDir(releaseId: String) = File(root, safe(releaseId))
+  fun bundleFile(releaseId: String) = File(releaseDir(releaseId), BUNDLE_NAME)
+
+  val installationId: String
+    get() = prefs.getString(KEY_INSTALLATION, null) ?: UUID.randomUUID().toString().also {
+      prefs.edit().putString(KEY_INSTALLATION, it).apply()
+    }
+
+  fun get(key: String): String? = prefs.getString(key, null)
+  fun isUnconfirmed() = prefs.getBoolean(KEY_UNCONFIRMED, false)
+
+  @Synchronized
+  fun resolveLaunchBundle(): String? {
+    val binary = binaryVersion()
+    if (prefs.getString(KEY_BINARY, null) != binary) {
+      root.deleteRecursively()
+      prefs.edit()
+        .remove(KEY_CURRENT).remove(KEY_PREVIOUS).remove(KEY_PENDING).remove(KEY_DOWNLOADED)
+        .putBoolean(KEY_UNCONFIRMED, false).putInt(KEY_ATTEMPTS, 0)
+        .putString(KEY_BINARY, binary)
+        .commit()
+    }
+
+    val edit = prefs.edit()
+    val pending = prefs.getString(KEY_PENDING, null)
+    if (pending != null && bundleFile(pending).exists()) {
+      edit.putString(KEY_PREVIOUS, prefs.getString(KEY_CURRENT, null))
+        .putString(KEY_CURRENT, pending)
+        .putBoolean(KEY_UNCONFIRMED, true)
+        .putInt(KEY_ATTEMPTS, 0)
+    }
+    edit.remove(KEY_PENDING).commit()
+
+    if (prefs.getBoolean(KEY_UNCONFIRMED, false)) {
+      val attempts = prefs.getInt(KEY_ATTEMPTS, 0) + 1
+      if (attempts >= 2) {
+        val failed = prefs.getString(KEY_CURRENT, null)
+        prefs.edit()
+          .putString(KEY_FAILED, failed)
+          .putString(KEY_CURRENT, prefs.getString(KEY_PREVIOUS, null))
+          .remove(KEY_PREVIOUS)
+          .putBoolean(KEY_UNCONFIRMED, false)
+          .putInt(KEY_ATTEMPTS, 0)
+          .commit()
+        failed?.let { releaseDir(it).deleteRecursively() }
+      } else {
+        prefs.edit().putInt(KEY_ATTEMPTS, attempts).commit()
+      }
+    }
+
+    val current = prefs.getString(KEY_CURRENT, null) ?: return null
+    val file = bundleFile(current)
+    if (!file.exists()) {
+      prefs.edit().remove(KEY_CURRENT).putBoolean(KEY_UNCONFIRMED, false).commit()
+      return null
+    }
+    return file.absolutePath
+  }
+
+  fun markSuccess() {
+    prefs.edit().putBoolean(KEY_UNCONFIRMED, false).putInt(KEY_ATTEMPTS, 0).commit()
+    val keep = setOf(get(KEY_CURRENT), get(KEY_PREVIOUS), get(KEY_PENDING), get(KEY_DOWNLOADED)).filterNotNull().map(::safe)
+    root.listFiles()?.filter { it.name !in keep }?.forEach { it.deleteRecursively() }
+  }
+
+  fun setPending(releaseId: String) {
+    require(bundleFile(releaseId).exists()) { "Release $releaseId has not been downloaded." }
+    prefs.edit().putString(KEY_PENDING, releaseId).remove(KEY_DOWNLOADED).commit()
+  }
+
+  fun clear(key: String) = prefs.edit().remove(key).commit()
+
+  /** Streams the package to disk, verifies its SHA-256, then unpacks it atomically. */
+  fun download(url: String, expectedSha256: String, releaseId: String) {
+    require(url.startsWith("https://")) { "Updates must be downloaded over HTTPS." }
+    root.mkdirs()
+    val tmp = File(root, ".${safe(releaseId)}.download")
+    val connection = java.net.URL(url).openConnection() as java.net.HttpURLConnection
+    connection.connectTimeout = 15_000
+    connection.readTimeout = 60_000
+    connection.instanceFollowRedirects = true
+    try {
+      if (connection.responseCode !in 200..299) throw IllegalStateException("Download failed: HTTP ${connection.responseCode}")
+      val digest = MessageDigest.getInstance("SHA-256")
+      connection.inputStream.use { input ->
+        FileOutputStream(tmp).use { output ->
+          val buffer = ByteArray(64 * 1024)
+          while (true) {
+            val read = input.read(buffer)
+            if (read < 0) break
+            digest.update(buffer, 0, read)
+            output.write(buffer, 0, read)
+          }
+        }
+      }
+      val actual = digest.digest().joinToString("") { "%02x".format(it) }
+      if (!actual.equals(expectedSha256, ignoreCase = true)) throw SecurityException("Checksum mismatch: the update was rejected.")
+
+      val staging = File(root, ".${safe(releaseId)}.staging")
+      staging.deleteRecursively()
+      unpack(tmp, staging)
+      if (!File(staging, BUNDLE_NAME).exists()) throw IllegalStateException("The update package has no $BUNDLE_NAME.")
+      val target = releaseDir(releaseId)
+      target.deleteRecursively()
+      if (!staging.renameTo(target)) throw IllegalStateException("Could not store the update.")
+      prefs.edit().putString(KEY_DOWNLOADED, releaseId).commit()
+    } finally {
+      connection.disconnect()
+      tmp.delete()
+    }
+  }
+
+  /**
+   * FireOTA package: gzip( "FOTA1\n" | u32 header length | JSON {files:[{path,size}]} | file bytes... ).
+   * Paths are validated so a package can never write outside its release directory.
+   */
+  private fun unpack(archive: File, into: File) {
+    DataInputStream(GZIPInputStream(FileInputStream(archive), 64 * 1024)).use { input ->
+      val magic = ByteArray(6)
+      input.readFully(magic)
+      if (String(magic, Charsets.US_ASCII) != "FOTA1\n") throw IllegalStateException("Not a FireOTA package.")
+      val headerLength = input.readInt()
+      if (headerLength <= 0 || headerLength > 4 * 1024 * 1024) throw IllegalStateException("Invalid package header.")
+      val header = ByteArray(headerLength)
+      input.readFully(header)
+      val files = JSONObject(String(header, Charsets.UTF_8)).getJSONArray("files")
+      val base = into.canonicalFile
+      for (i in 0 until files.length()) {
+        val entry = files.getJSONObject(i)
+        val path = entry.getString("path")
+        val size = entry.getLong("size")
+        val out = File(base, path).canonicalFile
+        if (path.startsWith("/") || path.contains("..") || !out.path.startsWith(base.path + File.separator)) {
+          throw SecurityException("Unsafe path in update package: $path")
+        }
+        out.parentFile?.mkdirs()
+        FileOutputStream(out).use { output ->
+          var remaining = size
+          val buffer = ByteArray(64 * 1024)
+          while (remaining > 0) {
+            val read = input.read(buffer, 0, minOf(buffer.size.toLong(), remaining).toInt())
+            if (read < 0) throw IllegalStateException("Truncated update package.")
+            output.write(buffer, 0, read)
+            remaining -= read
+          }
+        }
+      }
+    }
+  }
+
+  fun nativeVersion(): String = packageInfo()?.versionName ?: ""
+
+  private fun binaryVersion(): String {
+    val info = packageInfo() ?: return ""
+    val code = if (Build.VERSION.SDK_INT >= 28) info.longVersionCode else @Suppress("DEPRECATION") info.versionCode.toLong()
+    return "${info.versionName}-$code-${info.lastUpdateTime}"
+  }
+
+  private fun packageInfo() = try {
+    context.packageManager.getPackageInfo(context.packageName, 0)
+  } catch (_: PackageManager.NameNotFoundException) {
+    null
+  }
+
+  private fun safe(id: String) = id.replace(Regex("[^A-Za-z0-9_-]"), "")
+
+  companion object {
+    const val BUNDLE_NAME = "index.android.bundle"
+    const val KEY_INSTALLATION = "installationId"
+    const val KEY_BINARY = "binary"
+    const val KEY_CURRENT = "current"
+    const val KEY_PREVIOUS = "previous"
+    const val KEY_PENDING = "pending"
+    const val KEY_DOWNLOADED = "downloaded"
+    const val KEY_FAILED = "failed"
+    const val KEY_UNCONFIRMED = "unconfirmed"
+    const val KEY_ATTEMPTS = "attempts"
+  }
+}

package/fireota-react-native.podspec

@@ -0,0 +1,19 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "fireota-react-native"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"] || "https://www.npmjs.com/package/@fireota/react-native"
+  s.license      = package["license"]
+  s.authors      = package["author"]
+  s.platforms    = { :ios => "13.4" }
+  # Installed from node_modules by React Native autolinking; the git source is only used for trunk.
+  repo = (package["repository"].is_a?(Hash) ? package["repository"]["url"] : package["repository"]).to_s.sub(/^git\+/, "")
+  s.source       = { :git => repo, :tag => "v#{s.version}" }
+  s.source_files = "ios/**/*.{h,m}"
+  s.libraries    = "z"
+  s.dependency "React-Core"
+end

package/ios/FireOTA.h

@@ -0,0 +1,20 @@
+#import <Foundation/Foundation.h>
+#import <React/RCTBridgeModule.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * FireOTA native module. In AppDelegate (release builds):
+ *
+ *   - (NSURL *)bundleURL {
+ *     return [FireOTA bundleURL] ?: [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+ *   }
+ */
+@interface FireOTA : NSObject <RCTBridgeModule>
+
+/// The OTA bundle to load, or nil to use the bundle shipped in the app binary.
++ (nullable NSURL *)bundleURL;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/FireOTA.m

@@ -0,0 +1,346 @@
+#import "FireOTA.h"
+
+#import <CommonCrypto/CommonDigest.h>
+#import <React/RCTReloadCommand.h>
+#import <zlib.h>
+
+static NSString *const kBundleName = @"main.jsbundle";
+static NSString *const kSuite = @"dev.fireota";
+static NSString *const kInstallation = @"installationId";
+static NSString *const kBinary = @"binary";
+static NSString *const kCurrent = @"current";
+static NSString *const kPrevious = @"previous";
+static NSString *const kPending = @"pending";
+static NSString *const kDownloaded = @"downloaded";
+static NSString *const kFailed = @"failed";
+static NSString *const kUnconfirmed = @"unconfirmed";
+static NSString *const kAttempts = @"attempts";
+
+static NSUserDefaults *FOTADefaults(void) { return [[NSUserDefaults alloc] initWithSuiteName:kSuite]; }
+
+static NSString *FOTASafe(NSString *value)
+{
+  NSCharacterSet *allowed = [NSCharacterSet characterSetWithCharactersInString:
+      @"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-"];
+  return [[value componentsSeparatedByCharactersInSet:allowed.invertedSet] componentsJoinedByString:@""];
+}
+
+static NSURL *FOTARoot(void)
+{
+  NSURL *support = [[NSFileManager defaultManager] URLsForDirectory:NSApplicationSupportDirectory
+                                                          inDomains:NSUserDomainMask].firstObject;
+  NSURL *root = [support URLByAppendingPathComponent:@"fireota/releases" isDirectory:YES];
+  [[NSFileManager defaultManager] createDirectoryAtURL:root withIntermediateDirectories:YES attributes:nil error:nil];
+  [root setResourceValue:@YES forKey:NSURLIsExcludedFromBackupKey error:nil];
+  return root;
+}
+
+static NSURL *FOTAReleaseDir(NSString *releaseId)
+{
+  return [FOTARoot() URLByAppendingPathComponent:FOTASafe(releaseId) isDirectory:YES];
+}
+
+static NSURL *FOTABundleFile(NSString *releaseId)
+{
+  return [FOTAReleaseDir(releaseId) URLByAppendingPathComponent:kBundleName];
+}
+
+/// Changes on every App Store / TestFlight install, which invalidates bundles built for the old binary.
+static NSString *FOTABinaryVersion(void)
+{
+  NSDictionary *info = [NSBundle mainBundle].infoDictionary;
+  NSDictionary *attrs = [[NSFileManager defaultManager] attributesOfItemAtPath:[NSBundle mainBundle].executablePath error:nil];
+  return [NSString stringWithFormat:@"%@-%@-%.0f", info[@"CFBundleShortVersionString"] ?: @"", info[@"CFBundleVersion"] ?: @"",
+                                    [attrs.fileModificationDate timeIntervalSince1970]];
+}
+
+static BOOL FOTAExists(NSURL *url) { return [[NSFileManager defaultManager] fileExistsAtPath:url.path]; }
+
+static BOOL FOTARead(gzFile gz, void *into, unsigned length)
+{
+  unsigned done = 0;
+  while (done < length) {
+    int n = gzread(gz, (char *)into + done, length - done);
+    if (n <= 0) return NO;
+    done += (unsigned)n;
+  }
+  return YES;
+}
+
+@implementation FireOTA
+
+RCT_EXPORT_MODULE(FireOTA)
+
++ (BOOL)requiresMainQueueSetup { return NO; }
+
+/// Same launch rules as Android: a new binary clears OTA state, a pending release is promoted and
+/// must confirm, and a release reaching a second launch unconfirmed is rolled back.
++ (nullable NSURL *)bundleURL
+{
+  static NSURL *resolved = nil;
+  static BOOL didResolve = NO;
+  @synchronized(self) {
+    NSUserDefaults *d = FOTADefaults();
+    BOOL hasPending = [d stringForKey:kPending] != nil;
+    if (didResolve && !hasPending) return resolved; // once per launch, unless a reload applies an update
+
+    NSString *binary = FOTABinaryVersion();
+    if (![[d stringForKey:kBinary] isEqualToString:binary]) {
+      [[NSFileManager defaultManager] removeItemAtURL:FOTARoot() error:nil];
+      for (NSString *key in @[ kCurrent, kPrevious, kPending, kDownloaded ]) [d removeObjectForKey:key];
+      [d setBool:NO forKey:kUnconfirmed];
+      [d setInteger:0 forKey:kAttempts];
+      [d setObject:binary forKey:kBinary];
+    }
+
+    NSString *pending = [d stringForKey:kPending];
+    if (pending && FOTAExists(FOTABundleFile(pending))) {
+      NSString *current = [d stringForKey:kCurrent];
+      if (current) [d setObject:current forKey:kPrevious]; else [d removeObjectForKey:kPrevious];
+      [d setObject:pending forKey:kCurrent];
+      [d setBool:YES forKey:kUnconfirmed];
+      [d setInteger:0 forKey:kAttempts];
+    }
+    [d removeObjectForKey:kPending];
+
+    if ([d boolForKey:kUnconfirmed]) {
+      NSInteger attempts = [d integerForKey:kAttempts] + 1;
+      if (attempts >= 2) {
+        NSString *failed = [d stringForKey:kCurrent];
+        if (failed) {
+          [d setObject:failed forKey:kFailed];
+          [[NSFileManager defaultManager] removeItemAtURL:FOTAReleaseDir(failed) error:nil];
+        }
+        NSString *previous = [d stringForKey:kPrevious];
+        if (previous) [d setObject:previous forKey:kCurrent]; else [d removeObjectForKey:kCurrent];
+        [d removeObjectForKey:kPrevious];
+        [d setBool:NO forKey:kUnconfirmed];
+        [d setInteger:0 forKey:kAttempts];
+      } else {
+        [d setInteger:attempts forKey:kAttempts];
+      }
+    }
+
+    resolved = nil;
+    NSString *current = [d stringForKey:kCurrent];
+    if (current) {
+      NSURL *file = FOTABundleFile(current);
+      if (FOTAExists(file)) {
+        resolved = file;
+      } else {
+        [d removeObjectForKey:kCurrent];
+        [d setBool:NO forKey:kUnconfirmed];
+      }
+    }
+    didResolve = YES;
+    return resolved;
+  }
+}
+
+RCT_EXPORT_METHOD(getState:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  NSUserDefaults *d = FOTADefaults();
+  NSString *installation = [d stringForKey:kInstallation];
+  if (!installation) {
+    installation = [NSUUID UUID].UUIDString.lowercaseString;
+    [d setObject:installation forKey:kInstallation];
+  }
+  NSString *version = [NSBundle mainBundle].infoDictionary[@"CFBundleShortVersionString"] ?: @"";
+  resolve(@{
+    @"installationId" : installation,
+    @"nativeVersion" : version,
+    @"appVersion" : version,
+    @"currentReleaseId" : [d stringForKey:kCurrent] ?: [NSNull null],
+    @"pendingReleaseId" : [d stringForKey:kPending] ?: [NSNull null],
+    @"previousReleaseId" : [d stringForKey:kPrevious] ?: [NSNull null],
+    @"failedReleaseId" : [d stringForKey:kFailed] ?: [NSNull null],
+    @"isFirstRun" : @([d boolForKey:kUnconfirmed]),
+  });
+}
+
+RCT_EXPORT_METHOD(downloadUpdate:(NSString *)urlString
+                  sha256:(NSString *)expected
+                  releaseId:(NSString *)releaseId
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  NSURL *url = [NSURL URLWithString:urlString];
+  if (!url || ![url.scheme isEqualToString:@"https"]) {
+    reject(@"FIREOTA_DOWNLOAD", @"Updates must be downloaded over HTTPS.", nil);
+    return;
+  }
+  NSURLSessionConfiguration *config = [NSURLSessionConfiguration defaultSessionConfiguration];
+  config.timeoutIntervalForRequest = 60;
+  NSURLSession *session = [NSURLSession sessionWithConfiguration:config];
+  [[session downloadTaskWithURL:url
+              completionHandler:^(NSURL *location, NSURLResponse *response, NSError *error) {
+                NSInteger status =
+                    [response isKindOfClass:[NSHTTPURLResponse class]] ? ((NSHTTPURLResponse *)response).statusCode : 0;
+                if (error || !location || status < 200 || status > 299) {
+                  reject(@"FIREOTA_DOWNLOAD", [NSString stringWithFormat:@"Download failed (HTTP %ld).", (long)status], error);
+                  return;
+                }
+                if (![[FireOTA sha256OfFile:location] isEqualToString:expected.lowercaseString]) {
+                  reject(@"FIREOTA_CHECKSUM", @"Checksum mismatch: the update was rejected.", nil);
+                  return;
+                }
+                NSFileManager *fm = [NSFileManager defaultManager];
+                NSURL *staging =
+                    [FOTARoot() URLByAppendingPathComponent:[NSString stringWithFormat:@".%@.staging", FOTASafe(releaseId)]];
+                [fm removeItemAtURL:staging error:nil];
+                NSString *problem = [FireOTA unpack:location into:staging];
+                if (!problem && !FOTAExists([staging URLByAppendingPathComponent:kBundleName])) {
+                  problem = @"The update package has no main.jsbundle.";
+                }
+                if (problem) {
+                  [fm removeItemAtURL:staging error:nil];
+                  reject(@"FIREOTA_DOWNLOAD", problem, nil);
+                  return;
+                }
+                NSURL *target = FOTAReleaseDir(releaseId);
+                [fm removeItemAtURL:target error:nil];
+                NSError *moveError = nil;
+                if (![fm moveItemAtURL:staging toURL:target error:&moveError]) {
+                  reject(@"FIREOTA_DOWNLOAD", @"Could not store the update.", moveError);
+                  return;
+                }
+                [FOTADefaults() setObject:releaseId forKey:kDownloaded];
+                resolve(nil);
+              }] resume];
+}
+
+RCT_EXPORT_METHOD(installUpdate:(NSString *)releaseId resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  if (!FOTAExists(FOTABundleFile(releaseId))) {
+    reject(@"FIREOTA_INSTALL", @"This release has not been downloaded.", nil);
+    return;
+  }
+  NSUserDefaults *d = FOTADefaults();
+  [d setObject:releaseId forKey:kPending];
+  [d removeObjectForKey:kDownloaded];
+  resolve(nil);
+}
+
+RCT_EXPORT_METHOD(markSuccess:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  NSUserDefaults *d = FOTADefaults();
+  [d setBool:NO forKey:kUnconfirmed];
+  [d setInteger:0 forKey:kAttempts];
+  NSMutableSet *keep = [NSMutableSet set];
+  for (NSString *key in @[ kCurrent, kPrevious, kPending, kDownloaded ]) {
+    NSString *value = [d stringForKey:key];
+    if (value) [keep addObject:FOTASafe(value)];
+  }
+  NSFileManager *fm = [NSFileManager defaultManager];
+  for (NSURL *dir in [fm contentsOfDirectoryAtURL:FOTARoot() includingPropertiesForKeys:nil options:0 error:nil]) {
+    if (![keep containsObject:dir.lastPathComponent]) [fm removeItemAtURL:dir error:nil];
+  }
+  resolve(nil);
+}
+
+RCT_EXPORT_METHOD(clearPending:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  [FOTADefaults() removeObjectForKey:kPending];
+  [FOTADefaults() removeObjectForKey:kDownloaded];
+  resolve(nil);
+}
+
+RCT_EXPORT_METHOD(clearFailed:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  [FOTADefaults() removeObjectForKey:kFailed];
+  resolve(nil);
+}
+
+/// Reloads JavaScript; React Native asks AppDelegate.bundleURL again, which applies the pending release.
+RCT_EXPORT_METHOD(restartApp:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+{
+  resolve(nil);
+  dispatch_async(dispatch_get_main_queue(), ^{
+    RCTTriggerReloadCommandListeners(@"FireOTA update");
+  });
+}
+
++ (NSString *)sha256OfFile:(NSURL *)url
+{
+  NSInputStream *stream = [NSInputStream inputStreamWithURL:url];
+  [stream open];
+  CC_SHA256_CTX ctx;
+  CC_SHA256_Init(&ctx);
+  uint8_t buffer[65536];
+  NSInteger read;
+  while ((read = [stream read:buffer maxLength:sizeof(buffer)]) > 0) CC_SHA256_Update(&ctx, buffer, (CC_LONG)read);
+  [stream close];
+  unsigned char digest[CC_SHA256_DIGEST_LENGTH];
+  CC_SHA256_Final(digest, &ctx);
+  NSMutableString *hex = [NSMutableString stringWithCapacity:CC_SHA256_DIGEST_LENGTH * 2];
+  for (int i = 0; i < CC_SHA256_DIGEST_LENGTH; i++) [hex appendFormat:@"%02x", digest[i]];
+  return hex;
+}
+
+/// FireOTA package: gzip("FOTA1\n" | u32 big-endian header length | JSON {files:[{path,size}]} | bytes).
+/// Paths are validated so a package can never write outside its release directory.
++ (nullable NSString *)unpack:(NSURL *)archive into:(NSURL *)dir
+{
+  gzFile gz = gzopen(archive.fileSystemRepresentation, "rb");
+  if (!gz) return @"Could not open the update package.";
+  char magic[6];
+  uint8_t lengthBytes[4];
+  if (!FOTARead(gz, magic, 6) || memcmp(magic, "FOTA1\n", 6) != 0 || !FOTARead(gz, lengthBytes, 4)) {
+    gzclose(gz);
+    return @"Not a FireOTA package.";
+  }
+  uint32_t headerLength = ((uint32_t)lengthBytes[0] << 24) | ((uint32_t)lengthBytes[1] << 16) |
+                          ((uint32_t)lengthBytes[2] << 8) | lengthBytes[3];
+  if (headerLength == 0 || headerLength > 4 * 1024 * 1024) {
+    gzclose(gz);
+    return @"Invalid package header.";
+  }
+  NSMutableData *header = [NSMutableData dataWithLength:headerLength];
+  if (!FOTARead(gz, header.mutableBytes, headerLength)) {
+    gzclose(gz);
+    return @"Truncated update package.";
+  }
+  id json = [NSJSONSerialization JSONObjectWithData:header options:0 error:nil];
+  NSArray *files = [json isKindOfClass:[NSDictionary class]] ? json[@"files"] : nil;
+  if (![files isKindOfClass:[NSArray class]]) {
+    gzclose(gz);
+    return @"Invalid package header.";
+  }
+
+  NSString *problem = nil;
+  NSFileManager *fm = [NSFileManager defaultManager];
+  NSString *base = [dir.path stringByStandardizingPath];
+  [fm createDirectoryAtURL:dir withIntermediateDirectories:YES attributes:nil error:nil];
+  uint8_t buffer[65536];
+  for (NSDictionary *entry in files) {
+    NSString *path = entry[@"path"];
+    if (![path isKindOfClass:[NSString class]]) {
+      problem = @"Invalid package header.";
+      break;
+    }
+    NSString *out = [[base stringByAppendingPathComponent:path] stringByStandardizingPath];
+    if ([path hasPrefix:@"/"] || [path containsString:@".."] || ![out hasPrefix:[base stringByAppendingString:@"/"]]) {
+      problem = [NSString stringWithFormat:@"Unsafe path in update package: %@", path];
+      break;
+    }
+    [fm createDirectoryAtPath:[out stringByDeletingLastPathComponent] withIntermediateDirectories:YES attributes:nil error:nil];
+    [fm createFileAtPath:out contents:nil attributes:nil];
+    NSFileHandle *handle = [NSFileHandle fileHandleForWritingAtPath:out];
+    unsigned long long remaining = [entry[@"size"] unsignedLongLongValue];
+    while (remaining > 0) {
+      unsigned chunk = (unsigned)MIN((unsigned long long)sizeof(buffer), remaining);
+      if (!FOTARead(gz, buffer, chunk)) {
+        problem = @"Truncated update package.";
+        break;
+      }
+      [handle writeData:[NSData dataWithBytes:buffer length:chunk]];
+      remaining -= chunk;
+    }
+    [handle closeFile];
+    if (problem) break;
+  }
+  gzclose(gz);
+  return problem;
+}
+
+@end

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@fireota/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Over-the-air JavaScript updates for React Native apps, served from your own Firebase project by FireOTA.",
+  "license": "MIT",
+  "author": "FireOTA",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.ts",
+  "files": [
+    "src",
+    "android/build.gradle",
+    "android/src",
+    "ios",
+    "fireota-react-native.podspec",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "react-native": ">=0.73.0"
+  },
+  "dependencies": {
+    "@fireota/react-native": "file:fireota-react-native-0.1.0.tgz"
+  },
+  "keywords": [
+    "react-native",
+    "ota",
+    "over-the-air",
+    "code-push",
+    "hot-update",
+    "firebase",
+    "updates",
+    "hermes"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sujay-Dynamisch/FireOTA.git",
+    "directory": "packages/react-native"
+  },
+  "homepage": "https://github.com/Sujay-Dynamisch/FireOTA/tree/main/packages/react-native#readme",
+  "bugs": {
+    "url": "https://github.com/Sujay-Dynamisch/FireOTA/issues"
+  }
+}

package/src/index.ts

@@ -0,0 +1,265 @@
+/**
+ * FireOTA React Native SDK.
+ *
+ * Flow: check -> download (native, SHA-256 verified) -> install (pending) -> applied on the
+ * next start (or immediately for mandatory updates) -> the new bundle confirms itself on
+ * launch; a bundle that never confirms is rolled back to the previous one by the native loader.
+ */
+import { NativeModules, Platform } from "react-native";
+
+export type InstallMode = "nextRestart" | "immediate";
+export type UpdateStatus =
+  | "idle"
+  | "checking"
+  | "upToDate"
+  | "downloading"
+  | "downloaded"
+  | "installed"
+  | "error";
+
+export interface FireOTAConfig {
+  /** App ID from the FireOTA dashboard (Applications -> your app). */
+  appId: string;
+  /** Your FireOTA deployment, e.g. https://ota.example.com */
+  serverUrl: string;
+  /** Must equal the runtime version of the release; bump it whenever native code changes. */
+  runtimeVersion: string;
+  channel?: string;
+  /** Check (and download) automatically when configure() runs. Default true. */
+  checkOnAppStart?: boolean;
+  /** When a normal update is applied. Default "nextRestart". */
+  installMode?: InstallMode;
+  /** When a mandatory update is applied. Default "immediate". */
+  mandatoryInstallMode?: InstallMode;
+  onStatusChange?: (status: UpdateStatus, detail?: { releaseId?: string; error?: string }) => void;
+}
+
+export interface AvailableUpdate {
+  id: string;
+  version: string;
+  runtimeVersion: string;
+  mandatory: boolean;
+  notes: string;
+  bundle: { url: string; hash: string; size: number };
+}
+
+export interface CheckResult {
+  updateAvailable: boolean;
+  reason?: string;
+  release?: AvailableUpdate;
+}
+
+interface NativeState {
+  installationId: string;
+  nativeVersion: string;
+  appVersion: string;
+  currentReleaseId: string | null;
+  pendingReleaseId: string | null;
+  previousReleaseId: string | null;
+  /** Release rolled back by the native loader because it never confirmed a launch. */
+  failedReleaseId: string | null;
+  /** The running bundle has not confirmed a successful launch yet. */
+  isFirstRun: boolean;
+}
+
+interface FireOTANative {
+  getState(): Promise<NativeState>;
+  downloadUpdate(url: string, sha256: string, releaseId: string): Promise<void>;
+  installUpdate(releaseId: string): Promise<void>;
+  markSuccess(): Promise<void>;
+  clearPending(): Promise<void>;
+  clearFailed(): Promise<void>;
+  restartApp(): Promise<void>;
+}
+
+const native = NativeModules["FireOTA"] as FireOTANative | undefined;
+const PROTOCOL_VERSION = "1";
+
+let config: Required<Omit<FireOTAConfig, "onStatusChange">> & Pick<FireOTAConfig, "onStatusChange">;
+let status: UpdateStatus = "idle";
+let running: Promise<CheckResult> | null = null;
+
+function requireNative(): FireOTANative {
+  if (!native) {
+    throw new Error(
+      "FireOTA native module not found. Rebuild the app after installing @fireota/react-native (cd ios && pod install).",
+    );
+  }
+  return native;
+}
+
+function requireConfig() {
+  if (!config) throw new Error("Call FireOTA.configure() before using the SDK.");
+  return config;
+}
+
+function setStatus(next: UpdateStatus, detail?: { releaseId?: string; error?: string }) {
+  status = next;
+  config?.onStatusChange?.(next, detail);
+}
+
+function randomId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}
+
+async function post<T>(path: string, body: unknown): Promise<T> {
+  const response = await fetch(`${requireConfig().serverUrl.replace(/\/+$/, "")}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-fireota-sdk": `react-native/${PROTOCOL_VERSION}` },
+    body: JSON.stringify(body),
+  });
+  const json = (await response.json()) as { success: boolean; data?: T; error?: { code: string; message: string } };
+  if (!json.success) throw new Error(json.error?.message ?? `FireOTA request failed (${response.status})`);
+  return json.data as T;
+}
+
+/** Telemetry never blocks or fails an update. */
+async function report(event: string, releaseId: string, metadata?: Record<string, unknown>) {
+  try {
+    const state = await requireNative().getState();
+    await post("/api/public/v1/updates/events", {
+      app: config.appId,
+      releaseId,
+      platform: Platform.OS,
+      installationId: state.installationId,
+      runtimeVersion: config.runtimeVersion,
+      nativeVersion: state.nativeVersion,
+      appVersion: state.appVersion,
+      event,
+      eventId: `${event}:${releaseId}:${state.installationId}`,
+      ...(metadata ? { metadata } : {}),
+    });
+  } catch {
+    // ignored by design
+  }
+}
+
+/** Asks FireOTA whether a compatible release exists for this device. */
+export async function checkForUpdate(): Promise<CheckResult> {
+  const cfg = requireConfig();
+  const state = await requireNative().getState();
+  setStatus("checking");
+  const result = await post<CheckResult>("/api/public/v1/updates/check", {
+    app: cfg.appId,
+    channel: cfg.channel,
+    platform: Platform.OS,
+    installationId: state.installationId,
+    runtimeVersion: cfg.runtimeVersion,
+    nativeVersion: state.nativeVersion,
+    appVersion: state.appVersion,
+    currentReleaseId: state.pendingReleaseId ?? state.currentReleaseId,
+  });
+  // Defence in depth: never accept a release built for another runtime.
+  if (result.updateAvailable && result.release?.runtimeVersion !== cfg.runtimeVersion) {
+    return { updateAvailable: false, reason: "runtime_incompatible" };
+  }
+  if (!result.updateAvailable) setStatus("upToDate");
+  return result;
+}
+
+/** Downloads and verifies (SHA-256) an update. The running bundle is untouched. */
+export async function downloadUpdate(release: AvailableUpdate) {
+  if (!/^[0-9a-f]{64}$/i.test(release.bundle.hash)) throw new Error("The update has no valid checksum.");
+  setStatus("downloading", { releaseId: release.id });
+  void report("download_started", release.id);
+  await requireNative().downloadUpdate(release.bundle.url, release.bundle.hash.toLowerCase(), release.id);
+  void report("download_completed", release.id);
+  setStatus("downloaded", { releaseId: release.id });
+}
+
+/** Marks a downloaded update to load on the next start, or restarts now for "immediate". */
+export async function installUpdate(release: AvailableUpdate, mode: InstallMode = "nextRestart") {
+  await requireNative().installUpdate(release.id);
+  setStatus("installed", { releaseId: release.id });
+  if (mode === "immediate") await requireNative().restartApp();
+}
+
+/** Check + download + install in one call, honouring the configured install modes. */
+export function sync(): Promise<CheckResult> {
+  if (running) return running;
+  running = (async () => {
+    try {
+      const result = await checkForUpdate();
+      if (result.updateAvailable && result.release) {
+        await downloadUpdate(result.release);
+        await installUpdate(
+          result.release,
+          result.release.mandatory ? config.mandatoryInstallMode : config.installMode,
+        );
+      }
+      return result;
+    } catch (error) {
+      setStatus("error", { error: error instanceof Error ? error.message : String(error) });
+      // Never crash the host app: it keeps running the bundle it already has.
+      return { updateAvailable: false, reason: "error" };
+    } finally {
+      running = null;
+    }
+  })();
+  return running;
+}
+
+/** Restarts the app so a pending update loads now. */
+export function reload() {
+  return requireNative().restartApp();
+}
+
+/** Drops a downloaded-but-not-yet-applied update. */
+export function clearPendingUpdate() {
+  return requireNative().clearPending();
+}
+
+/** The release the app is running, or null for the bundle shipped in the binary. */
+export async function getCurrentRelease() {
+  const state = await requireNative().getState();
+  return { releaseId: state.currentReleaseId, pendingReleaseId: state.pendingReleaseId, installationId: state.installationId };
+}
+
+export function getUpdateStatus(): UpdateStatus {
+  return status;
+}
+
+/**
+ * Configures the SDK. Call once, as early as possible (e.g. index.js or the root component).
+ * Reaching this call proves the running bundle starts, so it is confirmed here; a bundle that
+ * crashes before this point is rolled back automatically on the next launch.
+ */
+export async function configure(options: FireOTAConfig) {
+  if (!options.appId || !options.serverUrl || !options.runtimeVersion) {
+    throw new Error("FireOTA.configure() needs appId, serverUrl and runtimeVersion.");
+  }
+  config = {
+    channel: "production",
+    checkOnAppStart: true,
+    installMode: "nextRestart",
+    mandatoryInstallMode: "immediate",
+    ...options,
+  };
+  const nativeModule = requireNative();
+  const state = await nativeModule.getState();
+
+  if (state.failedReleaseId) {
+    void report("rollback", state.failedReleaseId, { reason: "launch_not_confirmed" });
+    void report("install_failed", state.failedReleaseId, { reason: "launch_not_confirmed" });
+    await nativeModule.clearFailed();
+  }
+  if (state.isFirstRun && state.currentReleaseId) {
+    await nativeModule.markSuccess();
+    void report("install_succeeded", state.currentReleaseId);
+  }
+  if (config.checkOnAppStart) void sync();
+}
+
+export const FireOTA = {
+  configure,
+  checkForUpdate,
+  downloadUpdate,
+  installUpdate,
+  sync,
+  reload,
+  clearPendingUpdate,
+  getCurrentRelease,
+  getUpdateStatus,
+};
+
+export default FireOTA;