@hot-updater/react-native 0.23.1 → 0.24.1

package/src/checkForUpdate.ts

@@ -1,7 +1,6 @@
-import type { AppUpdateInfo, UpdateBundleParams } from "@hot-updater/core";
+import type { AppUpdateInfo } from "@hot-updater/core";
 import { Platform } from "react-native";
 import { HotUpdaterError } from "./error";
-import { fetchUpdateInfo, type UpdateSource } from "./fetchUpdateInfo";
 import {
   getAppVersion,
   getBundleId,
@@ -10,9 +9,17 @@ import {
   getMinBundleId,
   updateBundle,
 } from "./native";
+import type { HotUpdaterResolver } from "./types";
 
 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,13 @@ export type CheckForUpdateResult = AppUpdateInfo & {
   updateBundle: () => Promise<boolean>;
 };
 
+// Internal type that includes resolver for use within index.ts
+export interface InternalCheckForUpdateOptions extends CheckForUpdateOptions {
+  resolver: HotUpdaterResolver;
+}
+
 export async function checkForUpdate(
-  options: CheckForUpdateOptions,
+  options: InternalCheckForUpdateOptions,
 ): Promise<CheckForUpdateResult | null> {
   if (__DEV__) {
     return null;
@@ -57,62 +69,45 @@ export async function checkForUpdate(
 
   const fingerprintHash = getFingerprintHash();
 
-  return fetchUpdateInfo({
-    source: options.source,
-    params: {
-      bundleId: currentBundleId,
-      appVersion: currentAppVersion,
+  if (!options.resolver?.checkUpdate) {
+    options.onError?.(
+      new HotUpdaterError("Resolver is required but not configured"),
+    );
+    return null;
+  }
+
+  let updateInfo: AppUpdateInfo | null = null;
+
+  try {
+    updateInfo = await options.resolver.checkUpdate({
       platform,
+      appVersion: currentAppVersion,
+      bundleId: currentBundleId,
       minBundleId,
       channel,
+      updateStrategy: options.updateStrategy,
       fingerprintHash,
-    },
-    requestHeaders: options.requestHeaders,
-    onError: options.onError,
-    requestTimeout: options.requestTimeout,
-  }).then((updateInfo) => {
-    if (!updateInfo) {
-      return null;
-    }
-
-    return {
-      ...updateInfo,
-      updateBundle: async () => {
-        return updateBundle({
-          bundleId: updateInfo.id,
-          fileUrl: updateInfo.fileUrl,
-          fileHash: updateInfo.fileHash,
-          status: updateInfo.status,
-        });
-      },
-    };
-  });
-}
+      requestHeaders: options.requestHeaders,
+      requestTimeout: options.requestTimeout,
+    });
+  } catch (error) {
+    options.onError?.(error as Error);
+    return null;
+  }
 
-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";
-}
+  if (!updateInfo) {
+    return null;
+  }
 
-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;
-    }
+  return {
+    ...updateInfo,
+    updateBundle: async () => {
+      return updateBundle({
+        bundleId: updateInfo.id,
+        fileUrl: updateInfo.fileUrl,
+        fileHash: updateInfo.fileHash,
+        status: updateInfo.status,
+      });
+    },
   };
+}

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);