@hot-updater/react-native 1.0.0-rc.4 → 1.0.0-rc.41

package/src/init.types.ts

@@ -0,0 +1,24 @@
+import type { HotUpdaterClientPlugin } from "./clientPlugin";
+import type { HotUpdaterError } from "./error";
+import type { NotifyAppReadyResult } from "./native";
+import type { HotUpdaterBaseURL } from "./types";
+
+export interface HotUpdaterInitOptions<
+  TPlugins extends readonly HotUpdaterClientPlugin[] =
+    readonly HotUpdaterClientPlugin[],
+> {
+  /**
+   * Client plugins, such as `insights()` and `remoteConfig()` from
+   * `@hot-updater/react-native`. Each plugin's `setup` runs once for the
+   * instance `init` returns; its hooks observe that instance's launch,
+   * update checks, downloads, and update failures, and its API is on the
+   * instance, under the plugin's id. Plugin ids must be unique.
+   */
+  plugins?: TPlugins;
+  /** Base URL of a server exposing the Hot Updater v1 client HTTP protocol. */
+  baseURL: HotUpdaterBaseURL;
+  requestHeaders?: Record<string, string>;
+  requestTimeout?: number;
+  onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+  onError?: (error: HotUpdaterError | Error | unknown) => void;
+}

package/src/native.ts

@@ -1,12 +1,12 @@
 import {
-  type ChangedAsset,
+  type ArtifactAsset,
   type CatalogHighWater,
   INVALID_COHORT_ERROR_MESSAGE,
   isValidCohort,
   normalizeCohortValue,
   type UpdateStatus,
   type PersistedSelectionReceipt,
-} from "@hot-updater/core";
+} from "@hot-updater/protocol";
 import { NativeEventEmitter, Platform } from "react-native";
 
 import { HotUpdaterErrorCode, isHotUpdaterError } from "./error";
@@ -46,7 +46,7 @@ type ActiveBundleSnapshotCacheValues = {
 type ActiveBundleSnapshotCacheKey = keyof ActiveBundleSnapshotCacheValues;
 
 /**
- * Built-in reload behaviors used by `HotUpdater.reload()`.
+ * Built-in reload behaviors used by `hotUpdater.reload()`.
  *
  * - `reload`: In-process React Native reload.
  * - `processRestart`: Android-only cold restart. On iOS the same call behaves like `reload`.
@@ -74,7 +74,10 @@ class HotUpdaterSessionState {
   private readonly defaultChannel: string;
   private currentChannel: string;
   private cachedCohort: string | undefined;
-  private readonly inflightUpdates = new Map<string, Promise<boolean>>();
+  private readonly inflightUpdates = new Map<
+    string,
+    Promise<BundleDelivery | null>
+  >();
   private lastInstalledBundleId: string | null = null;
   private readonly activeBundleSnapshotCache = new Map<
     ActiveBundleSnapshotCacheKey,
@@ -103,11 +106,16 @@ class HotUpdaterSessionState {
     return this.lastInstalledBundleId === bundleId;
   }
 
-  getInflightUpdate(bundleId: string): Promise<boolean> | undefined {
+  getInflightUpdate(
+    bundleId: string,
+  ): Promise<BundleDelivery | null> | undefined {
     return this.inflightUpdates.get(bundleId);
   }
 
-  trackInflightUpdate(bundleId: string, promise: Promise<boolean>) {
+  trackInflightUpdate(
+    bundleId: string,
+    promise: Promise<BundleDelivery | null>,
+  ) {
     this.inflightUpdates.set(bundleId, promise);
   }
 
@@ -234,7 +242,7 @@ const getReloadProcess = (): (() => Promise<void>) | null => {
     : null;
 };
 
-export type HotUpdaterProgressArtifactType = "archive" | "diff";
+export type HotUpdaterProgressArtifactType = "diff";
 
 export type HotUpdaterDiffFileStatus =
   | "pending"
@@ -286,18 +294,11 @@ export interface HotUpdaterDiffProgressDetails {
   files: HotUpdaterDiffFileSnapshot[];
 }
 
-export type HotUpdaterProgressEvent =
-  | {
-      progress: number;
-      artifactType: "archive";
-      downloadedBytes?: number;
-      totalBytes?: number;
-    }
-  | {
-      progress: number;
-      artifactType: "diff";
-      details: HotUpdaterDiffProgressDetails;
-    };
+export type HotUpdaterProgressEvent = {
+  progress: number;
+  artifactType: "diff";
+  details: HotUpdaterDiffProgressDetails;
+};
 
 export type HotUpdaterEvent = {
   onProgress: HotUpdaterProgressEvent;
@@ -424,18 +425,42 @@ export const commitReleaseSelection = async (input: {
   return ok;
 };
 
+/** How native delivered a staged bundle. */
+export type BundleDelivery = {
+  /**
+   * "patch" when a bsdiff patch produced a file, "manifest" when only the
+   * changed files were downloaded, "archive" for the full archive.
+   */
+  readonly delivery: "patch" | "manifest" | "archive";
+  /** A patch was tried, but the file or the archive was downloaded instead. */
+  readonly patchFallback: boolean;
+};
+
+const readBundleDelivery = (value: unknown): BundleDelivery | null => {
+  if (typeof value !== "object" || value === null) return null;
+  const { delivery, patchFallback } = value as Record<string, unknown>;
+  if (
+    delivery !== "patch" &&
+    delivery !== "manifest" &&
+    delivery !== "archive"
+  ) {
+    return null;
+  }
+  return { delivery, patchFallback: patchFallback === true };
+};
+
 /**
- * Downloads files and applies them to the app.
+ * Stages a bundle for the next launch. Resolves with how native delivered
+ * it, or with null when this runtime had already staged it and nothing was
+ * downloaded; rejects when the download or install fails.
  *
- * @param {UpdateParams} params - Parameters object required for bundle update
- * @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> {
+export async function stageBundle(
+  params: UpdateParams,
+): Promise<BundleDelivery | null> {
   const updateBundleId = params.bundleId;
   const status = params.status;
-  const targetFileUrl = params.fileUrl;
-
   const currentBundleId = status === "UPDATE" ? getFreshBundleId() : undefined;
 
   // If native is still on the same bundle we installed in this session,
@@ -446,7 +471,7 @@ export async function updateBundle(params: UpdateParams): Promise<boolean> {
     sessionState.hasInstalledBundle(updateBundleId) &&
     currentBundleId === updateBundleId
   ) {
-    return true;
+    return null;
   }
 
   const shouldSkipCurrentBundleIdCheck =
@@ -467,30 +492,25 @@ export async function updateBundle(params: UpdateParams): Promise<boolean> {
   const existing = sessionState.getInflightUpdate(updateBundleId);
   if (existing) return existing;
 
-  const targetFileHash = params.fileHash;
   const targetChannel = params.channel;
   const targetManifestUrl = params.manifestUrl;
   const targetManifestFileHash = params.manifestFileHash;
-  const targetChangedAssets = params.changedAssets;
+  const targetAssets = params.assets;
 
   const promise = (async () => {
     try {
       const selection = params.selection;
-      const ok = await HotUpdaterNative.updateBundle({
+      const staged = await HotUpdaterNative.updateBundle({
         bundleId: updateBundleId,
         channel: targetChannel,
-        changedAssets:
-          (targetChangedAssets as Record<string, ChangedAsset> | null) ?? null,
-        fileUrl: targetFileUrl,
-        fileHash: targetFileHash ?? null,
-        manifestFileHash: targetManifestFileHash ?? null,
-        manifestUrl: targetManifestUrl ?? null,
+        assets: targetAssets as Record<string, ArtifactAsset>,
+        manifestFileHash: targetManifestFileHash,
+        manifestUrl: targetManifestUrl,
+        ...(params.archiveUrl ? { archiveUrl: params.archiveUrl } : {}),
         ...(selection === undefined ? {} : { selection }),
       });
-      if (ok) {
-        sessionState.markBundleInstalled(updateBundleId, targetChannel);
-      }
-      return ok;
+      sessionState.markBundleInstalled(updateBundleId, targetChannel);
+      return readBundleDelivery(staged);
     } finally {
       sessionState.clearInflightUpdate(updateBundleId);
     }
@@ -500,6 +520,18 @@ export async function updateBundle(params: UpdateParams): Promise<boolean> {
   return promise;
 }
 
+/**
+ * Downloads files and applies them to the app.
+ *
+ * @param {UpdateParams} params - Parameters object required for bundle update
+ * @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> {
+  await stageBundle(params);
+  return true;
+}
+
 /**
  * Fetches the current app version.
  */
@@ -546,7 +578,7 @@ export const reload = async () => {
 };
 
 /**
- * Configures how `HotUpdater.reload()` should behave.
+ * Configures how `hotUpdater.reload()` should behave.
  *
  * This API is available on both Android and iOS so app code can stay symmetric.
  * By default, HotUpdater uses `processRestart`.
@@ -705,64 +737,31 @@ export const getInstallId = (): string => {
   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"
-  ) {
+const requireStorageNativeMethod = <T extends (...args: any[]) => any>(
+  name: "getStorageItem" | "setStorageItem",
+): T => {
+  const method = (HotUpdaterNative as unknown as Record<string, unknown>)[name];
+  if (typeof method !== "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.",
+      `[HotUpdater] Native module is missing '${name}()'. 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 } : {}),
-  };
+  return method.bind(HotUpdaterNative) as T;
 };
 
-export type SetUserParams = {
-  userId?: string | number | null;
-  username?: string | null;
+/** Reads a value from the SDK's native key-value store. */
+export const getStorageItem = (key: string): string | null => {
+  const value =
+    requireStorageNativeMethod<(key: string) => unknown>("getStorageItem")(key);
+  return typeof value === "string" ? value : 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);
-}
+/** Writes a value to the SDK's native key-value store; null removes it. */
+export const setStorageItem = (key: string, value: string | null): void => {
+  requireStorageNativeMethod<(key: string, value: string | null) => void>(
+    "setStorageItem",
+  )(key, value);
+};
 
 /**
  * Result returned by notifyAppReady()
@@ -784,12 +783,13 @@ export type NotifyAppReadyResult =
       toReleaseId?: string;
     };
 
-export type NotifyAppReadyInsightsEvent = {
+/** An update applied or recovered at this launch, as native persisted it. */
+export type LaunchTransition = {
   type: "UPDATE_APPLIED" | "RECOVERED";
   fromBundleId: string;
   toBundleId: string;
-  fromReleaseId?: string | null;
-  toReleaseId?: string | null;
+  fromReleaseId: string | null;
+  toReleaseId: string | null;
   updateStrategy: PersistedUpdateStrategy;
 };
 
@@ -892,9 +892,9 @@ const getNotifyAppReadyTransition = (
   return null;
 };
 
-const getNotifyAppReadyInsightsEvent = (
+const getLaunchTransition = (
   result: RawNotifyAppReadyResult,
-): NotifyAppReadyInsightsEvent | null => {
+): LaunchTransition | null => {
   const transition = getNotifyAppReadyTransition(result);
 
   if (!transition || !isPersistedUpdateStrategy(result.updateStrategy)) {
@@ -905,12 +905,8 @@ const getNotifyAppReadyInsightsEvent = (
     type: transition.status,
     fromBundleId: transition.fromBundleId,
     toBundleId: transition.toBundleId,
-    ...(transition.fromReleaseId === null
-      ? {}
-      : { fromReleaseId: transition.fromReleaseId }),
-    ...(transition.toReleaseId === null
-      ? {}
-      : { toReleaseId: transition.toReleaseId }),
+    fromReleaseId: transition.fromReleaseId,
+    toReleaseId: transition.toReleaseId,
     updateStrategy: result.updateStrategy,
   };
 };
@@ -939,14 +935,14 @@ const normalizeNotifyAppReadyResult = (
 
 export const readNotifyAppReady = (): {
   result: NotifyAppReadyResult;
-  insightsEvent: NotifyAppReadyInsightsEvent | null;
+  transition: LaunchTransition | null;
   pending: boolean;
 } => {
   const rawResult = readRawNotifyAppReadyResult();
 
   return {
     result: normalizeNotifyAppReadyResult(rawResult),
-    insightsEvent: getNotifyAppReadyInsightsEvent(rawResult),
+    transition: getLaunchTransition(rawResult),
     pending: rawResult.status === "PENDING",
   };
 };
@@ -963,7 +959,7 @@ export const readNotifyAppReady = (): {
  *
  * @example
  * ```ts
- * const result = HotUpdater.notifyAppReady();
+ * const result = hotUpdater.notifyAppReady();
  *
  * if (result.status === "RECOVERED") {
  *   console.log(result.fromBundleId, result.toBundleId);

package/src/pluginHost.ts

@@ -0,0 +1,52 @@
+import {
+  createPluginHost,
+  type PluginHost,
+  type PluginHostEnvironment,
+} from "@hot-updater/protocol";
+import { Platform } from "react-native";
+
+import {
+  getAppVersion,
+  getBundleId,
+  getChannel,
+  getCohort,
+  getFingerprintHash,
+  getInstallId,
+  getMinBundleId,
+  getStorageItem,
+  setStorageItem,
+} from "./native";
+import { HOT_UPDATER_SDK_VERSION } from "./sdkVersion";
+
+export type { PluginHost, PluginHostConfig } from "@hot-updater/protocol";
+
+/** The native module and runtime every plugin host reads. */
+const environment: PluginHostEnvironment = {
+  fetch: (url, init) => fetch(url, init),
+  get platform() {
+    return Platform.OS === "android" ? "android" : "ios";
+  },
+  get isDebugBuild() {
+    return typeof __DEV__ !== "undefined" && __DEV__;
+  },
+  get sdkVersion() {
+    return HOT_UPDATER_SDK_VERSION;
+  },
+  getInstallId: () => getInstallId(),
+  getAppVersion: () => getAppVersion(),
+  getMinBundleId: () => getMinBundleId(),
+  getBundleId: () => getBundleId(),
+  getChannel: () => getChannel(),
+  getCohort: () => getCohort(),
+  getFingerprintHash: () => getFingerprintHash(),
+  getStorageItem: (key) => getStorageItem(key),
+  setStorageItem: (key, value) => setStorageItem(key, value),
+  now: () => Date.now(),
+};
+
+/**
+ * Creates an instance's plugin host: its plugins read the native module and
+ * fetch the server the instance was configured with.
+ */
+export const createAppPluginHost = (): PluginHost =>
+  createPluginHost(environment);