cordova-plugin-hot-updates 2.1.1 → 2.2.0

package/src/ios/HotUpdatesConstants.h

@@ -0,0 +1,45 @@
+/*!
+ * @file HotUpdatesConstants.h
+ * @brief Constants for Hot Updates Plugin
+ * @details Defines error codes, storage keys, and directory names
+ * @version 2.2.0
+ * @date 2025-11-13
+ * @author Mustafin Vladimir
+ * @copyright Copyright (c) 2025. All rights reserved.
+ */
+
+#import <Foundation/Foundation.h>
+
+#pragma mark - Error Codes
+
+extern NSString * const kErrorUpdateDataRequired;
+extern NSString * const kErrorURLRequired;
+extern NSString * const kErrorDownloadInProgress;
+extern NSString * const kErrorDownloadFailed;
+extern NSString * const kErrorHTTPError;
+extern NSString * const kErrorTempDirError;
+extern NSString * const kErrorExtractionFailed;
+extern NSString * const kErrorWWWNotFound;
+extern NSString * const kErrorNoUpdateReady;
+extern NSString * const kErrorUpdateFilesNotFound;
+extern NSString * const kErrorInstallFailed;
+extern NSString * const kErrorVersionRequired;
+
+#pragma mark - Storage Keys
+
+extern NSString * const kInstalledVersion;
+extern NSString * const kPendingVersion;
+extern NSString * const kHasPending;
+extern NSString * const kPreviousVersion;
+extern NSString * const kIgnoreList;
+extern NSString * const kCanaryVersion;
+extern NSString * const kDownloadInProgress;
+extern NSString * const kPendingUpdateURL;
+extern NSString * const kPendingUpdateReady;
+
+#pragma mark - Directory Names
+
+extern NSString * const kWWWDirName;
+extern NSString * const kPreviousWWWDirName;
+extern NSString * const kBackupWWWDirName;
+extern NSString * const kPendingUpdateDirName;

package/src/ios/HotUpdatesConstants.m

@@ -0,0 +1,46 @@
+/*!
+ * @file HotUpdatesConstants.m
+ * @brief Implementation of constants for Hot Updates Plugin
+ * @details Defines all constant values used throughout the plugin
+ * @version 2.2.0
+ * @date 2025-11-13
+ * @author Mustafin Vladimir
+ * @copyright Copyright (c) 2025. All rights reserved.
+ */
+
+#import <Foundation/Foundation.h>
+#import "HotUpdatesConstants.h"
+
+#pragma mark - Error Codes
+
+NSString * const kErrorUpdateDataRequired = @"UPDATE_DATA_REQUIRED";
+NSString * const kErrorURLRequired = @"URL_REQUIRED";
+NSString * const kErrorDownloadInProgress = @"DOWNLOAD_IN_PROGRESS";
+NSString * const kErrorDownloadFailed = @"DOWNLOAD_FAILED";
+NSString * const kErrorHTTPError = @"HTTP_ERROR";
+NSString * const kErrorTempDirError = @"TEMP_DIR_ERROR";
+NSString * const kErrorExtractionFailed = @"EXTRACTION_FAILED";
+NSString * const kErrorWWWNotFound = @"WWW_NOT_FOUND";
+NSString * const kErrorNoUpdateReady = @"NO_UPDATE_READY";
+NSString * const kErrorUpdateFilesNotFound = @"UPDATE_FILES_NOT_FOUND";
+NSString * const kErrorInstallFailed = @"INSTALL_FAILED";
+NSString * const kErrorVersionRequired = @"VERSION_REQUIRED";
+
+#pragma mark - Storage Keys
+
+NSString * const kInstalledVersion = @"hot_updates_installed_version";
+NSString * const kPendingVersion = @"hot_updates_pending_version";
+NSString * const kHasPending = @"hot_updates_has_pending";
+NSString * const kPreviousVersion = @"hot_updates_previous_version";
+NSString * const kIgnoreList = @"hot_updates_ignore_list";
+NSString * const kCanaryVersion = @"hot_updates_canary_version";
+NSString * const kDownloadInProgress = @"hot_updates_download_in_progress";
+NSString * const kPendingUpdateURL = @"hot_updates_pending_update_url";
+NSString * const kPendingUpdateReady = @"hot_updates_pending_ready";
+
+#pragma mark - Directory Names
+
+NSString * const kWWWDirName = @"www";
+NSString * const kPreviousWWWDirName = @"www_previous";
+NSString * const kBackupWWWDirName = @"www_backup";
+NSString * const kPendingUpdateDirName = @"pending_update";

package/www/HotUpdates.js

@@ -1,192 +1,212 @@
 var exec = require('cordova/exec');
 
 /**
- * Cordova Hot Updates Plugin
+ * Cordova Hot Updates Plugin v2.1.2
+ * Frontend-controlled manual hot updates for iOS
  *
- * Provides automatic over-the-air (OTA) updates for Cordova applications
- * using the WebView Reload approach for instant updates.
+ * Provides manual over-the-air (OTA) updates for Cordova applications
+ * using the WebView Reload approach. All update decisions are controlled
+ * by JavaScript - the native plugin only executes commands.
  *
  * Features:
- * - Automatic background update checking
- * - Seamless download and installation
- * - Version compatibility checks
- * - Configurable update intervals
+ * - Frontend-controlled manual updates (no automatic checking)
+ * - Two-step update flow: getUpdate() downloads, forceUpdate() installs
+ * - Automatic rollback with 20-second canary timer
+ * - IgnoreList system for tracking problematic versions (information only)
+ * - Auto-install pending updates on next app launch
+ * - WebView reload approach for instant updates without app restart
  * - No App Store approval required for web content updates
  *
- * @version 1.0.0
+ * @version 2.1.2
  * @author Mustafin Vladimir
  */
 var HotUpdates = {
 
     /**
-     * Get current version information
-     * Returns the currently active version (installed update or bundle version)
+     * Download update from server
      *
-     * @param {Function} successCallback - Success callback with version string
-     * @param {Function} errorCallback - Error callback
+     * Downloads update ZIP archive from the provided URL and saves to two locations:
+     * - temp_downloaded_update (for immediate installation via forceUpdate)
+     * - pending_update (for auto-installation on next app launch)
      *
-     * @example
-     * HotUpdates.getCurrentVersion(
-     *   function(version) {
-     *     console.log('Current version:', version);
-     *   },
-     *   function(error) {
-     *     console.error('Error getting version:', error);
-     *   }
-     * );
-     */
-    getCurrentVersion: function(successCallback, errorCallback) {
-        exec(successCallback, errorCallback, 'HotUpdates', 'getCurrentVersion', []);
-    },
-
-    /**
-     * Get pending update information
-     * Returns information about downloaded updates waiting to be installed
-     *
-     * @param {Function} successCallback - Success callback with update info object
-     * @param {Function} errorCallback - Error callback
+     * If the specified version is already downloaded, returns success without re-downloading.
+     * Does NOT check ignoreList - JavaScript controls all installation decisions.
      *
-     * Success callback receives object with:
-     * - hasPendingUpdate: boolean
-     * - pendingVersion: string (if available)
-     * - appBundleVersion: string
-     * - installedVersion: string (current hot update version)
-     * - message: string (human readable status)
+     * @param {Object} options - Update options
+     * @param {string} options.url - URL to download ZIP archive (required)
+     * @param {string} [options.version] - Version string (optional)
+     * @param {Function} callback - Callback function
+     *   - Called with null on success
+     *   - Called with {error: {message?: string}} on error
      *
      * @example
-     * HotUpdates.getPendingUpdateInfo(
-     *   function(info) {
-     *     if (info.hasPendingUpdate) {
-     *       console.log('Update ready:', info.pendingVersion);
-     *       console.log('Will install on next app restart');
+     * window.hotUpdate.getUpdate({
+     *     url: 'https://your-server.com/updates/2.0.0.zip',
+     *     version: '2.0.0'
+     * }, function(error) {
+     *     if (error) {
+     *         console.error('Download failed:', error);
+     *     } else {
+     *         console.log('Update downloaded successfully');
+     *         // Can now call forceUpdate() to install immediately
+     *         // Or user can ignore and it will auto-install on next launch
      *     }
-     *   },
-     *   function(error) {
-     *     console.error('Error getting update info:', error);
-     *   }
-     * );
+     * });
      */
-    getPendingUpdateInfo: function(successCallback, errorCallback) {
-        exec(successCallback, errorCallback, 'HotUpdates', 'getPendingUpdateInfo', []);
+    getUpdate: function(options, callback) {
+        if (!options || !options.url) {
+            if (callback) {
+                callback({error: {message: 'URL is required'}});
+            }
+            return;
+        }
+
+        exec(
+            function() {
+                // Success
+                if (callback) callback(null);
+            },
+            function(error) {
+                // Error
+                if (callback) callback({error: error});
+            },
+            'HotUpdates',
+            'getUpdate',
+            [options]
+        );
     },
 
     /**
-     * Check for updates manually
-     * Triggers an immediate check for available updates on the server
+     * Install downloaded update immediately
+     *
+     * Installs the update that was downloaded via getUpdate().
+     * This will:
+     * 1. Backup current version to www_previous
+     * 2. Copy downloaded update to Documents/www
+     * 3. Clear WebView cache (disk, memory, Service Worker)
+     * 4. Reload WebView
+     * 5. Start 20-second canary timer
      *
-     * @param {Function} successCallback - Success callback with check result
-     * @param {Function} errorCallback - Error callback
+     * IMPORTANT: JavaScript MUST call canary(version) within 20 seconds
+     * after reload to confirm successful bundle load. Otherwise automatic
+     * rollback will occur.
      *
-     * Success callback receives object with:
-     * - hasUpdate: boolean
-     * - currentVersion: string
-     * - availableVersion: string (if hasUpdate is true)
-     * - downloadURL: string (if hasUpdate is true)
+     * Does NOT check ignoreList - JavaScript decides what to install.
+     *
+     * @param {Function} callback - Callback function
+     *   - Called with null on success (before WebView reload)
+     *   - Called with {error: {message?: string}} on error
      *
      * @example
-     * HotUpdates.checkForUpdates(
-     *   function(result) {
-     *     if (result.hasUpdate) {
-     *       console.log('Update available:', result.availableVersion);
+     * window.hotUpdate.forceUpdate(function(error) {
+     *     if (error) {
+     *         console.error('Install failed:', error);
      *     } else {
-     *       console.log('No updates available');
+     *         console.log('Update installing, WebView will reload...');
+     *         // After reload, MUST call canary() within 20 seconds!
      *     }
-     *   },
-     *   function(error) {
-     *     console.error('Update check failed:', error);
-     *   }
-     * );
+     * });
      */
-    checkForUpdates: function(successCallback, errorCallback) {
-        exec(successCallback, errorCallback, 'HotUpdates', 'checkForUpdates', []);
+    forceUpdate: function(callback) {
+        exec(
+            function() {
+                // Success
+                if (callback) callback(null);
+            },
+            function(error) {
+                // Error
+                if (callback) callback({error: error});
+            },
+            'HotUpdates',
+            'forceUpdate',
+            []
+        );
     },
 
     /**
-     * Download available update
-     * Manually triggers download of an available update
+     * Confirm successful bundle load (canary check)
      *
-     * @param {string} downloadURL - URL to download the update from
-     * @param {string} version - Version string of the update
-     * @param {Function} successCallback - Success callback when download completes
-     * @param {Function} errorCallback - Error callback
-     * @param {Function} progressCallback - Optional progress callback with download percentage
+     * MUST be called within 20 seconds after forceUpdate() to confirm
+     * that the new bundle loaded successfully. This stops the canary timer
+     * and prevents automatic rollback.
      *
-     * @example
-     * HotUpdates.downloadUpdate(
-     *   'https://server.com/updates/v2.0.0.zip',
-     *   '2.0.0',
-     *   function() {
-     *     console.log('Download completed, update will install on restart');
-     *   },
-     *   function(error) {
-     *     console.error('Download failed:', error);
-     *   },
-     *   function(progress) {
-     *     console.log('Download progress:', progress + '%');
-     *   }
-     * );
-     */
-    downloadUpdate: function(downloadURL, version, successCallback, errorCallback, progressCallback) {
-        var callbackId = successCallback ? 'HotUpdates' + Date.now() : null;
-
-        if (progressCallback) {
-            // Register progress callback if provided
-            exec(progressCallback, null, 'HotUpdates', 'setProgressCallback', [callbackId]);
-        }
-
-        exec(successCallback, errorCallback, 'HotUpdates', 'downloadUpdate', [downloadURL, version, callbackId]);
-    },
-
-    /**
-     * Get plugin configuration
-     * Returns current plugin configuration settings
+     * If not called within 20 seconds:
+     * - Automatic rollback to previous version
+     * - Failed version added to ignoreList
+     * - WebView reloaded with previous version
      *
-     * @param {Function} successCallback - Success callback with config object
-     * @param {Function} errorCallback - Error callback
+     * Call this immediately after your app initialization completes.
      *
-     * Success callback receives object with:
-     * - serverURL: string (update server URL)
-     * - checkInterval: number (check interval in milliseconds)
-     * - appBundleVersion: string (native app version)
-     * - autoDownload: boolean (automatic download enabled)
+     * @param {string} version - Version that loaded successfully
+     * @param {Function} [callback] - Optional callback (not used, method is synchronous)
      *
      * @example
-     * HotUpdates.getConfiguration(
-     *   function(config) {
-     *     console.log('Server URL:', config.serverURL);
-     *     console.log('Check interval:', config.checkInterval + 'ms');
-     *   },
-     *   function(error) {
-     *     console.error('Error getting config:', error);
-     *   }
-     * );
+     * // Call as early as possible after app loads
+     * document.addEventListener('deviceready', function() {
+     *     window.hotUpdate.canary('2.0.0');
+     *     console.log('Canary confirmed, update successful');
+     * }, false);
      */
-    getConfiguration: function(successCallback, errorCallback) {
-        exec(successCallback, errorCallback, 'HotUpdates', 'getConfiguration', []);
+    canary: function(version, callback) {
+        exec(
+            function() {
+                if (callback) callback();
+            },
+            function() {
+                if (callback) callback();
+            },
+            'HotUpdates',
+            'canary',
+            [version]
+        );
     },
 
     /**
-     * Install pending update immediately (requires app restart)
-     * Forces installation of a downloaded update without waiting for next app launch
-     * This will restart the application!
+     * Get list of problematic versions (information only)
      *
-     * @param {Function} successCallback - Success callback (app will restart before this is called)
-     * @param {Function} errorCallback - Error callback
+     * Returns array of version strings that failed to load (triggered rollback).
+     * This is an INFORMATION-ONLY system - native does NOT block installation
+     * of versions in this list.
+     *
+     * JavaScript should read this list and decide whether to skip downloading/
+     * installing these versions. If JS decides to install a version from the
+     * ignoreList, that's allowed (per TS requirements).
+     *
+     * Native automatically adds versions to this list when rollback occurs.
+     * JavaScript cannot modify the list (no add/remove/clear methods per TS v2.1.0).
+     *
+     * @param {Function} callback - Callback function
+     *   - Called with {versions: string[]} - Array of problematic version strings
      *
      * @example
-     * HotUpdates.installUpdate(
-     *   function() {
-     *     // This callback may not be called as app restarts
-     *     console.log('Update installed, app restarting...');
-     *   },
-     *   function(error) {
-     *     console.error('Install failed:', error);
-     *   }
-     * );
+     * window.hotUpdate.getIgnoreList(function(result) {
+     *     console.log('Problematic versions:', result.versions);
+     *     // Example: {versions: ['1.9.0', '2.0.1']}
+     *
+     *     // JavaScript decides what to do with this information
+     *     var shouldSkip = result.versions.includes(availableVersion);
+     *     if (shouldSkip) {
+     *         console.log('Skipping known problematic version');
+     *     } else {
+     *         // Download and install
+     *     }
+     * });
      */
-    installUpdate: function(successCallback, errorCallback) {
-        exec(successCallback, errorCallback, 'HotUpdates', 'installUpdate', []);
+    getIgnoreList: function(callback) {
+        exec(
+            function(versions) {
+                // Success - native returns array of version strings
+                if (callback) callback({versions: versions || []});
+            },
+            function(error) {
+                // Error - return empty list
+                if (callback) callback({versions: []});
+            },
+            'HotUpdates',
+            'getIgnoreList',
+            []
+        );
     }
 };
 
-module.exports = HotUpdates;
+module.exports = HotUpdates;