@hot-updater/react-native 0.23.0 → 0.24.0

package/lib/typescript/module/wrap.d.ts

@@ -1,9 +1,72 @@
 import React from "react";
-import { type CheckForUpdateOptions } from "./checkForUpdate";
 import type { HotUpdaterError } from "./error";
-import type { RunUpdateProcessResponse } from "./runUpdateProcess";
+import { type NotifyAppReadyResult } from "./native";
+export interface RunUpdateProcessResponse {
+    status: "ROLLBACK" | "UPDATE" | "UP_TO_DATE";
+    shouldForceUpdate: boolean;
+    message: string | null;
+    id: string;
+}
 type UpdateStatus = "CHECK_FOR_UPDATE" | "UPDATING" | "UPDATE_PROCESS_COMPLETED";
-export interface HotUpdaterOptions extends CheckForUpdateOptions {
+/**
+ * Common options shared between auto and manual update modes
+ */
+interface CommonHotUpdaterOptions {
+    /**
+     * Base URL for update server
+     * @example "https://update.example.com"
+     */
+    baseURL: string;
+    /**
+     * Custom request headers for update checks
+     */
+    requestHeaders?: Record<string, string>;
+    /**
+     * Request timeout in milliseconds
+     * @default 5000
+     */
+    requestTimeout?: number;
+    /**
+     * Callback invoked when the app is ready and bundle verification completes.
+     * Provides information about bundle promotion, recovery from crashes, 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"
+     *
+     * @example
+     * ```tsx
+     * HotUpdater.wrap({
+     *   baseURL: "https://api.example.com",
+     *   updateMode: "manual",
+     *   onNotifyAppReady: ({ status, crashedBundleId }) => {
+     *     if (status === "RECOVERED") {
+     *       analytics.track('bundle_rollback', { crashedBundleId });
+     *     } else if (status === "PROMOTED") {
+     *       analytics.track('bundle_promoted');
+     *     }
+     *   }
+     * })(App);
+     * ```
+     */
+    onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+}
+export interface AutoUpdateOptions extends CommonHotUpdaterOptions {
+    /**
+     * Update strategy
+     * - "fingerprint": Use fingerprint hash to check for updates
+     * - "appVersion": Use app version to check for updates
+     */
+    updateStrategy: "fingerprint" | "appVersion";
+    /**
+     * Update mode
+     * - "auto": Automatically check and download updates
+     */
+    updateMode: "auto";
+    onError?: (error: HotUpdaterError | Error | unknown) => void;
     /**
      * Component to show while downloading a new bundle update.
      *
@@ -14,7 +77,8 @@ export interface HotUpdaterOptions extends CheckForUpdateOptions {
      *
      * ```tsx
      * HotUpdater.wrap({
-     *   source: "<update-server-url>",
+     *   baseURL: "<update-server-url>",
+     *   updateStrategy: "appVersion",
      *   fallbackComponent: ({ progress = 0 }) => (
      *     <View style={styles.container}>
      *       <Text style={styles.text}>Updating... {progress}%</Text>
@@ -30,7 +94,6 @@ export interface HotUpdaterOptions extends CheckForUpdateOptions {
         progress: number;
         message: string | null;
     }>;
-    onError?: (error: HotUpdaterError | Error | unknown) => void;
     onProgress?: (progress: number) => void;
     /**
      * When a force update exists, the app will automatically reload.
@@ -46,6 +109,14 @@ export interface HotUpdaterOptions extends CheckForUpdateOptions {
      */
     onUpdateProcessCompleted?: (response: RunUpdateProcessResponse) => void;
 }
+export interface ManualUpdateOptions extends CommonHotUpdaterOptions {
+    /**
+     * Update mode
+     * - "manual": Only notify app ready, user manually calls checkForUpdate()
+     */
+    updateMode: "manual";
+}
+export type HotUpdaterOptions = AutoUpdateOptions | ManualUpdateOptions;
 export declare function wrap<P extends React.JSX.IntrinsicAttributes = object>(options: HotUpdaterOptions): (WrappedComponent: React.ComponentType<P>) => React.ComponentType<P>;
 export {};
 //# sourceMappingURL=wrap.d.ts.map

package/lib/typescript/module/wrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../../src/wrap.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+C,MAAM,OAAO,CAAC;AACpE,OAAO,EAAE,KAAK,qBAAqB,EAAkB,MAAM,kBAAkB,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG/C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAGnE,KAAK,YAAY,GACb,kBAAkB,GAClB,UAAU,GACV,0BAA0B,CAAC;AAE/B,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB;IAC9D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,0BAA0B,CAAC,CAAC;QAC1D,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;KACxB,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,GAAG,KAAK,GAAG,OAAO,KAAK,IAAI,CAAC;IAC7D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,IAAI,CAAC;CACzE;AAED,wBAAgB,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,mBAAmB,GAAG,MAAM,EACnE,OAAO,EAAE,iBAAiB,GACzB,CAAC,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAuGtE"}
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../../src/wrap.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA+C,MAAM,OAAO,CAAC;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,UAAU,CAAC;AAGlB,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,YAAY,CAAC;IAC7C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,KAAK,YAAY,GACb,kBAAkB,GAClB,UAAU,GACV,0BAA0B,CAAC;AAE/B;;GAEG;AACH,UAAU,uBAAuB;IAC/B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,iBAAkB,SAAQ,uBAAuB;IAChE;;;;OAIG;IACH,cAAc,EAAE,aAAa,GAAG,YAAY,CAAC;IAE7C;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,GAAG,KAAK,GAAG,OAAO,KAAK,IAAI,CAAC;IAE7D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,0BAA0B,CAAC,CAAC;QAC1D,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;KACxB,CAAC,CAAC;IAEH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,IAAI,CAAC;CACzE;AAED,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE;;;OAGG;IACH,UAAU,EAAE,QAAQ,CAAC;CACtB;AAED,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;AAExE,wBAAgB,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,mBAAmB,GAAG,MAAM,EACnE,OAAO,EAAE,iBAAiB,GACzB,CAAC,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAwItE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hot-updater/react-native",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "React Native OTA solution for self-hosted",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -111,22 +111,23 @@
   },
   "devDependencies": {
     "@react-native-community/cli": "18.0.0",
+    "@types/node": "^22.10.5",
     "@types/react": "19.1.3",
     "@types/use-sync-external-store": "^0.0.6",
     "del-cli": "^6.0.0",
     "expo": "^50.0.0",
-    "react": "19.1.0",
+    "react": "19.1.2",
     "react-native": "0.79.1",
     "react-native-builder-bob": "^0.40.10",
     "typescript": "^5.8.3",
-    "hot-updater": "0.23.0"
+    "hot-updater": "0.24.0"
   },
   "dependencies": {
     "use-sync-external-store": "1.5.0",
-    "@hot-updater/cli-tools": "0.23.0",
-    "@hot-updater/plugin-core": "0.23.0",
-    "@hot-updater/js": "0.23.0",
-    "@hot-updater/core": "0.23.0"
+    "@hot-updater/cli-tools": "0.24.0",
+    "@hot-updater/js": "0.24.0",
+    "@hot-updater/core": "0.24.0",
+    "@hot-updater/plugin-core": "0.24.0"
   },
   "scripts": {
     "build": "bob build && tsc -p plugin/tsconfig.build.json",

package/plugin/build/withHotUpdater.js

@@ -42,6 +42,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var cli_tools_1 = require("@hot-updater/cli-tools");
 var config_plugins_1 = require("expo/config-plugins");
 var hot_updater_1 = require("hot-updater");
+var path_1 = __importDefault(require("path"));
 var package_json_1 = __importDefault(require("../../package.json"));
 var transformers_1 = require("./transformers");
 var fingerprintCache = null;
@@ -62,6 +63,36 @@ var getFingerprint = function () { return __awaiter(void 0, void 0, void 0, func
         }
     });
 }); };
+/**
+ * Extract public key from private key in signing config
+ */
+var getPublicKeyFromConfig = function (signingConfig) { return __awaiter(void 0, void 0, void 0, function () {
+    var privateKeyPath, privateKeyPEM, publicKeyPEM, error_1;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                if (!(signingConfig === null || signingConfig === void 0 ? void 0 : signingConfig.enabled) || !(signingConfig === null || signingConfig === void 0 ? void 0 : signingConfig.privateKeyPath)) {
+                    return [2 /*return*/, null];
+                }
+                _a.label = 1;
+            case 1:
+                _a.trys.push([1, 3, , 4]);
+                privateKeyPath = path_1.default.isAbsolute(signingConfig.privateKeyPath)
+                    ? signingConfig.privateKeyPath
+                    : path_1.default.resolve(process.cwd(), signingConfig.privateKeyPath);
+                return [4 /*yield*/, (0, hot_updater_1.loadPrivateKey)(privateKeyPath)];
+            case 2:
+                privateKeyPEM = _a.sent();
+                publicKeyPEM = (0, hot_updater_1.getPublicKeyFromPrivate)(privateKeyPEM);
+                return [2 /*return*/, publicKeyPEM.trim()];
+            case 3:
+                error_1 = _a.sent();
+                throw new Error("[hot-updater] Failed to extract public key: ".concat(error_1 instanceof Error ? error_1.message : String(error_1), "\n") +
+                    "Run 'npx hot-updater keys generate' to create signing keys");
+            case 4: return [2 /*return*/];
+        }
+    });
+}); };
 /**
  * Native code modifications - should only run once
  */
@@ -91,7 +122,7 @@ var withHotUpdaterConfigAsync = function (props) { return function (config) {
     var modifiedConfig = config;
     // === iOS: Add channel and fingerprint to Info.plist ===
     modifiedConfig = (0, config_plugins_1.withInfoPlist)(modifiedConfig, function (cfg) { return __awaiter(void 0, void 0, void 0, function () {
-        var fingerprintHash, config, fingerprint;
+        var fingerprintHash, config, fingerprint, publicKey;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
@@ -105,18 +136,23 @@ var withHotUpdaterConfigAsync = function (props) { return function (config) {
                     fingerprint = _a.sent();
                     fingerprintHash = fingerprint.ios.hash;
                     _a.label = 3;
-                case 3:
+                case 3: return [4 /*yield*/, getPublicKeyFromConfig(config.signing)];
+                case 4:
+                    publicKey = _a.sent();
                     cfg.modResults.HOT_UPDATER_CHANNEL = channel;
                     if (fingerprintHash) {
                         cfg.modResults.HOT_UPDATER_FINGERPRINT_HASH = fingerprintHash;
                     }
+                    if (publicKey) {
+                        cfg.modResults.HOT_UPDATER_PUBLIC_KEY = publicKey;
+                    }
                     return [2 /*return*/, cfg];
             }
         });
     }); });
     // === Android: Add channel and fingerprint to strings.xml ===
     modifiedConfig = (0, config_plugins_1.withStringsXml)(modifiedConfig, function (cfg) { return __awaiter(void 0, void 0, void 0, function () {
-        var fingerprintHash, config, fingerprint;
+        var fingerprintHash, config, fingerprint, publicKey;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
@@ -130,7 +166,9 @@ var withHotUpdaterConfigAsync = function (props) { return function (config) {
                     fingerprint = _a.sent();
                     fingerprintHash = fingerprint.android.hash;
                     _a.label = 3;
-                case 3:
+                case 3: return [4 /*yield*/, getPublicKeyFromConfig(config.signing)];
+                case 4:
+                    publicKey = _a.sent();
                     // Ensure resources object exists
                     if (!cfg.modResults.resources) {
                         cfg.modResults.resources = {};
@@ -163,6 +201,19 @@ var withHotUpdaterConfigAsync = function (props) { return function (config) {
                             _: fingerprintHash,
                         });
                     }
+                    if (publicKey) {
+                        // Remove existing hot_updater_public_key entry if it exists
+                        cfg.modResults.resources.string =
+                            cfg.modResults.resources.string.filter(function (item) { return !(item.$ && item.$.name === "hot_updater_public_key"); });
+                        // Add the new hot_updater_public_key entry
+                        cfg.modResults.resources.string.push({
+                            $: {
+                                name: "hot_updater_public_key",
+                                moduleConfig: "true",
+                            },
+                            _: publicKey,
+                        });
+                    }
                     return [2 /*return*/, cfg];
             }
         });

package/src/checkForUpdate.ts

@@ -1,7 +1,7 @@
 import type { AppUpdateInfo, UpdateBundleParams } from "@hot-updater/core";
 import { Platform } from "react-native";
 import { HotUpdaterError } from "./error";
-import { fetchUpdateInfo, type UpdateSource } from "./fetchUpdateInfo";
+import { fetchUpdateInfo } from "./fetchUpdateInfo";
 import {
   getAppVersion,
   getBundleId,
@@ -12,7 +12,14 @@ import {
 } from "./native";
 
 export interface CheckForUpdateOptions {
-  source: UpdateSource;
+  /**
+   * Update strategy
+   * - "fingerprint": Use fingerprint hash to check for updates
+   * - "appVersion": Use app version to check for updates
+   * - Can override the strategy set in HotUpdater.wrap()
+   */
+  updateStrategy: "appVersion" | "fingerprint";
+
   requestHeaders?: Record<string, string>;
   onError?: (error: Error) => void;
   /**
@@ -30,8 +37,32 @@ export type CheckForUpdateResult = AppUpdateInfo & {
   updateBundle: () => Promise<boolean>;
 };
 
+// Internal type that includes baseURL for use within index.ts
+export interface InternalCheckForUpdateOptions extends CheckForUpdateOptions {
+  baseURL: string;
+}
+
+// Internal function to build update URL (not exported)
+function buildUpdateUrl(
+  baseURL: string,
+  updateStrategy: "appVersion" | "fingerprint",
+  params: UpdateBundleParams,
+): string {
+  switch (updateStrategy) {
+    case "fingerprint": {
+      if (!params.fingerprintHash) {
+        throw new HotUpdaterError("Fingerprint hash is required");
+      }
+      return `${baseURL}/fingerprint/${params.platform}/${params.fingerprintHash}/${params.channel}/${params.minBundleId}/${params.bundleId}`;
+    }
+    case "appVersion": {
+      return `${baseURL}/app-version/${params.platform}/${params.appVersion}/${params.channel}/${params.minBundleId}/${params.bundleId}`;
+    }
+  }
+}
+
 export async function checkForUpdate(
-  options: CheckForUpdateOptions,
+  options: InternalCheckForUpdateOptions,
 ): Promise<CheckForUpdateResult | null> {
   if (__DEV__) {
     return null;
@@ -44,6 +75,13 @@ export async function checkForUpdate(
     return null;
   }
 
+  if (!options.baseURL || !options.updateStrategy) {
+    options.onError?.(
+      new HotUpdaterError("'baseURL' and 'updateStrategy' are required"),
+    );
+    return null;
+  }
+
   const currentAppVersion = getAppVersion();
   const platform = Platform.OS as "ios" | "android";
   const currentBundleId = getBundleId();
@@ -57,16 +95,17 @@ export async function checkForUpdate(
 
   const fingerprintHash = getFingerprintHash();
 
+  const url = buildUpdateUrl(options.baseURL, options.updateStrategy, {
+    platform,
+    appVersion: currentAppVersion,
+    fingerprintHash: fingerprintHash ?? null,
+    channel,
+    minBundleId,
+    bundleId: currentBundleId,
+  });
+
   return fetchUpdateInfo({
-    source: options.source,
-    params: {
-      bundleId: currentBundleId,
-      appVersion: currentAppVersion,
-      platform,
-      minBundleId,
-      channel,
-      fingerprintHash,
-    },
+    url,
     requestHeaders: options.requestHeaders,
     onError: options.onError,
     requestTimeout: options.requestTimeout,
@@ -88,31 +127,3 @@ export async function checkForUpdate(
     };
   });
 }
-
-export interface GetUpdateSourceOptions {
-  /**
-   * The update strategy to use.
-   * @description
-   * - "fingerprint": Use the fingerprint hash to check for updates.
-   * - "appVersion": Use the target app version to check for updates.
-   */
-  updateStrategy: "appVersion" | "fingerprint";
-}
-
-export const getUpdateSource =
-  (baseUrl: string, options: GetUpdateSourceOptions) =>
-  (params: UpdateBundleParams) => {
-    switch (options.updateStrategy) {
-      case "fingerprint": {
-        if (!params.fingerprintHash) {
-          throw new HotUpdaterError("Fingerprint hash is required");
-        }
-        return `${baseUrl}/fingerprint/${params.platform}/${params.fingerprintHash}/${params.channel}/${params.minBundleId}/${params.bundleId}`;
-      }
-      case "appVersion": {
-        return `${baseUrl}/app-version/${params.platform}/${params.appVersion}/${params.channel}/${params.minBundleId}/${params.bundleId}`;
-      }
-      default:
-        return baseUrl;
-    }
-  };

package/src/error.ts

@@ -1,3 +1,156 @@
+/**
+ * Hot Updater Error Codes
+ *
+ * This file defines all possible error codes that can be thrown by the native
+ * updateBundle function. These error codes are shared across iOS and Android
+ * implementations to ensure consistent error handling.
+ *
+ * Error Classification:
+ * - Parameter Validation: Invalid or missing function parameters
+ * - Bundle Storage: Errors during download, extraction, and storage
+ * - Signature Verification: Cryptographic verification failures (collapsed to a single public code)
+ * - Internal: Platform-specific or unexpected errors
+ *
+ * Retryability:
+ * - Retryable: DOWNLOAD_FAILED, INCOMPLETE_DOWNLOAD
+ * - Non-retryable: Most validation and verification errors
+ */
+
+export enum HotUpdaterErrorCode {
+  // ==================== Parameter Validation Errors ====================
+
+  /**
+   * Bundle ID is missing or empty.
+   * Thrown when bundleId parameter is null, undefined, or empty string.
+   * @retryable false
+   */
+  MISSING_BUNDLE_ID = "MISSING_BUNDLE_ID",
+
+  /**
+   * File URL is invalid or malformed.
+   * Thrown when fileUrl parameter cannot be parsed as a valid URL.
+   * @retryable false
+   */
+  INVALID_FILE_URL = "INVALID_FILE_URL",
+
+  // ==================== Bundle Storage Errors ====================
+
+  /**
+   * Failed to create required directory for bundle storage.
+   * Thrown when bundle directory creation fails due to permissions or disk errors.
+   * @retryable false - Usually indicates permissions or filesystem corruption
+   */
+  DIRECTORY_CREATION_FAILED = "DIRECTORY_CREATION_FAILED",
+
+  /**
+   * Bundle download failed.
+   * Covers network errors, HTTP errors (4xx/5xx), timeouts, and connection issues.
+   * Check error message for specific cause (network, HTTP status code, etc.).
+   * @retryable true - Network issues are often transient
+   */
+  DOWNLOAD_FAILED = "DOWNLOAD_FAILED",
+
+  /**
+   * Download incomplete - received size doesn't match expected size.
+   * Thrown when downloaded file size doesn't match Content-Length header.
+   * Error message includes both expected and actual byte counts.
+   * @retryable true - Download may succeed on retry
+   */
+  INCOMPLETE_DOWNLOAD = "INCOMPLETE_DOWNLOAD",
+
+  /**
+   * Bundle archive format is invalid or corrupted.
+   * Thrown when ZIP file has wrong magic bytes, invalid structure, or unsupported format.
+   * Also thrown for path traversal attempts during extraction.
+   * @retryable false - Indicates corrupted or malicious bundle
+   */
+  EXTRACTION_FORMAT_ERROR = "EXTRACTION_FORMAT_ERROR",
+
+  /**
+   * Bundle missing required platform files.
+   * Thrown when extracted bundle doesn't contain index.android.bundle (Android)
+   * or main.jsbundle (iOS).
+   * @retryable false - Indicates incorrectly built bundle
+   */
+  INVALID_BUNDLE = "INVALID_BUNDLE",
+
+  /**
+   * Insufficient disk space for bundle download and extraction.
+   * Thrown when available disk space is less than required (file size * 2).
+   * Error message includes required and available bytes.
+   * @retryable false - User must free up disk space
+   */
+  INSUFFICIENT_DISK_SPACE = "INSUFFICIENT_DISK_SPACE",
+
+  /**
+   * Bundle signature verification failed (general).
+   * Thrown when cryptographic signature verification fails.
+   * All signature/hash sub-errors are collapsed into this public code.
+   * @retryable false - Indicates tampered or incorrectly signed bundle
+   */
+  SIGNATURE_VERIFICATION_FAILED = "SIGNATURE_VERIFICATION_FAILED",
+
+  /**
+   * Failed to move bundle to final location.
+   * Thrown when atomic move from temp directory to final directory fails.
+   * iOS: Thrown if move operation fails.
+   * Android: Thrown if rename, move, AND copy all fail.
+   * @retryable false - Usually indicates filesystem corruption or permissions
+   */
+  MOVE_OPERATION_FAILED = "MOVE_OPERATION_FAILED",
+
+  /**
+   * Bundle is in crashed history and cannot be applied.
+   * Thrown when attempting to install a bundle that previously caused a crash.
+   * Use HotUpdater.clearCrashHistory() to allow retrying this bundle.
+   * @retryable false - Bundle was marked as crashed for safety
+   */
+  BUNDLE_IN_CRASHED_HISTORY = "BUNDLE_IN_CRASHED_HISTORY",
+
+  // ==================== Signature Verification Errors ====================
+  // (Collapsed into SIGNATURE_VERIFICATION_FAILED)
+
+  // ==================== Internal Errors ====================
+
+  /**
+   * Internal error: self deallocated during update (iOS only).
+   * Thrown when the native object is deallocated mid-operation.
+   * iOS-specific due to manual memory management (ARC).
+   * Not applicable to Android (uses garbage collection).
+   * @platform iOS
+   * @retryable false - Memory management issue
+   */
+  SELF_DEALLOCATED = "SELF_DEALLOCATED",
+
+  /**
+   * An unknown or unexpected error occurred.
+   * Catch-all for errors that don't fit other categories.
+   * Check error message for details.
+   * @retryable unknown - Depends on underlying cause
+   */
+  UNKNOWN_ERROR = "UNKNOWN_ERROR",
+}
+
+/**
+ * Type guard to check if an error is a HotUpdaterError
+ */
+export function isHotUpdaterError(
+  error: unknown,
+): error is { code: HotUpdaterErrorCode; message: string } {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    typeof error.code === "string" &&
+    Object.values(HotUpdaterErrorCode).includes(
+      error.code as HotUpdaterErrorCode,
+    )
+  );
+}
+
+/**
+ * Base error class for Hot Updater
+ */
 export class HotUpdaterError extends Error {
   constructor(message: string) {
     super(message);

package/src/fetchUpdateInfo.ts

@@ -1,76 +1,28 @@
-import type {
-  AppUpdateInfo,
-  UpdateBundleParams,
-  UpdateStrategy,
-} from "@hot-updater/core";
-
-export type UpdateSource =
-  | string
-  | ((params: UpdateBundleParams) => Promise<AppUpdateInfo | null>)
-  | ((params: UpdateBundleParams) => string);
-
-function buildRequestHeaders(
-  params: UpdateBundleParams,
-  requestHeaders?: Record<string, string>,
-): Record<string, string> {
-  const updateStrategy: UpdateStrategy = params.fingerprintHash
-    ? "fingerprint"
-    : "appVersion";
-
-  return {
-    "Content-Type": "application/json",
-    "x-app-platform": params.platform,
-    "x-bundle-id": params.bundleId,
-    ...(updateStrategy === "fingerprint"
-      ? { "x-fingerprint-hash": params.fingerprintHash! }
-      : { "x-app-version": params.appVersion }),
-    ...(params.minBundleId && { "x-min-bundle-id": params.minBundleId }),
-    ...(params.channel && { "x-channel": params.channel }),
-    ...requestHeaders,
-  };
-}
-
-async function resolveSource(
-  source: UpdateSource,
-  params: UpdateBundleParams,
-): Promise<{ url: string } | { info: AppUpdateInfo | null }> {
-  if (typeof source !== "function") {
-    return { url: source };
-  }
-  const result = source(params);
-  if (typeof result === "string") {
-    return { url: result };
-  }
-  return { info: await result };
-}
+import type { AppUpdateInfo } from "@hot-updater/core";
 
 export const fetchUpdateInfo = async ({
-  source,
-  params,
+  url,
   requestHeaders,
   onError,
   requestTimeout = 5000,
 }: {
-  source: UpdateSource;
-  params: UpdateBundleParams;
+  url: string;
   requestHeaders?: Record<string, string>;
   onError?: (error: Error) => void;
   requestTimeout?: number;
 }): Promise<AppUpdateInfo | null> => {
   try {
-    const resolvedSource = await resolveSource(source, params);
-    if ("info" in resolvedSource) {
-      return resolvedSource.info;
-    }
-
     const controller = new AbortController();
     const timeoutId = setTimeout(() => {
       controller.abort();
     }, requestTimeout);
 
-    const headers = buildRequestHeaders(params, requestHeaders);
+    const headers = {
+      "Content-Type": "application/json",
+      ...requestHeaders,
+    };
 
-    const response = await fetch(resolvedSource.url, {
+    const response = await fetch(url, {
       signal: controller.signal,
       headers,
     });
@@ -80,8 +32,8 @@ export const fetchUpdateInfo = async ({
       throw new Error(response.statusText);
     }
     return response.json();
-  } catch (error: any) {
-    if (error.name === "AbortError") {
+  } catch (error: unknown) {
+    if (error instanceof Error && error.name === "AbortError") {
       onError?.(new Error("Request timed out"));
     } else {
       onError?.(error as Error);