@appspacer/react-native 1.0.0

package/dist/CrashReporter.js

@@ -0,0 +1,41 @@
+import { getNativeModule } from "./native";
+export const initCrashReporter = (getSessionId) => {
+    const globalHandler = global.ErrorUtils;
+    if (!globalHandler || typeof globalHandler.setGlobalHandler !== "function") {
+        console.warn("[AppSpacer] Crash Analytics: global.ErrorUtils not available");
+        return;
+    }
+    const defaultHandler = globalHandler.getGlobalHandler();
+    globalHandler.setGlobalHandler(async (error, isFatal) => {
+        try {
+            const crashData = {
+                id: "js-" + Date.now().toString() + "-" + Math.random().toString(36).slice(2, 7),
+                type: "javascript",
+                session_id: getSessionId(),
+                payload: JSON.stringify({
+                    message: error?.message || "Unknown error",
+                    stack: error?.stack || "",
+                    isFatal: !!isFatal,
+                }),
+                timestamp: new Date().toISOString(),
+            };
+            const native = getNativeModule();
+            if (__DEV__)
+                console.log(`[AppSpacer] Captured JS ${isFatal ? 'FATAL ' : ''}crash. Saving to native storage: ${crashData.id}`);
+            // Synchronous-ish call to native to ensure it starts before process exits
+            native.saveCrashReport(JSON.stringify(crashData)).catch((err) => {
+                console.warn(`[AppSpacer] Failed to save JS crash report ${crashData.id}`, err);
+            });
+        }
+        catch (e) {
+            // Ignore errors in the crash reporter itself
+        }
+        // Preserve original handler — shows red box in dev, crashes in prod
+        if (typeof defaultHandler === "function") {
+            defaultHandler(error, isFatal);
+        }
+    });
+    if (__DEV__) {
+        console.log("[AppSpacer] Crash Analytics: Active in DEV mode. Crashes saved locally — reload the app to upload.");
+    }
+};

package/dist/NativeAppSpacer.d.ts

@@ -0,0 +1,34 @@
+import type { TurboModule } from "react-native";
+/**
+ * TurboModule specification for AppSpacer.
+ *
+ * This file is used by React Native's Codegen to generate
+ * type-safe native module interfaces for the New Architecture.
+ *
+ * For Old Architecture (Bridge), the module falls back to
+ * NativeModules.AppSpacerModule automatically.
+ */
+export interface Spec extends TurboModule {
+    getOtaStoragePath(): Promise<string>;
+    downloadPackage(url: string, destPath: string): Promise<string>;
+    verifyHash(filePath: string, expectedHash: string): Promise<boolean>;
+    unzipPackage(zipPath: string, destDir: string): Promise<void>;
+    installUpdate(unzippedDir: string): Promise<void>;
+    reloadApp(): void;
+    getCurrentPackageHash(): Promise<string | null>;
+    setCurrentPackageInfo(info: string): Promise<void>;
+    getCurrentPackageInfo(): Promise<string | null>;
+    markSuccess(): Promise<void>;
+    rollback(): Promise<void>;
+    getInstallId(): Promise<string>;
+    getAssetSourceDirectory(): Promise<string | null>;
+    clearOldUpdates(): Promise<number>;
+    getUpdateMetadata(): Promise<string | null>;
+    saveCrashReport(reportJson: string): Promise<void>;
+    getPendingCrashReports(): Promise<string>;
+    deleteCrashReport(id: string): Promise<void>;
+    addListener(eventName: string): void;
+    removeListeners(count: number): void;
+}
+declare const _default: Spec | null;
+export default _default;

package/dist/NativeAppSpacer.js

@@ -0,0 +1,2 @@
+import { TurboModuleRegistry } from "react-native";
+export default TurboModuleRegistry.get("AppSpacerModule");

package/dist/assetResolver.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Initialize the OTA asset resolver.
+ *
+ * This patches React Native's `Image.resolveAssetSource` so that assets
+ * bundled with OTA updates (images, fonts, icons, JSON) are loaded from the
+ * OTA directory instead of the default app binary location.
+ *
+ * Called automatically by `AppSpacer.init()` — no manual setup needed.
+ *
+ * @example
+ * ```ts
+ * // Automatic (recommended) — called inside AppSpacer.init()
+ * AppSpacer.init({ deploymentKey, appVersion });
+ *
+ * // Manual (advanced)
+ * import { initAssetResolver } from "react-native-appspacer";
+ * await initAssetResolver();
+ * ```
+ */
+export declare function initAssetResolver(): Promise<void>;
+/**
+ * Get the current OTA asset directory, or null if no OTA update is active.
+ */
+export declare function getOtaAssetDirectory(): string | null;

package/dist/assetResolver.js

@@ -0,0 +1,130 @@
+import { Platform, Image } from "react-native";
+import { getNativeModule } from "./native";
+/** Cached OTA asset directory path */
+let otaAssetDir = null;
+let isInitialized = false;
+/**
+ * Initialize the OTA asset resolver.
+ *
+ * This patches React Native's `Image.resolveAssetSource` so that assets
+ * bundled with OTA updates (images, fonts, icons, JSON) are loaded from the
+ * OTA directory instead of the default app binary location.
+ *
+ * Called automatically by `AppSpacer.init()` — no manual setup needed.
+ *
+ * @example
+ * ```ts
+ * // Automatic (recommended) — called inside AppSpacer.init()
+ * AppSpacer.init({ deploymentKey, appVersion });
+ *
+ * // Manual (advanced)
+ * import { initAssetResolver } from "react-native-appspacer";
+ * await initAssetResolver();
+ * ```
+ */
+export async function initAssetResolver() {
+    if (isInitialized)
+        return;
+    try {
+        const native = getNativeModule();
+        otaAssetDir = await native.getAssetSourceDirectory();
+        isInitialized = true;
+        if (!otaAssetDir)
+            return; // No OTA update active, use default resolution
+        patchAssetResolver(otaAssetDir);
+    }
+    catch {
+        // Native module not ready or no OTA update — fall through silently
+        isInitialized = true;
+    }
+}
+/**
+ * Get the current OTA asset directory, or null if no OTA update is active.
+ */
+export function getOtaAssetDirectory() {
+    return otaAssetDir;
+}
+/**
+ * Patch React Native's Image.resolveAssetSource to redirect asset URIs
+ * to the OTA update directory when an OTA update is active.
+ *
+ * How it works:
+ * - Metro bundler records assets as numeric IDs with metadata (httpServerLocation, name, type)
+ * - RN's default resolver turns these into URIs pointing to the app binary
+ * - We intercept and rewrite the URI to point to the OTA directory instead
+ */
+function patchAssetResolver(assetDir) {
+    const originalResolveAssetSource = Image.resolveAssetSource;
+    if (!originalResolveAssetSource)
+        return;
+    Image.resolveAssetSource = (source) => {
+        const resolved = originalResolveAssetSource(source);
+        // Only patch asset objects with httpServerLocation (bundled assets)
+        if (resolved &&
+            typeof source === "number" && // Only numeric asset IDs from require()
+            resolved.uri) {
+            try {
+                // For assets bundled via Metro, the source object has metadata
+                // like httpServerLocation, name, type, scales, etc.
+                const asset = Image.resolveAssetSource.call(null, source);
+                if (asset && !asset.uri.startsWith("http")) {
+                    // Build a file:// URI pointing to the OTA assets directory
+                    const assetPath = buildOtaAssetUri(assetDir, resolved);
+                    if (assetPath) {
+                        return { ...resolved, uri: assetPath };
+                    }
+                }
+            }
+            catch {
+                // Fall through to default resolution
+            }
+        }
+        return resolved;
+    };
+}
+/**
+ * Build a file:// URI pointing to an asset in the OTA directory.
+ *
+ * React Native Metro bundles assets with a structure like:
+ *   assets/src/images/logo.png      (original)
+ *   assets/src/images/logo@2x.png   (scaled)
+ *
+ * The OTA zip preserves this structure under the assets/ subdirectory.
+ */
+function buildOtaAssetUri(assetDir, resolved) {
+    // On Android, the asset URI looks like: "asset:///src/images/logo.png"
+    // On iOS, it's a file path within the app bundle
+    const uri = resolved.uri;
+    if (Platform.OS === "android") {
+        // Android: strip "asset:///" prefix and reconstruct with OTA path
+        if (uri.startsWith("asset:///")) {
+            const relativePath = uri.replace("asset:///", "");
+            return `file://${assetDir}/assets/${relativePath}`;
+        }
+        // Drawable resources (e.g. "res/drawable-mdpi/src_images_logo.png")
+        // These are compiled into the APK and can't be OTA-updated via file path.
+        // But Metro's --assets-dest produces flat files, so we handle that:
+        if (uri.startsWith("file://")) {
+            // Already a file URI, but pointing to the wrong location
+            const filename = uri.split("/").pop();
+            if (filename) {
+                return `file://${assetDir}/assets/${filename}`;
+            }
+        }
+    }
+    else if (Platform.OS === "ios") {
+        // iOS: replace the bundle path with OTA path
+        // Default URI looks like: "/path/to/App.app/assets/src/images/logo.png"
+        const assetsIndex = uri.indexOf("/assets/");
+        if (assetsIndex !== -1) {
+            const relativePath = uri.substring(assetsIndex);
+            return `file://${assetDir}${relativePath}`;
+        }
+        // Fallback: try to extract the filename
+        const filename = uri.split("/").pop();
+        if (filename) {
+            return `file://${assetDir}/assets/${filename}`;
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { AppSpacer, AppSpacerManager } from "./AppSpacer";
+export { useAppSpacerUpdate } from "./useAppSpacerUpdate";
+import { withAppSpacer } from "./withAppSpacer";
+export { withAppSpacer };
+export default withAppSpacer;
+export { initAssetResolver, getOtaAssetDirectory } from "./assetResolver";
+export * from "./types";
+export { initCrashReporter } from "./CrashReporter";

package/dist/index.js

@@ -0,0 +1,13 @@
+// Core
+export { AppSpacer, AppSpacerManager } from "./AppSpacer";
+// React Hooks and HOCs
+export { useAppSpacerUpdate } from "./useAppSpacerUpdate";
+import { withAppSpacer } from "./withAppSpacer";
+export { withAppSpacer };
+export default withAppSpacer;
+// Asset Resolver
+export { initAssetResolver, getOtaAssetDirectory } from "./assetResolver";
+// Types
+export * from "./types";
+// Crash Reporter
+export { initCrashReporter } from "./CrashReporter";

package/dist/native.d.ts

@@ -0,0 +1,88 @@
+import { NativeEventEmitter } from "react-native";
+export interface AppSpacerNativeModule {
+    /**
+     * Get the OTA storage directory path.
+     */
+    getOtaStoragePath(): Promise<string>;
+    /**
+     * Download a zip file from URL to a local temporary path.
+     */
+    downloadPackage(url: string, destPath: string): Promise<string>;
+    /**
+     * Verify the SHA256 hash of a file.
+     * Returns true if valid, throws or returns false otherwise.
+     */
+    verifyHash(filePath: string, expectedHash: string): Promise<boolean>;
+    /**
+     * Unzip a package into the specified destination directory.
+     */
+    unzipPackage(zipPath: string, destDir: string): Promise<void>;
+    /**
+     * Install the update (moves current to previous, and new to current).
+     */
+    installUpdate(unzippedDir: string): Promise<void>;
+    /**
+     * Reload the JavaScript bundle (restarts the React Native bridge).
+     */
+    reloadApp(): void;
+    /**
+     * Get the current installed package hash, if any.
+     */
+    getCurrentPackageHash(): Promise<string | null>;
+    /**
+     * Save metadata about the currently installed update.
+     */
+    setCurrentPackageInfo(info: string): Promise<void>;
+    /**
+     * Get metadata about the currently installed update.
+     */
+    getCurrentPackageInfo(): Promise<string | null>;
+    /**
+     * Mark the current update as successful to prevent crash loop rollback.
+     */
+    markSuccess(): Promise<void>;
+    /**
+     * Rollback to the previous bundle manually.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Get the persistent anonymous installation ID for deterministic rollout percentages.
+     */
+    getInstallId(): Promise<string>;
+    /**
+     * Get the OTA asset source directory path.
+     * Returns the root directory of the current OTA update where assets
+     * (images, fonts, icons, JSON) are stored. Returns null if no OTA update is active.
+     */
+    getAssetSourceDirectory(): Promise<string | null>;
+    /**
+     * Remove old update directories that are no longer active.
+     * Returns the number of directories removed.
+     */
+    clearOldUpdates(): Promise<number>;
+    /**
+     * Get metadata about the currently installed update.
+     * Returns JSON string with hash, releaseId, description, label, installedAt, isPending.
+     */
+    getUpdateMetadata(): Promise<string | null>;
+    /**
+     * Save a crash report to local storage.
+     */
+    saveCrashReport(reportJson: string): Promise<void>;
+    /**
+     * Get all pending crash reports as a JSON string.
+     */
+    getPendingCrashReports(): Promise<string>;
+    deleteCrashReport(id: string): Promise<void>;
+    testNativeCrash(): void;
+    addBreadcrumb(message: string): void;
+    setUserIdentity(userId: string, metadata: string): void;
+    addListener(eventName: string): void;
+    removeListeners(count: number): void;
+}
+/**
+ * Access the native AppSpacer module.
+ * Throws if the native module isn't linked.
+ */
+export declare function getNativeModule(): AppSpacerNativeModule;
+export declare function getEventEmitter(): NativeEventEmitter;

package/dist/native.js

@@ -0,0 +1,25 @@
+import { NativeModules, Platform, NativeEventEmitter } from "react-native";
+const NativeAppSpacer = NativeModules.AppSpacerModule;
+/**
+ * Access the native AppSpacer module.
+ * Throws if the native module isn't linked.
+ */
+export function getNativeModule() {
+    if (!NativeAppSpacer) {
+        throw new Error(`react-native-appspacer: Native module not found. ` +
+            `Make sure you have run 'pod install' (iOS) and rebuilt the app. ` +
+            `Platform: ${Platform.OS}`);
+    }
+    return NativeAppSpacer;
+}
+/**
+ * Event emitter for native download progress events.
+ */
+let _emitter = null;
+export function getEventEmitter() {
+    if (!_emitter) {
+        const nativeModule = getNativeModule();
+        _emitter = new NativeEventEmitter(nativeModule);
+    }
+    return _emitter;
+}

package/dist/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * AppSpacer SDK configuration.
+ */
+export interface AppSpacerConfig {
+    /** The Deployment Key for this environment (e.g. "sk_xxxx" or "pk_xxxx") */
+    deploymentKey: string;
+    /** Current app version (e.g. "1.0.0") */
+    appVersion: string;
+    /**
+     * How often to check for updates in seconds.
+     * Set to 0 to only check manually. Default: 0 (manual only).
+     */
+    checkInterval?: number;
+    /**
+     * Enable automatic crash analytics (Catches JS, iOS native, and Android native crashes)
+     * Defaults to false.
+     */
+    enableCrashReporting?: boolean;
+}
+/**
+ * Represents a crash report generated by the SDK.
+ */
+export interface CrashReport {
+    /** Unique ID for the crash report */
+    id: string;
+    /** Layer where the crash originated */
+    type: "javascript" | "native";
+    /** Serialized crash payload (stack trace, device info) */
+    payload: string;
+    /** ISO 8601 timestamp of when the crash occurred */
+    timestamp: string;
+    /** List of breadcrumbs leading up to the crash */
+    breadcrumbs?: string[];
+    /** Unique session ID for grouping crashes */
+    session_id?: string;
+    user_id?: string;
+    user_metadata?: object;
+}
+/**
+ * Represents a user activity breadcrumb.
+ */
+export interface Breadcrumb {
+    message: string;
+    category?: string;
+    data?: object;
+    timestamp: string;
+}
+/**
+ * Represents an available OTA update.
+ */
+export interface AppSpacerUpdate {
+    /** Whether an update is available */
+    updateAvailable: boolean;
+    /** Server-assigned release ID (used for install status reporting) */
+    releaseId?: string;
+    /** URL to download the OTA package zip */
+    packageUrl?: string;
+    /** SHA256 Hash of the package */
+    hash?: string;
+    /** Whether this update is mandatory */
+    mandatory?: boolean;
+    /** Release description */
+    description?: string;
+    /** Release label (e.g. v1, v2) */
+    label?: string;
+    /** Size of the package in bytes */
+    packageSize?: number;
+}
+/**
+ * Current state of the update process.
+ */
+export declare enum UpdateStatus {
+    /** No update activity */
+    IDLE = "IDLE",
+    /** Checking the server for updates */
+    CHECKING = "CHECKING",
+    /** An update is available but not yet downloaded */
+    UPDATE_AVAILABLE = "UPDATE_AVAILABLE",
+    /** Downloading the bundle */
+    DOWNLOADING = "DOWNLOADING",
+    /** Bundle downloaded, verified and ready to install */
+    INSTALLING = "INSTALLING",
+    /** Update installed, awaiting restart */
+    INSTALLED = "INSTALLED",
+    /** App is already up to date */
+    UP_TO_DATE = "UP_TO_DATE",
+    /** An error occurred */
+    ERROR = "ERROR"
+}
+/**
+ * Installation modes for AppSpacer.sync()
+ */
+export declare enum InstallMode {
+    /** Install and restart immediately */
+    IMMEDIATE = "IMMEDIATE",
+    /** Install and apply on next app restart */
+    ON_NEXT_RESTART = "ON_NEXT_RESTART",
+    /** Install and apply when app next resumes from background */
+    ON_NEXT_RESUME = "ON_NEXT_RESUME"
+}
+/**
+ * Metadata about the currently installed OTA update.
+ */
+export interface UpdateMetadata {
+    /** SHA256 hash of the installed package */
+    hash: string;
+    /** Server-assigned release ID */
+    releaseId?: string;
+    /** Release description */
+    description?: string;
+    /** Release label (e.g. v1, v2) */
+    label?: string;
+    /** ISO 8601 timestamp of when the update was installed */
+    installedAt?: string;
+    /** Whether the update is pending (hasn't been confirmed via markSuccess yet) */
+    isPending?: boolean;
+}
+/**
+ * Options for the built-in update dialog.
+ */
+export interface UpdateDialogOptions {
+    /** Title of the popup (Default: "Update Available") */
+    title?: string;
+    /** Message in the popup (Default: "An update is available for this app. Would you like to install it now?") */
+    message?: string;
+    /** Label for the 'Install' button (Default: "Install") */
+    installButtonLabel?: string;
+    /** Label for the 'Ignore' button on optional updates (Default: "Ignore") */
+    ignoreButtonLabel?: string;
+    /** Label for the 'Install' button on mandatory updates (Default: "Continue") */
+    mandatoryContinueButtonLabel?: string;
+    /** Message to display for mandatory updates (Default: "An update is available that must be installed.") */
+    mandatoryUpdateMessage?: string;
+    /** Whether to append the release description to the message (Default: true) */
+    appendReleaseDescription?: boolean;
+}
+/**
+ * Visual themes for the built-in update dialog.
+ */
+export declare enum UpdateUIType {
+    /** Premium dark theme with colored glow (Default) */
+    PREMIUM_DARK = "PREMIUM_DARK",
+    /** Modern glassmorphism with high transparency */
+    GLASS = "GLASS",
+    /** Ultra-clean minimalist light theme */
+    MINIMAL = "MINIMAL",
+    /** Modern bottom sheet layout (iOS-inspired) */
+    BOTTOM_SHEET = "BOTTOM_SHEET",
+    /** Immersive full-screen update experience */
+    FULL_SCREEN = "FULL_SCREEN"
+}
+/**
+ * Options for the AppSpacer.sync() lifecycle.
+ */
+export interface SyncOptions {
+    /** Where to install/apply (IMMEDIATE, ON_NEXT_RESTART, ON_NEXT_RESUME) */
+    installMode?: InstallMode;
+    /** Mode to use specifically for mandatory updates (Overrides installMode) */
+    mandatoryInstallMode?: InstallMode;
+    /** Whether to show a native prompt if an update is available */
+    updateDialog?: boolean | UpdateDialogOptions;
+    /** The UI theme to use for the update dialog (Default: PREMIUM_DARK) */
+    updateUI?: UpdateUIType;
+    /** Minimum background duration before applying (if ON_NEXT_RESUME) */
+    minimumBackgroundDuration?: number;
+}

package/dist/types.js

@@ -0,0 +1,50 @@
+/**
+ * Current state of the update process.
+ */
+export var UpdateStatus;
+(function (UpdateStatus) {
+    /** No update activity */
+    UpdateStatus["IDLE"] = "IDLE";
+    /** Checking the server for updates */
+    UpdateStatus["CHECKING"] = "CHECKING";
+    /** An update is available but not yet downloaded */
+    UpdateStatus["UPDATE_AVAILABLE"] = "UPDATE_AVAILABLE";
+    /** Downloading the bundle */
+    UpdateStatus["DOWNLOADING"] = "DOWNLOADING";
+    /** Bundle downloaded, verified and ready to install */
+    UpdateStatus["INSTALLING"] = "INSTALLING";
+    /** Update installed, awaiting restart */
+    UpdateStatus["INSTALLED"] = "INSTALLED";
+    /** App is already up to date */
+    UpdateStatus["UP_TO_DATE"] = "UP_TO_DATE";
+    /** An error occurred */
+    UpdateStatus["ERROR"] = "ERROR";
+})(UpdateStatus || (UpdateStatus = {}));
+/**
+ * Installation modes for AppSpacer.sync()
+ */
+export var InstallMode;
+(function (InstallMode) {
+    /** Install and restart immediately */
+    InstallMode["IMMEDIATE"] = "IMMEDIATE";
+    /** Install and apply on next app restart */
+    InstallMode["ON_NEXT_RESTART"] = "ON_NEXT_RESTART";
+    /** Install and apply when app next resumes from background */
+    InstallMode["ON_NEXT_RESUME"] = "ON_NEXT_RESUME";
+})(InstallMode || (InstallMode = {}));
+/**
+ * Visual themes for the built-in update dialog.
+ */
+export var UpdateUIType;
+(function (UpdateUIType) {
+    /** Premium dark theme with colored glow (Default) */
+    UpdateUIType["PREMIUM_DARK"] = "PREMIUM_DARK";
+    /** Modern glassmorphism with high transparency */
+    UpdateUIType["GLASS"] = "GLASS";
+    /** Ultra-clean minimalist light theme */
+    UpdateUIType["MINIMAL"] = "MINIMAL";
+    /** Modern bottom sheet layout (iOS-inspired) */
+    UpdateUIType["BOTTOM_SHEET"] = "BOTTOM_SHEET";
+    /** Immersive full-screen update experience */
+    UpdateUIType["FULL_SCREEN"] = "FULL_SCREEN";
+})(UpdateUIType || (UpdateUIType = {}));

package/dist/useAppSpacerUpdate.d.ts

@@ -0,0 +1,31 @@
+import type { AppSpacerUpdate, InstallMode, UpdateMetadata } from "./types";
+import { UpdateStatus } from "./types";
+interface UseAppSpacerUpdateResult {
+    /** Current status of the update process */
+    status: UpdateStatus;
+    /** Available update info (if any) */
+    update: AppSpacerUpdate | null;
+    /** Error message if status is ERROR */
+    error: string | null;
+    /** Download progress (0 to 1) while status is DOWNLOADING */
+    downloadProgress: number;
+    /** Manually check for updates */
+    checkForUpdate: () => Promise<void>;
+    /** Download, verify and prepare the update for installation */
+    downloadUpdate: () => Promise<void>;
+    /** Restart the app to apply the update */
+    restartApp: () => void;
+    /** Full lifecycle helper: check, download, and optionally restart */
+    sync: (options?: {
+        installMode?: InstallMode;
+    }) => Promise<void>;
+    /** Remove old update directories that are no longer active */
+    clearOldUpdates: () => Promise<number>;
+    /** Get metadata about the currently installed update */
+    getUpdateMetadata: () => Promise<UpdateMetadata | null>;
+}
+/**
+ * Production-grade React hook for AppSpacer OTA updates.
+ */
+export declare function useAppSpacerUpdate(): UseAppSpacerUpdateResult;
+export {};