@hot-updater/react-native 0.27.1 → 0.29.0

package/src/native.ts

@@ -1,4 +1,9 @@
-import type { UpdateStatus } from "@hot-updater/core";
+import {
+  INVALID_COHORT_ERROR_MESSAGE,
+  isValidCohort,
+  normalizeCohortValue,
+  type UpdateStatus,
+} from "@hot-updater/core";
 import { NativeEventEmitter, Platform } from "react-native";
 import { HotUpdaterErrorCode, isHotUpdaterError } from "./error";
 import HotUpdaterNative, {
@@ -8,6 +13,30 @@ import HotUpdaterNative, {
 export { HotUpdaterErrorCode, isHotUpdaterError };
 
 const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+const normalizeAndValidateCohort = (cohort: string): string => {
+  const normalized = normalizeCohortValue(cohort);
+  if (!isValidCohort(normalized)) {
+    throw new Error(INVALID_COHORT_ERROR_MESSAGE);
+  }
+  return normalized;
+};
+
+export interface ManifestAsset {
+  fileHash: string;
+}
+
+export interface Manifest {
+  bundleId: string;
+  assets: Record<string, ManifestAsset>;
+}
+
+type ActiveBundleSnapshotCacheValues = {
+  bundleId?: string;
+  manifest?: Manifest;
+  baseURL?: string | null;
+};
+
+type ActiveBundleSnapshotCacheKey = keyof ActiveBundleSnapshotCacheValues;
 
 /**
  * Built-in reload behaviors used by `HotUpdater.reload()`.
@@ -34,17 +63,16 @@ export type CustomReloadHandler = () => void | Promise<void>;
  */
 export type ReloadBehaviorSetting = ReloadBehavior | "custom";
 
-declare const __HOT_UPDATER_BUNDLE_ID: string | undefined;
-
-export const HotUpdaterConstants = {
-  HOT_UPDATER_BUNDLE_ID: __HOT_UPDATER_BUNDLE_ID || NIL_UUID,
-};
-
 class HotUpdaterSessionState {
   private readonly defaultChannel: string;
   private currentChannel: string;
+  private cachedCohort: string | undefined;
   private readonly inflightUpdates = new Map<string, Promise<boolean>>();
   private lastInstalledBundleId: string | null = null;
+  private readonly activeBundleSnapshotCache = new Map<
+    ActiveBundleSnapshotCacheKey,
+    ActiveBundleSnapshotCacheValues[ActiveBundleSnapshotCacheKey]
+  >();
 
   constructor() {
     const constants = HotUpdaterNative.getConstants();
@@ -85,12 +113,66 @@ class HotUpdaterSessionState {
     if (channel) {
       this.currentChannel = channel;
     }
+    this.clearActiveBundleSnapshotCache();
   }
 
   resetChannelState() {
     this.currentChannel = this.defaultChannel;
     this.lastInstalledBundleId = null;
     this.inflightUpdates.clear();
+    this.clearActiveBundleSnapshotCache();
+  }
+
+  getCachedBundleId(): string | undefined {
+    return this.getActiveBundleSnapshotValue("bundleId");
+  }
+
+  cacheBundleId(bundleId: string) {
+    this.setActiveBundleSnapshotValue("bundleId", bundleId);
+  }
+
+  getCachedManifest(): Manifest | undefined {
+    const manifest = this.getActiveBundleSnapshotValue("manifest");
+    return manifest ? cloneManifest(manifest) : undefined;
+  }
+
+  cacheManifest(manifest: Manifest) {
+    this.setActiveBundleSnapshotValue("manifest", cloneManifest(manifest));
+  }
+
+  getCachedBaseURL(): string | null | undefined {
+    return this.getActiveBundleSnapshotValue("baseURL");
+  }
+
+  cacheBaseURL(baseURL: string | null) {
+    this.setActiveBundleSnapshotValue("baseURL", baseURL);
+  }
+
+  getCachedCohort(): string | undefined {
+    return this.cachedCohort;
+  }
+
+  cacheCohort(cohort: string) {
+    this.cachedCohort = cohort;
+  }
+
+  private clearActiveBundleSnapshotCache() {
+    this.activeBundleSnapshotCache.clear();
+  }
+
+  private getActiveBundleSnapshotValue<K extends ActiveBundleSnapshotCacheKey>(
+    key: K,
+  ): ActiveBundleSnapshotCacheValues[K] | undefined {
+    return this.activeBundleSnapshotCache.get(key) as
+      | ActiveBundleSnapshotCacheValues[K]
+      | undefined;
+  }
+
+  private setActiveBundleSnapshotValue<K extends ActiveBundleSnapshotCacheKey>(
+    key: K,
+    value: ActiveBundleSnapshotCacheValues[K],
+  ) {
+    this.activeBundleSnapshotCache.set(key, value);
   }
 }
 
@@ -98,6 +180,16 @@ const sessionState = new HotUpdaterSessionState();
 let reloadBehavior: ReloadBehaviorSetting = "processRestart";
 let customReloadHandler: CustomReloadHandler | null = null;
 
+const cloneManifest = (manifest: Manifest): Manifest => ({
+  bundleId: manifest.bundleId,
+  assets: Object.fromEntries(
+    Object.entries(manifest.assets).map(([key, asset]) => [
+      key,
+      { fileHash: asset.fileHash },
+    ]),
+  ),
+});
+
 const getReloadProcess = (): (() => Promise<void>) | null => {
   const nativeModule = HotUpdaterNative as typeof HotUpdaterNative & {
     reloadProcess?: () => Promise<void>;
@@ -318,13 +410,72 @@ export const getMinBundleId = (): string => {
 /**
  * Fetches the current bundle version id.
  *
- * @async
- * @returns {string} Resolves with the current version id or null if not available.
+ * JS falls back to MIN_BUNDLE_ID only after native confirms there is no active
+ * downloaded bundle. When the native module does not expose `getBundleId()`,
+ * treat it as a JS/native SDK mismatch instead of silently reporting the
+ * built-in bundle.
+ *
+ * @returns {string} Resolves with the current version id.
  */
 export const getBundleId = (): string => {
-  return HotUpdaterConstants.HOT_UPDATER_BUNDLE_ID === NIL_UUID
-    ? getMinBundleId()
-    : HotUpdaterConstants.HOT_UPDATER_BUNDLE_ID;
+  const cachedBundleId = sessionState.getCachedBundleId();
+  if (cachedBundleId !== undefined) {
+    return cachedBundleId;
+  }
+
+  const nativeModule = HotUpdaterNative as typeof HotUpdaterNative & {
+    getBundleId?: () => string | null;
+  };
+
+  if (typeof nativeModule.getBundleId !== "function") {
+    throw new Error(
+      "[HotUpdater] Native module is missing 'getBundleId()'. This JS bundle requires a newer native @hot-updater/react-native SDK. Rebuild and release a new app version before delivering this OTA update.",
+    );
+  }
+
+  const bundleId = nativeModule.getBundleId();
+
+  const resolvedBundleId =
+    !bundleId || bundleId === NIL_UUID ? getMinBundleId() : bundleId;
+
+  sessionState.cacheBundleId(resolvedBundleId);
+  return resolvedBundleId;
+};
+
+/**
+ * Fetches the current manifest for the active bundle.
+ *
+ * Returns a normalized manifest with empty assets when manifest.json is missing
+ * or invalid.
+ */
+export const getManifest = (): Manifest => {
+  const cachedManifest = sessionState.getCachedManifest();
+  if (cachedManifest !== undefined) {
+    return cachedManifest;
+  }
+
+  const nativeModule = HotUpdaterNative as typeof HotUpdaterNative & {
+    getManifest?: () => Record<string, unknown> | string;
+  };
+  const manifest = nativeModule.getManifest?.();
+
+  let normalizedManifest: Manifest;
+
+  if (!manifest) {
+    normalizedManifest = createEmptyManifest();
+  } else if (typeof manifest === "string") {
+    try {
+      normalizedManifest = normalizeManifest(JSON.parse(manifest));
+    } catch {
+      normalizedManifest = createEmptyManifest();
+    }
+  } else {
+    normalizedManifest = normalizeManifest(manifest);
+  }
+
+  sessionState.cacheBundleId(normalizedManifest.bundleId);
+  sessionState.cacheManifest(normalizedManifest);
+  return cloneManifest(normalizedManifest);
 };
 
 /**
@@ -364,18 +515,16 @@ export const getFingerprintHash = (): string | null => {
  * Result returned by notifyAppReady()
  */
 export type NotifyAppReadyResult = {
-  status: "PROMOTED" | "RECOVERED" | "STABLE";
+  status: "RECOVERED" | "STABLE";
   crashedBundleId?: string;
 };
 
 /**
- * Notifies the native side that the app has successfully started with the current bundle.
- * If the bundle matches the staging bundle, it promotes to stable.
+ * Reads the native launch report for the current process.
  *
- * This function is called automatically when the module loads.
+ * This function is called automatically after the app has rendered.
  *
  * @returns {NotifyAppReadyResult} Bundle state information
- * - `status: "PROMOTED"` - Staging bundle was promoted to stable (ACTIVE event)
  * - `status: "RECOVERED"` - App recovered from crash, rollback occurred (ROLLBACK event)
  * - `status: "STABLE"` - No changes, already stable
  * - `crashedBundleId` - Present only when status is "RECOVERED"
@@ -384,33 +533,97 @@ export type NotifyAppReadyResult = {
  * ```ts
  * const result = HotUpdater.notifyAppReady();
  *
- * switch (result.status) {
- *   case "PROMOTED":
- *     // Send ACTIVE analytics event
- *     analytics.track('bundle_active', { bundleId: HotUpdater.getBundleId() });
- *     break;
- *   case "RECOVERED":
- *     // Send ROLLBACK analytics event
- *     analytics.track('bundle_rollback', { crashedBundleId: result.crashedBundleId });
- *     break;
- *   case "STABLE":
- *     // No special action needed
- *     break;
+ * if (result.status === "RECOVERED") {
+ *   // Send ROLLBACK analytics event
+ *   analytics.track("bundle_rollback", {
+ *     crashedBundleId: result.crashedBundleId,
+ *   });
  * }
  * ```
  */
 export const notifyAppReady = (): NotifyAppReadyResult => {
-  const bundleId = getBundleId();
-  const result = HotUpdaterNative.notifyAppReady({ bundleId });
-  // Oldarch returns JSON string, newarch returns array
+  const result = HotUpdaterNative.notifyAppReady();
+  // Older Android old-arch implementations returned JSON strings.
   if (typeof result === "string") {
     try {
-      return JSON.parse(result);
+      return normalizeNotifyAppReadyResult(JSON.parse(result));
     } catch {
       return { status: "STABLE" };
     }
   }
-  return result;
+  return normalizeNotifyAppReadyResult(result);
+};
+
+const normalizeNotifyAppReadyResult = (
+  result: NotifyAppReadyResult | { status?: string; crashedBundleId?: string },
+): NotifyAppReadyResult => {
+  if (result.status === "RECOVERED") {
+    return {
+      status: "RECOVERED",
+      crashedBundleId: result.crashedBundleId,
+    };
+  }
+
+  return { status: "STABLE" };
+};
+
+const createEmptyManifest = (): Manifest => ({
+  bundleId: getBundleId(),
+  assets: {},
+});
+
+const normalizeManifest = (value: unknown): Manifest => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return createEmptyManifest();
+  }
+
+  const bundleIdValue = (value as { bundleId?: unknown }).bundleId;
+  const bundleId =
+    typeof bundleIdValue === "string" && bundleIdValue.trim()
+      ? bundleIdValue.trim()
+      : getBundleId();
+
+  return {
+    bundleId,
+    assets: normalizeManifestAssets((value as { assets?: unknown }).assets),
+  };
+};
+
+const normalizeManifestAssets = (value: unknown): Manifest["assets"] => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([key, entry]) => {
+      const trimmedKey = key.trim();
+
+      if (!trimmedKey) {
+        return [];
+      }
+
+      if (typeof entry === "string") {
+        const fileHash = entry.trim();
+
+        if (!fileHash) {
+          return [];
+        }
+
+        return [[trimmedKey, { fileHash }] as const];
+      }
+
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return [];
+      }
+
+      const { fileHash } = entry as { fileHash?: unknown };
+      if (typeof fileHash !== "string" || !fileHash.trim()) {
+        return [];
+      }
+
+      return [[trimmedKey, { fileHash: fileHash.trim() }] as const];
+    }),
+  );
 };
 
 /**
@@ -421,7 +634,7 @@ export const notifyAppReady = (): NotifyAppReadyResult => {
  */
 export const getCrashHistory = (): string[] => {
   const result = HotUpdaterNative.getCrashHistory();
-  // Oldarch returns JSON string, newarch returns array
+  // Older Android old-arch implementations returned JSON strings.
   if (typeof result === "string") {
     try {
       return JSON.parse(result);
@@ -450,11 +663,15 @@ export const clearCrashHistory = (): boolean => {
  * @returns {string | null} Base URL string (e.g., "file:///data/.../bundle-store/abc123") or null if not available
  */
 export const getBaseURL = (): string | null => {
-  const result = HotUpdaterNative.getBaseURL();
-  if (typeof result === "string" && result !== "") {
-    return result;
+  const cachedBaseURL = sessionState.getCachedBaseURL();
+  if (cachedBaseURL !== undefined) {
+    return cachedBaseURL;
   }
-  return null;
+
+  const result = HotUpdaterNative.getBaseURL();
+  const baseURL = typeof result === "string" && result !== "" ? result : null;
+  sessionState.cacheBaseURL(baseURL);
+  return baseURL;
 };
 
 /**
@@ -471,3 +688,32 @@ export const resetChannel = async (): Promise<boolean> => {
   }
   return ok;
 };
+
+/**
+ * Sets the persisted cohort used for update checks.
+ *
+ * HotUpdater only derives a device-based cohort when nothing has been stored
+ * yet. If you need to restore that initial value later, read it with
+ * `getCohort()` before calling `setCohort()`, then store it yourself.
+ */
+export const setCohort = (cohort: string): void => {
+  const normalized = normalizeAndValidateCohort(cohort);
+  HotUpdaterNative.setCohort(normalized);
+  sessionState.cacheCohort(normalized);
+};
+
+/**
+ * Gets the persisted cohort used for rollout calculations.
+ * If none has been stored yet, native derives the initial value once and
+ * persists it before returning.
+ */
+export const getCohort = (): string => {
+  const cachedCohort = sessionState.getCachedCohort();
+  if (cachedCohort !== undefined) {
+    return cachedCohort;
+  }
+
+  const cohort = normalizeAndValidateCohort(HotUpdaterNative.getCohort());
+  sessionState.cacheCohort(cohort);
+  return cohort;
+};

package/src/specs/NativeHotUpdater.ts

@@ -1,5 +1,6 @@
 import type { TurboModule } from "react-native";
 import { TurboModuleRegistry } from "react-native";
+import type { UnsafeObject } from "react-native/Libraries/Types/CodegenTypes";
 
 export interface UpdateBundleParams {
   bundleId: string;
@@ -60,18 +61,16 @@ export interface Spec extends TurboModule {
   updateBundle(params: UpdateBundleParams): Promise<boolean>;
 
   /**
-   * Notifies the native side that the app has successfully started with the given bundle.
-   * If the bundle matches the staging bundle, it promotes to stable.
+   * Reads the launch report for the current process.
+   * This is a read-only API; native launch state has already been finalized.
    *
-   * @param params - Parameters containing the bundle ID
    * @returns Object with status and optional crashedBundleId
-   * - `status: "PROMOTED"` - Staging bundle was promoted to stable (ACTIVE event)
    * - `status: "RECOVERED"` - App recovered from crash, rollback occurred (ROLLBACK event)
    * - `status: "STABLE"` - No changes, already stable
    * - `crashedBundleId` - Present only when status is "RECOVERED"
    */
-  notifyAppReady(params: { bundleId: string }): {
-    status: "PROMOTED" | "RECOVERED" | "STABLE";
+  notifyAppReady(): {
+    status: "RECOVERED" | "STABLE";
     crashedBundleId?: string;
   };
 
@@ -107,6 +106,37 @@ export interface Spec extends TurboModule {
    */
   getBaseURL: () => string;
 
+  /**
+   * Gets the current active bundle ID from native bundle storage.
+   * Native reads the extracted bundle manifest first and falls back to the
+   * legacy BUNDLE_ID file when needed. Built-in bundle fallback is handled in JS.
+   *
+   * @returns Active bundle ID from bundle storage, or null when unavailable
+   */
+  getBundleId: () => string | null;
+
+  /**
+   * Gets the current manifest from native bundle storage.
+   * Returns an empty object when manifest.json is missing or invalid.
+   */
+  getManifest: () => UnsafeObject;
+
+  /**
+   * Sets the persisted cohort used for rollout calculations.
+   *
+   * Native only derives a device-based cohort when nothing has been stored
+   * yet. Call `getCohort()` first if the app needs to save that initial value
+   * for a later restore.
+   */
+  setCohort: (cohort: string) => void;
+
+  /**
+   * Gets the persisted cohort used for rollout calculations.
+   * If none has been stored yet, native derives the initial value once and
+   * persists it before returning.
+   */
+  getCohort: () => string;
+
   // EventEmitter
   addListener(eventName: string): void;
   removeListeners(count: number): void;

package/src/types.ts

@@ -30,6 +30,11 @@ export interface ResolverCheckUpdateParams {
    */
   channel: string;
 
+  /**
+   * Cohort identifier used for server-side rollout decisions.
+   */
+  cohort: string;
+
   /**
    * Update strategy being used
    */
@@ -57,11 +62,10 @@ export interface ResolverCheckUpdateParams {
 export interface ResolverNotifyAppReadyParams {
   /**
    * The bundle state from native notifyAppReady
-   * - "PROMOTED": Staging bundle was promoted to stable
    * - "RECOVERED": App recovered from crash, rollback occurred
    * - "STABLE": No changes, bundle is stable
    */
-  status: "PROMOTED" | "RECOVERED" | "STABLE";
+  status: "RECOVERED" | "STABLE";
 
   /**
    * Present only when status is "RECOVERED"
@@ -111,7 +115,7 @@ export interface HotUpdaterResolver {
   /**
    * Custom implementation for notifying app ready.
    * When provided, this completely replaces the default notifyAppReady network flow.
-   * Note: The native notifyAppReady for bundle promotion still happens automatically.
+   * Note: Native rollback/promotion semantics are already finalized before this callback runs.
    *
    * @param params - All parameters about the current app state
    * @returns Notification result

package/src/wrap.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useLayoutEffect, useState } from "react";
+import React, { useEffect, useState } from "react";
 import { checkForUpdate } from "./checkForUpdate";
 import type { HotUpdaterError } from "./error";
 import { useEventCallback } from "./hooks/useEventCallback";
@@ -39,12 +39,11 @@ interface CommonHotUpdaterOptions {
   requestTimeout?: number;
 
   /**
-   * Callback invoked when the app is ready and bundle verification completes.
-   * Provides information about bundle promotion, recovery from crashes, or stable state.
+   * Callback invoked when the app is ready and the native launch report is available.
+   * Provides information about rollback recovery or stable state.
    *
    * @param result - Bundle state information
    * @param result.status - Current bundle state:
-   *   - "PROMOTED": Staging bundle was promoted to stable (new update applied)
    *   - "RECOVERED": App recovered from a crash, rollback occurred
    *   - "STABLE": No changes, bundle is stable
    * @param result.crashedBundleId - Present only when status is "RECOVERED"
@@ -56,9 +55,7 @@ interface CommonHotUpdaterOptions {
    *   updateMode: "manual",
    *   onNotifyAppReady: ({ status, crashedBundleId }) => {
    *     if (status === "RECOVERED") {
-   *       analytics.track('bundle_rollback', { crashedBundleId });
-   *     } else if (status === "PROMOTED") {
-   *       analytics.track('bundle_promoted');
+   *       analytics.track("bundle_rollback", { crashedBundleId });
    *     }
    *   }
    * })(App);
@@ -220,7 +217,6 @@ const handleNotifyAppReady = async (options: {
   onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
 }): Promise<void> => {
   try {
-    // Always call native notifyAppReady for bundle promotion
     const nativeResult = nativeNotifyAppReady();
 
     // If resolver.notifyAppReady exists, call it with simplified params
@@ -249,7 +245,7 @@ export function wrap<P extends React.JSX.IntrinsicAttributes = object>(
   if (options.updateMode === "manual") {
     return (WrappedComponent: React.ComponentType<P>) => {
       const ManualHOC: React.FC<P> = (props: P) => {
-        useLayoutEffect(() => {
+        useEffect(() => {
           void handleNotifyAppReady(options);
         }, []);
 
@@ -342,13 +338,13 @@ export function wrap<P extends React.JSX.IntrinsicAttributes = object>(
         restOptions.onProgress?.(progress);
       }, [progress]);
 
-      // Notify native side that app is ready (JS bundle fully loaded)
-      useLayoutEffect(() => {
+      // Read the native launch report after the first render commit.
+      useEffect(() => {
         void handleNotifyAppReady(restOptions);
       }, []);
 
       // Start update check
-      useLayoutEffect(() => {
+      useEffect(() => {
         initHotUpdater();
       }, []);