react-native-instantpay-code-push 1.1.0

package/src/error.ts

@@ -0,0 +1,159 @@
+/**
+ * Ipay Code Push 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 IpayCodePushErrorCode {
+    // ==================== 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 IpayCodePush.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 IpayCodePushError
+ */
+export function isIpayCodePushError(
+    error: unknown,
+): error is { code: IpayCodePushErrorCode; message: string } {
+    return (
+        typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        Object.values(IpayCodePushErrorCode).includes(
+            error.code as IpayCodePushErrorCode,
+        )
+    );
+}
+
+/**
+ * Base error class for Ipay Code Push
+ */
+export class IpayCodePushError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "IpayCodePushError";
+    }
+}

package/src/fetchUpdateInfo.ts

@@ -0,0 +1,47 @@
+import type { AppUpdateInfo } from "./types";
+
+export const fetchUpdateInfo = async ({
+    url,
+    requestHeaders,
+    onError,
+    requestTimeout = 5000,
+}: {
+    url: string;
+    requestHeaders?: Record<string, string>;
+    onError?: (error: Error) => void;
+    requestTimeout?: number;
+}): Promise<AppUpdateInfo | null> => {
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+            controller.abort();
+        }, requestTimeout);
+
+        const headers = {
+            "Content-Type": "application/json",
+            ...requestHeaders,
+        };
+
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (response.status !== 200) {
+            throw new Error(response.statusText);
+        }
+
+        return response.json();
+    } catch (error: unknown) {
+
+        if (error instanceof Error && error.name === "AbortError") {
+            onError?.(new Error("Request timed out"));
+        } else {
+            onError?.(error as Error);
+        }
+
+        return null;
+    }
+};

package/src/global.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Global type definitions for IpayCodePush
+ */
+declare global {
+    /**
+     * Gets the base URL for the current active bundle directory.
+     * Returns the file:// URL to the bundle directory without trailing slash.
+     *
+     * This function is globally available for use in Expo DOM components
+     * and Babel plugin generated code without requiring an import.
+     *
+     * @returns {string} Base URL string (e.g., "file:///data/.../bundle-store/abc123") or null if not available
+     *
+     * @example
+     * ```ts
+     * const baseURL = globalThis.IpayCodePushGetBaseURL();
+     * const htmlPath = baseURL + "/www.bundle/index.html";
+     * ```
+     */
+    var IpayCodePushGetBaseURL: () => string | null;
+}
+
+export {};

package/src/hooks/useEventCallback.ts

@@ -0,0 +1,30 @@
+import { useCallback, useLayoutEffect, useRef } from "react";
+
+type EventCallback<Args extends unknown[], R> =
+  | ((...args: Args) => R)
+  | undefined;
+
+export function useEventCallback<Args extends unknown[], R>(
+    fn: (...args: Args) => R,
+): (...args: Args) => R;
+
+export function useEventCallback<Args extends unknown[], R>(
+    fn: EventCallback<Args, R>,
+): EventCallback<Args, R>;
+
+export function useEventCallback<Args extends unknown[], R>(
+    fn: EventCallback<Args, R>,
+): EventCallback<Args, R> {
+    const callbackRef = useRef<EventCallback<Args, R>>(() => {
+        throw new Error("Cannot call an event handler while rendering.");
+    });
+
+    useLayoutEffect(() => {
+        callbackRef.current = fn;
+    }, [fn]);
+
+    return useCallback(
+        (...args: Args) => callbackRef.current?.(...args),
+        [callbackRef],
+    ) as (...args: Args) => R;
+}

package/src/index.tsx

@@ -0,0 +1,379 @@
+import {
+    type CheckForUpdateOptions,
+    checkForUpdate,
+    type InternalCheckForUpdateOptions,
+} from "./checkForUpdate";
+
+import { createDefaultResolver } from './DefaultResolver';
+
+import {
+    addListener,
+    clearCrashHistory,
+    getAppVersion,
+    getBaseURL,
+    getBundleId,
+    getChannel,
+    getCrashHistory,
+    getFingerprintHash,
+    getMinBundleId,
+    reload,
+    type UpdateParams,
+    updateBundle,
+} from "./native";
+
+import { ipayCodePushStore } from "./store";
+
+import type { IpayCodePushResolver } from "./types";
+
+import { type IpayCodePushOptions, type InternalWrapOptions, wrap } from "./wrap";
+
+export type { IpayCodePushEvent, NotifyAppReadyResult } from "./native";
+
+export * from "./store";
+
+export {
+    extractSignatureFailure,
+    type IpayCodePushResolver,
+    isSignatureVerificationError,
+    type ResolverCheckUpdateParams,
+    type ResolverNotifyAppReadyParams,
+    type SignatureVerificationFailure,
+} from "./types";
+
+export type { IpayCodePushOptions, RunUpdateProcessResponse } from "./wrap";
+
+addListener("onProgress", ({ progress }) => {
+    ipayCodePushStore.setState({
+        progress,
+    });
+});
+
+/**
+ * Register getBaseURL to global objects for use without imports.
+ * This is needed for Expo DOM components and Babel plugin generated code.
+ */
+const registerGlobalGetBaseURL = () => {
+    const fn = getBaseURL;
+
+    // Register to globalThis (modern, cross-platform)
+    if (typeof globalThis !== "undefined") {
+
+        if (!globalThis.IpayCodePushGetBaseURL) {
+            globalThis.IpayCodePushGetBaseURL = fn;
+        }
+    }
+
+    // Register to global (React Native, Node.js)
+    if (typeof global !== "undefined") {
+        if (!global.IpayCodePushGetBaseURL) {
+            global.IpayCodePushGetBaseURL = fn;
+        }
+    }
+};
+
+// Call registration immediately on module load
+registerGlobalGetBaseURL();
+
+
+/**
+ * Creates a IpayCodePush client instance with all update management methods.
+ * This function is called once on module initialization to create a singleton instance.
+ */
+
+function createIpayCodePushClient() {
+    
+    // Global configuration stored from wrap
+    const globalConfig: {
+        resolver: IpayCodePushResolver | null;
+        requestHeaders?: Record<string, string>;
+        requestTimeout?: number;
+    } = {
+        resolver: null,
+    };
+
+    const ensureGlobalResolver = (methodName: string) => {
+        if (!globalConfig.resolver) {
+            throw new Error(
+                `[IpayCodePush] ${methodName} requires IpayCodePush.wrap() to be used.\n\n` +
+                `To fix this issue, wrap your root component with IpayCodePush.wrap():\n\n` +
+                `Option 1: With automatic updates\n` +
+                `  export default IpayCodePush.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 IpayCodePush.wrap({\n` +
+                `    baseURL: "<your-update-server-url>",\n` +
+                `    updateMode: "manual"\n` +
+                `  })(App);\n\n`
+            );
+        }
+        return globalConfig.resolver;
+    };
+
+    return {
+        /**
+         * `IpayCodePush.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 IpayCodePush.wrap({
+         *   baseURL: "<your-update-server-url>",
+         *   updateStrategy: "appVersion", //"appVersion" | "fingerprint"
+         *   updateMode: "auto",
+         *   requestHeaders: {
+         *     "Authorization": "Bearer <your-access-token>",
+         *   },
+         * })(App);
+         * ```
+         */
+        wrap: (options: IpayCodePushOptions) => {
+            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(
+                `[IpayCodePush] Either baseURL or resolver must be provided.\n\n` +
+                    `Option 1: Using baseURL (recommended for most cases)\n` +
+                    `  export default IpayCodePush.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 IpayCodePush.wrap({\n` +
+                    `    resolver: {\n` +
+                    `      checkUpdate: async (params) => { /* custom logic */ },\n` +
+                    `      notifyAppReady: async (params) => { /* custom logic */ }\n` +
+                    `    },\n` +
+                    `    updateMode: "manual"\n` +
+                    `  })(App);\n\n`,
+                );
+            }
+
+            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 `IpayCodePush.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 (IpayCodePush.isUpdateDownloaded()) {
+         *   await IpayCodePush.reload();
+         * }
+         * ```
+         */
+        isUpdateDownloaded: () => ipayCodePushStore.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 = IpayCodePush.getChannel();
+         * console.log(`Current channel: ${channel}`);
+         * ```
+         */
+        getChannel,
+
+        /**
+         * Adds a listener to IpayCodePush events.
+         *
+         * @param {keyof IpayCodePushEvent} eventName - The name of the event to listen for
+         * @param {(event: IpayCodePushEvent[T]) => void} listener - The callback function to handle the event
+         * @returns {() => void} A cleanup function that removes the event listener
+         *
+         * @example
+         * ```ts
+         * const unsubscribe = IpayCodePush.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 IpayCodePush.checkForUpdate({
+         *   source: "<your-update-server-url>",
+         *   requestHeaders: {
+         *     Authorization: "Bearer <your-access-token>",
+         *   },
+         * });
+         *
+         * if (!updateInfo) {
+         *   console.log("App is up to date");
+         *   return;
+         * }
+         *
+         * await IpayCodePush.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 IpayCodePush.checkForUpdate({
+         *   source: "<your-update-server-url>",
+         *   requestHeaders: {
+         *     Authorization: "Bearer <your-access-token>",
+         *   },
+         * });
+         *
+         * if (!updateInfo) {
+         *   return {
+         *     status: "UP_TO_DATE",
+         *   };
+         * }
+         *
+         * await IpayCodePush.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 = IpayCodePush.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 = IpayCodePush.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
+         * IpayCodePush.clearCrashHistory();
+         * ```
+         */
+        clearCrashHistory,
+    };
+}
+
+export const IpayCodePush = createIpayCodePushClient();
+
+