@otaupdate/react-native 1.0.0

package/src/OtaUpdate.ts

@@ -0,0 +1,293 @@
+import { AppState, type AppStateStatus } from 'react-native';
+import { fetchUpdate, OtaApiError, reportStatus } from './api';
+import { NativeOtaUpdate, isNativeModuleAvailable, onDownloadProgress } from './native';
+import {
+  InstallMode,
+  SyncStatus,
+  type CheckResult,
+  type CurrentPackage,
+  type DownloadProgress,
+  type LocalPackage,
+  type OtaConfiguration,
+  type OtaOptions,
+  type RemotePackage,
+  type SyncOptions,
+} from './types';
+
+let cachedConfig: OtaConfiguration | null = null;
+let syncInFlight: Promise<SyncStatus> | null = null;
+let lastSyncAt = 0;
+let appReadyNotified = false;
+
+async function getConfiguration(overrideDeploymentKey?: string): Promise<OtaConfiguration> {
+  if (!cachedConfig) {
+    cachedConfig = await NativeOtaUpdate.getConfiguration();
+  }
+  // Re-read the running package on every call: it changes after an install.
+  const current = await NativeOtaUpdate.getCurrentPackage().catch(() => null);
+  return {
+    ...cachedConfig,
+    deploymentKey: overrideDeploymentKey ?? cachedConfig.deploymentKey,
+    packageHash: (current?.packageHash as string | undefined) ?? null,
+    label: (current?.label as string | undefined) ?? null,
+  };
+}
+
+function assertConfigured(config: OtaConfiguration): void {
+  if (!config.deploymentKey) {
+    throw new Error(
+      'No deployment key configured. Set OtaDeploymentKey in Info.plist (iOS) / ' +
+        'ota_deployment_key in strings.xml (Android), or pass `deploymentKey` to sync(). ' +
+        'With Expo, set it in the config plugin options.',
+    );
+  }
+  if (!config.serverUrl) {
+    throw new Error(
+      'No OTA server URL configured. Set OtaServerUrl (iOS) / ota_server_url (Android), ' +
+        'or the `serverUrl` config plugin option.',
+    );
+  }
+}
+
+function toRemotePackage(
+  info: Record<string, any>,
+  config: OtaConfiguration,
+): RemotePackage {
+  const remote: RemotePackage = {
+    label: info.label,
+    packageHash: info.packageHash,
+    downloadUrl: info.downloadUrl ?? info.downloadURL,
+    size: info.size ?? 0,
+    isMandatory: Boolean(info.isMandatory),
+    description: info.description ?? null,
+    targetBinaryVersion: info.targetBinaryVersion ?? '',
+    rollout: info.rollout ?? 100,
+    isRollback: Boolean(info.isRollback),
+    deployment: info.deployment ?? '',
+    async download(onProgress?: (progress: DownloadProgress) => void): Promise<LocalPackage> {
+      const subscription = onProgress ? onDownloadProgress(onProgress) : null;
+      try {
+        // The native side verifies the SHA-256 before unzipping, so a corrupt
+        // or tampered download rejects here rather than bricking the app.
+        const result = await NativeOtaUpdate.downloadUpdate({
+          label: remote.label,
+          packageHash: remote.packageHash,
+          downloadUrl: remote.downloadUrl,
+          size: remote.size,
+          isMandatory: remote.isMandatory,
+          description: remote.description,
+        });
+        void reportStatus(config, 'downloaded', { label: remote.label });
+        return toLocalPackage(result, remote);
+      } finally {
+        subscription?.remove();
+      }
+    },
+  };
+  return remote;
+}
+
+function toLocalPackage(
+  result: { bundlePath: string; packageHash: string; label: string; size: number },
+  remote: RemotePackage,
+): LocalPackage {
+  return {
+    label: result.label,
+    packageHash: result.packageHash,
+    isMandatory: remote.isMandatory,
+    description: remote.description,
+    bundlePath: result.bundlePath,
+    size: result.size,
+    async install(
+      mode: InstallMode = InstallMode.ON_NEXT_RESTART,
+      minimumBackgroundDuration = 0,
+    ): Promise<void> {
+      await NativeOtaUpdate.installUpdate(result.packageHash, mode, minimumBackgroundDuration);
+      // No status report here on purpose. `download()` already recorded
+      // 'downloaded', and reporting again would double-count the metric; the
+      // next signal is 'success' from notifyAppReady() once the new bundle
+      // actually boots.
+    },
+  };
+}
+
+/** Asks the server whether a newer bundle applies to this device. */
+export async function checkForUpdate(deploymentKey?: string): Promise<CheckResult> {
+  const config = await getConfiguration(deploymentKey);
+  assertConfigured(config);
+
+  const { raw, reason, updateAppVersion } = await fetchUpdate(config);
+  if (!raw.isAvailable) return { update: null, reason, updateAppVersion };
+  return { update: toRemotePackage(raw, config) };
+}
+
+/**
+ * Check → download → install, in one call. Safe to call repeatedly; concurrent
+ * calls share the in-flight run rather than downloading twice.
+ */
+export async function sync(options: SyncOptions = {}): Promise<SyncStatus> {
+  if (syncInFlight) {
+    options.onSyncStatusChange?.(SyncStatus.SYNC_IN_PROGRESS);
+    return syncInFlight;
+  }
+  syncInFlight = runSync(options).finally(() => {
+    syncInFlight = null;
+    lastSyncAt = Date.now();
+  });
+  return syncInFlight;
+}
+
+async function runSync(options: SyncOptions): Promise<SyncStatus> {
+  const notify = (status: SyncStatus) => options.onSyncStatusChange?.(status);
+
+  try {
+    notify(SyncStatus.CHECKING_FOR_UPDATE);
+    const config = await getConfiguration(options.deploymentKey);
+    assertConfigured(config);
+
+    const { update } = await checkForUpdate(options.deploymentKey);
+    if (!update) {
+      notify(SyncStatus.UP_TO_DATE);
+      return SyncStatus.UP_TO_DATE;
+    }
+
+    if (!update.isMandatory && options.shouldInstall) {
+      notify(SyncStatus.AWAITING_USER_ACTION);
+      const proceed = await options.shouldInstall(update);
+      if (!proceed) {
+        notify(SyncStatus.UPDATE_IGNORED);
+        return SyncStatus.UPDATE_IGNORED;
+      }
+    }
+
+    notify(SyncStatus.DOWNLOADING_PACKAGE);
+    const local = await update.download(options.onDownloadProgress);
+
+    notify(SyncStatus.INSTALLING_UPDATE);
+    const mode = update.isMandatory
+      ? (options.mandatoryInstallMode ?? InstallMode.IMMEDIATE)
+      : (options.installMode ?? InstallMode.ON_NEXT_RESTART);
+    await local.install(mode, options.minimumBackgroundDuration ?? 0);
+
+    notify(SyncStatus.UPDATE_INSTALLED);
+    return SyncStatus.UPDATE_INSTALLED;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // A sync failure must never take the app down — surface it and move on.
+    if (!(err instanceof OtaApiError)) {
+      console.warn(`[ota-update] sync failed: ${message}`);
+    }
+    try {
+      const config = await getConfiguration(options.deploymentKey);
+      void reportStatus(config, 'failed', { error: message });
+    } catch {
+      /* configuration itself was unavailable */
+    }
+    notify(SyncStatus.UNKNOWN_ERROR);
+    return SyncStatus.UNKNOWN_ERROR;
+  }
+}
+
+/**
+ * Confirms the running bundle works. Until this is called, the next app start
+ * treats the update as broken and rolls back to the previous bundle.
+ *
+ * Call it once your app has rendered and its critical startup path has run.
+ */
+export async function notifyAppReady(): Promise<void> {
+  if (appReadyNotified) return;
+  appReadyNotified = true;
+  await NativeOtaUpdate.notifyApplicationReady();
+
+  try {
+    const config = await getConfiguration();
+    const current = await NativeOtaUpdate.getCurrentPackage();
+    if (current?.label) {
+      void reportStatus(config, 'success', { label: current.label as string });
+    }
+  } catch {
+    /* reporting is best-effort */
+  }
+}
+
+export async function restartApp(onlyIfUpdateIsPending = false): Promise<void> {
+  await NativeOtaUpdate.restartApp(onlyIfUpdateIsPending);
+}
+
+export async function getCurrentPackage(): Promise<CurrentPackage | null> {
+  const raw = await NativeOtaUpdate.getCurrentPackage();
+  if (!raw) return null;
+  return {
+    label: (raw.label as string) ?? null,
+    packageHash: (raw.packageHash as string) ?? null,
+    description: (raw.description as string) ?? null,
+    isMandatory: Boolean(raw.isMandatory),
+    bundlePath: (raw.bundlePath as string) ?? null,
+    appVersion: (raw.appVersion as string) ?? '',
+    isPending: Boolean(raw.isPending),
+    isFirstRun: Boolean(raw.isFirstRun),
+  };
+}
+
+/** Wipes every downloaded package and reverts to the bundle inside the binary. */
+export async function clearUpdates(): Promise<void> {
+  await NativeOtaUpdate.clearUpdates();
+}
+
+export async function getConfig(): Promise<OtaConfiguration> {
+  return getConfiguration();
+}
+
+// --- Automatic lifecycle wiring ---------------------------------------------
+
+let lifecycleSubscription: { remove: () => void } | null = null;
+
+/**
+ * Starts the app-start / app-resume sync loop. `withOtaUpdate` calls this for
+ * you; call it directly if you are not using the HOC.
+ */
+export function startAutoSync(options: OtaOptions = {}): () => void {
+  const {
+    checkOnAppStart = true,
+    checkOnResume = true,
+    minimumSyncInterval = 60,
+    sync: syncOptions = {},
+  } = options;
+
+  if (!isNativeModuleAvailable) {
+    console.warn(
+      '[ota-update] native module unavailable — auto-sync disabled. ' +
+        'This is expected in Expo Go and on web.',
+    );
+    return () => undefined;
+  }
+
+  // Confirm the running bundle immediately: if it was a pending update, this
+  // is what stops the next launch from rolling it back.
+  void notifyAppReady().catch(() => undefined);
+
+  if (checkOnAppStart) void sync(syncOptions);
+
+  if (checkOnResume) {
+    const handler = (state: AppStateStatus) => {
+      if (state !== 'active') return;
+      if (Date.now() - lastSyncAt < minimumSyncInterval * 1000) return;
+      void sync(syncOptions);
+    };
+    const subscription = AppState.addEventListener('change', handler);
+    lifecycleSubscription = subscription;
+  }
+
+  return () => {
+    lifecycleSubscription?.remove();
+    lifecycleSubscription = null;
+  };
+}
+
+/** Test seam — resets memoised configuration and sync state. */
+export function __resetForTests(): void {
+  cachedConfig = null;
+  syncInFlight = null;
+  lastSyncAt = 0;
+  appReadyNotified = false;
+}

package/src/api.ts

@@ -0,0 +1,122 @@
+import type { CheckResult, NoUpdateReason, OtaConfiguration } from './types';
+
+export interface UpdateCheckResponse {
+  updateInfo: {
+    isAvailable: boolean;
+    label?: string;
+    packageHash?: string;
+    downloadUrl?: string;
+    size?: number;
+    isMandatory?: boolean;
+    description?: string | null;
+    targetBinaryVersion?: string;
+    rollout?: number;
+    isRollback?: boolean;
+    deployment?: string;
+    reason?: NoUpdateReason;
+    updateAppVersion?: boolean;
+  };
+}
+
+export class OtaApiError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = 'OtaApiError';
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+async function request<T>(url: string, init: RequestInit, timeoutMs: number): Promise<T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    const text = await response.text();
+    if (!response.ok) {
+      let message = `${response.status} ${response.statusText}`;
+      try {
+        message = JSON.parse(text)?.error?.message ?? message;
+      } catch {
+        /* keep the status line */
+      }
+      throw new OtaApiError(message, response.status);
+    }
+    return (text ? JSON.parse(text) : {}) as T;
+  } catch (err) {
+    if (err instanceof OtaApiError) throw err;
+    if ((err as Error).name === 'AbortError') {
+      throw new OtaApiError(`Update check timed out after ${timeoutMs}ms`);
+    }
+    throw new OtaApiError((err as Error).message);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function fetchUpdate(
+  config: OtaConfiguration,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<Omit<CheckResult, 'update'> & { raw: UpdateCheckResponse['updateInfo'] }> {
+  const body = {
+    deploymentKey: config.deploymentKey,
+    appVersion: config.appVersion,
+    clientUniqueId: config.clientUniqueId,
+    label: config.label ?? undefined,
+    packageHash: config.packageHash ?? undefined,
+    bundleIdentifier: config.bundleIdentifier || undefined,
+  };
+
+  const response = await request<UpdateCheckResponse>(
+    `${config.serverUrl.replace(/\/+$/, '')}/updateCheck`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    },
+    timeoutMs,
+  );
+
+  return {
+    raw: response.updateInfo,
+    reason: response.updateInfo.reason,
+    updateAppVersion: response.updateInfo.updateAppVersion,
+  };
+}
+
+export type InstallStatus = 'downloaded' | 'success' | 'failed' | 'rolled_back';
+
+/**
+ * Best-effort telemetry. A failed report must never break the app, so callers
+ * are not expected to handle rejections — this never throws.
+ */
+export async function reportStatus(
+  config: OtaConfiguration,
+  status: InstallStatus,
+  extra: { label?: string | null; previousLabel?: string | null; error?: string } = {},
+): Promise<void> {
+  try {
+    await request(
+      `${config.serverUrl.replace(/\/+$/, '')}/reportStatus`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          deploymentKey: config.deploymentKey,
+          clientUniqueId: config.clientUniqueId,
+          appVersion: config.appVersion,
+          status,
+          label: extra.label ?? config.label ?? undefined,
+          previousLabel: extra.previousLabel ?? undefined,
+          error: extra.error,
+        }),
+      },
+      DEFAULT_TIMEOUT_MS,
+    );
+  } catch {
+    // Swallowed on purpose: metrics are not worth a crash.
+  }
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+import {
+  checkForUpdate,
+  clearUpdates,
+  getConfig,
+  getCurrentPackage,
+  notifyAppReady,
+  restartApp,
+  startAutoSync,
+  sync,
+} from './OtaUpdate';
+import { isNativeModuleAvailable } from './native';
+
+export { InstallMode, SyncStatus } from './types';
+export type {
+  CheckResult,
+  CurrentPackage,
+  DownloadProgress,
+  LocalPackage,
+  NoUpdateReason,
+  OtaConfiguration,
+  OtaOptions,
+  RemotePackage,
+  SyncOptions,
+} from './types';
+
+export {
+  checkForUpdate,
+  clearUpdates,
+  getConfig,
+  getCurrentPackage,
+  notifyAppReady,
+  restartApp,
+  startAutoSync,
+  sync,
+};
+export { withOtaUpdate } from './withOtaUpdate';
+export { useOtaUpdate } from './useOtaUpdate';
+export type { UseOtaUpdateState } from './useOtaUpdate';
+export { OtaApiError } from './api';
+export { isNativeModuleAvailable };
+
+/** Default export, so `import OtaUpdate from '@otaupdate/react-native'` works. */
+const OtaUpdate = {
+  sync,
+  checkForUpdate,
+  notifyAppReady,
+  restartApp,
+  getCurrentPackage,
+  getConfig,
+  clearUpdates,
+  startAutoSync,
+  isNativeModuleAvailable,
+};
+
+export default OtaUpdate;

package/src/native.ts

@@ -0,0 +1,64 @@
+import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
+import type { DownloadProgress, OtaConfiguration } from './types';
+
+const LINKING_ERROR =
+  `The native module for '@otaupdate/react-native' is not available.\n\n` +
+  Platform.select({
+    ios: '• Run `cd ios && pod install`\n',
+    android: '• Rebuild the Android app (Gradle autolinking picks the module up)\n',
+    default: '',
+  }) +
+  '• If you use Expo, add the config plugin to app.json and run `npx expo prebuild`\n' +
+  '• Reload the app after a native rebuild — a Metro-only reload is not enough\n' +
+  '• The module does not exist in Expo Go; use a development build.';
+
+export interface NativeOta {
+  getConfiguration(): Promise<OtaConfiguration>;
+  /** Downloads, verifies the SHA-256, and unzips. Resolves with the local path. */
+  downloadUpdate(update: {
+    label: string;
+    packageHash: string;
+    downloadUrl: string;
+    size: number;
+    isMandatory: boolean;
+    description: string | null;
+  }): Promise<{ bundlePath: string; packageHash: string; label: string; size: number }>;
+  installUpdate(
+    packageHash: string,
+    installMode: number,
+    minimumBackgroundDuration: number,
+  ): Promise<void>;
+  notifyApplicationReady(): Promise<void>;
+  restartApp(onlyIfUpdateIsPending: boolean): Promise<void>;
+  getCurrentPackage(): Promise<Record<string, unknown> | null>;
+  /** Removes every downloaded package and reverts to the bundle in the binary. */
+  clearUpdates(): Promise<void>;
+  /** True the first time the app runs after `packageHash` was applied. */
+  isFirstRun(packageHash: string): Promise<boolean>;
+  getConstants?(): Record<string, unknown>;
+}
+
+const nativeModule = NativeModules.OtaUpdate as NativeOta | undefined;
+
+export const NativeOtaUpdate: NativeOta = nativeModule
+  ? nativeModule
+  : (new Proxy({} as NativeOta, {
+      get() {
+        throw new Error(LINKING_ERROR);
+      },
+    }) as NativeOta);
+
+export const isNativeModuleAvailable = Boolean(nativeModule);
+
+export const DOWNLOAD_PROGRESS_EVENT = 'OtaUpdateDownloadProgress';
+
+let emitter: NativeEventEmitter | null = null;
+
+export function onDownloadProgress(
+  listener: (progress: DownloadProgress) => void,
+): { remove: () => void } {
+  if (!nativeModule) return { remove: () => undefined };
+  if (!emitter) emitter = new NativeEventEmitter(nativeModule as never);
+  const subscription = emitter.addListener(DOWNLOAD_PROGRESS_EVENT, listener);
+  return { remove: () => subscription.remove() };
+}

package/src/types.ts

@@ -0,0 +1,125 @@
+/** When a downloaded update actually replaces the running JS bundle. */
+export enum InstallMode {
+  /** Swap in on the next natural app start. Safest; the default. */
+  ON_NEXT_RESTART = 0,
+  /** Swap in the next time the app returns from the background. */
+  ON_NEXT_RESUME = 1,
+  /** Reload the JS bundle right now. Interrupts the user — use for mandatory fixes. */
+  IMMEDIATE = 2,
+}
+
+/** Progress of a `sync()` call, reported through `onSyncStatusChange`. */
+export enum SyncStatus {
+  UP_TO_DATE = 0,
+  UPDATE_INSTALLED = 1,
+  UPDATE_IGNORED = 2,
+  UNKNOWN_ERROR = 3,
+  SYNC_IN_PROGRESS = 4,
+  CHECKING_FOR_UPDATE = 5,
+  AWAITING_USER_ACTION = 6,
+  DOWNLOADING_PACKAGE = 7,
+  INSTALLING_UPDATE = 8,
+}
+
+export interface DownloadProgress {
+  totalBytes: number;
+  receivedBytes: number;
+}
+
+/** Metadata about an update that exists on the server but not yet on device. */
+export interface RemotePackage {
+  label: string;
+  packageHash: string;
+  downloadUrl: string;
+  size: number;
+  isMandatory: boolean;
+  description: string | null;
+  targetBinaryVersion: string;
+  rollout: number;
+  isRollback: boolean;
+  deployment: string;
+  /** Fetches and verifies the bundle, returning the on-device package. */
+  download(onProgress?: (progress: DownloadProgress) => void): Promise<LocalPackage>;
+}
+
+/** An update that has been downloaded and verified onto the device. */
+export interface LocalPackage {
+  label: string;
+  packageHash: string;
+  isMandatory: boolean;
+  description: string | null;
+  bundlePath: string;
+  size: number;
+  /** Applies the update according to `mode`. */
+  install(mode?: InstallMode, minimumBackgroundDuration?: number): Promise<void>;
+}
+
+/** The bundle currently running, if it came from an OTA update. */
+export interface CurrentPackage {
+  label: string | null;
+  packageHash: string | null;
+  description: string | null;
+  isMandatory: boolean;
+  bundlePath: string | null;
+  appVersion: string;
+  /** True until `notifyAppReady()` confirms this update booted successfully. */
+  isPending: boolean;
+  /** True on the first run after this update was applied. */
+  isFirstRun: boolean;
+}
+
+export type NoUpdateReason =
+  | 'up_to_date'
+  | 'not_in_rollout'
+  | 'no_matching_binary_version'
+  | 'update_app_version';
+
+export interface CheckResult {
+  update: RemotePackage | null;
+  reason?: NoUpdateReason;
+  /** Set when a newer *binary* is required — the fix is a store update, not OTA. */
+  updateAppVersion?: boolean;
+}
+
+export interface OtaConfiguration {
+  deploymentKey: string;
+  serverUrl: string;
+  appVersion: string;
+  clientUniqueId: string;
+  /** Hash/label of the bundle currently running, if it is an OTA package. */
+  packageHash: string | null;
+  label: string | null;
+  /**
+   * The app's real native bundle identifier (iOS `CFBundleIdentifier` /
+   * Android package name), read from the native runtime — not settable from
+   * JS. Sent on every update-check so the server can reject a deployment key
+   * used against an app it was not issued for.
+   */
+  bundleIdentifier: string;
+}
+
+export interface SyncOptions {
+  installMode?: InstallMode;
+  /** Install mode used when the release is flagged mandatory. */
+  mandatoryInstallMode?: InstallMode;
+  /** Seconds the app must stay backgrounded before an ON_NEXT_RESUME install applies. */
+  minimumBackgroundDuration?: number;
+  deploymentKey?: string;
+  onSyncStatusChange?: (status: SyncStatus) => void;
+  onDownloadProgress?: (progress: DownloadProgress) => void;
+  /**
+   * Return false to skip an update (e.g. after asking the user).
+   * Mandatory updates ignore the result.
+   */
+  shouldInstall?: (update: RemotePackage) => boolean | Promise<boolean>;
+}
+
+export interface OtaOptions {
+  /** Run a sync when the app starts. Default: true. */
+  checkOnAppStart?: boolean;
+  /** Run a sync each time the app returns to the foreground. Default: true. */
+  checkOnResume?: boolean;
+  /** Minimum seconds between automatic syncs. Default: 60. */
+  minimumSyncInterval?: number;
+  sync?: SyncOptions;
+}