cordova-plugin-hot-updates 2.1.2 → 2.2.1

package/README.md

@@ -1,4 +1,4 @@
-# Cordova Hot Updates Plugin v2.1.2
+# Cordova Hot Updates Plugin v2.2.1
 
 Frontend-controlled manual hot updates for Cordova iOS applications using WebView Reload approach.
 
@@ -85,6 +85,66 @@ function downloadAndInstall(url, version) {
 }
 ```
 
+## Error Handling
+
+All errors are returned in a unified format for programmatic handling:
+
+```javascript
+// Error format
+callback({
+  error: {
+    code: "ERROR_CODE",        // Code for programmatic handling
+    message: "Detailed message" // Detailed message for logs
+  }
+})
+
+// Success result
+callback(null)
+```
+
+### Error Codes
+
+#### getUpdate() errors:
+- `UPDATE_DATA_REQUIRED` - Missing updateData parameter
+- `URL_REQUIRED` - Missing url parameter
+- `DOWNLOAD_IN_PROGRESS` - Download already in progress
+- `DOWNLOAD_FAILED` - Network download error (message contains details)
+- `HTTP_ERROR` - HTTP status != 200 (message contains status code)
+- `TEMP_DIR_ERROR` - Error creating temporary directory
+- `EXTRACTION_FAILED` - Error extracting ZIP archive
+- `WWW_NOT_FOUND` - www folder not found in archive
+
+#### forceUpdate() errors:
+- `NO_UPDATE_READY` - getUpdate() not called first
+- `UPDATE_FILES_NOT_FOUND` - Downloaded update files not found
+- `INSTALL_FAILED` - Error copying files (message contains details)
+
+#### canary() errors:
+- `VERSION_REQUIRED` - Missing version parameter
+
+### Error Handling Example
+
+```javascript
+window.hotUpdate.getUpdate({url: 'http://...'}, function(result) {
+  if (result && result.error) {
+    console.error('[HotUpdates]', result.error.code, ':', result.error.message);
+
+    switch(result.error.code) {
+      case 'HTTP_ERROR':
+        // Handle HTTP errors
+        break;
+      case 'DOWNLOAD_FAILED':
+        // Handle network errors
+        break;
+      default:
+        console.error('Unknown error:', result.error);
+    }
+  } else {
+    console.log('Update downloaded successfully');
+  }
+});
+```
+
 ## API Reference
 
 All API methods are available via `window.hotUpdate` after the `deviceready` event.
@@ -208,6 +268,32 @@ window.hotUpdate.getIgnoreList(function(result) {
 
 ---
 
+### window.hotUpdate.getVersionInfo(callback)
+
+Returns version information (debug method).
+
+**Parameters:**
+- `callback` (Function) - `callback(info)`
+  - `info.appBundleVersion` (string) - Native app version from Info.plist
+  - `info.installedVersion` (string|null) - Current hot update version
+  - `info.previousVersion` (string|null) - Last working version (for rollback)
+  - `info.canaryVersion` (string|null) - Version confirmed by canary
+  - `info.pendingVersion` (string|null) - Version pending installation
+  - `info.hasPendingUpdate` (boolean) - Whether pending update exists
+  - `info.ignoreList` (string[]) - Array of problematic versions
+
+**Example:**
+```javascript
+window.hotUpdate.getVersionInfo(function(info) {
+    console.log('App version:', info.appBundleVersion);
+    console.log('Installed:', info.installedVersion);
+    console.log('Previous:', info.previousVersion);
+    console.log('Pending:', info.hasPendingUpdate ? info.pendingVersion : 'none');
+});
+```
+
+---
+
 ## Complete Update Flow
 
 ```javascript
@@ -402,47 +488,6 @@ document.addEventListener('deviceready', function() {
 }, false);
 ```
 
-## Migration from v1.0.0
-
-**Removed methods:**
-- `getCurrentVersion()` - Manage in JS
-- `getPendingUpdateInfo()` - Not needed
-- `checkForUpdates()` - Frontend controls
-- `downloadUpdate()` - Use `getUpdate()`
-- `installUpdate()` - Use `forceUpdate()`
-
-**New API:**
-- `window.hotUpdate.getUpdate({url, version?}, callback)`
-- `window.hotUpdate.forceUpdate(callback)`
-- `window.hotUpdate.canary(version, callback)`
-- `window.hotUpdate.getIgnoreList(callback)`
-
-**Changes:**
-- API via `window.hotUpdate` (not `window.HotUpdates`)
-- Callback signature: `callback(error)` pattern
-- No automatic background checking
-
-## Changelog
-
-### v2.1.2 (2025-11-13)
-
-**Breaking Changes:**
-- Changed API from `window.HotUpdates` to `window.hotUpdate`
-- Removed automatic update checking
-- Simplified to 4 methods: `getUpdate`, `forceUpdate`, `canary`, `getIgnoreList`
-
-**New Features:**
-- Frontend-controlled manual updates
-- Two-step update flow
-- 20-second canary timer
-- IgnoreList system
-- Auto-install on next launch
-- WebView cache clearing
-
-### v1.0.0
-
-- Initial release
-
 ## License
 
 Custom Non-Commercial License - See [LICENSE](LICENSE) file

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "cordova-plugin-hot-updates",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "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",
     "prepublishOnly": "npm run verify",
-    "verify": "node -e \"console.log('Verifying package structure...'); const fs = require('fs'); ['www/HotUpdates.js', 'src/ios/HotUpdates.h', 'src/ios/HotUpdates.m', 'plugin.xml', 'LICENSE', 'README.md'].forEach(f => { if (!fs.existsSync(f)) throw new Error('Missing required file: ' + f); }); console.log('✓ All required files present');\"",
+    "verify": "node -e \"console.log('Verifying package structure...'); const fs = require('fs'); ['www/HotUpdates.js', 'src/ios/HotUpdates.h', 'src/ios/HotUpdates.m', 'src/ios/HotUpdatesConstants.h', 'src/ios/HotUpdatesConstants.m', 'src/ios/HotUpdates+Helpers.h', 'src/ios/HotUpdates+Helpers.m', 'plugin.xml', 'LICENSE', 'README.md'].forEach(f => { if (!fs.existsSync(f)) throw new Error('Missing required file: ' + f); }); console.log('✓ All required files present');\"",
     "pack-test": "npm pack && echo '\n✓ Package created. Test installation with: cordova plugin add ./cordova-plugin-hot-updates-*.tgz'",
     "preversion": "npm run verify",
     "postversion": "git push && git push --tags"

package/plugin.xml

@@ -1,6 +1,6 @@
 <?xml version='1.0' encoding='utf-8'?>
 <plugin id="cordova-plugin-hot-updates"
-        version="2.1.2"
+        version="2.2.1"
         xmlns="http://apache.org/cordova/ns/plugins/1.0"
         xmlns:android="http://schemas.android.com/apk/res/android">
 
@@ -40,6 +40,10 @@
         <!-- Native iOS files -->
         <source-file src="src/ios/HotUpdates.h" />
         <source-file src="src/ios/HotUpdates.m" />
+        <source-file src="src/ios/HotUpdatesConstants.h" />
+        <source-file src="src/ios/HotUpdatesConstants.m" />
+        <source-file src="src/ios/HotUpdates+Helpers.h" />
+        <source-file src="src/ios/HotUpdates+Helpers.m" />
 
         <!-- Required frameworks -->
         <framework src="Foundation.framework" />

package/src/ios/HotUpdates+Helpers.h

@@ -0,0 +1,23 @@
+/*!
+ * @file HotUpdates+Helpers.h
+ * @brief Helper methods for Hot Updates Plugin
+ * @details Category extension providing utility methods for error handling
+ * @version 2.1.0
+ * @date 2025-11-13
+ * @author Mustafin Vladimir
+ * @copyright Copyright (c) 2025. All rights reserved.
+ */
+
+#import "HotUpdates.h"
+
+@interface HotUpdates (Helpers)
+
+/*!
+ * @brief Create error dictionary for JavaScript callback
+ * @param code Error code (e.g., "URL_REQUIRED")
+ * @param message Detailed message for logs
+ * @return Dictionary with error structure {error: {code: "...", message: "..."}}
+ */
+- (NSDictionary*)createError:(NSString*)code message:(NSString*)message;
+
+@end

package/src/ios/HotUpdates+Helpers.m

@@ -0,0 +1,24 @@
+/*!
+ * @file HotUpdates+Helpers.m
+ * @brief Implementation of helper methods for Hot Updates Plugin
+ * @details Provides utility methods for error handling and response formatting
+ * @version 2.1.0
+ * @date 2025-11-13
+ * @author Mustafin Vladimir
+ * @copyright Copyright (c) 2025. All rights reserved.
+ */
+
+#import "HotUpdates+Helpers.h"
+
+@implementation HotUpdates (Helpers)
+
+- (NSDictionary*)createError:(NSString*)code message:(NSString*)message {
+    return @{
+        @"error": @{
+            @"code": code,
+            @"message": message
+        }
+    };
+}
+
+@end

package/src/ios/HotUpdates.h

@@ -19,6 +19,8 @@
 
 #import <UIKit/UIKit.h>
 #import <Cordova/CDVPlugin.h>
+#import "HotUpdatesConstants.h"
+
 @interface HotUpdates : CDVPlugin
 {
     NSString *documentsPath;
@@ -30,40 +32,13 @@
     NSString *previousVersionPath;    // Путь к предыдущей версии
 }
 
-// Plugin lifecycle methods
-- (void)pluginInitialize;
-- (void)loadConfiguration;
-- (void)initializeWWWFolder;
-- (void)checkAndInstallPendingUpdate;
-- (void)switchToUpdatedContentWithReload;
-- (void)reloadWebView;
-
-// Update management methods (internal)
-- (void)installPendingUpdate:(NSString*)newVersion;
-- (BOOL)unzipFile:(NSString *)zipPath toDestination:(NSString *)destinationPath;
-
-// Version comparison utilities
-- (NSComparisonResult)compareVersion:(NSString*)version1 withVersion:(NSString*)version2;
-
-// JavaScript callable methods (minimal set for debugging)
-- (void)getCurrentVersion:(CDVInvokedUrlCommand*)command;
-- (void)getPendingUpdateInfo:(CDVInvokedUrlCommand*)command;
-
-// Ignore List management (JS can only read, native controls)
-- (void)getIgnoreList:(CDVInvokedUrlCommand*)command;
-
-// Debug methods (for manual testing only)
-- (void)addToIgnoreList:(CDVInvokedUrlCommand*)command;
-- (void)removeFromIgnoreList:(CDVInvokedUrlCommand*)command;
-- (void)clearIgnoreList:(CDVInvokedUrlCommand*)command;
-
-// Update methods (v2.1.0 - manual updates only)
+// JavaScript API methods (v2.1.0)
 - (void)getUpdate:(CDVInvokedUrlCommand*)command;      // Download update
 - (void)forceUpdate:(CDVInvokedUrlCommand*)command;    // Install downloaded update
 - (void)canary:(CDVInvokedUrlCommand*)command;         // Confirm successful load
-- (void)rollback:(CDVInvokedUrlCommand*)command;       // Rollback to previous version
+- (void)getIgnoreList:(CDVInvokedUrlCommand*)command;  // Get ignore list (JS reads only)
 
-// Information methods
-- (void)getVersionInfo:(CDVInvokedUrlCommand*)command;
+// Debug method
+- (void)getVersionInfo:(CDVInvokedUrlCommand*)command; // Get all version info for debugging
 
 @end