@appspacer/react-native 1.0.0

package/android/src/main/java/com/appspacer/AppSpacerPackage.java

@@ -0,0 +1,29 @@
+package com.appspacer;
+
+import androidx.annotation.NonNull;
+
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+public class AppSpacerPackage implements ReactPackage {
+
+    @NonNull
+    @Override
+    public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext reactContext) {
+        List<NativeModule> modules = new ArrayList<>();
+        modules.add(new AppSpacerModule(reactContext));
+        return modules;
+    }
+
+    @NonNull
+    @Override
+    public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext reactContext) {
+        return Collections.emptyList();
+    }
+}

package/dist/AppSpacer.d.ts

@@ -0,0 +1,116 @@
+import type { AppSpacerConfig, AppSpacerUpdate, UpdateMetadata, SyncOptions } from "./types";
+import { UpdateStatus } from "./types";
+type StatusListener = (status: UpdateStatus, detail?: string) => void;
+type ProgressListener = (progress: number) => void;
+/**
+ * Production-grade AppSpacer OTA manager.
+ */
+export declare class AppSpacerManager {
+    private config;
+    private status;
+    private listeners;
+    private progressListeners;
+    private checkTimer;
+    private pendingUpdate;
+    private appStateSubscription;
+    private breadcrumbAppStateSubscription;
+    private downloadProgressSubscription;
+    private sessionId;
+    private userMetadata;
+    /**
+     * Initialize the AppSpacer SDK.
+     */
+    init(config: AppSpacerConfig): void;
+    /**
+     * Tear down timers and listeners. Safe to call multiple times.
+     */
+    destroy(): void;
+    /**
+     * Explicitly notify the SDK that the app has successfully loaded.
+     * This prevents automatic rollback to the previous version.
+     */
+    notifyAppReady(): Promise<void>;
+    /**
+     * Check for updates from the AppSpacer server.
+     */
+    checkForUpdate(): Promise<AppSpacerUpdate>;
+    /**
+     * Download, verify, and prepare the update for installation.
+     */
+    downloadUpdate(): Promise<void>;
+    /**
+     * High-level sync method covering the full update lifecycle.
+     */
+    sync(options?: SyncOptions): Promise<AppSpacerUpdate>;
+    /**
+     * Remove old update directories that are no longer active.
+     * Keeps the current active update and the previous update for rollback.
+     * Returns the number of directories removed.
+     */
+    clearOldUpdates(): Promise<number>;
+    /**
+     * Get metadata about the currently installed update.
+     * Returns null if no OTA update is installed (running the embedded bundle).
+     */
+    getUpdateMetadata(): Promise<UpdateMetadata | null>;
+    /**
+     * Associate this session with a specific user.
+     * This is extremely useful for searching crashes by user ID in your dashboard.
+     */
+    setUserIdentity(userId: string, details?: object): void;
+    /**
+     * Add a breadcrumb to tracking. Breadcrumbs are included in crash reports
+     * to help reconstruct the events leading up to a crash.
+     */
+    addBreadcrumb(message: string, category?: string, data?: object): void;
+    /**
+     * Register a listener for download progress events.
+     * The callback receives a number between 0 and 1.
+     * Returns an unsubscribe function.
+     */
+    onDownloadProgress(listener: ProgressListener): () => void;
+    /**
+     * Report install status (installed or failed) to the backend.
+     */
+    private reportInstallStatus;
+    /**
+     * Process pending pending crash reports from native storage and send them to the backend.
+     */
+    private processCrashReports;
+    /**
+     * Get the current session ID.
+     */
+    getSessionId(): string;
+    /**
+     * Get the current update status.
+     */
+    getStatus(): UpdateStatus;
+    /**
+     * Reload the React Native bundle.
+     */
+    restartApp(): void;
+    onStatusChange(listener: StatusListener): () => void;
+    /**
+     * Display a native alert dialog to prompt the user about an update.
+     */
+    private showUpdateDialog;
+    /**
+     * Subscribe to native download progress events and fan out to JS listeners.
+     */
+    private subscribeToDownloadProgress;
+    private registerAutomaticBreadcrumbs;
+    /**
+     * Listen for app returning from background and restart to apply the installed update.
+     */
+    private waitForResumeThenRestart;
+    private startAutoCheck;
+    private stopAutoCheck;
+    private setStatus;
+    private assertConfigured;
+    /**
+     * fetch() wrapper with configurable timeout via AbortController.
+     */
+    private fetchWithTimeout;
+}
+export declare const AppSpacer: AppSpacerManager;
+export {};

package/dist/AppSpacer.js

@@ -0,0 +1,546 @@
+import { Platform, AppState, Alert } from "react-native";
+import { getNativeModule, getEventEmitter } from "./native";
+import { initAssetResolver } from "./assetResolver";
+import { initCrashReporter } from "./CrashReporter";
+import { UpdateStatus, InstallMode } from "./types";
+/** Default fetch timeout in milliseconds */
+const FETCH_TIMEOUT_MS = 15000;
+/** Default API URL for AppSpacer SaaS (Development uses local machine IP for Android emulators) */
+const DEFAULT_API_URL = __DEV__
+    ? Platform.select({
+        android: "http://10.0.2.2:8080/api",
+        ios: "http://localhost:8080/api",
+        default: "http://localhost:8080/api",
+    })
+    : "https://api.appspacer.com/api";
+/**
+ * Production-grade AppSpacer OTA manager.
+ */
+export class AppSpacerManager {
+    constructor() {
+        this.config = null;
+        this.status = UpdateStatus.IDLE;
+        this.listeners = new Set();
+        this.progressListeners = new Set();
+        this.checkTimer = null;
+        this.pendingUpdate = null;
+        this.appStateSubscription = null;
+        this.breadcrumbAppStateSubscription = null;
+        this.downloadProgressSubscription = null;
+        this.sessionId = "";
+        this.userMetadata = {};
+    }
+    /**
+     * Initialize the AppSpacer SDK.
+     */
+    init(config) {
+        // Clean up any previous initialization (safe for hot-reload)
+        this.destroy();
+        this.config = { ...config };
+        // Generate a unique session ID for this app launch
+        this.sessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        // Automatic rollback protection and successful boot notification
+        this.notifyAppReady();
+        // Check for pending crashes and upload them
+        if (config.enableCrashReporting) {
+            initCrashReporter(() => this.sessionId);
+            this.processCrashReports().catch(() => { });
+            this.registerAutomaticBreadcrumbs();
+            this.addBreadcrumb("SDK Initialized", "system");
+        }
+        // Initialize OTA asset resolver (patches Image.resolveAssetSource)
+        initAssetResolver().catch(() => { });
+        // Subscribe to native download progress events
+        this.subscribeToDownloadProgress();
+        // Start automatic checking if interval is set
+        if (config.checkInterval && config.checkInterval > 0) {
+            this.startAutoCheck(config.checkInterval);
+        }
+    }
+    /**
+     * Tear down timers and listeners. Safe to call multiple times.
+     */
+    destroy() {
+        this.stopAutoCheck();
+        if (this.appStateSubscription) {
+            this.appStateSubscription.remove();
+            this.appStateSubscription = null;
+        }
+        if (this.breadcrumbAppStateSubscription) {
+            this.breadcrumbAppStateSubscription.remove();
+            this.breadcrumbAppStateSubscription = null;
+        }
+        if (this.downloadProgressSubscription) {
+            this.downloadProgressSubscription.remove();
+            this.downloadProgressSubscription = null;
+        }
+    }
+    /**
+     * Explicitly notify the SDK that the app has successfully loaded.
+     * This prevents automatic rollback to the previous version.
+     */
+    async notifyAppReady() {
+        try {
+            const native = getNativeModule();
+            await native.markSuccess();
+            // If we just booted into a new version, report the successful install
+            const infoStr = await native.getCurrentPackageInfo();
+            if (infoStr) {
+                const info = JSON.parse(infoStr);
+                if (info.isPending && info.releaseId) {
+                    await this.reportInstallStatus(info.releaseId, "installed");
+                    // Mark as no longer pending
+                    await native.setCurrentPackageInfo(JSON.stringify({ ...info, isPending: false }));
+                }
+            }
+        }
+        catch {
+            // Ignore if native not ready
+        }
+    }
+    /**
+     * Check for updates from the AppSpacer server.
+     */
+    async checkForUpdate() {
+        this.assertConfigured();
+        this.setStatus(UpdateStatus.CHECKING);
+        try {
+            const native = getNativeModule();
+            const currentHash = await native.getCurrentPackageHash();
+            const installId = await native.getInstallId();
+            const response = await this.fetchWithTimeout(`${DEFAULT_API_URL}/updates/check`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    deployment_key: this.config.deploymentKey,
+                    app_version: this.config.appVersion,
+                    platform: Platform.OS,
+                    package_hash: currentHash,
+                    install_id: installId,
+                }),
+            });
+            if (!response.ok) {
+                throw new Error(`Server returned HTTP ${response.status}`);
+            }
+            const body = (await response.json());
+            if (!body.success) {
+                throw new Error("Failed to check for updates");
+            }
+            const update = {
+                updateAvailable: body.data.update_available,
+                releaseId: body.data.release_id,
+                packageUrl: body.data.package_url,
+                hash: body.data.hash,
+                mandatory: body.data.mandatory,
+                description: body.data.description,
+                label: body.data.label,
+                packageSize: body.data.package_size,
+            };
+            if (update.updateAvailable) {
+                this.pendingUpdate = update;
+                this.setStatus(UpdateStatus.UPDATE_AVAILABLE);
+                this.addBreadcrumb(`Update available: ${update.releaseId}`, "ota");
+            }
+            else {
+                this.setStatus(UpdateStatus.UP_TO_DATE);
+                this.addBreadcrumb("App is up to date", "ota");
+            }
+            return update;
+        }
+        catch (error) {
+            this.setStatus(UpdateStatus.ERROR, error.message);
+            throw error;
+        }
+    }
+    /**
+     * Download, verify, and prepare the update for installation.
+     */
+    async downloadUpdate() {
+        this.assertConfigured();
+        if (!this.pendingUpdate?.packageUrl || !this.pendingUpdate?.hash) {
+            throw new Error("No pending update. Call checkForUpdate() first.");
+        }
+        const native = getNativeModule();
+        const packageUrl = this.pendingUpdate.packageUrl;
+        const expectedHash = this.pendingUpdate.hash;
+        try {
+            this.setStatus(UpdateStatus.DOWNLOADING);
+            const storageDir = await native.getOtaStoragePath();
+            const downloadedZipPath = await native.downloadPackage(packageUrl, storageDir);
+            // Hash Verification
+            const isValid = await native.verifyHash(downloadedZipPath, expectedHash);
+            if (!isValid) {
+                // Cleanup and abort
+                throw new Error("Update package hash mismatch. Verification failed.");
+            }
+            this.setStatus(UpdateStatus.INSTALLING);
+            const unzippedDir = `${storageDir}/update_${expectedHash}`;
+            await native.unzipPackage(downloadedZipPath, unzippedDir);
+            // Final install preparation
+            await native.installUpdate(unzippedDir);
+            // Metadata with isPending flag for rollback protection
+            await native.setCurrentPackageInfo(JSON.stringify({
+                hash: expectedHash,
+                releaseId: this.pendingUpdate.releaseId,
+                description: this.pendingUpdate.description,
+                label: this.pendingUpdate.label,
+                installedAt: new Date().toISOString(),
+                isPending: true,
+            }));
+            this.setStatus(UpdateStatus.INSTALLED);
+        }
+        catch (error) {
+            // Report install failure to backend
+            if (this.pendingUpdate?.releaseId) {
+                this.reportInstallStatus(this.pendingUpdate.releaseId, "failed", error.message).catch(() => { });
+            }
+            this.setStatus(UpdateStatus.ERROR, error.message);
+            throw error;
+        }
+    }
+    /**
+     * High-level sync method covering the full update lifecycle.
+     */
+    async sync(options) {
+        const update = await this.checkForUpdate();
+        if (update.updateAvailable) {
+            const mode = update.mandatory
+                ? options?.mandatoryInstallMode ?? options?.installMode ?? InstallMode.IMMEDIATE
+                : options?.installMode ?? InstallMode.ON_NEXT_RESTART;
+            if (__DEV__)
+                console.log(`[AppSpacer] Update found: ${update.releaseId}. Mode: ${mode}. Mandatory: ${update.mandatory}`);
+            if (options?.updateDialog) {
+                const dialogOpts = typeof options.updateDialog === "boolean" ? {} : options.updateDialog;
+                const shouldInstall = await this.showUpdateDialog(update, dialogOpts);
+                if (!shouldInstall) {
+                    return update;
+                }
+            }
+            await this.downloadUpdate();
+            if (mode === InstallMode.IMMEDIATE) {
+                this.restartApp();
+            }
+            else if (mode === InstallMode.ON_NEXT_RESUME) {
+                this.waitForResumeThenRestart();
+            }
+        }
+        return update;
+    }
+    /**
+     * Remove old update directories that are no longer active.
+     * Keeps the current active update and the previous update for rollback.
+     * Returns the number of directories removed.
+     */
+    async clearOldUpdates() {
+        const native = getNativeModule();
+        return native.clearOldUpdates();
+    }
+    /**
+     * Get metadata about the currently installed update.
+     * Returns null if no OTA update is installed (running the embedded bundle).
+     */
+    async getUpdateMetadata() {
+        const native = getNativeModule();
+        const infoStr = await native.getUpdateMetadata();
+        if (!infoStr)
+            return null;
+        try {
+            return JSON.parse(infoStr);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Associate this session with a specific user.
+     * This is extremely useful for searching crashes by user ID in your dashboard.
+     */
+    setUserIdentity(userId, details) {
+        this.userMetadata = { id: userId, details };
+        try {
+            const native = getNativeModule();
+            native.setUserIdentity(userId, JSON.stringify(details || {}));
+        }
+        catch {
+            // Native not ready
+        }
+        this.addBreadcrumb(`User Identity set: ${userId}`, 'user');
+    }
+    /**
+     * Add a breadcrumb to tracking. Breadcrumbs are included in crash reports
+     * to help reconstruct the events leading up to a crash.
+     */
+    addBreadcrumb(message, category, data) {
+        if (!this.config?.enableCrashReporting)
+            return;
+        const timestamp = new Date().toISOString();
+        const breadcrumb = `[${timestamp}] ${category ? `(${category}) ` : ""}${message}${data ? ` ${JSON.stringify(data)}` : ""}`;
+        try {
+            const native = getNativeModule();
+            native.addBreadcrumb(breadcrumb);
+        }
+        catch {
+            // Native not available
+        }
+    }
+    /**
+     * Register a listener for download progress events.
+     * The callback receives a number between 0 and 1.
+     * Returns an unsubscribe function.
+     */
+    onDownloadProgress(listener) {
+        this.progressListeners.add(listener);
+        return () => this.progressListeners.delete(listener);
+    }
+    /**
+     * Report install status (installed or failed) to the backend.
+     */
+    async reportInstallStatus(releaseId, status, errorMessage) {
+        if (!this.config)
+            return;
+        try {
+            const native = getNativeModule();
+            const installId = await native.getInstallId();
+            await this.fetchWithTimeout(`${DEFAULT_API_URL}/updates/report-status`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    release_id: releaseId,
+                    device_id: installId,
+                    platform: Platform.OS,
+                    app_version: this.config.appVersion,
+                    status,
+                    ...(status === "failed" && errorMessage
+                        ? { error_message: errorMessage }
+                        : {}),
+                }),
+            });
+        }
+        catch {
+            // Background reporting failure is non-fatal
+        }
+    }
+    /**
+     * Process pending pending crash reports from native storage and send them to the backend.
+     */
+    async processCrashReports() {
+        if (!this.config?.enableCrashReporting)
+            return;
+        try {
+            const native = getNativeModule();
+            const pendingJson = await native.getPendingCrashReports();
+            if (!pendingJson)
+                return;
+            const reports = JSON.parse(pendingJson);
+            if (__DEV__ && reports.length > 0) {
+                console.log(`[AppSpacer] Found ${reports.length} pending crash report(s). Uploading...`);
+            }
+            for (const report of reports) {
+                try {
+                    // Attempt to parse payload if it's JSON from JS SDK
+                    let message = 'Crash occurred';
+                    let stack = report.payload;
+                    let isFatal = true;
+                    try {
+                        const parsed = JSON.parse(report.payload);
+                        if (parsed.message)
+                            message = parsed.message;
+                        if (parsed.stack)
+                            stack = parsed.stack;
+                        if (parsed.isFatal !== undefined)
+                            isFatal = parsed.isFatal;
+                    }
+                    catch (e) {
+                        // Native payloads might be plain text or manually formatted
+                    }
+                    // Fire and forget upload to crash analytics endpoint
+                    const installId = await native.getInstallId();
+                    const response = await this.fetchWithTimeout(`${DEFAULT_API_URL}/v1/crashes`, {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": "application/json",
+                            "x-api-key": this.config.deploymentKey,
+                        },
+                        body: JSON.stringify({
+                            id: report.id,
+                            session_id: report.session_id || this.sessionId,
+                            fatal: isFatal,
+                            exception: {
+                                type: report.type,
+                                message: message,
+                                stack_trace: stack
+                            },
+                            user_id: report.user_id || this.userMetadata.id,
+                            user_metadata: report.user_metadata || this.userMetadata.details,
+                            device: {
+                                os: Platform.OS,
+                                app_version: this.config.appVersion,
+                                ...report.device || {},
+                            },
+                            breadcrumbs: report.breadcrumbs || [],
+                            timestamp: report.timestamp,
+                        }),
+                    });
+                    if (response.ok) {
+                        if (__DEV__)
+                            console.log(`[AppSpacer] Successfully uploaded crash report: ${report.id}`);
+                        await native.deleteCrashReport(report.id);
+                    }
+                    else {
+                        const body = await response.text();
+                        console.warn(`[AppSpacer] Crash upload failed for ${report.id}. Status: ${response.status}. Body: ${body}`);
+                    }
+                }
+                catch (e) {
+                    console.warn(`[AppSpacer] Failed to upload crash report ${report.id}`, e);
+                }
+            }
+        }
+        catch (e) {
+            console.warn("[AppSpacer] Failed to process pending crashes", e);
+        }
+    }
+    /**
+     * Get the current session ID.
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Get the current update status.
+     */
+    getStatus() {
+        return this.status;
+    }
+    /**
+     * Reload the React Native bundle.
+     */
+    restartApp() {
+        const native = getNativeModule();
+        native.reloadApp();
+    }
+    onStatusChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    // ─── Private helpers ───────────────────────────────────────────────
+    /**
+     * Display a native alert dialog to prompt the user about an update.
+     */
+    showUpdateDialog(update, options) {
+        return new Promise((resolve) => {
+            const title = options.title ?? "Update Available";
+            let message = options.message ?? (update.mandatory
+                ? (options.mandatoryUpdateMessage ?? "An update is available that must be installed.")
+                : "An update is available for this app. Would you like to install it now?");
+            if (options.appendReleaseDescription !== false && update.description) {
+                message += `\n\nRelease notes:\n${update.description}`;
+            }
+            const buttons = [];
+            if (!update.mandatory) {
+                buttons.push({
+                    text: options.ignoreButtonLabel ?? "Ignore",
+                    style: "cancel",
+                    onPress: () => resolve(false),
+                });
+            }
+            buttons.push({
+                text: update.mandatory
+                    ? (options.mandatoryContinueButtonLabel ?? "Continue")
+                    : (options.installButtonLabel ?? "Install"),
+                onPress: () => resolve(true),
+            });
+            Alert.alert(title, message, buttons, { cancelable: !update.mandatory });
+        });
+    }
+    /**
+     * Subscribe to native download progress events and fan out to JS listeners.
+     */
+    subscribeToDownloadProgress() {
+        if (this.downloadProgressSubscription) {
+            this.downloadProgressSubscription.remove();
+        }
+        try {
+            const emitter = getEventEmitter();
+            this.downloadProgressSubscription = emitter.addListener("AppSpacerDownloadProgress", (event) => {
+                for (const listener of this.progressListeners) {
+                    try {
+                        listener(event.progress);
+                    }
+                    catch { }
+                }
+            });
+        }
+        catch {
+            // Event emitter not available — progress won't be reported
+        }
+    }
+    registerAutomaticBreadcrumbs() {
+        if (this.breadcrumbAppStateSubscription) {
+            this.breadcrumbAppStateSubscription.remove();
+        }
+        this.breadcrumbAppStateSubscription = AppState.addEventListener("change", (nextState) => {
+            this.addBreadcrumb(`App State changed: ${nextState}`, "system");
+        });
+        this.addBreadcrumb(`Native Platform: ${Platform.OS}`, "system");
+    }
+    /**
+     * Listen for app returning from background and restart to apply the installed update.
+     */
+    waitForResumeThenRestart() {
+        // Remove any previous subscription
+        if (this.appStateSubscription) {
+            this.appStateSubscription.remove();
+            this.appStateSubscription = null;
+        }
+        this.appStateSubscription = AppState.addEventListener("change", (nextState) => {
+            this.addBreadcrumb(`App State changed to: ${nextState}`, "system");
+            if (nextState === "active") {
+                // Clean up the listener before restarting
+                if (this.appStateSubscription) {
+                    this.appStateSubscription.remove();
+                    this.appStateSubscription = null;
+                }
+                this.restartApp();
+            }
+        });
+    }
+    startAutoCheck(intervalSeconds) {
+        this.stopAutoCheck();
+        this.checkTimer = setInterval(() => this.checkForUpdate().catch(() => { }), intervalSeconds * 1000);
+    }
+    stopAutoCheck() {
+        if (this.checkTimer) {
+            clearInterval(this.checkTimer);
+            this.checkTimer = null;
+        }
+    }
+    setStatus(status, detail) {
+        this.status = status;
+        for (const listener of this.listeners) {
+            try {
+                listener(status, detail);
+            }
+            catch { }
+        }
+    }
+    assertConfigured() {
+        if (!this.config) {
+            throw new Error("AppSpacer SDK not initialized. Call AppSpacer.init() first.");
+        }
+    }
+    /**
+     * fetch() wrapper with configurable timeout via AbortController.
+     */
+    async fetchWithTimeout(url, options, timeoutMs = FETCH_TIMEOUT_MS) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await fetch(url, { ...options, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+export const AppSpacer = new AppSpacerManager();

package/dist/CrashReporter.d.ts

@@ -0,0 +1 @@
+export declare const initCrashReporter: (getSessionId: () => string) => void;