relay-ota-react-native 0.1.0

package/src/filesystem.ts

@@ -0,0 +1,62 @@
+import type { IFileSystemAdapter } from './types';
+
+// Expo adapter — requires expo-file-system
+export function createExpoFileSystemAdapter(): IFileSystemAdapter {
+  // Lazily require so non-Expo projects don't fail at import time
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const ExpoFS = require('expo-file-system') as any;
+
+  return {
+    getDocumentDirectory() {
+      return ExpoFS.documentDirectory ?? '';
+    },
+    async exists(path) {
+      const info = await ExpoFS.getInfoAsync(path);
+      return info.exists;
+    },
+    async readAsString(path, encoding) {
+      return ExpoFS.readAsStringAsync(path, {
+        encoding: encoding === 'base64' ? ExpoFS.EncodingType.Base64 : ExpoFS.EncodingType.UTF8,
+      });
+    },
+    async writeAsString(path, content, encoding) {
+      await ExpoFS.writeAsStringAsync(path, content, {
+        encoding: encoding === 'base64' ? ExpoFS.EncodingType.Base64 : ExpoFS.EncodingType.UTF8,
+      });
+    },
+    async deleteFile(path) {
+      await ExpoFS.deleteAsync(path, { idempotent: true });
+    },
+    async makeDirectory(path) {
+      await ExpoFS.makeDirectoryAsync(path, { intermediates: true });
+    },
+  };
+}
+
+// Bare React Native adapter — requires react-native-fs
+export function createRNFSFileSystemAdapter(): IFileSystemAdapter {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const RNFS = require('react-native-fs') as any;
+
+  return {
+    getDocumentDirectory() {
+      return `${RNFS.DocumentDirectoryPath}/`;
+    },
+    async exists(path) {
+      return RNFS.exists(path);
+    },
+    async readAsString(path, encoding) {
+      return RNFS.readFile(path, encoding);
+    },
+    async writeAsString(path, content, encoding) {
+      await RNFS.writeFile(path, content, encoding);
+    },
+    async deleteFile(path) {
+      const exists = await RNFS.exists(path);
+      if (exists) await RNFS.unlink(path);
+    },
+    async makeDirectory(path) {
+      await RNFS.mkdir(path);
+    },
+  };
+}

package/src/hooks.ts

@@ -0,0 +1,46 @@
+import { useCallback } from 'react';
+import { useOtaContext } from './provider';
+import type { UpdateState } from './types';
+
+export interface UseOtaUpdateReturn extends UpdateState {
+  checkForUpdates: () => Promise<void>;
+  downloadUpdate: () => Promise<void>;
+  applyUpdate: () => Promise<void>;
+  rollback: () => Promise<void>;
+  isLoading: boolean;
+  hasUpdate: boolean;
+  isReady: boolean;
+}
+
+export function useOtaUpdate(): UseOtaUpdateReturn {
+  const { state, checkForUpdates, downloadUpdate, applyUpdate, rollback } = useOtaContext();
+
+  return {
+    ...state,
+    checkForUpdates: useCallback(checkForUpdates, [checkForUpdates]),
+    downloadUpdate: useCallback(downloadUpdate, [downloadUpdate]),
+    applyUpdate: useCallback(applyUpdate, [applyUpdate]),
+    rollback: useCallback(rollback, [rollback]),
+    isLoading: state.status === 'checking' || state.status === 'downloading',
+    hasUpdate: state.status === 'update_available',
+    isReady: state.status === 'ready',
+  };
+}
+
+// Hook that auto-downloads and applies mandatory updates
+export function useAutoUpdate(options?: { applyImmediately?: boolean }) {
+  const ota = useOtaUpdate();
+  const applyImmediately = options?.applyImmediately ?? false;
+
+  // Auto-download when update is detected
+  if (ota.hasUpdate && ota.release?.isMandatory) {
+    ota.downloadUpdate();
+  }
+
+  // Auto-apply when ready and applyImmediately is set
+  if (ota.isReady && applyImmediately) {
+    ota.applyUpdate();
+  }
+
+  return ota;
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export { OtaProvider, useOtaContext } from './provider';
+export { useOtaUpdate, useAutoUpdate } from './hooks';
+export { OtaUpdater } from './updater';
+export { checkForUpdate } from './client';
+export { downloadBundle } from './downloader';
+export { createExpoFileSystemAdapter, createRNFSFileSystemAdapter } from './filesystem';
+export {
+  isNativeModuleAvailable,
+  setStagedBundlePath,
+  getStagedBundlePath,
+  clearStagedBundlePath,
+  reload,
+} from './installer';
+export type {
+  OtaConfig,
+  UpdateStatus,
+  UpdateState,
+  IFileSystemAdapter,
+  INativeBundleUpdater,
+  Platform,
+} from './types';

package/src/installer.ts

@@ -0,0 +1,42 @@
+import { NativeModules } from 'react-native';
+import type { INativeBundleUpdater } from './types';
+
+// User must register their native module under this name
+const NATIVE_MODULE_NAME = 'OtaBundleUpdater';
+
+function getNativeModule(): INativeBundleUpdater | null {
+  return (NativeModules[NATIVE_MODULE_NAME] as INativeBundleUpdater) ?? null;
+}
+
+export function isNativeModuleAvailable(): boolean {
+  return getNativeModule() !== null;
+}
+
+export async function setStagedBundlePath(path: string): Promise<void> {
+  const mod = getNativeModule();
+  if (!mod) throw new Error(`Native module '${NATIVE_MODULE_NAME}' not found. See SDK setup docs.`);
+  await mod.setBundlePath(path);
+}
+
+export async function getStagedBundlePath(): Promise<string | null> {
+  const mod = getNativeModule();
+  if (!mod) return null;
+  return mod.getBundlePath();
+}
+
+export async function clearStagedBundlePath(): Promise<void> {
+  const mod = getNativeModule();
+  if (!mod) return;
+  await mod.clearBundlePath();
+}
+
+export function reload(): void {
+  const mod = getNativeModule();
+  if (mod) {
+    mod.reload();
+  } else {
+    // Dev fallback
+    const devSettings = NativeModules['DevSettings'] as { reload?: () => void } | undefined;
+    devSettings?.reload?.();
+  }
+}

package/src/native/OtaBundleUpdater.h

@@ -0,0 +1,5 @@
+#import <React/RCTBridgeModule.h>
+
+@interface OtaBundleUpdater : NSObject <RCTBridgeModule>
++ (NSURL *)bundleURLForBridge:(RCTBridge *)bridge;
+@end

package/src/native/OtaBundleUpdater.m

@@ -0,0 +1,56 @@
+#import "OtaBundleUpdater.h"
+#import <React/RCTBridge.h>
+#import <React/RCTRootView.h>
+
+static NSString *const kBundlePathKey = @"OtaBundleUpdaterPath";
+
+@implementation OtaBundleUpdater
+
+RCT_EXPORT_MODULE();
+
+// Called by React Native bridge to determine which bundle to load.
+// Add to AppDelegate.mm:
+//   #import "OtaBundleUpdater.h"
+//   - (NSURL *)sourceURLForBridge:(RCTBridge *)bridge {
+//     return [OtaBundleUpdater bundleURLForBridge:bridge];
+//   }
++ (NSURL *)bundleURLForBridge:(RCTBridge *)bridge {
+  NSString *storedPath = [[NSUserDefaults standardUserDefaults] stringForKey:kBundlePathKey];
+  if (storedPath && [[NSFileManager defaultManager] fileExistsAtPath:storedPath]) {
+    return [NSURL fileURLWithPath:storedPath];
+  }
+#if DEBUG
+  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
+#else
+  return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+#endif
+}
+
+RCT_EXPORT_METHOD(setBundlePath:(NSString *)path
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+  [[NSUserDefaults standardUserDefaults] setObject:path forKey:kBundlePathKey];
+  [[NSUserDefaults standardUserDefaults] synchronize];
+  resolve(nil);
+}
+
+RCT_EXPORT_METHOD(getBundlePath:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+  NSString *path = [[NSUserDefaults standardUserDefaults] stringForKey:kBundlePathKey];
+  resolve(path);
+}
+
+RCT_EXPORT_METHOD(clearBundlePath:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject) {
+  [[NSUserDefaults standardUserDefaults] removeObjectForKey:kBundlePathKey];
+  [[NSUserDefaults standardUserDefaults] synchronize];
+  resolve(nil);
+}
+
+RCT_EXPORT_METHOD(reload) {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    RCTTriggerReloadCommandListeners(@"OTA update applied");
+  });
+}
+
+@end

package/src/native/OtaBundleUpdaterModule.kt

@@ -0,0 +1,73 @@
+package com.ota.sdk
+
+import android.content.Context
+import com.facebook.react.bridge.*
+
+private const val PREF_KEY = "OtaBundleUpdaterPath"
+private const val PREFS_NAME = "OtaBundleUpdater"
+
+class OtaBundleUpdaterModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName() = "OtaBundleUpdater"
+
+    @ReactMethod
+    fun setBundlePath(path: String, promise: Promise) {
+        try {
+            reactApplicationContext
+                .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .edit()
+                .putString(PREF_KEY, path)
+                .apply()
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("SET_BUNDLE_PATH_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    fun getBundlePath(promise: Promise) {
+        val path = reactApplicationContext
+            .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .getString(PREF_KEY, null)
+        promise.resolve(path)
+    }
+
+    @ReactMethod
+    fun clearBundlePath(promise: Promise) {
+        try {
+            reactApplicationContext
+                .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .edit()
+                .remove(PREF_KEY)
+                .apply()
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CLEAR_BUNDLE_PATH_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    fun reload() {
+        currentActivity?.runOnUiThread {
+            val ctx = currentActivity ?: return@runOnUiThread
+            val intent = ctx.packageManager.getLaunchIntentForPackage(ctx.packageName)
+            intent?.addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK or android.content.Intent.FLAG_ACTIVITY_CLEAR_TASK)
+            ctx.startActivity(intent)
+            android.os.Process.killProcess(android.os.Process.myPid())
+        }
+    }
+
+    companion object {
+        // Call from MainApplication.kt to resolve the bundle path.
+        // In MainApplication.kt:
+        //   override fun getJSBundleFile(): String? =
+        //     OtaBundleUpdaterModule.getJSBundleFile(applicationContext) ?: super.getJSBundleFile()
+        fun getJSBundleFile(context: Context): String? {
+            val path = context
+                .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .getString(PREF_KEY, null)
+            return if (path != null && java.io.File(path).exists()) path else null
+        }
+    }
+}

package/src/native/OtaBundleUpdaterPackage.kt

@@ -0,0 +1,14 @@
+package com.ota.sdk
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class OtaBundleUpdaterPackage : ReactPackage {
+    override fun createNativeModules(context: ReactApplicationContext): List<NativeModule> =
+        listOf(OtaBundleUpdaterModule(context))
+
+    override fun createViewManagers(context: ReactApplicationContext): List<ViewManager<*, *>> =
+        emptyList()
+}

package/src/provider.tsx

@@ -0,0 +1,77 @@
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+import { OtaUpdater } from './updater';
+import type { OtaConfig, UpdateState, IFileSystemAdapter } from './types';
+
+interface OtaContextValue {
+  state: UpdateState;
+  checkForUpdates: () => Promise<void>;
+  downloadUpdate: () => Promise<void>;
+  applyUpdate: () => Promise<void>;
+  rollback: () => Promise<void>;
+}
+
+const OtaContext = createContext<OtaContextValue | null>(null);
+
+interface OtaProviderProps {
+  config: OtaConfig;
+  fileSystem: IFileSystemAdapter;
+  children: ReactNode;
+}
+
+export function OtaProvider({ config, fileSystem, children }: OtaProviderProps) {
+  const updaterRef = useRef<OtaUpdater | null>(null);
+
+  if (!updaterRef.current) {
+    updaterRef.current = new OtaUpdater(config, fileSystem);
+  }
+
+  const updater = updaterRef.current;
+  const [state, setState] = useState<UpdateState>(updater.getState());
+
+  useEffect(() => {
+    const unsub = updater.subscribe(setState);
+    return unsub;
+  }, [updater]);
+
+  // Check on foreground (AppState active)
+  useEffect(() => {
+    if (config.checkOnForeground === false) return;
+
+    const handler = (nextState: AppStateStatus) => {
+      if (nextState === 'active') {
+        updater.checkForUpdates();
+      }
+    };
+
+    const sub = AppState.addEventListener('change', handler);
+
+    // Initial check on mount
+    updater.checkForUpdates();
+
+    return () => sub.remove();
+  }, [updater, config.checkOnForeground]);
+
+  const value: OtaContextValue = {
+    state,
+    checkForUpdates: () => updater.checkForUpdates(),
+    downloadUpdate: () => updater.downloadUpdate(),
+    applyUpdate: () => updater.applyUpdate(),
+    rollback: () => updater.rollback(),
+  };
+
+  return <OtaContext.Provider value={value}>{children}</OtaContext.Provider>;
+}
+
+export function useOtaContext(): OtaContextValue {
+  const ctx = useContext(OtaContext);
+  if (!ctx) throw new Error('useOtaContext must be used inside <OtaProvider>');
+  return ctx;
+}

package/src/storage.ts

@@ -0,0 +1,42 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { OtaCheckResponse } from './types';
+
+const KEY_PENDING_RELEASE = '@ota/pending_release';
+const KEY_APPLIED_RELEASE = '@ota/applied_release';
+const KEY_BUNDLE_PATH = '@ota/bundle_path';
+
+type StoredRelease = NonNullable<OtaCheckResponse['release']>;
+
+export async function storePendingRelease(release: StoredRelease): Promise<void> {
+  await AsyncStorage.setItem(KEY_PENDING_RELEASE, JSON.stringify(release));
+}
+
+export async function getPendingRelease(): Promise<StoredRelease | null> {
+  const raw = await AsyncStorage.getItem(KEY_PENDING_RELEASE);
+  return raw ? (JSON.parse(raw) as StoredRelease) : null;
+}
+
+export async function clearPendingRelease(): Promise<void> {
+  await AsyncStorage.removeItem(KEY_PENDING_RELEASE);
+}
+
+export async function storeAppliedRelease(release: StoredRelease): Promise<void> {
+  await AsyncStorage.setItem(KEY_APPLIED_RELEASE, JSON.stringify(release));
+}
+
+export async function getAppliedRelease(): Promise<StoredRelease | null> {
+  const raw = await AsyncStorage.getItem(KEY_APPLIED_RELEASE);
+  return raw ? (JSON.parse(raw) as StoredRelease) : null;
+}
+
+export async function storeBundlePath(path: string): Promise<void> {
+  await AsyncStorage.setItem(KEY_BUNDLE_PATH, path);
+}
+
+export async function getBundlePath(): Promise<string | null> {
+  return AsyncStorage.getItem(KEY_BUNDLE_PATH);
+}
+
+export async function clearBundlePath(): Promise<void> {
+  await AsyncStorage.removeItem(KEY_BUNDLE_PATH);
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+export type Platform = 'IOS' | 'ANDROID';
+
+export interface OtaCheckRequest {
+  appId: string;
+  platform: Platform;
+  currentVersion: string;
+  runtimeVersion: string;
+  channel: string;
+}
+
+export interface OtaCheckResponse {
+  updateAvailable: boolean;
+  release?: {
+    id: string;
+    version: string;
+    downloadUrl: string;
+    checksum: string;
+    fileSize: number;
+    isMandatory: boolean;
+    releaseNotes?: string;
+    metadata?: Record<string, unknown>;
+  };
+}
+
+export interface OtaConfig {
+  serverUrl: string;
+  appId: string;
+  channel: string;
+  platform: Platform;
+  currentVersion: string;
+  runtimeVersion: string;
+  checkOnForeground?: boolean;
+  onUpdate?: (release: NonNullable<OtaCheckResponse['release']>) => void;
+  onError?: (error: Error) => void;
+}
+
+export type UpdateStatus =
+  | 'idle'
+  | 'checking'
+  | 'up_to_date'
+  | 'update_available'
+  | 'downloading'
+  | 'ready'
+  | 'error';
+
+export interface UpdateState {
+  status: UpdateStatus;
+  progress: number;
+  release: NonNullable<OtaCheckResponse['release']> | null;
+  error: Error | null;
+  localBundlePath: string | null;
+}
+
+export interface IFileSystemAdapter {
+  getDocumentDirectory(): string;
+  exists(path: string): Promise<boolean>;
+  readAsString(path: string, encoding: 'utf8' | 'base64'): Promise<string>;
+  writeAsString(path: string, content: string, encoding: 'utf8' | 'base64'): Promise<void>;
+  deleteFile(path: string): Promise<void>;
+  makeDirectory(path: string): Promise<void>;
+}
+
+export interface INativeBundleUpdater {
+  setBundlePath(path: string): Promise<void>;
+  getBundlePath(): Promise<string | null>;
+  clearBundlePath(): Promise<void>;
+  reload(): void;
+}

package/src/updater.ts

@@ -0,0 +1,115 @@
+import { checkForUpdate } from './client';
+import { downloadBundle } from './downloader';
+import { setStagedBundlePath, clearStagedBundlePath, reload } from './installer';
+import {
+  storePendingRelease,
+  clearPendingRelease,
+  storeAppliedRelease,
+  getAppliedRelease,
+  storeBundlePath,
+  clearBundlePath,
+} from './storage';
+import type { OtaConfig, UpdateState, IFileSystemAdapter } from './types';
+
+export type StateListener = (state: UpdateState) => void;
+
+const initialState: UpdateState = {
+  status: 'idle',
+  progress: 0,
+  release: null,
+  error: null,
+  localBundlePath: null,
+};
+
+export class OtaUpdater {
+  private state: UpdateState = { ...initialState };
+  private listeners: Set<StateListener> = new Set();
+  private config: OtaConfig;
+  private fs: IFileSystemAdapter;
+
+  constructor(config: OtaConfig, fs: IFileSystemAdapter) {
+    this.config = config;
+    this.fs = fs;
+  }
+
+  getState(): UpdateState {
+    return this.state;
+  }
+
+  subscribe(listener: StateListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private emit(patch: Partial<UpdateState>): void {
+    this.state = { ...this.state, ...patch };
+    this.listeners.forEach((l) => l(this.state));
+  }
+
+  async checkForUpdates(): Promise<void> {
+    if (this.state.status === 'checking' || this.state.status === 'downloading') return;
+
+    this.emit({ status: 'checking', error: null });
+    try {
+      const applied = await getAppliedRelease();
+      const currentVersion = applied?.version ?? this.config.currentVersion;
+      const result = await checkForUpdate(this.config.serverUrl, {
+        appId: this.config.appId,
+        channel: this.config.channel,
+        platform: this.config.platform,
+        currentVersion,
+        runtimeVersion: this.config.runtimeVersion,
+      });
+
+      if (!result.updateAvailable || !result.release) {
+        this.emit({ status: 'up_to_date', release: null });
+        return;
+      }
+
+      this.emit({ status: 'update_available', release: result.release });
+      await storePendingRelease(result.release);
+      this.config.onUpdate?.(result.release);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emit({ status: 'error', error });
+      this.config.onError?.(error);
+    }
+  }
+
+  async downloadUpdate(): Promise<void> {
+    if (!this.state.release || this.state.status !== 'update_available') return;
+
+    const release = this.state.release;
+    this.emit({ status: 'downloading', progress: 0 });
+
+    try {
+      const bundlePath = await downloadBundle(release, this.fs, (progress) => {
+        this.emit({ progress });
+      });
+
+      await setStagedBundlePath(bundlePath);
+      await storeBundlePath(bundlePath);
+
+      this.emit({ status: 'ready', localBundlePath: bundlePath, progress: 100 });
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emit({ status: 'error', error });
+      this.config.onError?.(error);
+    }
+  }
+
+  async applyUpdate(): Promise<void> {
+    if (this.state.status !== 'ready' || !this.state.release) return;
+    await storeAppliedRelease(this.state.release);
+    await clearPendingRelease();
+    reload();
+  }
+
+  async rollback(): Promise<void> {
+    await clearStagedBundlePath();
+    await clearBundlePath();
+    await clearPendingRelease();
+    this.emit({ ...initialState, status: 'idle' });
+    reload();
+  }
+}