@otaupdate/react-native 1.0.0

package/README.md

@@ -0,0 +1,321 @@
+# @otaupdate/react-native
+
+Over-the-air JS bundle updates for React Native. Ships the JS + assets of a
+release to installed apps without going through the App Store or Play Store.
+
+Works in **bare React Native** and **Expo** (via a config plugin). Native code
+handles download, SHA-256 verification, unzip, bundle swap-in, and
+rollback-on-failure; JS handles the update check and the app-facing API.
+
+> **What OTA can and cannot ship.** Anything that lives in the JS bundle and its
+> assets: screens, logic, images, styles. Nothing native: a new native module, a
+> permission, an SDK version bump, or an `Info.plist` change still needs a store
+> release. Shipping a JS bundle that calls a native API the installed binary
+> doesn't have will crash the app — use `targetBinaryVersion` to keep those
+> releases apart.
+
+---
+
+## Install
+
+```bash
+npm install @otaupdate/react-native
+```
+
+### Bare React Native
+
+**iOS**
+
+```bash
+cd ios && pod install
+```
+
+Then point React Native at the OTA bundle. In `AppDelegate.swift` (RN 0.77+):
+
+```swift
+import OtaUpdate
+
+override func bundleURL() -> URL? {
+#if DEBUG
+  return RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+#else
+  return OtaUpdate.bundleURL()      // <- was Bundle.main.url(forResource: "main", …)
+#endif
+}
+```
+
+Or in `AppDelegate.mm` (RN 0.76 and earlier):
+
+```objc
+#import <OtaUpdate/OtaUpdate.h>
+
+- (NSURL *)getBundleURL {
+#if DEBUG
+  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
+#else
+  return [OtaUpdate bundleURL];     // <- was [[NSBundle mainBundle] URLForResource:…]
+#endif
+}
+```
+
+Add the configuration to `ios/<YourApp>/Info.plist`:
+
+```xml
+<key>OtaDeploymentKey</key>
+<string>YOUR_IOS_DEPLOYMENT_KEY</string>
+<key>OtaServerUrl</key>
+<string>https://ota.example.com</string>
+```
+
+**Android**
+
+Autolinking registers the module. Add the one override in
+`android/app/src/main/java/.../MainApplication.kt`:
+
+```kotlin
+import com.otaupdate.OtaUpdate
+
+override val reactNativeHost: ReactNativeHost =
+  object : DefaultReactNativeHost(this) {
+    override fun getJSMainModuleName(): String = "index"
+
+    override fun getJSBundleFile(): String? =
+      OtaUpdate.getJSBundleFile(applicationContext)   // <- add this
+    // …
+  }
+```
+
+And the configuration in `android/app/src/main/res/values/strings.xml`:
+
+```xml
+<string name="ota_deployment_key" translatable="false">YOUR_ANDROID_DEPLOYMENT_KEY</string>
+<string name="ota_server_url" translatable="false">https://ota.example.com</string>
+```
+
+### Expo
+
+Add the config plugin to `app.json`. There is nothing to patch by hand — the
+plugin writes the configuration, and the bundle swap-in is wired up
+automatically (see [how Expo differs](#how-expo-differs) below):
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@otaupdate/react-native",
+        {
+          "serverUrl": "https://ota.example.com",
+          "iosDeploymentKey": "YOUR_IOS_DEPLOYMENT_KEY",
+          "androidDeploymentKey": "YOUR_ANDROID_DEPLOYMENT_KEY"
+        }
+      ]
+    ]
+  }
+}
+```
+
+```bash
+npx expo prebuild --clean     # or just let EAS Build run it
+```
+
+> The native module does not exist in **Expo Go**. Use a development build
+> (`npx expo run:ios` / `eas build --profile development`). In Expo Go the SDK
+> logs a warning and no-ops instead of crashing.
+
+#### How Expo differs
+
+Expo apps are **bridgeless**: `MainApplication` builds a `ReactHost` straight
+from `ExpoReactHostFactory` and never exposes a `ReactNativeHost`, so there is
+no `getJSBundleFile()` to override. Instead this package registers a
+`ReactNativeHostHandler` — Expo's own extension point, the same one
+`expo-updates` uses — which Expo asks for the bundle path at startup. Expo
+autolinking discovers it; you don't wire anything up.
+
+Two consequences worth knowing:
+
+- The config plugin **does not modify `MainApplication`** on Android. If you go
+  looking for an edit there after `prebuild`, its absence is correct.
+- The handler returns `null` when developer support is on, so a debug build
+  keeps loading from Metro and a downloaded bundle never shadows your live
+  reload.
+
+This package is therefore linked by **both** linkers, and needs to be: React
+Native autolinking registers `OtaUpdatePackage` (the native module JS calls),
+while Expo autolinking registers `OtaUpdateExpoPackage` (the bundle path). Expo
+normally drops a package from React Native autolinking when it is also an Expo
+module with its own Gradle file, which would leave `NativeModules.OtaUpdate`
+undefined — the shipped `react-native.config.js` opts out of that skip. Don't
+delete it.
+
+Verified against Expo SDK 57 / React Native 0.86 with the new architecture, on both platforms.
+
+## Platform verification status
+
+**Android — verified end to end.** On an Expo SDK 57 / RN 0.86 release build
+(new architecture, bridgeless) running on an emulator: publish → download →
+SHA-256 verify → bundle swap on restart, `IMMEDIATE` in-process reload, and
+rollback rescuing a device already on the bad build. Confirmed by screenshot,
+native log, and server-side install reports.
+
+**iOS — verified end to end.** On an Expo SDK 57 / RN 0.86 Release build
+(Xcode 26, iPhone 17 Pro simulator, iOS 26.5): publish → download → SHA-256
+verify → bundle swap on restart, `IMMEDIATE` in-process reload, and rollback
+restoring the earlier bundle byte-for-byte. Confirmed by screenshot, package
+hash and server-side install reports.
+
+One library fix came out of that first real build: the podspec now sets
+`DEFINES_MODULE = YES`. React Native and Expo build pods as static libraries,
+and an Objective-C static library is not importable as a Swift module unless
+CocoaPods emits a module map — without it every Expo app with a Swift
+AppDelegate failed to compile with `no such module 'OtaUpdate'`, even though
+the pod linked correctly and the Objective-C itself was fine.
+
+
+---
+
+## Use it
+
+The one-liner — checks on app start and on every foreground, installs on next
+restart:
+
+```tsx
+import { withOtaUpdate } from '@otaupdate/react-native';
+
+function App() {
+  return <YourApp />;
+}
+
+export default withOtaUpdate(App);
+```
+
+That is enough for most apps. `withOtaUpdate` also calls `notifyAppReady()` on
+mount, which is what arms rollback protection — see below.
+
+### Manual control
+
+```ts
+import OtaUpdate, { InstallMode, SyncStatus } from '@otaupdate/react-native';
+
+const status = await OtaUpdate.sync({
+  installMode: InstallMode.ON_NEXT_RESTART,
+  mandatoryInstallMode: InstallMode.IMMEDIATE,
+  onSyncStatusChange: (s) => console.log(SyncStatus[s]),
+  onDownloadProgress: ({ receivedBytes, totalBytes }) =>
+    console.log(`${Math.round((receivedBytes / totalBytes) * 100)}%`),
+  // Ask before installing. Mandatory releases ignore this.
+  shouldInstall: (update) => confirmWithUser(update.description),
+});
+```
+
+### Update UI with the hook
+
+```tsx
+import { useOtaUpdate, SyncStatus } from '@otaupdate/react-native';
+
+function UpdateBanner() {
+  const { available, progress, isSyncing, check, update } = useOtaUpdate();
+
+  useEffect(() => { void check(); }, []);
+  if (!available) return null;
+
+  return (
+    <View>
+      <Text>Version {available.label} is available</Text>
+      {available.description ? <Text>{available.description}</Text> : null}
+      {progress ? (
+        <Text>{Math.round((progress.receivedBytes / progress.totalBytes) * 100)}%</Text>
+      ) : null}
+      <Button title="Update" onPress={() => update()} disabled={isSyncing} />
+    </View>
+  );
+}
+```
+
+---
+
+## Rollback protection — the part not to skip
+
+An update that crashes on boot would be unrecoverable without this, so the SDK
+treats every freshly installed bundle as unproven:
+
+1. `install()` marks the package **pending**.
+2. The next launch boots into it and flags it as *loading*.
+3. `notifyAppReady()` **confirms** it. From then on it is permanent.
+4. If the app launches again while the package is still *loading* — i.e. the
+   last run never reached `notifyAppReady()` — the native side reverts to the
+   previous bundle, blacklists the bad hash, and reports `rolled_back` to the
+   server so it shows up in the dashboard.
+
+`withOtaUpdate` and `startAutoSync` call `notifyAppReady()` for you. If you wire
+things up yourself, **you must call it**, after your critical startup path:
+
+```ts
+import { notifyAppReady } from '@otaupdate/react-native';
+
+useEffect(() => {
+  void notifyAppReady();
+}, []);
+```
+
+Call it too early and a crash a second later still counts as healthy; call it
+too late (or never) and every update rolls itself back.
+
+---
+
+## Install modes
+
+| Mode | When the new bundle loads |
+|---|---|
+| `ON_NEXT_RESTART` *(default)* | The next time the user cold-starts the app. Never interrupts. |
+| `ON_NEXT_RESUME` | The next foreground, after `minimumBackgroundDuration` seconds in the background. |
+| `IMMEDIATE` | Right away, with a JS reload. Reserved for mandatory fixes — it interrupts whatever the user was doing. |
+
+---
+
+## API
+
+| Export | Purpose |
+|---|---|
+| `sync(options)` | Check → download → install. Concurrent calls share one run. |
+| `checkForUpdate()` | Just the check. Returns `{ update, reason }`. |
+| `notifyAppReady()` | Confirm the running bundle (see rollback above). |
+| `restartApp(onlyIfPending?)` | Reload the JS bundle. |
+| `getCurrentPackage()` | Running label, hash, pending/first-run flags. |
+| `clearUpdates()` | Wipe all downloads, revert to the binary bundle. |
+| `startAutoSync(options)` | The app-start/resume loop `withOtaUpdate` uses. |
+| `withOtaUpdate(App, options)` | Root-component HOC. |
+| `useOtaUpdate(options)` | Hook for update UI. |
+| `isNativeModuleAvailable` | `false` in Expo Go and on web. |
+
+`checkForUpdate()` returns a `reason` when there is no update — `up_to_date`,
+`not_in_rollout`, `no_matching_binary_version`, or `update_app_version` (a
+release exists but needs a newer native binary, i.e. prompt for a store update).
+
+---
+
+## Publishing
+
+From the project root, with the [CLI](../cli/README.md):
+
+```bash
+ota release-react MyApp-iOS 1.4.0 --platform ios -d Production -r 20
+```
+
+`targetBinaryVersion` (`1.4.0` above) is the native app version the bundle is
+compatible with. Devices on other binary versions never receive it.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `The native module … is not available` | Native rebuild missing (`pod install` / Gradle), or running in Expo Go. A Metro reload is not enough. |
+| Update downloads but never applies (bare RN) | `getJSBundleFile` / `bundleURL` override missing — the app keeps loading the bundle from the binary. |
+| Update downloads but never applies (Expo) | The `ReactNativeHostHandler` was not autolinked. Re-run `npx expo prebuild --clean`; check `android/app/build/generated/autolinking` mentions `OtaUpdateExpoPackage`. |
+| Download fails while the check succeeds | The presigned URL points at a host the device can't reach. Set `S3_PUBLIC_ENDPOINT` (and `PUBLIC_API_URL`) to a LAN IP or public hostname, not `localhost`. |
+| `CLEARTEXT communication not permitted` | Android blocks plain HTTP from API 28. Use HTTPS, or `usesCleartextTraffic` for local testing only. |
+| Every update rolls back | `notifyAppReady()` is never reached — usually an early crash, or the call sits behind a screen the user has to navigate to. |
+| `no_matching_binary_version` | The release's `targetBinaryVersion` does not cover the installed native version. |
+| Works in debug, not release | Debug builds load from Metro; the OTA path only runs in release builds. |

package/android/build.gradle

@@ -0,0 +1,70 @@
+buildscript {
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+    classpath("com.android.tools.build:gradle:8.6.0")
+    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${safeExtGet('kotlinVersion', '1.9.24')}")
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+
+// Expo apps are bridgeless and have no ReactNativeHost to override, so the
+// bundle path is supplied through Expo's ReactNativeHostHandler instead (see
+// src/expo/java). That source set is only compiled when Expo is actually
+// present — bare React Native projects have no expo-modules-core to link
+// against and use the getJSBundleFile() override on ReactNativeHost.
+def expoModulesCore = findProject(':expo-modules-core')
+def isExpoProject = expoModulesCore != null
+
+android {
+  namespace "com.otaupdate"
+  compileSdkVersion safeExtGet('compileSdkVersion', 34)
+
+  sourceSets {
+    main {
+      if (isExpoProject) {
+        java.srcDirs += 'src/expo/java'
+      }
+    }
+  }
+
+  defaultConfig {
+    minSdkVersion safeExtGet('minSdkVersion', 23)
+    targetSdkVersion safeExtGet('targetSdkVersion', 34)
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+
+  lintOptions {
+    abortOnError false
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:${safeExtGet('kotlinVersion', '1.9.24')}"
+
+  // compileOnly: the host app already ships expo-modules-core at runtime.
+  if (isExpoProject) {
+    compileOnly project(':expo-modules-core')
+  }
+}

package/android/src/expo/java/com/otaupdate/OtaUpdateExpoPackage.kt

@@ -0,0 +1,37 @@
+package com.otaupdate
+
+import android.content.Context
+import expo.modules.core.interfaces.Package
+import expo.modules.core.interfaces.ReactNativeHostHandler
+
+/**
+ * Expo integration.
+ *
+ * Modern Expo apps are bridgeless: `MainApplication` builds a `ReactHost`
+ * straight from `ExpoReactHostFactory` and there is no `ReactNativeHost` whose
+ * `getJSBundleFile()` we could override. Expo's supported extension point for
+ * exactly this is `ReactNativeHostHandler` — the same one `expo-updates` uses —
+ * so we register one instead of rewriting the app's `MainApplication`.
+ *
+ * That also means the config plugin does not have to patch Kotlin source, which
+ * is what broke against the RN 0.86 template.
+ *
+ * Discovery: Expo autolinking scans a module's Android sources for files named
+ * `*Package.kt` that import `expo.modules.core.interfaces.Package`. This file
+ * only compiles when `:expo-modules-core` is on the classpath — see the
+ * conditional source set in `android/build.gradle`, which keeps bare React
+ * Native builds (no Expo) working.
+ */
+class OtaUpdateExpoPackage : Package {
+  override fun createReactNativeHostHandlers(context: Context): List<ReactNativeHostHandler> =
+    listOf(
+      object : ReactNativeHostHandler {
+        override fun getJSBundleFile(useDeveloperSupport: Boolean): String? {
+          // Debug builds load from Metro. Handing back a downloaded bundle
+          // there would silently replace the developer's live-reloading code.
+          if (useDeveloperSupport) return null
+          return OtaUpdate.getJSBundleFile(context)
+        }
+      },
+    )
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

package/android/src/main/java/com/otaupdate/OtaUpdate.kt

@@ -0,0 +1,98 @@
+package com.otaupdate
+
+import android.content.Context
+import android.content.pm.PackageManager
+import android.util.Log
+
+/**
+ * Entry point used by the host app's `MainApplication`.
+ *
+ * In `ReactNativeHost`:
+ *
+ *   override fun getJSBundleFile(): String? = OtaUpdate.getJSBundleFile(applicationContext)
+ *
+ * That single override is what makes updates take effect: React Native asks
+ * for the bundle path at start-up, and we hand back the most recent healthy
+ * downloaded bundle (or null, meaning "use the one in the APK").
+ */
+object OtaUpdate {
+
+  private const val DEFAULT_ASSET_BUNDLE = "index.android.bundle"
+  private const val META_DEPLOYMENT_KEY = "com.otaupdate.DEPLOYMENT_KEY"
+  private const val META_SERVER_URL = "com.otaupdate.SERVER_URL"
+
+  @Volatile private var store: OtaUpdateStore? = null
+  @Volatile private var initialized = false
+
+  @JvmStatic
+  @Synchronized
+  fun store(context: Context): OtaUpdateStore =
+    store ?: OtaUpdateStore(context.applicationContext).also { store = it }
+
+  /**
+   * Resolves the JS bundle for this launch and advances the rollback state
+   * machine. Safe to call more than once; only the first call has effects.
+   */
+  @JvmStatic
+  fun getJSBundleFile(context: Context): String? = getJSBundleFile(context, DEFAULT_ASSET_BUNDLE)
+
+  @JvmStatic
+  @Synchronized
+  fun getJSBundleFile(context: Context, assetsBundleName: String): String? {
+    return try {
+      val s = store(context)
+      if (!initialized) {
+        initialized = true
+        s.initializeAfterRestart()
+      } else {
+        // Resolved again without a new process: an in-process reload from an
+        // IMMEDIATE or ON_NEXT_RESUME install. Promote the pending package,
+        // but do not let it look like a boot that failed to confirm.
+        s.promotePendingIfAny()
+      }
+      // null tells React Native to load `assets://index.android.bundle`.
+      s.currentBundlePath()
+    } catch (e: Exception) {
+      // Never let OTA state break app start-up.
+      Log.e(OtaUpdateStore.TAG, "failed to resolve OTA bundle; using the binary bundle", e)
+      null
+    }
+  }
+
+  // --- Build-time configuration --------------------------------------------
+
+  @JvmStatic
+  fun deploymentKey(context: Context): String =
+    stringResource(context, "ota_deployment_key")
+      ?: metaData(context, META_DEPLOYMENT_KEY)
+      ?: ""
+
+  @JvmStatic
+  fun serverUrl(context: Context): String =
+    stringResource(context, "ota_server_url") ?: metaData(context, META_SERVER_URL) ?: ""
+
+  @JvmStatic
+  fun appVersion(context: Context): String =
+    try {
+      context.packageManager.getPackageInfo(context.packageName, 0).versionName ?: "0.0.0"
+    } catch (e: PackageManager.NameNotFoundException) {
+      "0.0.0"
+    }
+
+  private fun stringResource(context: Context, name: String): String? {
+    val id = context.resources.getIdentifier(name, "string", context.packageName)
+    if (id == 0) return null
+    return context.getString(id).takeIf { it.isNotBlank() }
+  }
+
+  private fun metaData(context: Context, key: String): String? =
+    try {
+      val info = context.packageManager.getApplicationInfo(
+        context.packageName,
+        PackageManager.GET_META_DATA,
+      )
+      info.metaData?.getString(key)?.takeIf { it.isNotBlank() }
+    } catch (e: Exception) {
+      null
+    }
+}