cordova-plugin-hot-updates 2.1.0 → 2.1.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cordova-plugin-hot-updates",
-  "version": "2.1.0",
-  "description": "Cordova plugin for frontend-controlled over-the-air (OTA) hot updates using WebView Reload approach. Enables seamless web content updates without requiring App Store approval.",
+  "version": "2.1.2",
+  "description": "Frontend-controlled manual hot updates for Cordova iOS apps using WebView Reload approach. Manual updates only, JavaScript controls all decisions.",
   "main": "www/HotUpdates.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -23,6 +23,7 @@
     "over-the-air",
     "webview",
     "reload",
+    "manual",
     "ecosystem:cordova",
     "cordova-ios",
     "mobile",
@@ -58,10 +59,8 @@
     "www/",
     "src/",
     "scripts/",
-    "docs/",
     "plugin.xml",
     "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
+    "LICENSE"
   ]
 }

package/plugin.xml

@@ -1,16 +1,17 @@
 <?xml version='1.0' encoding='utf-8'?>
 <plugin id="cordova-plugin-hot-updates"
-        version="1.0.0"
+        version="2.1.2"
         xmlns="http://apache.org/cordova/ns/plugins/1.0"
         xmlns:android="http://schemas.android.com/apk/res/android">
 
     <name>Cordova Hot Updates Plugin</name>
     <description>
-        Cordova plugin for automatic over-the-air (OTA) hot updates using WebView Reload approach.
+        Cordova plugin for frontend-controlled manual hot updates using WebView Reload approach.
+        Manual updates only, JavaScript controls all decisions.
         Enables seamless web content updates without requiring App Store approval.
     </description>
     <license>Custom Non-Commercial</license>
-    <keywords>cordova,hot,updates,ota,over-the-air,webview,reload</keywords>
+    <keywords>cordova,hot,updates,ota,over-the-air,webview,reload,manual</keywords>
     <repo>https://github.com/vladimirDarksy/Cordova_hot_update.git</repo>
     <issue>https://github.com/vladimirDarksy/Cordova_hot_update/issues</issue>
 
@@ -23,7 +24,7 @@
 
     <!-- JavaScript interface -->
     <js-module src="www/HotUpdates.js" name="HotUpdates">
-        <clobbers target="HotUpdates" />
+        <clobbers target="hotUpdate" />
     </js-module>
 
     <!-- iOS platform -->
@@ -62,12 +63,6 @@
                 <true/>
             </dict>
         </edit-config>
-
-        <!-- Configuration preferences with default values -->
-        <preference name="hot_updates_server_url" default="https://your-server.com/api/updates" />
-        <preference name="hot_updates_check_interval" default="300000" />
-        <preference name="hot_updates_auto_download" default="true" />
-        <preference name="hot_updates_auto_install" default="true" />
     </platform>
 
     <!-- Android platform (placeholder for future implementation) -->

package/src/ios/HotUpdates.m

@@ -12,8 +12,8 @@
  *          - IgnoreList for tracking problematic versions
  *          - Auto-install pending updates on next app launch
  *
- * @version 2.1.0
- * @date 2025-11-03
+ * @version 2.1.2
+ * @date 2025-11-13
  * @author Mustafin Vladimir
  * @copyright Copyright (c) 2025. All rights reserved.
  */

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;