@hot-updater/react-native 0.23.1 → 0.24.1

package/src/index.ts

@@ -1,26 +1,37 @@
-import { checkForUpdate } from "./checkForUpdate";
+import {
+  type CheckForUpdateOptions,
+  checkForUpdate,
+  type InternalCheckForUpdateOptions,
+} from "./checkForUpdate";
+import { createDefaultResolver } from "./DefaultResolver";
 import {
   addListener,
+  clearCrashHistory,
   getAppVersion,
   getBundleId,
   getChannel,
+  getCrashHistory,
   getFingerprintHash,
   getMinBundleId,
   reload,
+  type UpdateParams,
   updateBundle,
 } from "./native";
-import { runUpdateProcess } from "./runUpdateProcess";
 import { hotUpdaterStore } from "./store";
-import { wrap } from "./wrap";
+import type { HotUpdaterResolver } from "./types";
+import { type HotUpdaterOptions, type InternalWrapOptions, wrap } from "./wrap";
 
-export type { HotUpdaterEvent } from "./native";
+export type { HotUpdaterEvent, NotifyAppReadyResult } from "./native";
 export * from "./store";
 export {
   extractSignatureFailure,
+  type HotUpdaterResolver,
   isSignatureVerificationError,
+  type ResolverCheckUpdateParams,
+  type ResolverNotifyAppReadyParams,
   type SignatureVerificationFailure,
 } from "./types";
-export type { HotUpdaterOptions } from "./wrap";
+export type { HotUpdaterOptions, RunUpdateProcessResponse } from "./wrap";
 
 addListener("onProgress", ({ progress }) => {
   hotUpdaterStore.setState({
@@ -28,205 +39,303 @@ addListener("onProgress", ({ progress }) => {
   });
 });
 
-export const HotUpdater = {
-  /**
-   * `HotUpdater.wrap` checks for updates at the entry point, and if there is a bundle to update, it downloads the bundle and applies the update strategy.
-   *
-   * @param {object} options - Configuration options
-   * @param {string} options.source - Update server URL
-   * @param {object} [options.requestHeaders] - Request headers
-   * @param {React.ComponentType} [options.fallbackComponent] - Component to display during updates
-   * @param {boolean} [options.reloadOnForceUpdate=true] - Whether to automatically reload the app on force updates
-   * @param {Function} [options.onUpdateProcessCompleted] - Callback after update process completes
-   * @param {Function} [options.onProgress] - Callback to track bundle download progress
-   * @returns {Function} Higher-order component that wraps the app component
-   *
-   * @example
-   * ```tsx
-   * export default HotUpdater.wrap({
-   *   source: "<your-update-server-url>",
-   *   requestHeaders: {
-   *     "Authorization": "Bearer <your-access-token>",
-   *   },
-   * })(App);
-   * ```
-   */
-  wrap,
-  /**
-   * Reloads the app.
-   */
-  reload,
-  /**
-   * Returns whether an update has finished downloading in this app session.
-   *
-   * When it returns true, calling `HotUpdater.reload()` (or restarting the app)
-   * will apply the downloaded update bundle.
-   *
-   * - Derived from `progress` reaching 1.0
-   * - Resets to false when a new download starts (progress < 1)
-   *
-   * @returns {boolean} True if a downloaded update is ready to apply
-   * @example
-   * ```ts
-   * if (HotUpdater.isUpdateDownloaded()) {
-   *   await HotUpdater.reload();
-   * }
-   * ```
-   */
-  isUpdateDownloaded: () => hotUpdaterStore.getSnapshot().isUpdateDownloaded,
-  /**
-   * Fetches the current app version.
-   */
-  getAppVersion,
-  /**
-   * Fetches the current bundle ID of the app.
-   */
-  getBundleId,
-  /**
-   * Retrieves the initial bundle ID based on the build time of the native app.
-   */
-  getMinBundleId,
-  /**
-   * Fetches the current channel of the app.
-   *
-   * If no channel is specified, the app is assigned to the 'production' channel.
-   *
-   * @returns {string} The current release channel of the app
-   * @default "production"
-   * @example
-   * ```ts
-   * const channel = HotUpdater.getChannel();
-   * console.log(`Current channel: ${channel}`);
-   * ```
-   */
-  getChannel,
-  /**
-   * Adds a listener to HotUpdater events.
-   *
-   * @param {keyof HotUpdaterEvent} eventName - The name of the event to listen for
-   * @param {(event: HotUpdaterEvent[T]) => void} listener - The callback function to handle the event
-   * @returns {() => void} A cleanup function that removes the event listener
-   *
-   * @example
-   * ```ts
-   * const unsubscribe = HotUpdater.addListener("onProgress", ({ progress }) => {
-   *   console.log(`Update progress: ${progress * 100}%`);
-   * });
-   *
-   * // Unsubscribe when no longer needed
-   * unsubscribe();
-   * ```
-   */
-  addListener,
-  /**
-   * Manually checks for updates.
-   *
-   * @param {Object} config - Update check configuration
-   * @param {string} config.source - Update server URL
-   * @param {Record<string, string>} [config.requestHeaders] - Request headers
-   *
-   * @returns {Promise<UpdateInfo | null>} Update information or null if up to date
-   *
-   * @example
-   * ```ts
-   * const updateInfo = await HotUpdater.checkForUpdate({
-   *   source: "<your-update-server-url>",
-   *   requestHeaders: {
-   *     Authorization: "Bearer <your-access-token>",
-   *   },
-   * });
-   *
-   * if (!updateInfo) {
-   *   console.log("App is up to date");
-   *   return;
-   * }
-   *
-   * await HotUpdater.updateBundle(updateInfo.id, updateInfo.fileUrl);
-   * if (updateInfo.shouldForceUpdate) {
-   *   await HotUpdater.reload();
-   * }
-   * ```
-   */
-  checkForUpdate,
-  /**
-   * Manually checks and applies updates for the application.
-   *
-   * @param {RunUpdateProcessConfig} config - Update process configuration
-   * @param {string} config.source - Update server URL
-   * @param {Record<string, string>} [config.requestHeaders] - Request headers
-   * @param {boolean} [config.reloadOnForceUpdate=false] - Whether to automatically reload on force update
-   *
-   * @example
-   * ```ts
-   * // Auto reload on force update
-   * const result = await HotUpdater.runUpdateProcess({
-   *   source: "<your-update-server-url>",
-   *   requestHeaders: {
-   *     // Add necessary headers
-   *   },
-   *   reloadOnForceUpdate: true
-   * });
-   *
-   * // Manually handle reload on force update
-   * const result = await HotUpdater.runUpdateProcess({
-   *   source: "<your-update-server-url>",
-   *   reloadOnForceUpdate: false
-   * });
-   *
-   * if(result.status !== "UP_TO_DATE" && result.shouldForceUpdate) {
-   *   await HotUpdater.reload();
-   * }
-   * ```
-   *
-   * @returns {Promise<RunUpdateProcessResponse>} The result of the update process
-   */
-  runUpdateProcess,
-  /**
-   * Updates the bundle of the app.
-   *
-   * @param {UpdateBundleParams} params - Parameters object required for bundle update
-   * @param {string} params.bundleId - The bundle ID of the app
-   * @param {string|null} params.fileUrl - The URL of the zip file
-   *
-   * @returns {Promise<boolean>} Whether the update was successful
-   *
-   * @example
-   * ```ts
-   * const updateInfo = await HotUpdater.checkForUpdate({
-   *   source: "<your-update-server-url>",
-   *   requestHeaders: {
-   *     Authorization: "Bearer <your-access-token>",
-   *   },
-   * });
-   *
-   * if (!updateInfo) {
-   *   return {
-   *     status: "UP_TO_DATE",
-   *   };
-   * }
-   *
-   * await HotUpdater.updateBundle({
-   *   bundleId: updateInfo.id,
-   *   fileUrl: updateInfo.fileUrl
-   * });
-   * if (updateInfo.shouldForceUpdate) {
-   *   await HotUpdater.reload();
-   * }
-   * ```
-   */
-  updateBundle,
-  /**
-   * Fetches the fingerprint of the app.
-   *
-   * @returns {string} The fingerprint of the app
-   *
-   * @example
-   * ```ts
-   * const fingerprint = HotUpdater.getFingerprintHash();
-   * console.log(`Fingerprint: ${fingerprint}`);
-   * ```
-   */
-  getFingerprintHash,
-};
+/**
+ * Creates a HotUpdater client instance with all update management methods.
+ * This function is called once on module initialization to create a singleton instance.
+ */
+function createHotUpdaterClient() {
+  // Global configuration stored from wrap
+  const globalConfig: {
+    resolver: HotUpdaterResolver | null;
+    requestHeaders?: Record<string, string>;
+    requestTimeout?: number;
+  } = {
+    resolver: null,
+  };
+
+  const ensureGlobalResolver = (methodName: string) => {
+    if (!globalConfig.resolver) {
+      throw new Error(
+        `[HotUpdater] ${methodName} requires HotUpdater.wrap() to be used.\n\n` +
+          `To fix this issue, wrap your root component with HotUpdater.wrap():\n\n` +
+          `Option 1: With automatic updates\n` +
+          `  export default HotUpdater.wrap({\n` +
+          `    baseURL: "<your-update-server-url>",\n` +
+          `    updateStrategy: "appVersion",\n` +
+          `    updateMode: "auto"\n` +
+          `  })(App);\n\n` +
+          `Option 2: Manual updates only (custom flow)\n` +
+          `  export default HotUpdater.wrap({\n` +
+          `    baseURL: "<your-update-server-url>",\n` +
+          `    updateMode: "manual"\n` +
+          `  })(App);\n\n` +
+          `For more information, visit: https://hot-updater.dev/docs/react-native-api/wrap`,
+      );
+    }
+    return globalConfig.resolver;
+  };
+
+  return {
+    /**
+     * `HotUpdater.wrap` checks for updates at the entry point, and if there is a bundle to update, it downloads the bundle and applies the update strategy.
+     *
+     * @param {object} options - Configuration options
+     * @param {string} options.source - Update server URL
+     * @param {object} [options.requestHeaders] - Request headers
+     * @param {React.ComponentType} [options.fallbackComponent] - Component to display during updates
+     * @param {boolean} [options.reloadOnForceUpdate=true] - Whether to automatically reload the app on force updates
+     * @param {Function} [options.onUpdateProcessCompleted] - Callback after update process completes
+     * @param {Function} [options.onProgress] - Callback to track bundle download progress
+     * @returns {Function} Higher-order component that wraps the app component
+     *
+     * @example
+     * ```tsx
+     * export default HotUpdater.wrap({
+     *   baseURL: "<your-update-server-url>",
+     *   updateStrategy: "appVersion",
+     *   updateMode: "auto",
+     *   requestHeaders: {
+     *     "Authorization": "Bearer <your-access-token>",
+     *   },
+     * })(App);
+     * ```
+     */
+    wrap: (options: HotUpdaterOptions) => {
+      let normalizedOptions: InternalWrapOptions;
+
+      if ("baseURL" in options && options.baseURL) {
+        const { baseURL, ...rest } = options;
+        normalizedOptions = {
+          ...rest,
+          resolver: createDefaultResolver(baseURL),
+        };
+      } else if ("resolver" in options && options.resolver) {
+        normalizedOptions = options;
+      } else {
+        throw new Error(
+          `[HotUpdater] Either baseURL or resolver must be provided.\n\n` +
+            `Option 1: Using baseURL (recommended for most cases)\n` +
+            `  export default HotUpdater.wrap({\n` +
+            `    baseURL: "<your-update-server-url>",\n` +
+            `    updateStrategy: "appVersion",\n` +
+            `    updateMode: "auto"\n` +
+            `  })(App);\n\n` +
+            `Option 2: Using custom resolver (advanced)\n` +
+            `  export default HotUpdater.wrap({\n` +
+            `    resolver: {\n` +
+            `      checkUpdate: async (params) => { /* custom logic */ },\n` +
+            `      notifyAppReady: async (params) => { /* custom logic */ }\n` +
+            `    },\n` +
+            `    updateMode: "manual"\n` +
+            `  })(App);\n\n` +
+            `For more information, visit: https://hot-updater.dev/docs/react-native-api/wrap`,
+        );
+      }
+
+      globalConfig.resolver = normalizedOptions.resolver;
+      globalConfig.requestHeaders = options.requestHeaders;
+      globalConfig.requestTimeout = options.requestTimeout;
+
+      return wrap(normalizedOptions);
+    },
+
+    /**
+     * Reloads the app.
+     */
+    reload,
+
+    /**
+     * Returns whether an update has finished downloading in this app session.
+     *
+     * When it returns true, calling `HotUpdater.reload()` (or restarting the app)
+     * will apply the downloaded update bundle.
+     *
+     * - Derived from `progress` reaching 1.0
+     * - Resets to false when a new download starts (progress < 1)
+     *
+     * @returns {boolean} True if a downloaded update is ready to apply
+     * @example
+     * ```ts
+     * if (HotUpdater.isUpdateDownloaded()) {
+     *   await HotUpdater.reload();
+     * }
+     * ```
+     */
+    isUpdateDownloaded: () => hotUpdaterStore.getSnapshot().isUpdateDownloaded,
+
+    /**
+     * Fetches the current app version.
+     */
+    getAppVersion,
+
+    /**
+     * Fetches the current bundle ID of the app.
+     */
+    getBundleId,
+
+    /**
+     * Retrieves the initial bundle ID based on the build time of the native app.
+     */
+    getMinBundleId,
+
+    /**
+     * Fetches the current channel of the app.
+     *
+     * If no channel is specified, the app is assigned to the 'production' channel.
+     *
+     * @returns {string} The current release channel of the app
+     * @default "production"
+     * @example
+     * ```ts
+     * const channel = HotUpdater.getChannel();
+     * console.log(`Current channel: ${channel}`);
+     * ```
+     */
+    getChannel,
+
+    /**
+     * Adds a listener to HotUpdater events.
+     *
+     * @param {keyof HotUpdaterEvent} eventName - The name of the event to listen for
+     * @param {(event: HotUpdaterEvent[T]) => void} listener - The callback function to handle the event
+     * @returns {() => void} A cleanup function that removes the event listener
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = HotUpdater.addListener("onProgress", ({ progress }) => {
+     *   console.log(`Update progress: ${progress * 100}%`);
+     * });
+     *
+     * // Unsubscribe when no longer needed
+     * unsubscribe();
+     * ```
+     */
+    addListener,
+
+    /**
+     * Manually checks for updates.
+     *
+     * @param {Object} config - Update check configuration
+     * @param {string} config.source - Update server URL
+     * @param {Record<string, string>} [config.requestHeaders] - Request headers
+     *
+     * @returns {Promise<UpdateInfo | null>} Update information or null if up to date
+     *
+     * @example
+     * ```ts
+     * const updateInfo = await HotUpdater.checkForUpdate({
+     *   source: "<your-update-server-url>",
+     *   requestHeaders: {
+     *     Authorization: "Bearer <your-access-token>",
+     *   },
+     * });
+     *
+     * if (!updateInfo) {
+     *   console.log("App is up to date");
+     *   return;
+     * }
+     *
+     * await HotUpdater.updateBundle(updateInfo.id, updateInfo.fileUrl);
+     * if (updateInfo.shouldForceUpdate) {
+     *   await HotUpdater.reload();
+     * }
+     * ```
+     */
+    checkForUpdate: (config: CheckForUpdateOptions) => {
+      const resolver = ensureGlobalResolver("checkForUpdate");
+
+      const mergedConfig: InternalCheckForUpdateOptions = {
+        ...config,
+        resolver,
+        requestHeaders: {
+          ...globalConfig.requestHeaders,
+          ...config.requestHeaders,
+        },
+        requestTimeout: config.requestTimeout ?? globalConfig.requestTimeout,
+      };
+
+      return checkForUpdate(mergedConfig);
+    },
+
+    /**
+     * Updates the bundle of the app.
+     *
+     * @param {UpdateBundleParams} params - Parameters object required for bundle update
+     * @param {string} params.bundleId - The bundle ID of the app
+     * @param {string|null} params.fileUrl - The URL of the zip file
+     *
+     * @returns {Promise<boolean>} Whether the update was successful
+     *
+     * @example
+     * ```ts
+     * const updateInfo = await HotUpdater.checkForUpdate({
+     *   source: "<your-update-server-url>",
+     *   requestHeaders: {
+     *     Authorization: "Bearer <your-access-token>",
+     *   },
+     * });
+     *
+     * if (!updateInfo) {
+     *   return {
+     *     status: "UP_TO_DATE",
+     *   };
+     * }
+     *
+     * await HotUpdater.updateBundle({
+     *   bundleId: updateInfo.id,
+     *   fileUrl: updateInfo.fileUrl
+     * });
+     * if (updateInfo.shouldForceUpdate) {
+     *   await HotUpdater.reload();
+     * }
+     * ```
+     */
+    updateBundle: (params: UpdateParams) => {
+      ensureGlobalResolver("updateBundle");
+      return updateBundle(params);
+    },
+
+    /**
+     * Fetches the fingerprint of the app.
+     *
+     * @returns {string} The fingerprint of the app
+     *
+     * @example
+     * ```ts
+     * const fingerprint = HotUpdater.getFingerprintHash();
+     * console.log(`Fingerprint: ${fingerprint}`);
+     * ```
+     */
+    getFingerprintHash,
+
+    /**
+     * Gets the list of bundle IDs that have been marked as crashed.
+     * These bundles will be rejected if attempted to install again.
+     *
+     * @returns {string[]} Array of crashed bundle IDs
+     *
+     * @example
+     * ```ts
+     * const crashedBundles = HotUpdater.getCrashHistory();
+     * console.log("Crashed bundles:", crashedBundles);
+     * ```
+     */
+    getCrashHistory,
+
+    /**
+     * Clears the crashed bundle history, allowing previously crashed bundles
+     * to be installed again.
+     *
+     * @returns {boolean} true if clearing was successful
+     *
+     * @example
+     * ```ts
+     * // Clear crash history to allow retrying a previously failed bundle
+     * HotUpdater.clearCrashHistory();
+     * ```
+     */
+    clearCrashHistory,
+  };
+}
 
-export { getUpdateSource } from "./checkForUpdate";
+export const HotUpdater = createHotUpdaterClient();

package/src/native.ts

@@ -1,9 +1,12 @@
 import type { UpdateStatus } from "@hot-updater/core";
 import { NativeEventEmitter } from "react-native";
+import { HotUpdaterErrorCode, isHotUpdaterError } from "./error";
 import HotUpdaterNative, {
   type UpdateBundleParams,
 } from "./specs/NativeHotUpdater";
 
+export { HotUpdaterErrorCode, isHotUpdaterError };
+
 const NIL_UUID = "00000000-0000-0000-0000-000000000000";
 
 declare const __HOT_UPDATER_BUNDLE_ID: string | undefined;
@@ -43,7 +46,8 @@ let lastInstalledBundleId: string | null = null;
  * 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, otherwise rejects with an error.
+ * @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>;
 /**
@@ -146,7 +150,7 @@ export const getMinBundleId = (): string => {
  * Fetches the current bundle version id.
  *
  * @async
- * @returns {Promise<string>} Resolves with the current version id or null if not available.
+ * @returns {string} Resolves with the current version id or null if not available.
  */
 export const getBundleId = (): string => {
   return HotUpdaterConstants.HOT_UPDATER_BUNDLE_ID === NIL_UUID
@@ -173,3 +177,85 @@ export const getFingerprintHash = (): string | null => {
   const constants = HotUpdaterNative.getConstants();
   return constants.FINGERPRINT_HASH;
 };
+
+/**
+ * Result returned by notifyAppReady()
+ */
+export type NotifyAppReadyResult = {
+  status: "PROMOTED" | "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.
+ *
+ * This function is called automatically when the module loads.
+ *
+ * @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"
+ *
+ * @example
+ * ```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;
+ * }
+ * ```
+ */
+export const notifyAppReady = (): NotifyAppReadyResult => {
+  const bundleId = getBundleId();
+  const result = HotUpdaterNative.notifyAppReady({ bundleId });
+  // Oldarch returns JSON string, newarch returns array
+  if (typeof result === "string") {
+    try {
+      return JSON.parse(result);
+    } catch {
+      return { status: "STABLE" };
+    }
+  }
+  return result;
+};
+
+/**
+ * Gets the list of bundle IDs that have been marked as crashed.
+ * These bundles will be rejected if attempted to install again.
+ *
+ * @returns {string[]} Array of crashed bundle IDs
+ */
+export const getCrashHistory = (): string[] => {
+  const result = HotUpdaterNative.getCrashHistory();
+  // Oldarch returns JSON string, newarch returns array
+  if (typeof result === "string") {
+    try {
+      return JSON.parse(result);
+    } catch {
+      return [];
+    }
+  }
+  return result;
+};
+
+/**
+ * Clears the crashed bundle history, allowing previously crashed bundles
+ * to be installed again.
+ *
+ * @returns {boolean} true if clearing was successful
+ */
+export const clearCrashHistory = (): boolean => {
+  return HotUpdaterNative.clearCrashHistory();
+};