@hot-updater/react-native 0.36.6 → 1.0.0-rc.0

package/src/native.ts

@@ -1,9 +1,11 @@
 import {
   type ChangedAsset,
+  type CatalogHighWater,
   INVALID_COHORT_ERROR_MESSAGE,
   isValidCohort,
   normalizeCohortValue,
   type UpdateStatus,
+  type PersistedSelectionReceipt,
 } from "@hot-updater/core";
 import { NativeEventEmitter, Platform } from "react-native";
 
@@ -15,6 +17,8 @@ import HotUpdaterNative, {
 export { HotUpdaterErrorCode, isHotUpdaterError };
 
 const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+type PersistedUpdateStrategy = "fingerprint" | "appVersion";
+
 const normalizeAndValidateCohort = (cohort: string): string => {
   const normalized = normalizeCohortValue(cohort);
   if (!isValidCohort(normalized)) {
@@ -211,7 +215,7 @@ const getNativeBundleId = (): string | null => {
 };
 
 const resolveBundleId = (bundleId: string | null): string => {
-  return !bundleId || bundleId === NIL_UUID ? getMinBundleId() : bundleId;
+  return !bundleId || bundleId === NIL_UUID ? getMinimumReleaseId() : bundleId;
 };
 
 const getFreshBundleId = (): string => {
@@ -317,6 +321,109 @@ export type UpdateParams = UpdateBundleParams & {
   shouldSkipCurrentBundleIdCheck?: boolean;
 };
 
+export interface ActiveUpdateState {
+  readonly activeSelection: ActiveUpdateSelection | null;
+  readonly stableSelection: ActiveUpdateSelection | null;
+  readonly verificationPending: boolean;
+}
+
+type ActiveUpdateSelection = Pick<
+  PersistedSelectionReceipt,
+  "kind" | "releaseId" | "bundleId" | "channel"
+>;
+
+export interface InternalActiveUpdateState {
+  readonly activeSelection: PersistedSelectionReceipt | null;
+  readonly stableSelection: PersistedSelectionReceipt | null;
+  readonly verificationPending: boolean;
+  readonly highestSeenCatalogs: Readonly<Record<string, CatalogHighWater>>;
+}
+
+export interface ReleaseSelectionGuard {
+  readonly catalogId: string;
+  readonly scopeKey: string;
+  readonly generation: number;
+  readonly catalogHash: string;
+  readonly selectionContextHash: string;
+  readonly channel: string;
+}
+
+const requireReleaseCatalogNativeMethod = <T extends (...args: any[]) => any>(
+  name: string,
+): T => {
+  const method = (HotUpdaterNative as unknown as Record<string, unknown>)[name];
+  if (typeof method !== "function") {
+    throw new Error(
+      `[HotUpdater] Native module is missing '${name}()'. Rebuild the native app before using Release catalogs.`,
+    );
+  }
+  return method.bind(HotUpdaterNative) as T;
+};
+
+export const acceptReleaseCatalog = (input: {
+  readonly catalogId: string;
+  readonly scopeKey: string;
+  readonly generation: number;
+  readonly catalogHash: string;
+  readonly channel: string;
+  readonly selectionContextHash: string;
+}): boolean =>
+  requireReleaseCatalogNativeMethod<(params: object) => boolean>(
+    "acceptReleaseCatalog",
+  )(input);
+
+export const getActiveUpdateState = (): InternalActiveUpdateState => {
+  const value = requireReleaseCatalogNativeMethod<() => unknown>(
+    "getActiveUpdateState",
+  )();
+  if (typeof value === "string") {
+    return JSON.parse(value) as InternalActiveUpdateState;
+  }
+  return value as InternalActiveUpdateState;
+};
+
+export const getPublicActiveUpdateState = (): ActiveUpdateState => {
+  const state = getActiveUpdateState();
+  const selection = (
+    receipt: PersistedSelectionReceipt | null,
+  ): ActiveUpdateSelection | null =>
+    receipt === null
+      ? null
+      : {
+          kind: receipt.kind,
+          releaseId: receipt.releaseId,
+          bundleId: receipt.bundleId,
+          channel: receipt.channel,
+        };
+  return {
+    activeSelection: selection(state.activeSelection),
+    stableSelection: selection(state.stableSelection),
+    verificationPending: state.verificationPending,
+  };
+};
+
+export const isReleaseSelectionCurrent = (
+  input: ReleaseSelectionGuard,
+): boolean =>
+  requireReleaseCatalogNativeMethod<(params: object) => boolean>(
+    "isReleaseSelectionCurrent",
+  )(input);
+
+export const commitReleaseSelection = async (input: {
+  readonly selection: PersistedSelectionReceipt;
+  readonly guard: ReleaseSelectionGuard;
+}): Promise<boolean> => {
+  const ok = await requireReleaseCatalogNativeMethod<
+    (params: object) => Promise<boolean>
+  >("commitReleaseSelection")(input);
+  if (ok)
+    sessionState.markBundleInstalled(
+      input.selection.bundleId,
+      input.selection.channel,
+    );
+  return ok;
+};
+
 /**
  * Downloads files and applies them to the app.
  *
@@ -324,30 +431,10 @@ export type UpdateParams = UpdateBundleParams & {
  * @returns {Promise<boolean>} Resolves with true if download was successful
  * @throws {Error} Rejects with error.code from HotUpdaterErrorCode enum and error.message
  */
-export async function updateBundle(params: UpdateParams): Promise<boolean>;
-/**
- * @deprecated Use updateBundle(params: UpdateBundleParamsWithStatus) instead
- */
-export async function updateBundle(
-  bundleId: string,
-  fileUrl: string | null,
-): Promise<boolean>;
-export async function updateBundle(
-  paramsOrBundleId: UpdateParams | string,
-  fileUrl?: string | null,
-): Promise<boolean> {
-  const updateBundleId =
-    typeof paramsOrBundleId === "string"
-      ? paramsOrBundleId
-      : paramsOrBundleId.bundleId;
-
-  const status =
-    typeof paramsOrBundleId === "string" ? "UPDATE" : paramsOrBundleId.status;
-
-  const targetFileUrl =
-    typeof paramsOrBundleId === "string"
-      ? (fileUrl ?? null)
-      : paramsOrBundleId.fileUrl;
+export async function updateBundle(params: UpdateParams): Promise<boolean> {
+  const updateBundleId = params.bundleId;
+  const status = params.status;
+  const targetFileUrl = params.fileUrl;
 
   const currentBundleId = status === "UPDATE" ? getFreshBundleId() : undefined;
 
@@ -363,9 +450,7 @@ export async function updateBundle(
   }
 
   const shouldSkipCurrentBundleIdCheck =
-    typeof paramsOrBundleId === "string"
-      ? false
-      : paramsOrBundleId.shouldSkipCurrentBundleIdCheck === true;
+    params.shouldSkipCurrentBundleIdCheck === true;
 
   if (
     !shouldSkipCurrentBundleIdCheck &&
@@ -382,28 +467,15 @@ export async function updateBundle(
   const existing = sessionState.getInflightUpdate(updateBundleId);
   if (existing) return existing;
 
-  const targetFileHash =
-    typeof paramsOrBundleId === "string"
-      ? undefined
-      : paramsOrBundleId.fileHash;
-
-  const targetChannel =
-    typeof paramsOrBundleId === "string" ? undefined : paramsOrBundleId.channel;
-  const targetManifestUrl =
-    typeof paramsOrBundleId === "string"
-      ? undefined
-      : paramsOrBundleId.manifestUrl;
-  const targetManifestFileHash =
-    typeof paramsOrBundleId === "string"
-      ? undefined
-      : paramsOrBundleId.manifestFileHash;
-  const targetChangedAssets =
-    typeof paramsOrBundleId === "string"
-      ? undefined
-      : paramsOrBundleId.changedAssets;
+  const targetFileHash = params.fileHash;
+  const targetChannel = params.channel;
+  const targetManifestUrl = params.manifestUrl;
+  const targetManifestFileHash = params.manifestFileHash;
+  const targetChangedAssets = params.changedAssets;
 
   const promise = (async () => {
     try {
+      const selection = params.selection;
       const ok = await HotUpdaterNative.updateBundle({
         bundleId: updateBundleId,
         channel: targetChannel,
@@ -413,6 +485,7 @@ export async function updateBundle(
         fileHash: targetFileHash ?? null,
         manifestFileHash: targetManifestFileHash ?? null,
         manifestUrl: targetManifestUrl ?? null,
+        ...(selection === undefined ? {} : { selection }),
       });
       if (ok) {
         sessionState.markBundleInstalled(updateBundleId, targetChannel);
@@ -515,16 +588,18 @@ export function setReloadBehavior(
 }
 
 /**
- * Fetches the minimum bundle id, which represents the initial bundle of the app
- * since it is created at build time.
+ * Fetches the build-time minimum Release id.
  *
- * @returns {string} Resolves with the minimum bundle id or null if not available.
+ * @returns {string} The minimum Release id.
  */
-export const getMinBundleId = (): string => {
+export const getMinimumReleaseId = (): string => {
   const constants = HotUpdaterNative.getConstants();
   return constants.MIN_BUNDLE_ID;
 };
 
+export const getReleaseId = async (): Promise<string | null> =>
+  getActiveUpdateState().activeSelection?.releaseId ?? null;
+
 /**
  * Fetches the current bundle version id.
  *
@@ -613,12 +688,264 @@ export const getFingerprintHash = (): string | null => {
   return constants.FINGERPRINT_HASH;
 };
 
+export const getInstallId = (): string => {
+  const nativeModule = HotUpdaterNative as typeof HotUpdaterNative & {
+    getInstallId?: () => string;
+  };
+
+  if (typeof nativeModule.getInstallId !== "function") {
+    throw new Error(
+      "[HotUpdater] Native module is missing 'getInstallId()'. This JS bundle requires a newer native @hot-updater/react-native SDK. Rebuild and release a new app version before delivering this OTA update.",
+    );
+  }
+
+  return nativeModule.getInstallId();
+};
+
+export type PersistedUserIdentity = {
+  userId?: string;
+  username?: string;
+};
+
+export const getPersistedUserIdentity = (): PersistedUserIdentity => {
+  const nativeModule = HotUpdaterNative as typeof HotUpdaterNative & {
+    getUserId?: () => string | null;
+    getUsername?: () => string | null;
+  };
+
+  if (
+    typeof nativeModule.getUserId !== "function" ||
+    typeof nativeModule.getUsername !== "function"
+  ) {
+    throw new Error(
+      "[HotUpdater] Native module is missing 'getUserId()' or 'getUsername()'. 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 userId = nativeModule.getUserId();
+  const username = nativeModule.getUsername();
+
+  return {
+    ...(userId != null ? { userId } : {}),
+    ...(username != null ? { username } : {}),
+  };
+};
+
+export type SetUserParams = {
+  userId?: string | number | null;
+  username?: string | null;
+};
+
+export function setUser(params: SetUserParams): void;
+export function setUser(params: null): void;
+export function setUser(params: SetUserParams | null): void {
+  const nativeModule = HotUpdaterNative as typeof HotUpdaterNative & {
+    setUser?: (userId: string | null, username: string | null) => void;
+  };
+
+  if (typeof nativeModule.setUser !== "function") {
+    throw new Error(
+      "[HotUpdater] Native module is missing 'setUser()'. This JS bundle requires a newer native @hot-updater/react-native SDK. Rebuild and release a new app version before delivering this OTA update.",
+    );
+  }
+
+  if (params === null) {
+    nativeModule.setUser(null, null);
+    return;
+  }
+
+  const normalizedUserId =
+    params.userId === null || params.userId === undefined
+      ? null
+      : String(params.userId);
+  nativeModule.setUser(normalizedUserId, params.username ?? null);
+}
+
 /**
  * Result returned by notifyAppReady()
  */
-export type NotifyAppReadyResult = {
-  status: "RECOVERED" | "STABLE";
+export type NotifyAppReadyResult =
+  | { status: "UNCHANGED" }
+  | {
+      status: "UPDATE_APPLIED";
+      fromBundleId: string;
+      toBundleId: string;
+      fromReleaseId?: string;
+      toReleaseId?: string;
+    }
+  | {
+      status: "RECOVERED";
+      fromBundleId: string;
+      toBundleId: string;
+      fromReleaseId?: string;
+      toReleaseId?: string;
+    };
+
+export type NotifyAppReadyAnalyticsEvent = {
+  type: "UPDATE_APPLIED" | "RECOVERED";
+  fromBundleId: string;
+  toBundleId: string;
+  fromReleaseId?: string | null;
+  toReleaseId?: string | null;
+  updateStrategy: PersistedUpdateStrategy;
+};
+
+type RawNotifyAppReadyResult = {
+  status?: string;
   crashedBundleId?: string;
+  fromReleaseId?: string;
+  fromBundleId?: string;
+  toReleaseId?: string;
+  toBundleId?: string;
+  updateStrategy?: PersistedUpdateStrategy;
+};
+
+const isPersistedUpdateStrategy = (
+  value: unknown,
+): value is PersistedUpdateStrategy => {
+  return value === "appVersion" || value === "fingerprint";
+};
+
+const readRawNotifyAppReadyResult = (): RawNotifyAppReadyResult => {
+  const result = HotUpdaterNative.notifyAppReady();
+
+  if (typeof result === "string") {
+    try {
+      const parsed = JSON.parse(result) as unknown;
+      if (
+        typeof parsed !== "object" ||
+        parsed === null ||
+        Array.isArray(parsed)
+      ) {
+        return {};
+      }
+      return parsed as RawNotifyAppReadyResult;
+    } catch {
+      return {};
+    }
+  }
+
+  if (typeof result !== "object" || result === null || Array.isArray(result)) {
+    return {};
+  }
+
+  return result as RawNotifyAppReadyResult;
+};
+
+const readDirectionalBundleId = (bundleId: unknown): string | null => {
+  if (typeof bundleId !== "string") {
+    return null;
+  }
+  const normalizedBundleId = bundleId.trim();
+  if (normalizedBundleId.length === 0) {
+    return null;
+  }
+  return resolveBundleId(normalizedBundleId);
+};
+
+const readDirectionalReleaseId = (releaseId: unknown): string | null => {
+  if (typeof releaseId !== "string") return null;
+  const normalizedReleaseId = releaseId.trim();
+  return normalizedReleaseId.length === 0 ? null : normalizedReleaseId;
+};
+
+const getNotifyAppReadyTransition = (
+  result: RawNotifyAppReadyResult,
+): {
+  status: "UPDATE_APPLIED" | "RECOVERED";
+  fromBundleId: string;
+  toBundleId: string;
+  fromReleaseId: string | null;
+  toReleaseId: string | null;
+} | null => {
+  if (result.status === "UPDATE_APPLIED" || result.status === "PROMOTED") {
+    const fromBundleId = readDirectionalBundleId(result.fromBundleId);
+    const toBundleId = readDirectionalBundleId(result.toBundleId);
+    if (fromBundleId && toBundleId) {
+      return {
+        status: "UPDATE_APPLIED",
+        fromBundleId,
+        toBundleId,
+        fromReleaseId: readDirectionalReleaseId(result.fromReleaseId),
+        toReleaseId: readDirectionalReleaseId(result.toReleaseId),
+      };
+    }
+  }
+
+  if (result.status === "RECOVERED") {
+    const fromBundleId = readDirectionalBundleId(result.fromBundleId);
+    const toBundleId = readDirectionalBundleId(result.toBundleId);
+    if (fromBundleId && toBundleId) {
+      return {
+        status: "RECOVERED",
+        fromBundleId,
+        toBundleId,
+        fromReleaseId: readDirectionalReleaseId(result.fromReleaseId),
+        toReleaseId: readDirectionalReleaseId(result.toReleaseId),
+      };
+    }
+  }
+
+  return null;
+};
+
+const getNotifyAppReadyAnalyticsEvent = (
+  result: RawNotifyAppReadyResult,
+): NotifyAppReadyAnalyticsEvent | null => {
+  const transition = getNotifyAppReadyTransition(result);
+
+  if (!transition || !isPersistedUpdateStrategy(result.updateStrategy)) {
+    return null;
+  }
+
+  return {
+    type: transition.status,
+    fromBundleId: transition.fromBundleId,
+    toBundleId: transition.toBundleId,
+    ...(transition.fromReleaseId === null
+      ? {}
+      : { fromReleaseId: transition.fromReleaseId }),
+    ...(transition.toReleaseId === null
+      ? {}
+      : { toReleaseId: transition.toReleaseId }),
+    updateStrategy: result.updateStrategy,
+  };
+};
+
+const normalizeNotifyAppReadyResult = (
+  result: RawNotifyAppReadyResult,
+): NotifyAppReadyResult => {
+  const transition = getNotifyAppReadyTransition(result);
+
+  if (transition) {
+    return {
+      status: transition.status,
+      fromBundleId: transition.fromBundleId,
+      toBundleId: transition.toBundleId,
+      ...(transition.fromReleaseId === null
+        ? {}
+        : { fromReleaseId: transition.fromReleaseId }),
+      ...(transition.toReleaseId === null
+        ? {}
+        : { toReleaseId: transition.toReleaseId }),
+    };
+  }
+
+  return { status: "UNCHANGED" };
+};
+
+export const readNotifyAppReady = (): {
+  result: NotifyAppReadyResult;
+  analyticsEvent: NotifyAppReadyAnalyticsEvent | null;
+  pending: boolean;
+} => {
+  const rawResult = readRawNotifyAppReadyResult();
+
+  return {
+    result: normalizeNotifyAppReadyResult(rawResult),
+    analyticsEvent: getNotifyAppReadyAnalyticsEvent(rawResult),
+    pending: rawResult.status === "PENDING",
+  };
 };
 
 /**
@@ -627,46 +954,21 @@ export type NotifyAppReadyResult = {
  * This function is called automatically after the app has rendered.
  *
  * @returns {NotifyAppReadyResult} Bundle state information
- * - `status: "RECOVERED"` - App recovered from crash, rollback occurred (ROLLBACK event)
- * - `status: "STABLE"` - No changes, already stable
- * - `crashedBundleId` - Present only when status is "RECOVERED"
+ * - `status: "UNCHANGED"` - No qualifying OTA transition to report
+ * - `status: "UPDATE_APPLIED"` - A pending update became active
+ * - `status: "RECOVERED"` - Crash recovery rolled back to another bundle
  *
  * @example
  * ```ts
  * const result = HotUpdater.notifyAppReady();
  *
  * if (result.status === "RECOVERED") {
- *   // Send ROLLBACK analytics event
- *   analytics.track("bundle_rollback", {
- *     crashedBundleId: result.crashedBundleId,
- *   });
+ *   console.log(result.fromBundleId, result.toBundleId);
  * }
  * ```
  */
 export const notifyAppReady = (): NotifyAppReadyResult => {
-  const result = HotUpdaterNative.notifyAppReady();
-  // Older Android old-arch implementations returned JSON strings.
-  if (typeof result === "string") {
-    try {
-      return normalizeNotifyAppReadyResult(JSON.parse(result));
-    } catch {
-      return { status: "STABLE" };
-    }
-  }
-  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" };
+  return readNotifyAppReady().result;
 };
 
 const createEmptyManifest = (): Manifest => ({