@rovq/react-native 0.0.0-stage → 0.2.0

package/ios/React/RovqModule.mm

@@ -0,0 +1,91 @@
+// Objective-C++ because a TurboModule must return a C++ object. The work happens in Swift.
+#import <Foundation/Foundation.h>
+#import <RovqSpec/RovqSpec.h>
+#import <React/RCTReloadCommand.h>
+#import <React/RCTUtils.h>
+
+#if __has_include(<Rovq/Rovq-Swift.h>)
+#import <Rovq/Rovq-Swift.h>
+#else
+#import "Rovq-Swift.h"
+#endif
+
+@interface RovqModule : NativeRovqSpecBase <NativeRovqSpec>
+@end
+
+@implementation RovqModule
+
+RCT_EXPORT_MODULE(Rovq)
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+  return std::make_shared<facebook::react::NativeRovqSpecJSI>(params);
+}
+
+- (void)checkForUpdate:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [RovqHost checkForUpdateWithCompletion:^(NSDictionary<NSString *, id> *result) {
+    resolve(result);
+  }];
+}
+
+- (void)downloadUpdate:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [RovqHost downloadUpdateOnProgress:[self progressReporter]
+                              completion:^(NSDictionary<NSString *, id> *result) {
+                                resolve(result);
+                              }];
+}
+
+- (void)installUpdate:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [RovqHost installUpdateWithCompletion:^(NSDictionary<NSString *, id> *result) {
+    resolve(result);
+  }];
+}
+
+- (void)sync:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [RovqHost syncOnProgress:[self progressReporter]
+                    completion:^(NSDictionary<NSString *, id> *result) {
+                      resolve(result);
+                    }];
+}
+
+// Weak, because a download keeps running through a reload, when this module has gone.
+- (void (^)(int64_t, int64_t))progressReporter
+{
+  __weak RovqModule *weakSelf = self;
+  return ^(int64_t received, int64_t total) {
+    [weakSelf emitOnDownloadProgress:@{@"receivedBytes" : @(received), @"totalBytes" : @(total)}];
+  };
+}
+
+- (void)notifyApplicationReady
+{
+  [RovqHost notifyReady];
+}
+
+- (void)restartApp
+{
+  // Always later, never at once: RCTExecuteOnMainQueue runs immediately when already on the main
+  // thread, which reloads JavaScript while it is still inside this call.
+  dispatch_async(dispatch_get_main_queue(), ^{
+    RCTTriggerReloadCommandListeners(@"ROVQ restart");
+  });
+}
+
+- (void)rollback:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [RovqHost rollbackWithCompletion:^(BOOL result) {
+    resolve(@(result));
+  }];
+}
+
+- (void)getStatus:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  resolve([RovqHost status]);
+}
+
+@end

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@rovq/react-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Over-the-air updates for React Native, with signed releases and automatic rollback",
+  "keywords": [
+    "react-native",
+    "ota",
+    "over-the-air",
+    "updates",
+    "codepush",
+    "hot-update",
+    "rollback"
+  ],
+  "license": "MIT",
+  "author": "moatazMahdi",
+  "homepage": "https://github.com/moatazMahdi/rovq#readme",
+  "bugs": "https://github.com/moatazMahdi/rovq/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moatazMahdi/rovq.git",
+    "directory": "packages/react-native"
+  },
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "android/src/main",
+    "android/src/react",
+    "android/build.gradle",
+    "ios/Engine",
+    "ios/React",
+    "Rovq.podspec",
+    "react-native.config.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": "*",
+    "react-native": ">=0.82"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "codegenConfig": {
+    "name": "RovqSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.rovq.engine.react"
+    },
+    "ios": {
+      "modulesProvider": {
+        "Rovq": "RovqModule"
+      }
+    }
+  },
+  "devDependencies": {
+    "@swc/core": "1.16.22",
+    "@swc/jest": "0.2.39",
+    "@types/jest": "30.0.0",
+    "@types/react": "^19.3.0",
+    "jest": "30.5.2",
+    "react": "19.3.0",
+    "react-native": "0.88.1",
+    "typescript": "~6.0.3",
+    "@types/node": "^24.19.2"
+  },
+  "react-native": "src/index.ts",
+  "types": "src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "jest",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/react-native.config.js

@@ -0,0 +1,11 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        // The module lives apart from the engine, so autolinking cannot guess its package.
+        packageImportPath: 'import com.rovq.engine.react.RovqPackage;',
+        packageInstance: 'new RovqPackage()',
+      },
+    },
+  },
+};

package/src/NativeRovq.ts

@@ -0,0 +1,72 @@
+import type { CodegenTypes, TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+// React Native generates the native base classes from this file, and its code generator cannot
+// express a union of object shapes. So these are flat, and index.ts turns them into the types
+// that apps use. Only `react-native` and this file's own types may appear here.
+
+export interface NativeUpdate {
+  releaseId: string;
+  sequence: number;
+  mandatory: boolean;
+  packageSize: number;
+}
+
+export interface NativeCheckResult {
+  result: string;
+  update?: NativeUpdate;
+  alreadyDownloaded?: boolean;
+  code?: string;
+  message?: string;
+}
+
+export interface NativeDownloadResult {
+  result: string;
+  update?: NativeUpdate;
+  code?: string;
+  message?: string;
+}
+
+export interface NativeInstallResult {
+  result: string;
+  releaseId?: string;
+  code?: string;
+  message?: string;
+}
+
+export interface NativeSyncResult {
+  result: string;
+  releaseId?: string;
+  mandatory?: boolean;
+  code?: string;
+  message?: string;
+}
+
+/** Empty if the engine is not running. */
+export interface NativeStatus {
+  deviceId?: string;
+  currentReleaseId?: string | null;
+  downloadedReleaseId?: string | null;
+  pendingReleaseId?: string | null;
+  tryingReleaseId?: string | null;
+  highestSequence?: number;
+}
+
+export interface NativeDownloadProgress {
+  receivedBytes: number;
+  totalBytes: number;
+}
+
+export interface Spec extends TurboModule {
+  checkForUpdate(): Promise<NativeCheckResult>;
+  downloadUpdate(): Promise<NativeDownloadResult>;
+  installUpdate(): Promise<NativeInstallResult>;
+  sync(): Promise<NativeSyncResult>;
+  notifyApplicationReady(): void;
+  restartApp(): void;
+  rollback(): Promise<boolean>;
+  getStatus(): Promise<NativeStatus>;
+  readonly onDownloadProgress: CodegenTypes.EventEmitter<NativeDownloadProgress>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('Rovq');

package/src/api.ts

@@ -0,0 +1,228 @@
+import { RovqError, toRovqError } from './errors';
+import Native from './NativeRovq';
+import type { NativeUpdate } from './NativeRovq';
+
+export { RovqError } from './errors';
+export type { RovqErrorCode } from './errors';
+
+/** Comes from a manifest whose signature the device has already verified. */
+export interface UpdateInfo {
+  releaseId: string;
+  sequence: number;
+  mandatory: boolean;
+  packageSizeBytes: number;
+}
+
+export type CheckResult =
+  | { status: 'UP_TO_DATE' }
+  /** The server stopped the running release. It takes effect on the next restart. */
+  | { status: 'ROLLED_BACK' }
+  /** `alreadyDownloaded` means `downloadUpdate` has nothing left to fetch. */
+  | { status: 'UPDATE_AVAILABLE'; update: UpdateInfo; alreadyDownloaded: boolean };
+
+export type SyncResult =
+  | { status: 'UP_TO_DATE' }
+  | { status: 'ROLLED_BACK' }
+  /** Installed. It loads on the next restart. */
+  | { status: 'UPDATE_READY'; releaseId: string; mandatory: boolean };
+
+export interface DownloadProgress {
+  receivedBytes: number;
+  totalBytes: number;
+}
+
+export interface DownloadOptions {
+  /** Called when the whole percentage changes, so at most about 100 times. */
+  onProgress?: (progress: DownloadProgress) => void;
+}
+
+export interface CurrentUpdate {
+  releaseId: string;
+  /** False until `notifyApplicationReady`. Without it, the next start abandons this release. */
+  confirmed: boolean;
+}
+
+export interface EngineStatus {
+  deviceId: string;
+  currentReleaseId: string | null;
+  downloadedReleaseId: string | null;
+  pendingReleaseId: string | null;
+  tryingReleaseId: string | null;
+  highestSequence: number;
+}
+
+interface NativeFailure {
+  result: string;
+  code?: string;
+  message?: string;
+}
+
+function failureOf(answer: NativeFailure): RovqError {
+  return answer.result === 'FAILED'
+    ? toRovqError(answer.code, answer.message)
+    : new RovqError('UNKNOWN', `Unexpected answer from the update engine: ${answer.result}`);
+}
+
+function toUpdateInfo(update: NativeUpdate): UpdateInfo {
+  return {
+    releaseId: update.releaseId,
+    sequence: update.sequence,
+    mandatory: update.mandatory,
+    packageSizeBytes: update.packageSize,
+  };
+}
+
+/** Native promises reject only on an unexpected failure, which still gets the SDK's error type. */
+async function callNative<T>(call: () => Promise<T>): Promise<T> {
+  try {
+    return await call();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new RovqError('UNKNOWN', message, { cause: error });
+  }
+}
+
+async function withProgress<T>(options: DownloadOptions, call: () => Promise<T>): Promise<T> {
+  const { onProgress } = options;
+  if (onProgress === undefined) return callNative(call);
+  const subscription = Native.onDownloadProgress((progress) => {
+    // A bug in a progress bar must not become a fatal error, which would roll back this release.
+    try {
+      onProgress({ receivedBytes: progress.receivedBytes, totalBytes: progress.totalBytes });
+    } catch (error) {
+      console.warn('ROVQ: onProgress threw an error', error);
+    }
+  });
+  try {
+    return await callNative(call);
+  } finally {
+    subscription.remove();
+  }
+}
+
+/**
+ * Asks the server for an update, and verifies any offer before returning it.
+ *
+ * If the server has disabled the running release, this also rolls it back, and that takes
+ * effect on the next restart.
+ *
+ * @throws RovqError
+ */
+export async function checkForUpdate(): Promise<CheckResult> {
+  const answer = await callNative(() => Native.checkForUpdate());
+  switch (answer.result) {
+    case 'UP_TO_DATE':
+    case 'ROLLED_BACK':
+      return { status: answer.result };
+    case 'UPDATE_AVAILABLE':
+      if (answer.update === undefined) throw failureOf(answer);
+      return {
+        status: 'UPDATE_AVAILABLE',
+        update: toUpdateInfo(answer.update),
+        alreadyDownloaded: answer.alreadyDownloaded ?? false,
+      };
+    default:
+      throw failureOf(answer);
+  }
+}
+
+/**
+ * Downloads and verifies the update found by the last `checkForUpdate`. Nothing runs it until
+ * `installUpdate`.
+ *
+ * @throws RovqError with `NO_UPDATE_AVAILABLE` if there was no check since the app started.
+ */
+export async function downloadUpdate(options: DownloadOptions = {}): Promise<UpdateInfo> {
+  const answer = await withProgress(options, () => Native.downloadUpdate());
+  if (answer.result !== 'DOWNLOADED' || answer.update === undefined) throw failureOf(answer);
+  return toUpdateInfo(answer.update);
+}
+
+/**
+ * Makes the downloaded update load on the next restart. It needs no network.
+ *
+ * @returns the ID of the release that will load.
+ * @throws RovqError with `NO_UPDATE_DOWNLOADED` if there is nothing to install.
+ */
+export async function installUpdate(): Promise<string> {
+  const answer = await callNative(() => Native.installUpdate());
+  if (answer.result !== 'INSTALLED' || answer.releaseId === undefined) throw failureOf(answer);
+  return answer.releaseId;
+}
+
+/**
+ * Checks, downloads, and installs in one call, for an app that does not ask the user first.
+ *
+ * @throws RovqError
+ */
+export async function sync(options: DownloadOptions = {}): Promise<SyncResult> {
+  const answer = await withProgress(options, () => Native.sync());
+  switch (answer.result) {
+    case 'UP_TO_DATE':
+    case 'ROLLED_BACK':
+      return { status: answer.result };
+    case 'UPDATE_READY':
+      if (answer.releaseId === undefined) throw failureOf(answer);
+      return {
+        status: 'UPDATE_READY',
+        releaseId: answer.releaseId,
+        mandatory: answer.mandatory ?? false,
+      };
+    default:
+      throw failureOf(answer);
+  }
+}
+
+/** Reloads JavaScript in the same process, which applies an installed update or rollback. */
+export function restartApp(): void {
+  Native.restartApp();
+}
+
+/**
+ * Confirms that this release works. Call it once the app has started properly.
+ * **A release that never calls this is abandoned on the next start.**
+ */
+export function notifyApplicationReady(): void {
+  Native.notifyApplicationReady();
+}
+
+/**
+ * Goes back to the previous confirmed release, or to the bundle inside the app. It takes
+ * effect on the next restart.
+ *
+ * @returns whether there was anything to leave.
+ */
+export async function rollback(): Promise<boolean> {
+  return callNative(() => Native.rollback());
+}
+
+/**
+ * @throws RovqError with `ENGINE_UNAVAILABLE` if the native side was not set up.
+ */
+export async function getStatus(): Promise<EngineStatus> {
+  const status = await callNative(() => Native.getStatus());
+  if (status.deviceId === undefined) {
+    throw new RovqError('ENGINE_UNAVAILABLE', 'The update engine is not running');
+  }
+  return {
+    deviceId: status.deviceId,
+    currentReleaseId: status.currentReleaseId ?? null,
+    downloadedReleaseId: status.downloadedReleaseId ?? null,
+    pendingReleaseId: status.pendingReleaseId ?? null,
+    tryingReleaseId: status.tryingReleaseId ?? null,
+    highestSequence: status.highestSequence ?? 0,
+  };
+}
+
+/**
+ * @returns the update running now, or null for the bundle inside the app.
+ * @throws RovqError with `ENGINE_UNAVAILABLE` if the native side was not set up.
+ */
+export async function getCurrentUpdate(): Promise<CurrentUpdate | null> {
+  const status = await getStatus();
+  if (status.currentReleaseId === null) return null;
+  return {
+    releaseId: status.currentReleaseId,
+    confirmed: status.tryingReleaseId === null,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,44 @@
+/** Every reason an SDK call can fail. Native code has the same list, and a test keeps them equal. */
+export const ROVQ_ERROR_CODES = [
+  // The update failed its security checks, so the device refused it.
+  'UNKNOWN_SIGNING_KEY',
+  'REVOKED_SIGNING_KEY',
+  'INVALID_SIGNATURE',
+  'INVALID_MANIFEST',
+  'MANIFEST_MISMATCH',
+  'STALE_SEQUENCE',
+  'INSECURE_URL',
+  'SIZE_MISMATCH',
+  'HASH_MISMATCH',
+  'INVALID_PACKAGE',
+  // The network or the disk failed, so trying again later can work.
+  'DOWNLOAD_FAILED',
+  'STORAGE_FAILED',
+  // Failed its checks recently, so the engine waits before downloading the same file again.
+  'DOWNLOAD_POSTPONED',
+  // The app called the SDK out of order, or without setting up the native side.
+  'NO_UPDATE_AVAILABLE',
+  'NO_UPDATE_DOWNLOADED',
+  'ENGINE_UNAVAILABLE',
+] as const;
+
+export type RovqErrorCode = (typeof ROVQ_ERROR_CODES)[number] | 'UNKNOWN';
+
+const known: ReadonlySet<string> = new Set(ROVQ_ERROR_CODES);
+
+/** Compare `code`, not `message`. Codes are stable, and messages are for logs. */
+export class RovqError extends Error {
+  readonly code: RovqErrorCode;
+
+  constructor(code: RovqErrorCode, message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'RovqError';
+    this.code = code;
+  }
+}
+
+/** A code this SDK does not know means the native side is newer, so it is reported as unknown. */
+export function toRovqError(code: string | undefined, message: string | undefined): RovqError {
+  const safeCode = code !== undefined && known.has(code) ? (code as RovqErrorCode) : 'UNKNOWN';
+  return new RovqError(safeCode, message ?? code ?? 'The update engine reported a failure');
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './api';
+export { runUpdateFlow } from './update-flow';
+export type { UpdateMode, UpdatePhase, UpdateState } from './update-flow';
+export { RovqUpdateGate, RovqUpdateProgress, useRovqUpdate } from './react';
+export type {
+  RovqUpdateGateProps,
+  RovqUpdateProgressProps,
+  UseRovqUpdate,
+  UseRovqUpdateOptions,
+} from './react';

package/src/react.tsx

@@ -0,0 +1,158 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+import type { StyleProp, TextStyle, ViewStyle } from 'react-native';
+import { notifyApplicationReady } from './api';
+import { INITIAL_STATE, runUpdateFlow } from './update-flow';
+import type { UpdateMode, UpdateState } from './update-flow';
+
+export interface UseRovqUpdateOptions {
+  /** Defaults to `auto`, which follows the `--mandatory` flag of each release. */
+  mode?: UpdateMode;
+  /** Checks as soon as the component mounts. Defaults to true. */
+  checkOnMount?: boolean;
+  /**
+   * Confirms that this release works, which a release must do or it is abandoned on the next
+   * start. Defaults to true. Turn it off to call `notifyApplicationReady` yourself, later.
+   */
+  notifyReady?: boolean;
+}
+
+export interface UseRovqUpdate extends UpdateState {
+  /** Checks again. Does nothing while a check is already running. */
+  check: () => Promise<void>;
+}
+
+export function useRovqUpdate(options: UseRovqUpdateOptions = {}): UseRovqUpdate {
+  const { mode = 'auto', checkOnMount = true, notifyReady = true } = options;
+  const [state, setState] = useState<UpdateState>(INITIAL_STATE);
+  const running = useRef(false);
+  const mounted = useRef(true);
+
+  const check = useCallback(async () => {
+    if (running.current) return;
+    running.current = true;
+    try {
+      await runUpdateFlow(mode, (next) => {
+        if (mounted.current) setState(next);
+      });
+    } finally {
+      running.current = false;
+    }
+  }, [mode]);
+
+  useEffect(() => {
+    mounted.current = true;
+    if (notifyReady) notifyApplicationReady();
+    if (checkOnMount) void check();
+    return () => {
+      mounted.current = false;
+    };
+    // Runs once, on mount.
+  }, []);
+
+  return { ...state, check };
+}
+
+export interface RovqUpdateProgressProps {
+  /** From 0 to 1. */
+  progress: number;
+  /** `bar` draws a line that fills up, and `percent` shows a number. Defaults to `bar`. */
+  variant?: 'bar' | 'percent';
+  color?: string;
+  trackColor?: string;
+  /** Height of the bar. */
+  height?: number;
+  style?: StyleProp<ViewStyle>;
+  textStyle?: StyleProp<TextStyle>;
+}
+
+export function RovqUpdateProgress({
+  progress,
+  variant = 'bar',
+  color = '#16a34a',
+  trackColor = '#e4e4e7',
+  height = 6,
+  style,
+  textStyle,
+}: RovqUpdateProgressProps) {
+  const percent = Math.max(0, Math.min(100, Math.round(progress * 100)));
+  if (variant === 'percent') {
+    return (
+      <Text
+        style={[styles.percent, textStyle]}
+        accessibilityRole="progressbar"
+        accessibilityValue={{ min: 0, max: 100, now: percent }}
+      >
+        {percent}%
+      </Text>
+    );
+  }
+  return (
+    <View
+      style={[
+        styles.track,
+        { height, borderRadius: height / 2, backgroundColor: trackColor },
+        style,
+      ]}
+      accessibilityRole="progressbar"
+      accessibilityValue={{ min: 0, max: 100, now: percent }}
+    >
+      <View
+        style={{ width: `${percent}%`, height, borderRadius: height / 2, backgroundColor: color }}
+      />
+    </View>
+  );
+}
+
+export interface RovqUpdateGateProps extends UseRovqUpdateOptions {
+  children: ReactNode;
+  variant?: 'bar' | 'percent';
+  /** Shown above the progress. Defaults to "Updating…". */
+  title?: string;
+  color?: string;
+  backgroundColor?: string;
+  /** Draws your own screen in place of the default one. */
+  renderProgress?: (state: UpdateState) => ReactNode;
+}
+
+/**
+ * Wraps the app. A foreground update covers it with a progress screen, then restarts. Anything
+ * else shows the app as usual, including while checking, so a slow server never holds it up.
+ */
+export function RovqUpdateGate({
+  children,
+  variant = 'bar',
+  title = 'Updating…',
+  color,
+  backgroundColor = '#ffffff',
+  renderProgress,
+  ...options
+}: RovqUpdateGateProps) {
+  const state = useRovqUpdate(options);
+  const covering =
+    state.foreground &&
+    (state.phase === 'downloading' || state.phase === 'installing' || state.phase === 'restarting');
+  if (!covering) return <>{children}</>;
+  if (renderProgress) return <>{renderProgress(state)}</>;
+  return (
+    <View style={[styles.screen, { backgroundColor }]}>
+      <Text style={styles.title}>{title}</Text>
+      <View style={styles.progress}>
+        <RovqUpdateProgress
+          progress={state.progress ?? 1}
+          variant={variant}
+          {...(color ? { color } : {})}
+        />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  percent: { fontSize: 16, fontVariant: ['tabular-nums'] },
+  track: { width: '100%', overflow: 'hidden' },
+  screen: { flex: 1, alignItems: 'center', justifyContent: 'center', padding: 32 },
+  title: { fontSize: 17, fontWeight: '600', marginBottom: 16 },
+  progress: { width: '100%', maxWidth: 280, alignItems: 'center' },
+});