ubriot-updates-rn 0.1.0

package/README.md

@@ -0,0 +1,173 @@
+# @ubriot/updates-rn
+
+Over-the-air (OTA) JavaScript update client for **bare React Native** apps (no Expo),
+built on top of the existing Ubriot update backend. It lets a shipped app download a
+newer JS bundle in the background, swap it in on the next launch, and automatically roll
+back to the last known good bundle if a new one fails to boot.
+
+It reuses the Ubriot update service that already powers the Expo clients. You publish
+updates the same way, with the Ubriot CLI `update` command. This package is only the
+native + JS runtime that consumes those updates in a bare app.
+
+## What it does
+
+- Talks to the existing `GET /ubriot/updates/manifest` endpoint (Expo-Updates-style
+  manifest contract, including the `expo-runtime-version`, `expo-channel-name`, and
+  `expo-current-update-id` request headers).
+- Downloads the manifest's `launchAsset` bundle to app storage (iOS
+  `Library/ubriot-updates/`, Android `filesDir/ubriot-updates/`).
+- Persists which bundle is `pending`, `active`, `verified`, and `lastKnownGood` in a
+  small `state.json` next to the bundles.
+- Boots the verified/active downloaded bundle instead of the embedded one, with
+  crash-rollback safety.
+- Never blocks or crashes app start: every network and file operation is wrapped, and a
+  failed OTA quietly falls back to the embedded bundle.
+
+## Install
+
+Add it as a dependency (workspace or file path), then rebuild the native app.
+
+```jsonc
+// package.json
+"dependencies": {
+  "@ubriot/updates-rn": "*"
+}
+```
+
+The native module autolinks (CocoaPods on iOS, `autolinkLibrariesWithApp()` /
+gradle on Android). Run `pod install` in `ios/` and rebuild.
+
+## JS API
+
+```ts
+import * as UbriotUpdates from "@ubriot/updates-rn";
+
+UbriotUpdates.configure({
+  apiBase: "https://api.ubriot.dev/api/v1",
+  appSlug: "your-app-slug",
+  channel: "production",
+  runtimeVersion: "your-app-1.0.0",
+});
+
+// Convenience: check -> download -> apply (does not restart by default)
+const result = await UbriotUpdates.sync(); // 'up-to-date' | 'updated'
+
+// Or drive each step:
+const { available, manifestId } = await UbriotUpdates.checkForUpdate();
+const { ready } = await UbriotUpdates.downloadUpdate();
+await UbriotUpdates.applyUpdate({ restart: true }); // reload JS now
+
+// Call once the app has rendered and run OK. Promotes the active bundle to
+// "verified" so it becomes the rollback target instead of being rolled back.
+UbriotUpdates.markLaunchSuccessful();
+```
+
+Recommended app-start pattern:
+
+```ts
+useEffect(() => {
+  UbriotUpdates.configure({ /* ... */ });
+  UbriotUpdates.sync().catch(() => {});
+  const t = setTimeout(() => UbriotUpdates.markLaunchSuccessful(), 4000);
+  return () => clearTimeout(t);
+}, []);
+```
+
+`sync()` downloads and stages the update; it applies on the next launch. Use
+`applyUpdate({ restart: true })` if you want to reload immediately.
+
+## Rollback model
+
+- A freshly applied bundle is `active` but unverified.
+- On the first launch of an unverified active bundle, a launch counter is incremented and
+  persisted **before** JS runs.
+- If the app boots that bundle again while still unverified (meaning the previous launch
+  never reached `markLaunchSuccessful()`, e.g. it crashed on load), the client reverts to
+  the last known good bundle (or the embedded bundle) instead.
+- `markLaunchSuccessful()` marks the active bundle verified and records it as the new last
+  known good.
+
+## Native integration
+
+Autolinking registers the native module. You only need to point the app at the resolved
+bundle so downloaded updates actually load.
+
+### iOS (`AppDelegate`)
+
+Use the embedded bundle in DEBUG (Metro) and the OTA-resolved bundle in RELEASE.
+
+Objective-C:
+
+```objc
+#import <UbriotUpdatesRn/UbriotUpdates.h>
+
+- (NSURL *)bundleURL {
+#if DEBUG
+  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
+#else
+  return [UbriotUpdates bundleURL];
+#endif
+}
+```
+
+Swift (add a bridging header that imports `<UbriotUpdatesRn/UbriotUpdates.h>`):
+
+```swift
+override func bundleURL() -> URL? {
+#if DEBUG
+  RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+#else
+  UbriotUpdates.bundleURL()
+#endif
+}
+```
+
+`+ [UbriotUpdates bundleURL]` returns the verified/active downloaded bundle when present
+and valid (applying rollback), otherwise the embedded `main.jsbundle`.
+
+### Android (`MainApplication`)
+
+Pass the resolved bundle path to `getDefaultReactHost` (new architecture) or return it
+from `ReactNativeHost.getJSBundleFile()` (classic). Return `null` to fall back to the
+embedded asset bundle.
+
+```kotlin
+import dev.ubriot.updates.UbriotUpdatesModule
+
+override val reactHost: ReactHost by lazy {
+  getDefaultReactHost(
+    context = applicationContext,
+    packageList = PackageList(this).packages,
+    jsBundleFilePath =
+      if (BuildConfig.DEBUG) null
+      else UbriotUpdatesModule.resolveBundleFilePath(applicationContext),
+  )
+}
+```
+
+`resolveBundleFilePath(context)` applies the same rollback logic as iOS and returns the
+bundle file path or `null`.
+
+## Publishing an update
+
+Publishing uses the existing Ubriot CLI, unchanged:
+
+```bash
+UBRIOT_API_BASE=https://api.ubriot.dev/api/v1 \
+  node ../cli/dist/index.js update \
+  --app your-app-slug \
+  --channel production \
+  --runtime-version your-app-1.0.0 \
+  --public-url https://api.ubriot.dev/api/v1 \
+  --message "what changed"
+```
+
+The `runtimeVersion` you pass here MUST match the `runtimeVersion` passed to
+`configure()`. Only JS-only changes can ship over the air; anything touching native code
+requires a new store/TestFlight build with a bumped runtime version.
+
+## Signature verification
+
+Manifest signature verification is stubbed (`verifyManifestSignature` currently returns
+`true`) and structured as a single async gate in `checkForUpdate`, ready to enforce a
+signed-manifest policy later.

package/UbriotUpdatesRn.podspec

@@ -0,0 +1,19 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "UbriotUpdatesRn"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://ubriot.dev"
+  s.license      = { :type => "MIT" }
+  s.authors      = { "Ubriot" => "team@ubriot.dev" }
+  s.platforms    = { :ios => "15.1" }
+  s.source       = { :git => "https://github.com/ubriot/ubriot.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm}"
+  s.requires_arc = true
+
+  s.dependency "React-Core"
+end

package/android/build.gradle

@@ -0,0 +1,39 @@
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "dev.ubriot.updates"
+  compileSdk safeExtGet("compileSdkVersion", 36)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)
+    targetSdkVersion safeExtGet("targetSdkVersion", 36)
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib"
+}

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/dev/ubriot/updates/UbriotUpdatesModule.kt

@@ -0,0 +1,268 @@
+package dev.ubriot.updates
+
+import android.content.Context
+import com.facebook.react.ReactApplication
+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 com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.bridge.WritableMap
+import org.json.JSONObject
+import java.io.File
+import java.net.HttpURLConnection
+import java.net.URL
+
+data class UbriotUpdateEntry(val id: String, val bundlePath: String)
+
+class UbriotUpdateState(
+  var runningId: String? = null,
+  var active: UbriotUpdateEntry? = null,
+  var verified: Boolean = false,
+  var pending: UbriotUpdateEntry? = null,
+  var lastKnownGood: UbriotUpdateEntry? = null,
+  var launchCount: Int = 0,
+)
+
+class UbriotUpdatesModule(
+  private val reactContext: ReactApplicationContext,
+) : ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName(): String = "UbriotUpdates"
+
+  private fun filesDir(): File = reactContext.applicationContext.filesDir
+
+  @ReactMethod
+  fun getState(promise: Promise) {
+    try {
+      promise.resolve(stateToWritableMap(readState(filesDir())))
+    } catch (error: Throwable) {
+      promise.reject("ubriot_updates_state_failed", error)
+    }
+  }
+
+  @ReactMethod
+  fun downloadBundle(url: String, manifestId: String, promise: Promise) {
+    Thread {
+      var connection: HttpURLConnection? = null
+      try {
+        if (url.isEmpty() || manifestId.isEmpty()) {
+          promise.reject("ubriot_updates_bad_args", "url and manifestId are required")
+          return@Thread
+        }
+        val directory = updatesDir(filesDir())
+        if (!directory.exists()) directory.mkdirs()
+        val destination = File(directory, "${sanitize(manifestId)}.jsbundle")
+
+        connection = (URL(url).openConnection() as HttpURLConnection).apply {
+          instanceFollowRedirects = true
+          connectTimeout = 30000
+          readTimeout = 60000
+          requestMethod = "GET"
+        }
+        val status = connection.responseCode
+        if (status < 200 || status >= 400) {
+          promise.reject("ubriot_updates_download_failed", "Update download HTTP $status")
+          return@Thread
+        }
+        connection.inputStream.use { input ->
+          destination.outputStream().use { output -> input.copyTo(output) }
+        }
+        if (!destination.exists() || destination.length() == 0L) {
+          promise.reject("ubriot_updates_download_failed", "Empty update payload")
+          return@Thread
+        }
+        val state = readState(filesDir())
+        state.pending = UbriotUpdateEntry(manifestId, destination.absolutePath)
+        writeState(filesDir(), state)
+
+        val result = Arguments.createMap()
+        result.putBoolean("ready", true)
+        result.putString("bundlePath", destination.absolutePath)
+        promise.resolve(result)
+      } catch (error: Throwable) {
+        promise.reject("ubriot_updates_download_failed", error)
+      } finally {
+        connection?.disconnect()
+      }
+    }.start()
+  }
+
+  @ReactMethod
+  fun applyPending(promise: Promise) {
+    try {
+      val state = readState(filesDir())
+      val pending = state.pending
+      if (pending != null) {
+        state.active = pending
+        state.verified = false
+        state.launchCount = 0
+        state.pending = null
+        writeState(filesDir(), state)
+      }
+      promise.resolve(null)
+    } catch (error: Throwable) {
+      promise.reject("ubriot_updates_apply_failed", error)
+    }
+  }
+
+  @ReactMethod
+  fun markLaunchSuccessful(promise: Promise) {
+    try {
+      val state = readState(filesDir())
+      val active = state.active
+      if (active != null && !state.verified) {
+        state.verified = true
+        state.lastKnownGood = active
+        state.launchCount = 0
+        writeState(filesDir(), state)
+      }
+      promise.resolve(null)
+    } catch (error: Throwable) {
+      promise.reject("ubriot_updates_mark_failed", error)
+    }
+  }
+
+  @ReactMethod
+  fun reload(promise: Promise) {
+    try {
+      val application = reactContext.applicationContext
+      UiThreadUtil.runOnUiThread {
+        try {
+          if (application is ReactApplication) {
+            application.reactHost.reload("Ubriot OTA update")
+          }
+        } catch (_: Throwable) {
+        }
+      }
+      promise.resolve(null)
+    } catch (error: Throwable) {
+      promise.reject("ubriot_updates_reload_failed", error)
+    }
+  }
+
+  private fun stateToWritableMap(state: UbriotUpdateState): WritableMap {
+    val map = Arguments.createMap()
+    map.putString("runningId", state.runningId)
+    map.putMap("active", entryToWritableMap(state.active))
+    map.putBoolean("verified", state.verified)
+    map.putMap("pending", entryToWritableMap(state.pending))
+    map.putMap("lastKnownGood", entryToWritableMap(state.lastKnownGood))
+    map.putInt("launchCount", state.launchCount)
+    return map
+  }
+
+  private fun entryToWritableMap(entry: UbriotUpdateEntry?): WritableMap? {
+    if (entry == null) return null
+    val map = Arguments.createMap()
+    map.putString("id", entry.id)
+    map.putString("bundlePath", entry.bundlePath)
+    return map
+  }
+
+  companion object {
+    private const val DIR_NAME = "ubriot-updates"
+    private const val STATE_FILE = "state.json"
+
+    private fun updatesDir(filesDir: File): File = File(filesDir, DIR_NAME)
+
+    private fun stateFile(filesDir: File): File = File(updatesDir(filesDir), STATE_FILE)
+
+    private fun sanitize(value: String): String {
+      val cleaned = value.replace(Regex("[^A-Za-z0-9._-]"), "-")
+      return if (cleaned.isEmpty()) "update" else cleaned
+    }
+
+    private fun entryFromJson(obj: JSONObject?): UbriotUpdateEntry? {
+      if (obj == null) return null
+      val id = obj.optString("id", "")
+      val path = obj.optString("bundlePath", "")
+      if (id.isEmpty() || path.isEmpty()) return null
+      return UbriotUpdateEntry(id, path)
+    }
+
+    private fun entryToJson(entry: UbriotUpdateEntry?): Any {
+      if (entry == null) return JSONObject.NULL
+      return JSONObject().put("id", entry.id).put("bundlePath", entry.bundlePath)
+    }
+
+    @Synchronized
+    fun readState(filesDir: File): UbriotUpdateState {
+      return try {
+        val file = stateFile(filesDir)
+        if (!file.exists()) return UbriotUpdateState()
+        val json = JSONObject(file.readText())
+        UbriotUpdateState(
+          runningId = json.optString("runningId", "").ifEmpty { null },
+          active = entryFromJson(json.optJSONObject("active")),
+          verified = json.optBoolean("verified", false),
+          pending = entryFromJson(json.optJSONObject("pending")),
+          lastKnownGood = entryFromJson(json.optJSONObject("lastKnownGood")),
+          launchCount = json.optInt("launchCount", 0),
+        )
+      } catch (_: Throwable) {
+        UbriotUpdateState()
+      }
+    }
+
+    @Synchronized
+    fun writeState(filesDir: File, state: UbriotUpdateState) {
+      try {
+        val directory = updatesDir(filesDir)
+        if (!directory.exists()) directory.mkdirs()
+        val json = JSONObject()
+          .put("runningId", state.runningId ?: JSONObject.NULL)
+          .put("active", entryToJson(state.active))
+          .put("verified", state.verified)
+          .put("pending", entryToJson(state.pending))
+          .put("lastKnownGood", entryToJson(state.lastKnownGood))
+          .put("launchCount", state.launchCount)
+        stateFile(filesDir).writeText(json.toString())
+      } catch (_: Throwable) {
+      }
+    }
+
+    @JvmStatic
+    fun resolveBundleFilePath(context: Context): String? {
+      return try {
+        val filesDir = context.filesDir
+        val state = readState(filesDir)
+        val active = state.active
+        if (active != null && File(active.bundlePath).exists()) {
+          if (state.verified) {
+            state.runningId = active.id
+            writeState(filesDir, state)
+            return active.bundlePath
+          }
+          if (state.launchCount < 1) {
+            state.launchCount = 1
+            state.runningId = active.id
+            writeState(filesDir, state)
+            return active.bundlePath
+          }
+          state.active = null
+          state.verified = false
+          state.launchCount = 0
+        } else if (active != null) {
+          state.active = null
+          state.verified = false
+          state.launchCount = 0
+        }
+
+        val lastKnownGood = state.lastKnownGood
+        if (lastKnownGood != null && File(lastKnownGood.bundlePath).exists()) {
+          state.runningId = lastKnownGood.id
+          writeState(filesDir, state)
+          return lastKnownGood.bundlePath
+        }
+
+        state.runningId = null
+        writeState(filesDir, state)
+        null
+      } catch (_: Throwable) {
+        null
+      }
+    }
+  }
+}

package/android/src/main/java/dev/ubriot/updates/UbriotUpdatesPackage.kt

@@ -0,0 +1,13 @@
+package dev.ubriot.updates
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class UbriotUpdatesPackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
+    listOf(UbriotUpdatesModule(reactContext))
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> = emptyList()
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export type UbriotUpdatesConfig = {
+    apiBase: string;
+    appSlug: string;
+    channel: string;
+    runtimeVersion: string;
+};
+export type UpdateCheckResult = {
+    available: boolean;
+    manifestId?: string;
+};
+export type DownloadResult = {
+    ready: boolean;
+};
+export type ApplyOptions = {
+    restart?: boolean;
+};
+export type SyncResult = "up-to-date" | "updated";
+export declare function configure(next: UbriotUpdatesConfig): void;
+export declare function checkForUpdate(): Promise<UpdateCheckResult>;
+export declare function downloadUpdate(): Promise<DownloadResult>;
+export declare function applyUpdate(options?: ApplyOptions): Promise<void>;
+export declare function sync(): Promise<SyncResult>;
+export declare function markLaunchSuccessful(): void;

package/dist/index.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure = configure;
+exports.checkForUpdate = checkForUpdate;
+exports.downloadUpdate = downloadUpdate;
+exports.applyUpdate = applyUpdate;
+exports.sync = sync;
+exports.markLaunchSuccessful = markLaunchSuccessful;
+const react_native_1 = require("react-native");
+const MANIFEST_PATH = "/ubriot/updates/manifest";
+let config = null;
+let stagedManifest = null;
+function getNativeModule() {
+    const native = react_native_1.NativeModules.UbriotUpdates;
+    if (!native || typeof native.getState !== "function") {
+        throw new Error("UbriotUpdates native module is not installed. Rebuild the app after adding @ubriot/updates-rn.");
+    }
+    return native;
+}
+function requireConfig() {
+    if (!config) {
+        throw new Error("Ubriot updates: call configure() before using the update client.");
+    }
+    return config;
+}
+function currentPlatform() {
+    return react_native_1.Platform.OS === "android" ? "android" : "ios";
+}
+function normalizeBase(apiBase) {
+    return apiBase.replace(/\/+$/, "");
+}
+async function verifyManifestSignature(_manifest) {
+    return true;
+}
+function configure(next) {
+    config = {
+        apiBase: normalizeBase(next.apiBase),
+        appSlug: next.appSlug,
+        channel: next.channel,
+        runtimeVersion: next.runtimeVersion,
+    };
+}
+async function checkForUpdate() {
+    var _a, _b, _c, _d;
+    const cfg = requireConfig();
+    const native = getNativeModule();
+    let runningId = null;
+    let pendingId = null;
+    try {
+        const state = await native.getState();
+        runningId = (_a = state === null || state === void 0 ? void 0 : state.runningId) !== null && _a !== void 0 ? _a : null;
+        pendingId = (_c = (_b = state === null || state === void 0 ? void 0 : state.pending) === null || _b === void 0 ? void 0 : _b.id) !== null && _c !== void 0 ? _c : null;
+    }
+    catch {
+        runningId = null;
+        pendingId = null;
+    }
+    const platform = currentPlatform();
+    const query = new URLSearchParams({
+        appId: cfg.appSlug,
+        channel: cfg.channel,
+        platform,
+        runtimeVersion: cfg.runtimeVersion,
+    });
+    const url = `${cfg.apiBase}${MANIFEST_PATH}?${query.toString()}`;
+    const headers = {
+        accept: "application/expo+json",
+        "expo-platform": platform,
+        "expo-runtime-version": cfg.runtimeVersion,
+        "expo-channel-name": cfg.channel,
+        "expo-protocol-version": "1",
+    };
+    if (runningId) {
+        headers["expo-current-update-id"] = runningId;
+    }
+    const response = await fetch(url, { method: "GET", headers });
+    if (response.status === 204 || response.status === 304) {
+        stagedManifest = null;
+        return { available: false };
+    }
+    if (!response.ok) {
+        stagedManifest = null;
+        return { available: false };
+    }
+    const manifest = (await response.json().catch(() => null));
+    const manifestId = manifest === null || manifest === void 0 ? void 0 : manifest.id;
+    const launchAssetUrl = (_d = manifest === null || manifest === void 0 ? void 0 : manifest.launchAsset) === null || _d === void 0 ? void 0 : _d.url;
+    if (!manifest || !manifestId || !launchAssetUrl) {
+        stagedManifest = null;
+        return { available: false };
+    }
+    if (manifestId === runningId || manifestId === pendingId) {
+        stagedManifest = null;
+        return { available: false };
+    }
+    const trusted = await verifyManifestSignature(manifest);
+    if (!trusted) {
+        stagedManifest = null;
+        return { available: false };
+    }
+    stagedManifest = { id: manifestId, launchAssetUrl };
+    return { available: true, manifestId };
+}
+async function downloadUpdate() {
+    requireConfig();
+    const native = getNativeModule();
+    if (!stagedManifest) {
+        const check = await checkForUpdate();
+        if (!check.available) {
+            return { ready: false };
+        }
+    }
+    if (!stagedManifest) {
+        return { ready: false };
+    }
+    try {
+        const result = await native.downloadBundle(stagedManifest.launchAssetUrl, stagedManifest.id);
+        return { ready: !!(result === null || result === void 0 ? void 0 : result.ready) };
+    }
+    catch {
+        return { ready: false };
+    }
+}
+async function applyUpdate(options = {}) {
+    const native = getNativeModule();
+    await native.applyPending();
+    if (options.restart) {
+        try {
+            await native.reload();
+        }
+        catch {
+            // reload is best-effort; the update still applies on the next launch
+        }
+    }
+}
+async function sync() {
+    const check = await checkForUpdate();
+    if (!check.available) {
+        return "up-to-date";
+    }
+    const download = await downloadUpdate();
+    if (!download.ready) {
+        return "up-to-date";
+    }
+    await applyUpdate({ restart: false });
+    return "updated";
+}
+function markLaunchSuccessful() {
+    try {
+        const native = react_native_1.NativeModules.UbriotUpdates;
+        if (native && typeof native.markLaunchSuccessful === "function") {
+            native.markLaunchSuccessful().catch(() => { });
+        }
+    }
+    catch {
+        // never allow launch bookkeeping to crash the host app
+    }
+}

package/ios/UbriotUpdates.h

@@ -0,0 +1,7 @@
+#import <React/RCTBridgeModule.h>
+
+@interface UbriotUpdates : NSObject <RCTBridgeModule>
+
++ (NSURL *)bundleURL;
+
+@end

package/ios/UbriotUpdates.m

@@ -0,0 +1,228 @@
+#import "UbriotUpdates.h"
+#import <React/RCTReloadCommand.h>
+
+@implementation UbriotUpdates
+
+RCT_EXPORT_MODULE();
+
++ (BOOL)requiresMainQueueSetup {
+  return NO;
+}
+
+#pragma mark - Storage helpers
+
++ (NSString *)updatesDirectory {
+  NSString *library = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES).firstObject;
+  return [library stringByAppendingPathComponent:@"ubriot-updates"];
+}
+
++ (NSString *)stateFilePath {
+  return [[self updatesDirectory] stringByAppendingPathComponent:@"state.json"];
+}
+
++ (void)ensureDirectory {
+  NSFileManager *manager = [NSFileManager defaultManager];
+  NSString *directory = [self updatesDirectory];
+  if (![manager fileExistsAtPath:directory]) {
+    [manager createDirectoryAtPath:directory withIntermediateDirectories:YES attributes:nil error:nil];
+  }
+}
+
++ (NSMutableDictionary *)defaultState {
+  return [@{
+    @"runningId": [NSNull null],
+    @"active": [NSNull null],
+    @"verified": @NO,
+    @"pending": [NSNull null],
+    @"lastKnownGood": [NSNull null],
+    @"launchCount": @0,
+  } mutableCopy];
+}
+
++ (NSMutableDictionary *)readState {
+  NSData *data = [NSData dataWithContentsOfFile:[self stateFilePath]];
+  if (!data) {
+    return [self defaultState];
+  }
+  id parsed = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
+  if (![parsed isKindOfClass:[NSDictionary class]]) {
+    return [self defaultState];
+  }
+  NSMutableDictionary *state = [self defaultState];
+  [state addEntriesFromDictionary:parsed];
+  return state;
+}
+
++ (void)writeState:(NSDictionary *)state {
+  [self ensureDirectory];
+  NSData *data = [NSJSONSerialization dataWithJSONObject:state options:0 error:nil];
+  if (data) {
+    [data writeToFile:[self stateFilePath] atomically:YES];
+  }
+}
+
++ (NSString *)sanitize:(NSString *)value {
+  NSCharacterSet *allowed = [NSCharacterSet characterSetWithCharactersInString:@"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._-"];
+  NSString *cleaned = [[value componentsSeparatedByCharactersInSet:allowed.invertedSet] componentsJoinedByString:@"-"];
+  return cleaned.length ? cleaned : @"update";
+}
+
++ (NSURL *)embeddedBundleURL {
+  return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+}
+
+#pragma mark - Bundle resolution with rollback
+
++ (NSURL *)bundleURL {
+  @try {
+    NSMutableDictionary *state = [self readState];
+    NSFileManager *manager = [NSFileManager defaultManager];
+    id active = state[@"active"];
+    if ([active isKindOfClass:[NSDictionary class]]) {
+      NSString *path = active[@"bundlePath"];
+      NSString *activeId = active[@"id"];
+      if (path.length && [manager fileExistsAtPath:path]) {
+        if ([state[@"verified"] boolValue]) {
+          state[@"runningId"] = activeId ?: [NSNull null];
+          [self writeState:state];
+          return [NSURL fileURLWithPath:path];
+        }
+        NSInteger launchCount = [state[@"launchCount"] integerValue];
+        if (launchCount < 1) {
+          state[@"launchCount"] = @1;
+          state[@"runningId"] = activeId ?: [NSNull null];
+          [self writeState:state];
+          return [NSURL fileURLWithPath:path];
+        }
+        state[@"active"] = [NSNull null];
+        state[@"verified"] = @NO;
+        state[@"launchCount"] = @0;
+      } else {
+        state[@"active"] = [NSNull null];
+        state[@"verified"] = @NO;
+        state[@"launchCount"] = @0;
+      }
+    }
+
+    id lastKnownGood = state[@"lastKnownGood"];
+    if ([lastKnownGood isKindOfClass:[NSDictionary class]]) {
+      NSString *path = lastKnownGood[@"bundlePath"];
+      if (path.length && [manager fileExistsAtPath:path]) {
+        state[@"runningId"] = lastKnownGood[@"id"] ?: [NSNull null];
+        [self writeState:state];
+        return [NSURL fileURLWithPath:path];
+      }
+    }
+
+    state[@"runningId"] = [NSNull null];
+    [self writeState:state];
+  } @catch (__unused NSException *exception) {
+  }
+  return [self embeddedBundleURL];
+}
+
+#pragma mark - Exported methods
+
+RCT_EXPORT_METHOD(getState:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+  @try {
+    resolve([UbriotUpdates readState]);
+  } @catch (NSException *exception) {
+    reject(@"ubriot_updates_state_failed", exception.reason, nil);
+  }
+}
+
+RCT_EXPORT_METHOD(downloadBundle:(NSString *)url
+                  manifestId:(NSString *)manifestId
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject) {
+  @try {
+    if (url.length == 0 || manifestId.length == 0) {
+      reject(@"ubriot_updates_bad_args", @"url and manifestId are required", nil);
+      return;
+    }
+    NSURL *remote = [NSURL URLWithString:url];
+    if (!remote) {
+      reject(@"ubriot_updates_bad_url", @"Invalid update url", nil);
+      return;
+    }
+    [UbriotUpdates ensureDirectory];
+    NSString *fileName = [NSString stringWithFormat:@"%@.jsbundle", [UbriotUpdates sanitize:manifestId]];
+    NSString *destination = [[UbriotUpdates updatesDirectory] stringByAppendingPathComponent:fileName];
+
+    NSURLSessionDataTask *task = [[NSURLSession sharedSession] dataTaskWithURL:remote
+                                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
+      if (error || data.length == 0) {
+        reject(@"ubriot_updates_download_failed", error ? error.localizedDescription : @"Empty update payload", error);
+        return;
+      }
+      if ([response isKindOfClass:[NSHTTPURLResponse class]]) {
+        NSInteger status = ((NSHTTPURLResponse *)response).statusCode;
+        if (status < 200 || status >= 300) {
+          reject(@"ubriot_updates_download_failed", [NSString stringWithFormat:@"Update download HTTP %ld", (long)status], nil);
+          return;
+        }
+      }
+      NSError *writeError = nil;
+      if (![data writeToFile:destination options:NSDataWritingAtomic error:&writeError]) {
+        reject(@"ubriot_updates_write_failed", writeError ? writeError.localizedDescription : @"Could not persist update", writeError);
+        return;
+      }
+      @try {
+        NSMutableDictionary *state = [UbriotUpdates readState];
+        state[@"pending"] = @{ @"id": manifestId, @"bundlePath": destination };
+        [UbriotUpdates writeState:state];
+      } @catch (__unused NSException *exception) {
+      }
+      resolve(@{ @"ready": @YES, @"bundlePath": destination });
+    }];
+    [task resume];
+  } @catch (NSException *exception) {
+    reject(@"ubriot_updates_download_failed", exception.reason, nil);
+  }
+}
+
+RCT_EXPORT_METHOD(applyPending:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+  @try {
+    NSMutableDictionary *state = [UbriotUpdates readState];
+    id pending = state[@"pending"];
+    if ([pending isKindOfClass:[NSDictionary class]]) {
+      state[@"active"] = pending;
+      state[@"verified"] = @NO;
+      state[@"launchCount"] = @0;
+      state[@"pending"] = [NSNull null];
+      [UbriotUpdates writeState:state];
+    }
+    resolve(nil);
+  } @catch (NSException *exception) {
+    reject(@"ubriot_updates_apply_failed", exception.reason, nil);
+  }
+}
+
+RCT_EXPORT_METHOD(markLaunchSuccessful:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+  @try {
+    NSMutableDictionary *state = [UbriotUpdates readState];
+    id active = state[@"active"];
+    if ([active isKindOfClass:[NSDictionary class]] && ![state[@"verified"] boolValue]) {
+      state[@"verified"] = @YES;
+      state[@"lastKnownGood"] = active;
+      state[@"launchCount"] = @0;
+      [UbriotUpdates writeState:state];
+    }
+    resolve(nil);
+  } @catch (NSException *exception) {
+    reject(@"ubriot_updates_mark_failed", exception.reason, nil);
+  }
+}
+
+RCT_EXPORT_METHOD(reload:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    @try {
+      RCTTriggerReloadCommandListeners(@"Ubriot OTA update");
+      resolve(nil);
+    } @catch (NSException *exception) {
+      reject(@"ubriot_updates_reload_failed", exception.reason, nil);
+    }
+  });
+}
+
+@end

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "ubriot-updates-rn",
+  "version": "0.1.0",
+  "description": "Ubriot over-the-air JS update client for bare React Native (iOS + Android)",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "react-native": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "android",
+    "ios",
+    "UbriotUpdatesRn.podspec",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": ">=0.76"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.10",
+    "react-native": "0.83.6",
+    "typescript": "~5.9.2"
+  },
+  "keywords": [
+    "react-native",
+    "ota",
+    "over-the-air",
+    "updates",
+    "codepush",
+    "ubriot"
+  ],
+  "license": "MIT",
+  "homepage": "https://ubriot.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dormdeveloper/specvista-monorepo",
+    "directory": "products/ubriot/updates-rn"
+  }
+}

package/src/index.ts

@@ -0,0 +1,218 @@
+import { NativeModules, Platform } from "react-native";
+
+export type UbriotUpdatesConfig = {
+  apiBase: string;
+  appSlug: string;
+  channel: string;
+  runtimeVersion: string;
+};
+
+export type UpdateCheckResult = {
+  available: boolean;
+  manifestId?: string;
+};
+
+export type DownloadResult = {
+  ready: boolean;
+};
+
+export type ApplyOptions = {
+  restart?: boolean;
+};
+
+export type SyncResult = "up-to-date" | "updated";
+
+type NativeEntry = {
+  id: string;
+  bundlePath: string;
+} | null;
+
+type NativeState = {
+  runningId: string | null;
+  active: NativeEntry;
+  verified: boolean;
+  pending: NativeEntry;
+  lastKnownGood: NativeEntry;
+  launchCount: number;
+};
+
+type NativeUbriotUpdates = {
+  getState(): Promise<NativeState>;
+  downloadBundle(url: string, manifestId: string): Promise<{ ready: boolean; bundlePath: string }>;
+  applyPending(): Promise<void>;
+  markLaunchSuccessful(): Promise<void>;
+  reload(): Promise<void>;
+};
+
+type LaunchManifest = {
+  id: string;
+  launchAssetUrl: string;
+};
+
+const MANIFEST_PATH = "/ubriot/updates/manifest";
+
+let config: UbriotUpdatesConfig | null = null;
+let stagedManifest: LaunchManifest | null = null;
+
+function getNativeModule(): NativeUbriotUpdates {
+  const native = NativeModules.UbriotUpdates as NativeUbriotUpdates | undefined;
+  if (!native || typeof native.getState !== "function") {
+    throw new Error("UbriotUpdates native module is not installed. Rebuild the app after adding @ubriot/updates-rn.");
+  }
+  return native;
+}
+
+function requireConfig(): UbriotUpdatesConfig {
+  if (!config) {
+    throw new Error("Ubriot updates: call configure() before using the update client.");
+  }
+  return config;
+}
+
+function currentPlatform(): "ios" | "android" {
+  return Platform.OS === "android" ? "android" : "ios";
+}
+
+function normalizeBase(apiBase: string): string {
+  return apiBase.replace(/\/+$/, "");
+}
+
+async function verifyManifestSignature(_manifest: unknown): Promise<boolean> {
+  return true;
+}
+
+export function configure(next: UbriotUpdatesConfig): void {
+  config = {
+    apiBase: normalizeBase(next.apiBase),
+    appSlug: next.appSlug,
+    channel: next.channel,
+    runtimeVersion: next.runtimeVersion,
+  };
+}
+
+export async function checkForUpdate(): Promise<UpdateCheckResult> {
+  const cfg = requireConfig();
+  const native = getNativeModule();
+
+  let runningId: string | null = null;
+  let pendingId: string | null = null;
+  try {
+    const state = await native.getState();
+    runningId = state?.runningId ?? null;
+    pendingId = state?.pending?.id ?? null;
+  } catch {
+    runningId = null;
+    pendingId = null;
+  }
+
+  const platform = currentPlatform();
+  const query = new URLSearchParams({
+    appId: cfg.appSlug,
+    channel: cfg.channel,
+    platform,
+    runtimeVersion: cfg.runtimeVersion,
+  });
+  const url = `${cfg.apiBase}${MANIFEST_PATH}?${query.toString()}`;
+
+  const headers: Record<string, string> = {
+    accept: "application/expo+json",
+    "expo-platform": platform,
+    "expo-runtime-version": cfg.runtimeVersion,
+    "expo-channel-name": cfg.channel,
+    "expo-protocol-version": "1",
+  };
+  if (runningId) {
+    headers["expo-current-update-id"] = runningId;
+  }
+
+  const response = await fetch(url, { method: "GET", headers });
+  if (response.status === 204 || response.status === 304) {
+    stagedManifest = null;
+    return { available: false };
+  }
+  if (!response.ok) {
+    stagedManifest = null;
+    return { available: false };
+  }
+
+  const manifest = (await response.json().catch(() => null)) as
+    | { id?: string; launchAsset?: { url?: string } }
+    | null;
+  const manifestId = manifest?.id;
+  const launchAssetUrl = manifest?.launchAsset?.url;
+  if (!manifest || !manifestId || !launchAssetUrl) {
+    stagedManifest = null;
+    return { available: false };
+  }
+  if (manifestId === runningId || manifestId === pendingId) {
+    stagedManifest = null;
+    return { available: false };
+  }
+
+  const trusted = await verifyManifestSignature(manifest);
+  if (!trusted) {
+    stagedManifest = null;
+    return { available: false };
+  }
+
+  stagedManifest = { id: manifestId, launchAssetUrl };
+  return { available: true, manifestId };
+}
+
+export async function downloadUpdate(): Promise<DownloadResult> {
+  requireConfig();
+  const native = getNativeModule();
+
+  if (!stagedManifest) {
+    const check = await checkForUpdate();
+    if (!check.available) {
+      return { ready: false };
+    }
+  }
+  if (!stagedManifest) {
+    return { ready: false };
+  }
+
+  try {
+    const result = await native.downloadBundle(stagedManifest.launchAssetUrl, stagedManifest.id);
+    return { ready: !!result?.ready };
+  } catch {
+    return { ready: false };
+  }
+}
+
+export async function applyUpdate(options: ApplyOptions = {}): Promise<void> {
+  const native = getNativeModule();
+  await native.applyPending();
+  if (options.restart) {
+    try {
+      await native.reload();
+    } catch {
+      // reload is best-effort; the update still applies on the next launch
+    }
+  }
+}
+
+export async function sync(): Promise<SyncResult> {
+  const check = await checkForUpdate();
+  if (!check.available) {
+    return "up-to-date";
+  }
+  const download = await downloadUpdate();
+  if (!download.ready) {
+    return "up-to-date";
+  }
+  await applyUpdate({ restart: false });
+  return "updated";
+}
+
+export function markLaunchSuccessful(): void {
+  try {
+    const native = NativeModules.UbriotUpdates as NativeUbriotUpdates | undefined;
+    if (native && typeof native.markLaunchSuccessful === "function") {
+      native.markLaunchSuccessful().catch(() => {});
+    }
+  } catch {
+    // never allow launch bookkeeping to crash the host app
+  }
+}