@hot-updater/react-native 0.24.0 → 0.24.1

package/src/types.ts

@@ -1,3 +1,138 @@
+import type { AppUpdateInfo } from "@hot-updater/core";
+import type { NotifyAppReadyResult } from "./native";
+
+/**
+ * Parameters passed to resolver.checkUpdate method
+ */
+export interface ResolverCheckUpdateParams {
+  /**
+   * The platform the app is running on
+   */
+  platform: "ios" | "android";
+
+  /**
+   * The current app version
+   */
+  appVersion: string;
+
+  /**
+   * The current bundle ID
+   */
+  bundleId: string;
+
+  /**
+   * Minimum bundle ID from build time
+   */
+  minBundleId: string;
+
+  /**
+   * The channel name (e.g., "production", "staging")
+   */
+  channel: string;
+
+  /**
+   * Update strategy being used
+   */
+  updateStrategy: "fingerprint" | "appVersion";
+
+  /**
+   * The fingerprint hash (only present when using fingerprint strategy)
+   */
+  fingerprintHash: string | null;
+
+  /**
+   * Request headers from global config (for optional use)
+   */
+  requestHeaders?: Record<string, string>;
+
+  /**
+   * Request timeout from global config (for optional use)
+   */
+  requestTimeout?: number;
+}
+
+/**
+ * Parameters passed to resolver.notifyAppReady method
+ */
+export interface ResolverNotifyAppReadyParams {
+  /**
+   * The bundle state from native notifyAppReady
+   * - "PROMOTED": Staging bundle was promoted to stable
+   * - "RECOVERED": App recovered from crash, rollback occurred
+   * - "STABLE": No changes, bundle is stable
+   */
+  status: "PROMOTED" | "RECOVERED" | "STABLE";
+
+  /**
+   * Present only when status is "RECOVERED"
+   */
+  crashedBundleId?: string;
+
+  /**
+   * Request headers from global config (for optional use)
+   */
+  requestHeaders?: Record<string, string>;
+
+  /**
+   * Request timeout from global config (for optional use)
+   */
+  requestTimeout?: number;
+}
+
+/**
+ * Resolver interface for custom network operations
+ */
+export interface HotUpdaterResolver {
+  /**
+   * Custom implementation for checking updates.
+   * When provided, this completely replaces the default fetchUpdateInfo flow.
+   *
+   * @param params - All parameters needed to check for updates
+   * @returns Update information or null if up to date
+   *
+   * @example
+   * ```typescript
+   * checkUpdate: async (params) => {
+   *   const response = await fetch(`https://api.custom.com/check`, {
+   *     method: 'POST',
+   *     body: JSON.stringify(params),
+   *     headers: params.requestHeaders,
+   *   });
+   *
+   *   if (!response.ok) return null;
+   *   return response.json();
+   * }
+   * ```
+   */
+  checkUpdate?: (
+    params: ResolverCheckUpdateParams,
+  ) => Promise<AppUpdateInfo | null>;
+
+  /**
+   * Custom implementation for notifying app ready.
+   * When provided, this completely replaces the default notifyAppReady network flow.
+   * Note: The native notifyAppReady for bundle promotion still happens automatically.
+   *
+   * @param params - All parameters about the current app state
+   * @returns Notification result
+   *
+   * @example
+   * ```typescript
+   * notifyAppReady: async (params) => {
+   *   await fetch(`https://api.custom.com/notify`, {
+   *     method: 'POST',
+   *     body: JSON.stringify(params),
+   *   });
+   *
+   *   return { status: "STABLE" };
+   * }
+   * ```
+   */
+  notifyAppReady?: (
+    params: ResolverNotifyAppReadyParams,
+  ) => Promise<NotifyAppReadyResult | undefined>;
+}
+
 /**
  * Information about a signature verification failure.
  * This is a security-critical event that indicates the bundle

package/src/wrap.tsx

@@ -9,6 +9,7 @@ import {
   reload,
 } from "./native";
 import { useHotUpdaterStore } from "./store";
+import type { HotUpdaterResolver } from "./types";
 
 export interface RunUpdateProcessResponse {
   status: "ROLLBACK" | "UPDATE" | "UP_TO_DATE";
@@ -26,12 +27,6 @@ type UpdateStatus =
  * 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
    */
@@ -72,91 +67,190 @@ interface CommonHotUpdaterOptions {
   onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
 }
 
-export interface AutoUpdateOptions extends CommonHotUpdaterOptions {
+/**
+ * Configuration with baseURL for standard server-based updates
+ */
+interface BaseURLConfig {
   /**
-   * Update strategy
-   * - "fingerprint": Use fingerprint hash to check for updates
-   * - "appVersion": Use app version to check for updates
+   * Base URL for update server
+   * @example "https://update.example.com"
    */
-  updateStrategy: "fingerprint" | "appVersion";
+  baseURL: string;
 
   /**
-   * Update mode
-   * - "auto": Automatically check and download updates
+   * Resolver is not allowed when using baseURL
    */
-  updateMode: "auto";
+  resolver?: never;
+}
 
-  onError?: (error: HotUpdaterError | Error | unknown) => void;
+/**
+ * Configuration with resolver for custom network operations
+ */
+interface ResolverConfig {
+  /**
+   * Custom resolver for network operations
+   */
+  resolver: HotUpdaterResolver;
 
   /**
-   * Component to show while downloading a new bundle update.
-   *
-   * When an update exists and the bundle is being downloaded, this component will block access
-   * to the entry point and show download progress.
-   *
-   * @see {@link https://hot-updater.dev/docs/react-native-api/wrap#fallback-component}
-   *
-   * ```tsx
-   * HotUpdater.wrap({
-   *   baseURL: "<update-server-url>",
-   *   updateStrategy: "appVersion",
-   *   fallbackComponent: ({ progress = 0 }) => (
-   *     <View style={styles.container}>
-   *       <Text style={styles.text}>Updating... {progress}%</Text>
-   *     </View>
-   *   )
-   * })(App)
-   * ```
-   *
-   * If not defined, the bundle will download in the background without blocking the screen.
+   * baseURL is not allowed when using resolver
    */
+  baseURL?: never;
+}
+
+/**
+ * Union type ensuring baseURL and resolver are mutually exclusive
+ */
+type NetworkConfig = BaseURLConfig | ResolverConfig;
+
+export type AutoUpdateOptions = CommonHotUpdaterOptions &
+  NetworkConfig & {
+    /**
+     * 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.
+     *
+     * When an update exists and the bundle is being downloaded, this component will block access
+     * to the entry point and show download progress.
+     *
+     * @see {@link https://hot-updater.dev/docs/react-native-api/wrap#fallback-component}
+     *
+     * ```tsx
+     * HotUpdater.wrap({
+     *   baseURL: "<update-server-url>",
+     *   updateStrategy: "appVersion",
+     *   fallbackComponent: ({ progress = 0 }) => (
+     *     <View style={styles.container}>
+     *       <Text style={styles.text}>Updating... {progress}%</Text>
+     *     </View>
+     *   )
+     * })(App)
+     * ```
+     *
+     * If not defined, the bundle will download in the background without blocking the screen.
+     */
+    fallbackComponent?: React.FC<{
+      status: Exclude<UpdateStatus, "UPDATE_PROCESS_COMPLETED">;
+      progress: number;
+      message: string | null;
+    }>;
+
+    onProgress?: (progress: number) => void;
+
+    /**
+     * When a force update exists, the app will automatically reload.
+     * If `false`, When a force update exists, the app will not reload. `shouldForceUpdate` will be returned as `true` in `onUpdateProcessCompleted`.
+     * If `true`, When a force update exists, the app will automatically reload.
+     * @default true
+     */
+    reloadOnForceUpdate?: boolean;
+
+    /**
+     * Callback function that is called when the update process is completed.
+     *
+     * @see {@link https://hot-updater.dev/docs/react-native-api/wrap#onupdateprocesscompleted}
+     */
+    onUpdateProcessCompleted?: (response: RunUpdateProcessResponse) => void;
+  };
+
+export type ManualUpdateOptions = CommonHotUpdaterOptions &
+  NetworkConfig & {
+    /**
+     * Update mode
+     * - "manual": Only notify app ready, user manually calls checkForUpdate()
+     */
+    updateMode: "manual";
+  };
+
+export type HotUpdaterOptions = AutoUpdateOptions | ManualUpdateOptions;
+
+/**
+ * Internal options after normalization in index.ts
+ * Always has resolver (never baseURL)
+ */
+type InternalCommonOptions = {
+  resolver: HotUpdaterResolver;
+  requestHeaders?: Record<string, string>;
+  requestTimeout?: number;
+  onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+};
+
+type InternalAutoUpdateOptions = InternalCommonOptions & {
+  updateStrategy: "fingerprint" | "appVersion";
+  updateMode: "auto";
+  onError?: (error: HotUpdaterError | Error | unknown) => void;
   fallbackComponent?: React.FC<{
     status: Exclude<UpdateStatus, "UPDATE_PROCESS_COMPLETED">;
     progress: number;
     message: string | null;
   }>;
-
   onProgress?: (progress: number) => void;
-
-  /**
-   * When a force update exists, the app will automatically reload.
-   * If `false`, When a force update exists, the app will not reload. `shouldForceUpdate` will be returned as `true` in `onUpdateProcessCompleted`.
-   * If `true`, When a force update exists, the app will automatically reload.
-   * @default true
-   */
   reloadOnForceUpdate?: boolean;
-
-  /**
-   * Callback function that is called when the update process is completed.
-   *
-   * @see {@link https://hot-updater.dev/docs/react-native-api/wrap#onupdateprocesscompleted}
-   */
   onUpdateProcessCompleted?: (response: RunUpdateProcessResponse) => void;
-}
+};
 
-export interface ManualUpdateOptions extends CommonHotUpdaterOptions {
-  /**
-   * Update mode
-   * - "manual": Only notify app ready, user manually calls checkForUpdate()
-   */
+type InternalManualUpdateOptions = InternalCommonOptions & {
   updateMode: "manual";
-}
+};
 
-export type HotUpdaterOptions = AutoUpdateOptions | ManualUpdateOptions;
+export type InternalWrapOptions =
+  | InternalAutoUpdateOptions
+  | InternalManualUpdateOptions;
+
+/**
+ * Helper function to handle notifyAppReady flow
+ */
+const handleNotifyAppReady = async (options: {
+  resolver?: HotUpdaterResolver;
+  requestHeaders?: Record<string, string>;
+  requestTimeout?: number;
+  onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+}): Promise<void> => {
+  try {
+    // Always call native notifyAppReady for bundle promotion
+    const nativeResult = nativeNotifyAppReady();
+
+    // If resolver.notifyAppReady exists, call it with simplified params
+    if (options.resolver?.notifyAppReady) {
+      await options.resolver
+        .notifyAppReady({
+          status: nativeResult.status,
+          crashedBundleId: nativeResult.crashedBundleId,
+          requestHeaders: options.requestHeaders,
+          requestTimeout: options.requestTimeout,
+        })
+        .catch((e: unknown) => {
+          console.warn("[HotUpdater] Resolver notifyAppReady failed:", e);
+        });
+    }
+
+    options.onNotifyAppReady?.(nativeResult);
+  } catch (e) {
+    console.warn("[HotUpdater] Failed to notify app ready:", e);
+  }
+};
 
 export function wrap<P extends React.JSX.IntrinsicAttributes = object>(
-  options: HotUpdaterOptions,
+  options: InternalWrapOptions,
 ): (WrappedComponent: React.ComponentType<P>) => React.ComponentType<P> {
   if (options.updateMode === "manual") {
     return (WrappedComponent: React.ComponentType<P>) => {
       const ManualHOC: React.FC<P> = (props: P) => {
         useLayoutEffect(() => {
-          try {
-            const result = nativeNotifyAppReady();
-            options.onNotifyAppReady?.(result);
-          } catch (e) {
-            console.warn("[HotUpdater] Failed to notify app ready:", e);
-          }
+          void handleNotifyAppReady(options);
         }, []);
 
         return <WrappedComponent {...props} />;
@@ -182,12 +276,12 @@ export function wrap<P extends React.JSX.IntrinsicAttributes = object>(
           setUpdateStatus("CHECK_FOR_UPDATE");
 
           const updateInfo = await checkForUpdate({
-            baseURL: restOptions.baseURL,
+            resolver: restOptions.resolver,
             updateStrategy: restOptions.updateStrategy,
             requestHeaders: restOptions.requestHeaders,
             requestTimeout: restOptions.requestTimeout,
             onError: restOptions.onError,
-          } as Parameters<typeof checkForUpdate>[0]);
+          });
 
           setMessage(updateInfo?.message ?? null);
 
@@ -250,12 +344,7 @@ export function wrap<P extends React.JSX.IntrinsicAttributes = object>(
 
       // Notify native side that app is ready (JS bundle fully loaded)
       useLayoutEffect(() => {
-        try {
-          const result = nativeNotifyAppReady();
-          restOptions.onNotifyAppReady?.(result);
-        } catch (e) {
-          console.warn("[HotUpdater] Failed to notify app ready:", e);
-        }
+        void handleNotifyAppReady(restOptions);
       }, []);
 
       // Start update check