@hot-updater/react-native 0.30.12 → 0.31.0

package/src/index.ts

@@ -28,17 +28,21 @@ import {
 import { hotUpdaterStore } from "./store";
 import type { HotUpdaterResolver } from "./types";
 import {
+  type AutoUpdateOptions,
   type HotUpdaterInitOptions,
   type HotUpdaterOptions,
   init,
   type InternalInitOptions,
   type InternalWrapOptions,
+  type ManualUpdateOptions,
   wrap,
 } from "./wrap";
 
 export type {
   CustomReloadHandler,
   HotUpdaterEvent,
+  HotUpdaterProgressArtifactType,
+  HotUpdaterProgressEvent,
   Manifest,
   ManifestAsset,
   NotifyAppReadyResult,
@@ -56,8 +60,10 @@ export {
   type SignatureVerificationFailure,
 } from "./types";
 export type {
+  HotUpdaterFallbackComponentProps,
   HotUpdaterInitOptions,
   HotUpdaterOptions,
+  ManualUpdateOptions,
   RunUpdateProcessResponse,
 } from "./wrap";
 
@@ -79,6 +85,33 @@ const registerGlobalGetBaseURL = () => {
 // Call registration immediately on module load
 registerGlobalGetBaseURL();
 
+type HotUpdaterWrap = {
+  (options: AutoUpdateOptions): ReturnType<typeof wrap>;
+  /**
+   * @deprecated Replace manual `HotUpdater.wrap` with `HotUpdater.init`.
+   *
+   * ```tsx
+   * import { HotUpdater } from "@hot-updater/react-native";
+   *
+   * HotUpdater.init({
+   *   baseURL: "<your-update-server-url>",
+   * });
+   *
+   * export default App;
+   * ```
+   *
+   * Then call `HotUpdater.checkForUpdate(...)` from your manual update flow.
+   * See https://hot-updater.dev/docs/guides/custom-update
+   */
+  (options: ManualUpdateOptions): ReturnType<typeof wrap>;
+  (options: HotUpdaterOptions): ReturnType<typeof wrap>;
+};
+
+const isManualWrapOptions = (
+  options: HotUpdaterOptions,
+): options is ManualUpdateOptions =>
+  "updateMode" in options && options.updateMode === "manual";
+
 /**
  * Creates a HotUpdater client instance with all update management methods.
  * This function is called once on module initialization to create a singleton instance.
@@ -89,6 +122,7 @@ function createHotUpdaterClient() {
     resolver: HotUpdaterResolver | null;
     requestHeaders?: Record<string, string>;
     requestTimeout?: number;
+    onError?: (error: unknown) => void;
   } = {
     resolver: null,
   };
@@ -96,54 +130,67 @@ function createHotUpdaterClient() {
   const createMissingNetworkConfigError = (apiName: "init" | "wrap") => {
     if (apiName === "init") {
       return new Error(
-        `[HotUpdater] baseURL must be provided.\n\n` +
-          `Configure HotUpdater before calling update APIs:\n\n` +
+        `[HotUpdater] Either baseURL or resolver must be provided.\n\n` +
+          `Configure HotUpdater before calling update APIs with the standard baseURL setup:\n\n` +
           `  HotUpdater.init({\n` +
           `    baseURL: "<your-update-server-url>",\n` +
           `  });\n\n` +
-          `For more information, visit: https://hot-updater.dev/docs/react-native-api/init`,
+          `For manual update flows, visit: https://hot-updater.dev/docs/guides/custom-update`,
       );
     }
 
     const baseURLExample =
       `  export default HotUpdater.wrap({\n` +
       `    baseURL: "<your-update-server-url>",\n` +
-      `    updateStrategy: "appVersion",\n` +
-      `    updateMode: "auto"\n` +
-      `  })(App);\n\n`;
-
-    const resolverExample =
-      `  export default HotUpdater.wrap({\n` +
-      `    resolver: {\n` +
-      `      checkUpdate: async (params) => { /* custom logic */ },\n` +
-      `      notifyAppReady: async (params) => { /* custom logic */ }\n` +
-      `    },\n` +
-      `    updateMode: "manual"\n` +
+      `    updateStrategy: "appVersion"\n` +
       `  })(App);\n\n`;
 
     return new Error(
       `[HotUpdater] Either baseURL or resolver must be provided.\n\n` +
-        `Option 1: Using baseURL (recommended for most cases)\n` +
+        `Configure HotUpdater.wrap with the standard baseURL setup:\n\n` +
         baseURLExample +
-        `Option 2: Using custom resolver (advanced)\n` +
-        resolverExample +
-        `For more information, visit: https://hot-updater.dev/docs/react-native-api/${apiName}`,
+        `For manual update flows, use HotUpdater.init() and visit: ` +
+        `https://hot-updater.dev/docs/guides/custom-update`,
     );
   };
 
   const normalizeOptions = (
     options: HotUpdaterOptions,
   ): InternalWrapOptions => {
-    if ("baseURL" in options && options.baseURL) {
-      const { baseURL, ...rest } = options;
+    if (isManualWrapOptions(options)) {
+      if ("baseURL" in options && options.baseURL) {
+        const { baseURL, ...rest } = options;
+        return {
+          ...rest,
+          resolver: createDefaultResolver(baseURL),
+          updateMode: "manual",
+        };
+      }
+
+      if ("resolver" in options && options.resolver) {
+        return {
+          ...options,
+          updateMode: "manual",
+        };
+      }
+    }
+
+    const autoOptions = options as AutoUpdateOptions;
+
+    if ("baseURL" in autoOptions && autoOptions.baseURL) {
+      const { baseURL, ...rest } = autoOptions;
       return {
         ...rest,
         resolver: createDefaultResolver(baseURL),
+        updateMode: "auto",
       };
     }
 
-    if ("resolver" in options && options.resolver) {
-      return options;
+    if ("resolver" in autoOptions && autoOptions.resolver) {
+      return {
+        ...autoOptions,
+        updateMode: "auto",
+      };
     }
 
     throw createMissingNetworkConfigError("wrap");
@@ -152,21 +199,23 @@ function createHotUpdaterClient() {
   const normalizeInitOptions = (
     options: HotUpdaterInitOptions,
   ): InternalInitOptions => {
-    const {
-      baseURL,
-      updateMode: _updateMode,
-      ...rest
-    } = options as HotUpdaterInitOptions & {
-      updateMode?: unknown;
-    };
-
-    if (baseURL) {
+    const { updateMode: _updateMode, ...rest } =
+      options as HotUpdaterInitOptions & {
+        updateMode?: unknown;
+      };
+
+    if ("baseURL" in rest && rest.baseURL) {
+      const { baseURL, ...baseURLRest } = rest;
       return {
-        ...rest,
+        ...baseURLRest,
         resolver: createDefaultResolver(baseURL),
       };
     }
 
+    if ("resolver" in rest && rest.resolver) {
+      return rest;
+    }
+
     throw createMissingNetworkConfigError("init");
   };
 
@@ -177,6 +226,7 @@ function createHotUpdaterClient() {
     globalConfig.resolver = normalizedOptions.resolver;
     globalConfig.requestHeaders = options.requestHeaders;
     globalConfig.requestTimeout = options.requestTimeout;
+    globalConfig.onError = options.onError;
   };
 
   const ensureGlobalResolver = (methodName: string) => {
@@ -187,15 +237,13 @@ function createHotUpdaterClient() {
           `Option 1: With HotUpdater.wrap()\n` +
           `  export default HotUpdater.wrap({\n` +
           `    baseURL: "<your-update-server-url>",\n` +
-          `    updateStrategy: "appVersion",\n` +
-          `    updateMode: "auto"\n` +
+          `    updateStrategy: "appVersion"\n` +
           `  })(App);\n\n` +
           `Option 2: With HotUpdater.init() for custom runtimes\n` +
           `  HotUpdater.init({\n` +
           `    baseURL: "<your-update-server-url>",\n` +
           `  });\n\n` +
-          `For more information, visit: https://hot-updater.dev/docs/react-native-api/wrap ` +
-          `or https://hot-updater.dev/docs/react-native-api/init`,
+          `For manual update flows, visit: https://hot-updater.dev/docs/guides/custom-update`,
       );
     }
     return globalConfig.resolver;
@@ -219,7 +267,6 @@ function createHotUpdaterClient() {
      * export default HotUpdater.wrap({
      *   baseURL: "<your-update-server-url>",
      *   updateStrategy: "appVersion",
-     *   updateMode: "auto",
      *   requestHeaders: {
      *     "Authorization": "Bearer <your-access-token>",
      *   },
@@ -237,8 +284,8 @@ function createHotUpdaterClient() {
      * Initializes HotUpdater without wrapping a React component.
      *
      * Use this for manual update flows in runtimes where a root component HOC
-     * is not convenient. It has the same initialization effect as
-     * `HotUpdater.wrap({ updateMode: "manual" })(App)`.
+     * is not convenient. Replace deprecated manual
+     * `HotUpdater.wrap({ updateMode: "manual" })(App)` usage with this API.
      *
      * @example
      * ```tsx
@@ -420,6 +467,7 @@ function createHotUpdaterClient() {
           ...config.requestHeaders,
         },
         requestTimeout: config.requestTimeout ?? globalConfig.requestTimeout,
+        onError: config.onError ?? globalConfig.onError,
       };
 
       return checkForUpdate(mergedConfig);
@@ -472,8 +520,12 @@ function createHotUpdaterClient() {
       const ok = await resetChannel();
       if (ok) {
         hotUpdaterStore.setState({
+          artifactType: null,
+          details: null,
+          downloadedBytes: undefined,
           isUpdateDownloaded: false,
           progress: 0,
+          totalBytes: undefined,
         });
       }
       return ok;
@@ -522,4 +574,11 @@ function createHotUpdaterClient() {
   };
 }
 
-export const HotUpdater = createHotUpdaterClient();
+type HotUpdaterClient = Omit<
+  ReturnType<typeof createHotUpdaterClient>,
+  "wrap"
+> & {
+  wrap: HotUpdaterWrap;
+};
+
+export const HotUpdater: HotUpdaterClient = createHotUpdaterClient();

package/src/native.spec.ts

@@ -167,6 +167,7 @@ describe("notifyAppReady", () => {
       assets: {
         "assets/logo.png": {
           fileHash: "hash-logo",
+          signature: "sig-logo",
         },
         "index.android.bundle": {
           fileHash: "hash-bundle",
@@ -181,6 +182,7 @@ describe("notifyAppReady", () => {
       assets: {
         "assets/logo.png": {
           fileHash: "hash-logo",
+          signature: "sig-logo",
         },
         "index.android.bundle": {
           fileHash: "hash-bundle",
@@ -337,11 +339,147 @@ describe("notifyAppReady", () => {
       bundleId: "bundle-123",
     });
     expect(getBaseURL()).toBe("file:///bundle-123");
-    expect(nativeModuleMock.getBundleId).toHaveBeenCalledTimes(2);
+    expect(nativeModuleMock.getBundleId).toHaveBeenCalledTimes(3);
     expect(nativeModuleMock.getManifest).toHaveBeenCalledTimes(2);
     expect(nativeModuleMock.getBaseURL).toHaveBeenCalledTimes(2);
   });
 
+  it("reinstalls a session-installed bundle after native resets to built-in", async () => {
+    nativeModuleMock.getConstants.mockReturnValue({
+      APP_VERSION: null,
+      CHANNEL: "production",
+      DEFAULT_CHANNEL: "production",
+      FINGERPRINT_HASH: null,
+      MIN_BUNDLE_ID: "00000000-0000-0000-0000-000000000001",
+    });
+    nativeModuleMock.getBundleId.mockReturnValue(
+      "00000000-0000-0000-0000-000000000002",
+    );
+    nativeModuleMock.updateBundle.mockResolvedValue(true);
+
+    const { getBundleId, updateBundle } = await import("./native");
+
+    await updateBundle({
+      bundleId: "00000000-0000-0000-0000-000000000003",
+      fileHash: null,
+      fileUrl: "https://example.com/bundle.zip",
+      status: "UPDATE",
+    });
+
+    nativeModuleMock.getBundleId.mockReturnValue(
+      "00000000-0000-0000-0000-000000000003",
+    );
+    expect(getBundleId()).toBe("00000000-0000-0000-0000-000000000003");
+
+    nativeModuleMock.getBundleId.mockReturnValue(null);
+
+    await expect(
+      updateBundle({
+        bundleId: "00000000-0000-0000-0000-000000000003",
+        fileHash: null,
+        fileUrl: "https://example.com/bundle.zip",
+        status: "UPDATE",
+      }),
+    ).resolves.toBe(true);
+
+    expect(nativeModuleMock.updateBundle).toHaveBeenCalledTimes(2);
+  });
+
+  it("skips a session-installed bundle when native still reports it active", async () => {
+    nativeModuleMock.getConstants.mockReturnValue({
+      APP_VERSION: null,
+      CHANNEL: "production",
+      DEFAULT_CHANNEL: "production",
+      FINGERPRINT_HASH: null,
+      MIN_BUNDLE_ID: "00000000-0000-0000-0000-000000000001",
+    });
+    nativeModuleMock.getBundleId.mockReturnValue(
+      "00000000-0000-0000-0000-000000000002",
+    );
+    nativeModuleMock.updateBundle.mockResolvedValue(true);
+
+    const { updateBundle } = await import("./native");
+
+    await updateBundle({
+      bundleId: "00000000-0000-0000-0000-000000000003",
+      fileHash: null,
+      fileUrl: "https://example.com/bundle.zip",
+      status: "UPDATE",
+    });
+
+    nativeModuleMock.getBundleId.mockReturnValue(
+      "00000000-0000-0000-0000-000000000003",
+    );
+
+    await expect(
+      updateBundle({
+        bundleId: "00000000-0000-0000-0000-000000000003",
+        fileHash: null,
+        fileUrl: "https://example.com/bundle.zip",
+        status: "UPDATE",
+      }),
+    ).resolves.toBe(true);
+
+    expect(nativeModuleMock.updateBundle).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards manifest artifact parameters to native updateBundle", async () => {
+    nativeModuleMock.getBundleId.mockReturnValue("bundle-123");
+    nativeModuleMock.updateBundle.mockResolvedValue(true);
+
+    const { updateBundle } = await import("./native");
+
+    await updateBundle({
+      bundleId: "bundle-789",
+      changedAssets: {
+        "index.ios.bundle": {
+          file: {
+            compression: "br",
+            url: "https://example.com/files/index.ios.bundle.br",
+          },
+          fileHash: "hash-next",
+          patch: {
+            algorithm: "bsdiff",
+            baseBundleId: "bundle-123",
+            baseFileHash: "hash-prev",
+            patchFileHash: "hash-patch",
+            patchUrl: "https://example.com/files/index.ios.bundle.bsdiff",
+          },
+        },
+      },
+      fileHash: "sig:archive",
+      fileUrl: "https://example.com/bundle.zip",
+      manifestFileHash: "sig:manifest",
+      manifestUrl: "https://example.com/manifest.json",
+      status: "UPDATE",
+    });
+
+    expect(nativeModuleMock.updateBundle).toHaveBeenCalledWith({
+      bundleId: "bundle-789",
+      changedAssets: {
+        "index.ios.bundle": {
+          file: {
+            compression: "br",
+            url: "https://example.com/files/index.ios.bundle.br",
+          },
+          fileHash: "hash-next",
+          patch: {
+            algorithm: "bsdiff",
+            baseBundleId: "bundle-123",
+            baseFileHash: "hash-prev",
+            patchFileHash: "hash-patch",
+            patchUrl: "https://example.com/files/index.ios.bundle.bsdiff",
+          },
+        },
+      },
+      channel: undefined,
+      fileHash: "sig:archive",
+      fileUrl: "https://example.com/bundle.zip",
+      manifestFileHash: "sig:manifest",
+      manifestUrl: "https://example.com/manifest.json",
+    });
+  });
+
   it("invalidates cached bundle getters after resetChannel succeeds", async () => {
     nativeModuleMock.getConstants.mockReturnValue({
       APP_VERSION: null,

package/src/native.ts

@@ -1,4 +1,5 @@
 import {
+  type ChangedAsset,
   INVALID_COHORT_ERROR_MESSAGE,
   isValidCohort,
   normalizeCohortValue,
@@ -24,6 +25,7 @@ const normalizeAndValidateCohort = (cohort: string): string => {
 
 export interface ManifestAsset {
   fileHash: string;
+  signature?: string;
 }
 
 export interface Manifest {
@@ -186,11 +188,38 @@ const cloneManifest = (manifest: Manifest): Manifest => ({
   assets: Object.fromEntries(
     Object.entries(manifest.assets).map(([key, asset]) => [
       key,
-      { fileHash: asset.fileHash },
+      {
+        fileHash: asset.fileHash,
+        ...(asset.signature ? { signature: asset.signature } : {}),
+      },
     ]),
   ),
 });
 
+const getNativeBundleId = (): string | null => {
+  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.",
+    );
+  }
+
+  return nativeModule.getBundleId();
+};
+
+const resolveBundleId = (bundleId: string | null): string => {
+  return !bundleId || bundleId === NIL_UUID ? getMinBundleId() : bundleId;
+};
+
+const getFreshBundleId = (): string => {
+  const resolvedBundleId = resolveBundleId(getNativeBundleId());
+  sessionState.cacheBundleId(resolvedBundleId);
+  return resolvedBundleId;
+};
+
 const getReloadProcess = (): (() => Promise<void>) | null => {
   const nativeModule = HotUpdaterNative as typeof HotUpdaterNative & {
     reloadProcess?: () => Promise<void>;
@@ -201,10 +230,73 @@ const getReloadProcess = (): (() => Promise<void>) | null => {
     : null;
 };
 
+export type HotUpdaterProgressArtifactType = "archive" | "diff";
+
+export type HotUpdaterDiffFileStatus =
+  | "pending"
+  | "downloading"
+  | "downloaded"
+  | "failed";
+
+export interface HotUpdaterDiffFileSnapshot {
+  /**
+   * Manifest asset path for this progress entry.
+   *
+   * This is the stable identity of the asset in the installed bundle. Use this
+   * when matching progress back to the manifest or to the final file location.
+   */
+  path: string;
+  /**
+   * Artifact path currently being transferred for this progress entry.
+   *
+   * Usually this is the same as `path`. It can differ when the updater
+   * downloads an intermediate artifact that will be applied to produce the
+   * final asset.
+   */
+  downloadPath: string;
+  /**
+   * Current download state for this asset within the manifest diff update.
+   */
+  status: HotUpdaterDiffFileStatus;
+  /**
+   * Download progress for this file, normalized from 0 to 1.
+   */
+  progress: number;
+  /**
+   * Stable display order among diff files.
+   */
+  order: number;
+  /**
+   * Bytes downloaded for `downloadPath`, when the native downloader reports it.
+   */
+  downloadedBytes?: number;
+  /**
+   * Total expected bytes for `downloadPath`, when known.
+   */
+  totalBytes?: number;
+}
+
+export interface HotUpdaterDiffProgressDetails {
+  totalFilesCount: number;
+  completedFilesCount: number;
+  files: HotUpdaterDiffFileSnapshot[];
+}
+
+export type HotUpdaterProgressEvent =
+  | {
+      progress: number;
+      artifactType: "archive";
+      downloadedBytes?: number;
+      totalBytes?: number;
+    }
+  | {
+      progress: number;
+      artifactType: "diff";
+      details: HotUpdaterDiffProgressDetails;
+    };
+
 export type HotUpdaterEvent = {
-  onProgress: {
-    progress: number;
-  };
+  onProgress: HotUpdaterProgressEvent;
 };
 
 const eventEmitter = new NativeEventEmitter(HotUpdaterNative);
@@ -252,8 +344,21 @@ export async function updateBundle(
   const status =
     typeof paramsOrBundleId === "string" ? "UPDATE" : paramsOrBundleId.status;
 
-  // If we have already installed this bundle in this session, skip re-download.
-  if (status === "UPDATE" && sessionState.hasInstalledBundle(updateBundleId)) {
+  const targetFileUrl =
+    typeof paramsOrBundleId === "string"
+      ? (fileUrl ?? null)
+      : paramsOrBundleId.fileUrl;
+
+  const currentBundleId = status === "UPDATE" ? getFreshBundleId() : undefined;
+
+  // If native is still on the same bundle we installed in this session,
+  // skip re-download. Native state can move back to the built-in bundle after
+  // rollback/reset, so check a fresh native bundle id before using this guard.
+  if (
+    status === "UPDATE" &&
+    sessionState.hasInstalledBundle(updateBundleId) &&
+    currentBundleId === updateBundleId
+  ) {
     return true;
   }
 
@@ -265,7 +370,8 @@ export async function updateBundle(
   if (
     !shouldSkipCurrentBundleIdCheck &&
     status === "UPDATE" &&
-    updateBundleId.localeCompare(getBundleId()) <= 0
+    currentBundleId !== undefined &&
+    updateBundleId.localeCompare(currentBundleId) <= 0
   ) {
     throw new Error(
       "Update bundle id is not newer than the current bundle id. Preventing infinite update loop.",
@@ -276,11 +382,6 @@ export async function updateBundle(
   const existing = sessionState.getInflightUpdate(updateBundleId);
   if (existing) return existing;
 
-  const targetFileUrl =
-    typeof paramsOrBundleId === "string"
-      ? (fileUrl ?? null)
-      : paramsOrBundleId.fileUrl;
-
   const targetFileHash =
     typeof paramsOrBundleId === "string"
       ? undefined
@@ -288,14 +389,30 @@ export async function updateBundle(
 
   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 promise = (async () => {
     try {
       const ok = 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,
       });
       if (ok) {
         sessionState.markBundleInstalled(updateBundleId, targetChannel);
@@ -424,23 +541,7 @@ export const getBundleId = (): string => {
     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;
+  return getFreshBundleId();
 };
 
 /**
@@ -617,12 +718,25 @@ const normalizeManifestAssets = (value: unknown): Manifest["assets"] => {
         return [];
       }
 
-      const { fileHash } = entry as { fileHash?: unknown };
+      const { fileHash, signature } = entry as {
+        fileHash?: unknown;
+        signature?: unknown;
+      };
       if (typeof fileHash !== "string" || !fileHash.trim()) {
         return [];
       }
 
-      return [[trimmedKey, { fileHash: fileHash.trim() }] as const];
+      return [
+        [
+          trimmedKey,
+          {
+            fileHash: fileHash.trim(),
+            ...(typeof signature === "string" && signature.trim()
+              ? { signature: signature.trim() }
+              : {}),
+          },
+        ] as const,
+      ];
     }),
   );
 };

package/src/sdkVersion.ts

@@ -0,0 +1 @@
+export const HOT_UPDATER_SDK_VERSION = "0.30.12";