@fireota/react-native 0.0.0-stage → 0.1.1

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,235 @@
-# Temporary Holding Version
-
-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.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Sujay-Dynamisch/FireOTA/main/public/logo-mark.png" alt="FireOTA" width="96" />
+</p>
+
+<h1 align="center">FireOTA</h1>
+
+<p align="center">
+  Over-the-air updates for React Native — served from <strong>your own Firebase project</strong>.<br />
+  Staged rollouts, checksum verification, automatic rollback, audit logs and a CI-ready CLI.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@fireota/react-native"><img alt="@fireota/react-native" src="https://img.shields.io/npm/v/@fireota/react-native?label=%40fireota%2Freact-native" /></a>
+  <a href="https://www.npmjs.com/package/@fireota/cli"><img alt="@fireota/cli" src="https://img.shields.io/npm/v/@fireota/cli?label=%40fireota%2Fcli" /></a>
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue" />
+</p>
+
+---
+
+## What it does
+
+Ship JavaScript fixes and features to your React Native app **without a store review**:
+
+1. `npx fireota publish` bundles your JS (Hermes bytecode + images) and uploads it to **your** Firebase Storage bucket.
+2. FireOTA records the release — version, runtime, SHA-256, channel, rollout — and writes every action to an audit log.
+3. The SDK in your app checks for a compatible release on launch, downloads it **directly from your bucket**, verifies the checksum, and applies it on the next start.
+4. If the new bundle crashes before starting, the device rolls back to the previous bundle automatically and reports it.
+
+You own the artifacts and pay Google directly for storage and bandwidth. FireOTA never proxies downloads.
+
+## Features
+
+| | |
+| --- | --- |
+| **Releases** | Strict state machine (draft → ready → published → paused / rolled back / archived), atomic publish and rollback |
+| **Rollouts** | Deterministic per-device buckets, 0–100 %, per-platform channel targets (Android and iOS independent) |
+| **Safety** | Server-side SHA-256, exact runtime matching, native-version constraints, automatic pause on high failure rates |
+| **Teams** | Organizations, roles (owner, admin, release manager, developer, viewer), Supabase Row Level Security |
+| **Integrations** | Scoped API keys, CI/CD API, HMAC-signed webhooks with retries, notifications, analytics |
+| **Firebase** | Google OAuth (PKCE) per customer project, encrypted refresh tokens, live Storage write verification |
+
+## Repository layout
+
+```text
+src/                     Web dashboard + API (TanStack Start, React, Tailwind)
+  routes/                Pages and HTTP routes (/api/public/v1/*, /health, /docs)
+  lib/backend/           Release engine, OTA resolver, Firebase adapter, RBAC, webhooks
+  lib/api/               Server functions used by the dashboard
+  components/docs/       Documentation site content (/docs)
+supabase/migrations/     Database schema, RLS policies and transactional functions
+packages/react-native/   @fireota/react-native — the app SDK (Kotlin + Objective-C)
+packages/cli/            @fireota/cli — bundle, upload and publish from a terminal or CI
+tests/                   Integration, end-to-end and package-format tests
+```
+
+## Quick start (local)
+
+**Prerequisites:** Node.js 20+, a [Supabase](https://supabase.com) project, a Google Cloud OAuth client.
+
+```sh
+git clone https://github.com/Sujay-Dynamisch/FireOTA.git
+cd FireOTA
+npm install
+```
+
+### 1. Environment
+
+Create `.env` in the project root (never commit it):
+
+```sh
+# Supabase -> Project Settings -> API
+SUPABASE_URL="https://<project-ref>.supabase.co"
+SUPABASE_PUBLISHABLE_KEY="sb_publishable_..."
+VITE_SUPABASE_URL="https://<project-ref>.supabase.co"
+VITE_SUPABASE_PUBLISHABLE_KEY="sb_publishable_..."
+SUPABASE_PROJECT_ID="<project-ref>"
+VITE_SUPABASE_PROJECT_ID="<project-ref>"
+
+# Server-only secrets
+SUPABASE_SERVICE_ROLE_KEY="..."        # Supabase -> API Keys -> Secret key (bypasses RLS)
+FIREOTA_ENCRYPTION_KEY="..."           # random; encrypts Google tokens and webhook secrets — never change it
+FIREOTA_CRON_SECRET="..."              # bearer token for the maintenance endpoint
+
+# Google Cloud -> APIs & Services -> Credentials -> OAuth client (Web application)
+GOOGLE_CLIENT_ID="..."
+GOOGLE_CLIENT_SECRET="..."
+GOOGLE_REDIRECT_URI="http://localhost:8080/api/public/v1/firebase/callback"
+```
+
+Generate random secrets with:
+
+```sh
+node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
+```
+
+### 2. Database
+
+Apply every file in `supabase/migrations/` in order — with the Supabase CLI (`supabase link` then `supabase db push`) or by running them in the SQL editor.
+
+### 3. Auth and Google OAuth
+
+- **Supabase → Authentication → URL Configuration:** Site URL `http://localhost:8080`; add redirect URLs `http://localhost:8080/dashboard`, `/onboarding`, `/reset-password`.
+- **Supabase → Authentication → Providers → Google:** enable it with your OAuth client for "Continue with Google".
+- **Google Cloud → OAuth client → Authorised redirect URIs:** add `http://localhost:8080/api/public/v1/firebase/callback` and `https://<project-ref>.supabase.co/auth/v1/callback`.
+
+### 4. Run
+
+```sh
+npm run dev        # http://localhost:8080
+```
+
+Open `/signup`, create your workspace, connect a Firebase project (Cloud Storage must be set up) and register your app.
+
+## Deploy to Vercel
+
+The repository includes [`vercel.json`](vercel.json). Nitro detects Vercel and builds a Node.js function plus static assets.
+
+1. Import the repository in Vercel (no framework preset needed).
+2. Add every variable from the `.env` section under **Project → Settings → Environment Variables**, with production URLs:
+   - `GOOGLE_REDIRECT_URI=https://<your-domain>/api/public/v1/firebase/callback`
+   - `CRON_SECRET=<random>` — Vercel sends it to the maintenance cron automatically.
+3. Deploy, then update the production URLs in Supabase Auth and in the Google OAuth client.
+4. Check `https://<your-domain>/health/ready` returns `{"status":"ok"}`.
+
+The cron in `vercel.json` runs the maintenance job (webhook retries, OAuth state cleanup) daily, which works on the Hobby plan. On Pro, change the schedule to `*/5 * * * *` for faster webhook retries.
+
+> **Upload size on Vercel:** Vercel Functions accept request bodies up to **4.5 MB**. Larger update packages must be published against a deployment without that limit (or a direct-to-Storage upload, on the roadmap).
+
+## 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"
+  }
+}