@hot-updater/react-native 0.23.1 → 0.24.1

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

@@ -1,5 +1,7 @@
 import type { UpdateStatus } from "@hot-updater/core";
+import { HotUpdaterErrorCode, isHotUpdaterError } from "./error";
 import { type UpdateBundleParams } from "./specs/NativeHotUpdater";
+export { HotUpdaterErrorCode, isHotUpdaterError };
 export declare const HotUpdaterConstants: {
     HOT_UPDATER_BUNDLE_ID: string;
 };
@@ -16,7 +18,8 @@ export type UpdateParams = UpdateBundleParams & {
  * 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 declare function updateBundle(params: UpdateParams): Promise<boolean>;
 /**
@@ -42,7 +45,7 @@ export declare 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 declare const getBundleId: () => string;
 /**
@@ -57,4 +60,57 @@ export declare const getChannel: () => string;
  * @returns {string | null} Resolves with the fingerprint hash
  */
 export declare const getFingerprintHash: () => string | null;
+/**
+ * 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 declare const notifyAppReady: () => NotifyAppReadyResult;
+/**
+ * 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 declare const getCrashHistory: () => string[];
+/**
+ * Clears the crashed bundle history, allowing previously crashed bundles
+ * to be installed again.
+ *
+ * @returns {boolean} true if clearing was successful
+ */
+export declare const clearCrashHistory: () => boolean;
 //# sourceMappingURL=native.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../../../src/native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAyB,EACvB,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAMlC,eAAO,MAAM,mBAAmB;;CAE/B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,eAAe,EACzD,WAAW,CAAC,EACZ,UAAU,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,eAQ9C,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG;IAC9C,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAOF;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAC3E;;GAEG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,OAAO,CAAC,CAAC;AAgEpB;;GAEG;AACH,eAAO,MAAM,aAAa,QAAO,MAAM,GAAG,IAGzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,MAAM,qBAElB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,MAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAO,MAI9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAAO,MAG7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAO,MAAM,GAAG,IAG9C,CAAC"}
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../../../src/native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACjE,OAAyB,EACvB,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,CAAC;AAMlD,eAAO,MAAM,mBAAmB;;CAE/B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,eAAe,EACzD,WAAW,CAAC,EACZ,UAAU,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,eAQ9C,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG;IAC9C,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAOF;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAC3E;;GAEG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,OAAO,CAAC,CAAC;AAgEpB;;GAEG;AACH,eAAO,MAAM,aAAa,QAAO,MAAM,GAAG,IAGzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,MAAM,qBAElB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,MAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAO,MAI9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAAO,MAG7B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAO,MAAM,GAAG,IAG9C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,cAAc,QAAO,oBAYjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAO,MAAM,EAWxC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAO,OAEpC,CAAC"}

package/lib/typescript/module/specs/NativeHotUpdater.d.ts

@@ -15,7 +15,69 @@ export interface UpdateBundleParams {
 }
 export interface Spec extends TurboModule {
     reload(): Promise<void>;
+    /**
+     * Downloads and applies a bundle update.
+     *
+     * @param params - Update bundle parameters
+     * @returns Promise that resolves to true if successful
+     * @throws {HotUpdaterErrorCode} Rejects with one of the following error codes:
+     *
+     *   Parameter validation:
+     *   - MISSING_BUNDLE_ID: Missing or empty bundleId
+     *   - INVALID_FILE_URL: Invalid fileUrl provided
+     *
+     *   Bundle storage:
+     *   - DIRECTORY_CREATION_FAILED: Failed to create bundle directory
+     *   - DOWNLOAD_FAILED: Failed to download bundle
+     *   - INCOMPLETE_DOWNLOAD: Download incomplete (size mismatch)
+     *   - EXTRACTION_FORMAT_ERROR: Invalid or corrupted archive format
+     *   - INVALID_BUNDLE: Bundle missing required platform files
+     *   - INSUFFICIENT_DISK_SPACE: Insufficient disk space
+     *   - MOVE_OPERATION_FAILED: Failed to move bundle files
+     *   - BUNDLE_IN_CRASHED_HISTORY: Bundle was previously marked as crashed
+     *
+     *   Signature:
+     *   - SIGNATURE_VERIFICATION_FAILED: Any signature/hash verification failure
+     *
+     *   Internal:
+     *   - SELF_DEALLOCATED: Native object was deallocated (iOS)
+     *   - UNKNOWN_ERROR: Fallback for rare or platform-specific errors
+     *
+     *   Note: iOS normalizes rare signature/storage errors to SIGNATURE_VERIFICATION_FAILED
+     *   or UNKNOWN_ERROR to keep the JS error surface small.
+     */
     updateBundle(params: UpdateBundleParams): Promise<boolean>;
+    /**
+     * Notifies the native side that the app has successfully started with the given bundle.
+     * If the bundle matches the staging bundle, it promotes to stable.
+     *
+     * @param params - Parameters containing the bundle ID
+     * @returns Object with status and optional crashedBundleId
+     * - `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"
+     */
+    notifyAppReady(params: {
+        bundleId: string;
+    }): {
+        status: "PROMOTED" | "RECOVERED" | "STABLE";
+        crashedBundleId?: string;
+    };
+    /**
+     * Gets the list of bundle IDs that have been marked as crashed.
+     * These bundles will be rejected if attempted to install again.
+     *
+     * @returns Array of crashed bundle IDs
+     */
+    getCrashHistory(): string[];
+    /**
+     * Clears the crashed bundle history, allowing previously crashed bundles
+     * to be installed again.
+     *
+     * @returns true if clearing was successful
+     */
+    clearCrashHistory(): boolean;
     addListener(eventName: string): void;
     removeListeners(count: number): void;
     readonly getConstants: () => {

package/lib/typescript/module/specs/NativeHotUpdater.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativeHotUpdater.d.ts","sourceRoot":"","sources":["../../../../src/specs/NativeHotUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,IAAK,SAAQ,WAAW;IAEvC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAG3D,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM;QAC3B,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,CAAC;CACH;;AAED,wBAAoE"}
+{"version":3,"file":"NativeHotUpdater.d.ts","sourceRoot":"","sources":["../../../../src/specs/NativeHotUpdater.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,IAAK,SAAQ,WAAW;IAEvC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3D;;;;;;;;;;OAUG;IACH,cAAc,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG;QAC5C,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;QAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IAEF;;;;;OAKG;IACH,eAAe,IAAI,MAAM,EAAE,CAAC;IAE5B;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO,CAAC;IAG7B,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM;QAC3B,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,CAAC;CACH;;AAED,wBAAoE"}

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

@@ -1,3 +1,118 @@
+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/lib/typescript/module/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAgBpE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GACf,4BAA4B,CAS9B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAC;IAE5B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,cAAc,EAAE,aAAa,GAAG,YAAY,CAAC;IAE7C;;OAEG;IACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;IAE5C;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAAW,CAAC,EAAE,CACZ,MAAM,EAAE,yBAAyB,KAC9B,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,CACf,MAAM,EAAE,4BAA4B,KACjC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAgBpE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GACf,4BAA4B,CAS9B"}

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

@@ -1,9 +1,99 @@
 import React from "react";
-import { type CheckForUpdateOptions } from "./checkForUpdate";
 import type { HotUpdaterError } from "./error";
-import type { RunUpdateProcessResponse } from "./runUpdateProcess";
+import { type NotifyAppReadyResult } from "./native";
+import type { HotUpdaterResolver } from "./types";
+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 {
+    /**
+     * 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;
+}
+/**
+ * Configuration with baseURL for standard server-based updates
+ */
+interface BaseURLConfig {
+    /**
+     * Base URL for update server
+     * @example "https://update.example.com"
+     */
+    baseURL: string;
+    /**
+     * Resolver is not allowed when using baseURL
+     */
+    resolver?: never;
+}
+/**
+ * Configuration with resolver for custom network operations
+ */
+interface ResolverConfig {
+    /**
+     * Custom resolver for network operations
+     */
+    resolver: HotUpdaterResolver;
+    /**
+     * 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.
      *
@@ -14,7 +104,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 +121,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.
@@ -45,7 +135,42 @@ export interface HotUpdaterOptions extends CheckForUpdateOptions {
      * @see {@link https://hot-updater.dev/docs/react-native-api/wrap#onupdateprocesscompleted}
      */
     onUpdateProcessCompleted?: (response: RunUpdateProcessResponse) => void;
-}
-export declare function wrap<P extends React.JSX.IntrinsicAttributes = object>(options: HotUpdaterOptions): (WrappedComponent: React.ComponentType<P>) => React.ComponentType<P>;
+};
+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;
+    reloadOnForceUpdate?: boolean;
+    onUpdateProcessCompleted?: (response: RunUpdateProcessResponse) => void;
+};
+type InternalManualUpdateOptions = InternalCommonOptions & {
+    updateMode: "manual";
+};
+export type InternalWrapOptions = InternalAutoUpdateOptions | InternalManualUpdateOptions;
+export declare function wrap<P extends React.JSX.IntrinsicAttributes = object>(options: InternalWrapOptions): (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":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hot-updater/react-native",
-  "version": "0.23.1",
+  "version": "0.24.1",
   "description": "React Native OTA solution for self-hosted",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -120,14 +120,14 @@
     "react-native": "0.79.1",
     "react-native-builder-bob": "^0.40.10",
     "typescript": "^5.8.3",
-    "hot-updater": "0.23.1"
+    "hot-updater": "0.24.1"
   },
   "dependencies": {
     "use-sync-external-store": "1.5.0",
-    "@hot-updater/cli-tools": "0.23.1",
-    "@hot-updater/core": "0.23.1",
-    "@hot-updater/js": "0.23.1",
-    "@hot-updater/plugin-core": "0.23.1"
+    "@hot-updater/cli-tools": "0.24.1",
+    "@hot-updater/core": "0.24.1",
+    "@hot-updater/plugin-core": "0.24.1",
+    "@hot-updater/js": "0.24.1"
   },
   "scripts": {
     "build": "bob build && tsc -p plugin/tsconfig.build.json",

package/plugin/build/withHotUpdater.js

@@ -39,10 +39,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-var node_path_1 = __importDefault(require("node:path"));
 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;
@@ -77,9 +77,9 @@ var getPublicKeyFromConfig = function (signingConfig) { return __awaiter(void 0,
                 _a.label = 1;
             case 1:
                 _a.trys.push([1, 3, , 4]);
-                privateKeyPath = node_path_1.default.isAbsolute(signingConfig.privateKeyPath)
+                privateKeyPath = path_1.default.isAbsolute(signingConfig.privateKeyPath)
                     ? signingConfig.privateKeyPath
-                    : node_path_1.default.resolve(process.cwd(), signingConfig.privateKeyPath);
+                    : path_1.default.resolve(process.cwd(), signingConfig.privateKeyPath);
                 return [4 /*yield*/, (0, hot_updater_1.loadPrivateKey)(privateKeyPath)];
             case 2:
                 privateKeyPEM = _a.sent();

package/src/DefaultResolver.ts

@@ -0,0 +1,36 @@
+import type { AppUpdateInfo } from "@hot-updater/core";
+import { fetchUpdateInfo } from "./fetchUpdateInfo";
+import type { HotUpdaterResolver, ResolverCheckUpdateParams } from "./types";
+
+/**
+ * Creates a default resolver that uses baseURL for network operations.
+ * This encapsulates the existing baseURL logic into a resolver.
+ *
+ * @param baseURL - The base URL for the update server
+ * @returns A HotUpdaterResolver that uses the baseURL
+ */
+export function createDefaultResolver(baseURL: string): HotUpdaterResolver {
+  return {
+    checkUpdate: async (
+      params: ResolverCheckUpdateParams,
+    ): Promise<AppUpdateInfo | null> => {
+      // Build URL based on strategy (existing buildUpdateUrl logic)
+      let url: string;
+      if (params.updateStrategy === "fingerprint") {
+        if (!params.fingerprintHash) {
+          throw new Error("Fingerprint hash is required");
+        }
+        url = `${baseURL}/fingerprint/${params.platform}/${params.fingerprintHash}/${params.channel}/${params.minBundleId}/${params.bundleId}`;
+      } else {
+        url = `${baseURL}/app-version/${params.platform}/${params.appVersion}/${params.channel}/${params.minBundleId}/${params.bundleId}`;
+      }
+
+      // Use existing fetchUpdateInfo
+      return fetchUpdateInfo({
+        url,
+        requestHeaders: params.requestHeaders,
+        requestTimeout: params.requestTimeout,
+      });
+    },
+  };
+}