react-native-custom-ota 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,215 @@
-# Temporary Holding Version
+# react-native-custom-ota ⚡
 
-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.
+Thư viện cập nhật ứng dụng từ xa qua mạng (Over-The-Air - OTA) tự host dành cho React Native, hoạt động tương tự như **`react-native-code-push`**, hỗ trợ đầy đủ New Architecture (Fabric/TurboModules), mã băm SHA-256 toàn vẹn và cơ chế **Tự phục hồi (Startup Rollback)** khi bản cập nhật bị crash.
+
+---
+
+## 🌟 Tính năng nổi bật
+
+- 🔄 **Đồng bộ 1 chạm (CodePush-like API)**: Hỗ trợ `CustomOTA.sync()` và HOC `withCustomOTA(App)`.
+- 🛡️ **Cơ chế Rollback an toàn**: Nếu bản cập nhật bị crash ở tầng JS trước khi boot thành công, Native Resolver sẽ tự động phát hiện và khôi phục về bản backup ổn định trước đó.
+- 📦 **Tích hợp Native cực kỳ đơn giản**: Chỉ cần thêm 1 dòng code ở Android và 1 dòng ở iOS (Hỗ trợ React Native Autolinking).
+- 🛠️ **Tích hợp CLI phát hành nhanh**: `npx custom-ota release` tự động chạy Metro, nén zip và upload lên server chỉ trong 1-2 giây.
+- 🚀 **Tương thích cả Old Architecture & New Architecture** (React Native 0.70+ đến 0.87+).
+
+---
+
+## 📦 Cài đặt
+
+Trong dự án React Native của bạn:
+
+```bash
+# Cài đặt qua Yarn
+yarn add react-native-custom-ota react-native-fs
+
+# Hoặc qua NPM
+npm install react-native-custom-ota react-native-fs
+```
+
+Đối với **iOS**, cài đặt CocoaPods:
+```bash
+cd ios && pod install && cd ..
+```
+
+---
+
+## ⚙️ Cấu hình Native (Chỉ 1 dòng mỗi nền tảng)
+
+### 1. Android
+Mở file `android/app/src/main/java/.../MainApplication.kt` (hoặc `MainApplication.java`):
+
+```kotlin
+import com.customota.CustomOTABundleResolver
+
+class MainApplication : Application(), ReactApplication {
+
+  // New Architecture (RN 0.76+):
+  override val reactHost: ReactHost by lazy {
+    val otaBundle = CustomOTABundleResolver.getBundleFile(applicationContext)
+
+    getDefaultReactHost(
+      context = applicationContext,
+      packageList = PackageList(this).packages,
+      jsBundleFilePath = otaBundle, // <-- Thêm dòng này
+      useDevSupport = otaBundle == null && BuildConfig.DEBUG
+    )
+  }
+
+  // Hoặc với Old Architecture (ReactNativeHost):
+  override fun getJSBundleFile(): String? {
+    return CustomOTABundleResolver.getBundleFile(applicationContext) ?: super.getJSBundleFile()
+  }
+}
+```
+
+---
+
+### 2. iOS
+Mở file `ios/.../AppDelegate.swift` (hoặc `AppDelegate.mm`):
+
+```swift
+import RNCustomOTA
+
+class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
+  override func bundleURL() -> URL? {
+    // 1. Kiểm tra bản OTA trước tiên:
+    if let otaURL = CustomOTABundleResolver.currentBundleURL() {
+      return otaURL
+    }
+
+    // 2. Mặc định fallback:
+#if DEBUG
+    return RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+#else
+    return Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+#endif
+  }
+}
+```
+
+---
+
+## 🚀 Cách sử dụng phía React Native (JS / TS)
+
+> [!NOTE]
+> **Bảo mật API Key**: Khi server bật xác thực bảo mật, bạn cần truyền `apiKey` (loại **Pull Key**, bắt đầu bằng `ota_pull_live_...`). Nếu không có key hợp lệ, server sẽ từ chối với mã lỗi `API_KEY_REQUIRED` (HTTP 401).
+
+### Cách 1: Sử dụng HOC (Tương tự CodePush - Khuyên dùng)
+
+Bọc component gốc `App` bằng HOC `withCustomOTA`:
+
+```tsx
+import React from "react";
+import { View, Text } from "react-native";
+import CustomOTA, { CheckFrequency } from "react-native-custom-ota";
+
+function App() {
+  return (
+    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
+      <Text>Ứng dụng của tôi</Text>
+    </View>
+  );
+}
+
+export default CustomOTA.wrap({
+  serverUrl: "http://my-ota-server.com:4500",
+  apiKey: "ota_pull_live_xxxx", // API Key có quyền Pull để tải bản cập nhật
+  appId: "com.otademoapp",      // Định danh ứng dụng (tuỳ chọn)
+  checkFrequency: CheckFrequency.ON_APP_RESUME, // Tự động check khi mở app hoặc resume
+  updateDialog: true, // Tự động hiện popup hỏi người dùng khi có bản mới
+})(App);
+```
+
+---
+
+### Cách 2: Gọi `CustomOTA.sync()` linh hoạt
+
+Tự gọi đồng bộ bất cứ lúc nào (ví dụ trong `useEffect` hoặc khi người dùng bấm nút):
+
+```tsx
+import CustomOTA, { SyncStatus } from "react-native-custom-ota";
+
+// Gọi đồng bộ tự động:
+CustomOTA.sync({
+  serverUrl: "http://my-ota-server.com:4500",
+  apiKey: "ota_pull_live_xxxx", // Pull API Key
+  appId: "com.otademoapp",
+  updateDialog: {
+    title: "Có bản cập nhật mới!",
+    optionalUpdateMessage: "Bạn có muốn cài đặt ngay bây giờ?",
+    optionalInstallButtonLabel: "Cài đặt ngay",
+    optionalIgnoreButtonLabel: "Để sau"
+  }
+}, (status) => {
+  switch (status) {
+    case SyncStatus.DOWNLOADING_PACKAGE:
+      console.log("Đang tải bản cập nhật...");
+      break;
+    case SyncStatus.UPDATE_INSTALLED:
+      console.log("Đã cài xong!");
+      break;
+  }
+}, (progress) => {
+  console.log(`Tiến độ: ${Math.round(progress * 100)}%`);
+});
+```
+
+---
+
+### Cách 3: Điều khiển thủ công từng bước
+
+```tsx
+import CustomOTA from "react-native-custom-ota";
+
+async function manualCheck() {
+  // 1. Kiểm tra update
+  const update = await CustomOTA.checkForUpdate({
+    serverUrl: "http://my-ota-server.com:4500",
+    apiKey: "ota_pull_live_xxxx", // Pull API Key
+    appId: "com.otademoapp"
+  });
+
+  if (update && update.updateAvailable) {
+    // 2. Tải và cài đặt
+    await CustomOTA.downloadAndInstall(update, (progress) => {
+      console.log("Progress:", progress);
+    });
+
+    // 3. Khởi động lại ứng dụng
+    await CustomOTA.restartApp();
+  }
+}
+```
+
+---
+
+## 🛠️ Công cụ CLI: Phát hành bản cập nhật mới
+
+Sau khi sửa code trong dự án React Native, bạn có thể dùng CLI đi kèm thư viện:
+
+```bash
+# Phát hành cho iOS với Push Key (-k hoặc biến OTA_API_KEY)
+npx custom-ota release -a com.otademoapp -p ios -v 1.0.4 -m "Sửa lỗi giao diện" -s http://localhost:4500 -k ota_push_live_xxxx
+
+# Phát hành cho Android
+npx custom-ota release -a com.otademoapp -p android -v 1.0.4 -s http://localhost:4500 -k ota_push_live_xxxx
+
+# Phát hành cùng lúc cả iOS và Android qua biến môi trường
+OTA_API_KEY=ota_push_live_xxxx npx custom-ota release -a com.otademoapp -p all -v 1.0.4 -s http://localhost:4500
+```
+
+### Các cờ hỗ trợ trong CLI:
+| Cờ | Tên dài | Ý nghĩa | Mặc định |
+| :--- | :--- | :--- | :--- |
+| `-p` | `--platform` | Nền tảng: `android`, `ios`, `all` (Bắt buộc) | |
+| `-v` | `--version` | Phiên bản OTA (Bắt buộc) | |
+| `-a` | `--app-id` | Mã định danh ứng dụng | Tự đọc từ `app.json` / `package.json` |
+| `-k` | `--api-key` | Push API Key (hoặc qua `OTA_API_KEY`) | |
+| `-s` | `--server` | Địa chỉ OTA Server | `http://localhost:4500` |
+| `-m` | `--notes` | Ghi chú phát hành | `"OTA update"` |
+| `--min-native` | `--minNativeVersion` | Phiên bản Native tối thiểu hỗ trợ | `1.0.0` |
+
+---
+
+## 📄 License
+MIT

package/RNCustomOTA.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "RNCustomOTA"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://github.com/custom-ota/react-native-custom-ota"
+  s.license      = package["license"]
+  s.authors      = package["author"]
+  s.platforms    = { :ios => "13.4" }
+  s.source       = { :git => "https://github.com/custom-ota/react-native-custom-ota.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  s.requires_arc = true
+
+  s.dependency "React-Core"
+  s.dependency "SSZipArchive"
+end

package/android/build.gradle

@@ -0,0 +1,21 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace "com.customota"
+    compileSdkVersion rootProject.hasProperty('compileSdkVersion') ? rootProject.compileSdkVersion : 34
+
+    defaultConfig {
+        minSdkVersion rootProject.hasProperty('minSdkVersion') ? rootProject.minSdkVersion : 23
+        targetSdkVersion rootProject.hasProperty('targetSdkVersion') ? rootProject.targetSdkVersion : 34
+    }
+
+    lintOptions {
+        abortOnError false
+    }
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-android'
+    implementation "org.jetbrains.kotlin:kotlin-stdlib"
+}

package/android/src/main/java/com/customota/CustomOTABundleResolver.kt

@@ -0,0 +1,85 @@
+package com.customota
+
+import android.content.Context
+import java.io.File
+import org.json.JSONArray
+import org.json.JSONObject
+
+object CustomOTABundleResolver {
+
+    /**
+     * Lấy đường dẫn file JS bundle của OTA.
+     * Tự động kiểm tra trạng thái crash/pending để phục hồi (Rollback) bản backup trước đó.
+     */
+    @JvmStatic
+    fun getBundleFile(context: Context): String? {
+        checkAndRollbackIfPending(context)
+
+        val file = File(
+            context.filesDir,
+            "ota/current/index.android.bundle"
+        )
+
+        return if (file.exists() && file.length() > 0) {
+            file.absolutePath
+        } else {
+            null
+        }
+    }
+
+    @JvmStatic
+    fun getStateFile(context: Context): File {
+        return File(
+            context.filesDir,
+            "ota/state.json"
+        )
+    }
+
+    @JvmStatic
+    fun checkAndRollbackIfPending(context: Context) {
+        val stateFile = getStateFile(context)
+        if (!stateFile.exists()) return
+
+        try {
+            val jsonStr = stateFile.readText()
+            val json = JSONObject(jsonStr)
+
+            val pending = json.optBoolean("pending", false)
+            if (!pending) return
+
+            val trial = json.optBoolean("trial", false)
+            val currentDir = File(context.filesDir, "ota/current")
+            val backupDir = File(context.filesDir, "ota/backup")
+
+            if (trial) {
+                // Đã thử chạy lần trước mà bị crash trước khi gọi markReady() -> ROLLBACK!
+                if (backupDir.exists()) {
+                    currentDir.deleteRecursively()
+                    backupDir.renameTo(currentDir)
+                } else {
+                    currentDir.deleteRecursively()
+                }
+
+                val failedVer = json.optString("currentVersion", "")
+                val failedArray = json.optJSONArray("failedVersions") ?: JSONArray()
+                if (failedVer.isNotEmpty()) {
+                    failedArray.put(failedVer)
+                }
+                json.put("failedVersions", failedArray)
+
+                val prevVer = json.optString("previousVersion", "0.0.0")
+                json.put("currentVersion", prevVer)
+                json.put("pending", false)
+                json.put("trial", false)
+                json.put("ready", true)
+            } else {
+                // Lần đầu mở bản mới: cho phép chạy và đánh dấu trial = true
+                json.put("trial", true)
+            }
+
+            stateFile.writeText(json.toString(2))
+        } catch (e: Exception) {
+            e.printStackTrace()
+        }
+    }
+}

package/android/src/main/java/com/customota/OTAUpdaterModule.kt

@@ -0,0 +1,152 @@
+package com.customota
+
+import android.app.Activity
+import android.os.Handler
+import android.os.Looper
+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.io.File
+import java.io.FileInputStream
+import java.io.FileOutputStream
+import java.util.zip.ZipInputStream
+
+class OTAUpdaterModule(
+    private val reactContext: ReactApplicationContext
+) : ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String = "OTAUpdater"
+
+    @ReactMethod
+    fun unzip(zipPath: String, targetDir: String, promise: Promise) {
+        try {
+            val dest = File(targetDir)
+            if (!dest.exists()) {
+                dest.mkdirs()
+            }
+
+            val buffer = ByteArray(4096)
+            val zis = ZipInputStream(FileInputStream(zipPath))
+            var zipEntry = zis.nextEntry
+
+            while (zipEntry != null) {
+                val newFile = File(dest, zipEntry.name)
+                if (!newFile.canonicalPath.startsWith(dest.canonicalPath)) {
+                    throw SecurityException("Zip Slip detected: " + zipEntry.name)
+                }
+
+                if (zipEntry.isDirectory) {
+                    newFile.mkdirs()
+                } else {
+                    newFile.parentFile?.mkdirs()
+                    val fos = FileOutputStream(newFile)
+                    var len: Int
+                    while (zis.read(buffer).also { len = it } > 0) {
+                        fos.write(buffer, 0, len)
+                    }
+                    fos.close()
+                }
+                zipEntry = zis.nextEntry
+            }
+            zis.closeEntry()
+            zis.close()
+
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("OTA_UNZIP", e)
+        }
+    }
+
+    @ReactMethod
+    fun markReady(promise: Promise) {
+        try {
+            val stateFile = File(
+                reactContext.filesDir,
+                "ota/state.json"
+            )
+
+            if (stateFile.exists()) {
+                val json = JSONObject(stateFile.readText())
+                json.put("pending", false)
+                json.put("ready", true)
+                json.put("trial", false)
+                stateFile.writeText(json.toString(2))
+
+                File(
+                    reactContext.filesDir,
+                    "ota/backup"
+                ).deleteRecursively()
+            }
+
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("OTA_READY", e)
+        }
+    }
+
+    @ReactMethod
+    fun getCurrentVersion(promise: Promise) {
+        try {
+            val stateFile = File(
+                reactContext.filesDir,
+                "ota/state.json"
+            )
+
+            if (!stateFile.exists()) {
+                promise.resolve("0.0.0")
+                return
+            }
+
+            val json = stateFile.readText()
+            val regex =
+                Regex("\"currentVersion\"\\s*:\\s*\"([^\"]+)\"")
+
+            promise.resolve(
+                regex.find(json)?.groupValues?.get(1)
+                    ?: "0.0.0"
+            )
+        } catch (e: Exception) {
+            promise.reject("OTA_VERSION", e)
+        }
+    }
+
+    @ReactMethod
+    fun restart(promise: Promise) {
+        try {
+            val activity: Activity? =
+                reactContext.currentActivity
+
+            if (activity == null) {
+                promise.reject(
+                    "OTA_RESTART",
+                    "No current Activity"
+                )
+                return
+            }
+
+            promise.resolve(null)
+
+            Handler(Looper.getMainLooper()).postDelayed({
+                val packageManager =
+                    reactContext.packageManager
+
+                val intent =
+                    packageManager.getLaunchIntentForPackage(
+                        reactContext.packageName
+                    )
+
+                intent?.addFlags(
+                    android.content.Intent.FLAG_ACTIVITY_NEW_TASK or
+                    android.content.Intent.FLAG_ACTIVITY_CLEAR_TOP or
+                    android.content.Intent.FLAG_ACTIVITY_CLEAR_TASK
+                )
+
+                reactContext.startActivity(intent)
+                activity.finishAffinity()
+            }, 300)
+        } catch (e: Exception) {
+            promise.reject("OTA_RESTART", e)
+        }
+    }
+}

package/android/src/main/java/com/customota/OTAUpdaterPackage.kt

@@ -0,0 +1,22 @@
+package com.customota
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class OTAUpdaterPackage : ReactPackage {
+    override fun createNativeModules(
+        reactContext: ReactApplicationContext
+    ): List<NativeModule> {
+        return listOf(
+            OTAUpdaterModule(reactContext)
+        )
+    }
+
+    override fun createViewManagers(
+        reactContext: ReactApplicationContext
+    ): List<ViewManager<*, *>> {
+        return emptyList()
+    }
+}