cordova-plugin-hot-updates 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,239 @@
+# Changelog
+
+All notable changes to cordova-plugin-hot-updates will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.0] - 2025-11-04
+
+### 🛠️ Fixed
+
+- **getUpdate() duplicate downloads**: Added check for already installed version - `getUpdate()` now returns success without re-downloading if the requested version is already installed
+- **Duplicate code**: Removed duplicate `setBool:YES forKey:kPendingUpdateReady` call in `saveDownloadedUpdate()`
+
+### 🧹 Improved
+
+- **Cleaner logs**: Removed all emoji and debug messages from native code - logs are now professional and suitable for production
+- **Code cleanup**: Removed 3 unused internal methods (~80 lines of dead code):
+  - `removeVersionFromIgnoreList()`
+  - `isVersionIgnored()`
+  - `compareVersion:withVersion:`
+- **Updated documentation**: Header comment now accurately reflects frontend-controlled architecture
+
+### 📊 Technical Details
+
+**Files changed**: 1 (HotUpdates.m)
+- Added: ~15 lines
+- Removed: ~80 lines
+- Methods removed: 3
+
+**No breaking changes** - API remains fully compatible with v2.0.0
+
+---
+
+## [2.0.0] - 2025-10-30
+
+### 🔥 Breaking Changes
+
+- **Rollback behavior changed**: After successful rollback, `previousVersion` is now cleared to prevent infinite rollback loops. This means you can only rollback once without performing a new update first.
+
+### ✨ Added
+
+- **Loop Prevention**: Added protection against infinite update/rollback cycles
+  - `forceUpdate` now rejects attempts to install already installed version (error: `version_already_installed`)
+  - `rollback` validates that previous version differs from current (error: `same_version`)
+  - `rollback` clears `previousVersion` metadata after successful rollback
+
+- **Enhanced Error Codes**: 13 detailed error codes for better error handling
+  - **forceUpdate**: 9 error codes (`version_already_installed`, `version_ignored`, `version_incompatible`, `download_failed`, `http_error`, `unzip_failed`, `invalid_package`, `install_failed`, `Download already in progress`)
+  - **rollback**: 4 error codes (`no_previous_version`, `previous_files_missing`, `same_version`, `file_operation_failed`)
+
+- **Improved Version Checking**: `getVersionInfo` now properly validates all conditions for rollback availability
+  - Checks: folder exists + metadata exists + versions are different
+  - New fields: `rollbackAvailable` (folder exists), `rollbackReady` (all conditions met)
+
+- **Enhanced API Responses**:
+  - `rollback` success response includes `canRollbackAgain: false` field
+  - `rollback` error response includes detailed error information: `error`, `message`, `currentVersion`, `previousVersion`, `canRollback`, `hasPreviousMetadata`
+  - `forceUpdate` error includes `currentVersion` and `requestedVersion` for `version_already_installed` error
+
+### 🛠️ Fixed
+
+- Fixed infinite rollback loop caused by version metadata swapping
+- Fixed `canRollback` incorrectly returning `true` when versions are identical
+- Fixed ability to install the same version multiple times
+- Fixed rollback not detecting corrupted metadata
+
+### 📝 Changed
+
+- Reduced excessive debug logging, keeping only essential logs
+- Improved log clarity and consistency across all methods
+- Metadata management now uses strict version validation
+
+### 🔒 Security
+
+- Added validation to prevent rollback to same version (potential attack vector)
+- Enhanced version comparison logic to prevent bypass attempts
+
+## [1.0.0] - 2025-10-27
+
+### ✨ Initial Release
+
+- Frontend-controlled WebView Reload approach
+- Automatic background update checking
+- Force update capability with instant WebView reload
+- Rollback mechanism with automatic backup
+- IgnoreList for blocking problematic versions
+- Canary system for version verification
+- Semantic version comparison
+- minAppVersion compatibility checking
+- Auto-update toggle (disabled by default)
+- First launch detection and handling
+- Support for iOS 11.2+
+
+---
+
+## Migration Guide: 1.0.0 → 2.0.0
+
+### Breaking Changes
+
+**1. Rollback Behavior**
+
+**Before (v1.0.0):**
+```
+Installed: 2.7.8, Previous: 2.7.7
+rollback() → Installed: 2.7.7, Previous: 2.7.8 ⚠️ (could create infinite loop)
+```
+
+**After (v2.0.0):**
+```
+Installed: 2.7.8, Previous: 2.7.7
+rollback() → Installed: 2.7.7, Previous: nil ✅ (loop prevented)
+```
+
+### What You Need to Update
+
+**1. Error Handling for forceUpdate**
+
+Add handler for new `version_already_installed` error:
+
+```javascript
+window.HotUpdates.forceUpdate(data, function(result) {
+  if (result.error === 'version_already_installed') {
+    // New in v2.0.0: Handle already installed version
+    showNotification('This version is already installed');
+    return;
+  }
+  // ... rest of error handling
+});
+```
+
+**2. Error Handling for rollback**
+
+Update rollback error handling with new detailed errors:
+
+```javascript
+window.HotUpdates.rollback(function(result) {
+  if (!result.success) {
+    // New in v2.0.0: Detailed error codes
+    switch(result.error) {
+      case 'no_previous_version':
+        showError('No previous version to rollback to');
+        break;
+      case 'previous_files_missing':
+        showError('Previous version files not found');
+        break;
+      case 'same_version':
+        showError('Cannot rollback to the same version');
+        break;
+      case 'file_operation_failed':
+        showError('Rollback failed');
+        break;
+    }
+  }
+});
+```
+
+**3. UI Updates for Rollback**
+
+Check `canRollbackAgain` field after rollback:
+
+```javascript
+window.HotUpdates.rollback(function(result) {
+  if (result.success) {
+    console.log('Rollback successful');
+    console.log('Can rollback again:', result.canRollbackAgain); // Always false in v2.0.0
+
+    // Hide rollback button after successful rollback
+    if (!result.canRollbackAgain) {
+      hideRollbackButton();
+    }
+  }
+});
+```
+
+**4. Version Info Checks**
+
+Use improved `canRollback` field:
+
+```javascript
+window.HotUpdates.getVersionInfo(function(info) {
+  // v2.0.0: More accurate rollback availability check
+  if (info.canRollback) {
+    // All conditions met: folder + metadata + different versions
+    enableRollbackButton();
+  } else {
+    disableRollbackButton();
+  }
+
+  // New fields in v2.0.0:
+  console.log('Rollback folder exists:', info.rollbackAvailable);
+  console.log('Rollback ready:', info.rollbackReady);
+});
+```
+
+### Testing After Migration
+
+Run these tests to ensure v2.0.0 works correctly:
+
+```javascript
+// Test 1: Prevent duplicate installation
+window.HotUpdates.getCurrentVersion(function(current) {
+  window.HotUpdates.forceUpdate({
+    url: 'http://example.com/update.zip',
+    version: current // Same as current!
+  }, function(result) {
+    // Should return error: version_already_installed ✅
+    console.assert(result.error === 'version_already_installed');
+  });
+});
+
+// Test 2: Rollback loop prevention
+window.HotUpdates.forceUpdate({url: '...', version: '2.7.8'}, function(r1) {
+  if (r1.status === 'installed') {
+    window.HotUpdates.rollback(function(r2) {
+      if (r2.success) {
+        // First rollback: should succeed ✅
+        window.HotUpdates.rollback(function(r3) {
+          // Second rollback: should fail with no_previous_version ✅
+          console.assert(!r3.success);
+          console.assert(r3.error === 'no_previous_version');
+        });
+      }
+    });
+  }
+});
+```
+
+### Performance Impact
+
+- **No performance degradation**: All changes are optimizations
+- **Reduced log output**: Less console spam in production
+- **Faster error detection**: Version checks happen earlier
+
+### Support
+
+- Documentation: [README.md](README.md)
+- Issues: [GitHub Issues](https://github.com/vladimirDarksy/Cordova_hot_update/issues)
+- Version comparison: [1.0.0...2.0.0](https://github.com/vladimirDarksy/Cordova_hot_update/compare/v1.0.0...v2.0.0)

package/docs/API.md

@@ -0,0 +1,352 @@
+# Hot Updates API v2.1.0
+
+## 🎯 4 метода для управления обновлениями
+
+---
+
+## 1. getUpdate() - Скачать обновление
+
+Скачивает обновление в фоновом режиме. **Не устанавливает!**
+
+```javascript
+window.flasher.getUpdate({url, version}, callback)
+```
+
+### Параметры:
+
+| Параметр | Тип | Обязательный | Описание |
+|----------|-----|--------------|----------|
+| url | string | ✅ | URL архива обновления (.zip) |
+| version | string | ⚠️ | Версия обновления (опционально) |
+| callback | function | ✅ | Вызывается после завершения |
+
+### Callback:
+
+```javascript
+function callback(error) {
+    if (error) {
+        // Ошибка: {error: {message: "текст ошибки"}}
+        console.error('Ошибка скачивания:', error.error.message);
+    } else {
+        // Успех: null или undefined
+        console.log('Обновление скачано');
+    }
+}
+```
+
+### Пример:
+
+```javascript
+window.flasher.getUpdate({
+    url: 'https://api.example.com/updates/2.7.8.zip',
+    version: '2.7.8'
+}, function(error) {
+    if (error) {
+        alert('Не удалось скачать обновление');
+        return;
+    }
+    // Показать popup "Обновить приложение?"
+    showUpdatePopup();
+});
+```
+
+### Возможные ошибки:
+
+| Ошибка | Причина |
+|--------|---------|
+| `URL required` | Не передан URL |
+| `Download failed` | Проблемы с сетью |
+| `HTTP error` | Сервер вернул ошибку (не 200) |
+| `Unzip failed` | Битый архив |
+| `Invalid package` | В архиве нет папки www |
+| `Download already in progress` | Уже идет загрузка |
+
+### Важно:
+
+- Если версия уже скачана - вернет **success** (не будет перезагружать)
+- Обновление НЕ устанавливается автоматически
+- Нужно вызвать `forceUpdate()` для установки
+
+---
+
+## 2. forceUpdate() - Установить обновление
+
+Устанавливает скачанное обновление и перезагружает WebView.
+
+```javascript
+window.flasher.forceUpdate(callback)
+```
+
+### Параметры:
+
+| Параметр | Тип | Обязательный | Описание |
+|----------|-----|--------------|----------|
+| callback | function | ✅ | Вызывается перед перезагрузкой |
+
+### Callback:
+
+```javascript
+function callback(error) {
+    if (error) {
+        // Ошибка: {error: {message: "текст ошибки"}}
+        console.error('Ошибка установки:', error.error.message);
+    } else {
+        // Успех: null или undefined
+        console.log('Обновление установлено, перезагрузка...');
+        // Через ~1 секунду WebView перезагрузится
+    }
+}
+```
+
+### Пример:
+
+```javascript
+window.flasher.forceUpdate(function(error) {
+    if (error) {
+        alert('Не удалось установить обновление');
+        return;
+    }
+    // WebView сейчас перезагрузится с новой версией
+});
+```
+
+### Возможные ошибки:
+
+| Ошибка | Причина |
+|--------|---------|
+| `No update ready to install` | Не было вызвано `getUpdate()` |
+| `Install failed` | Ошибка файловой системы |
+
+### Важно:
+
+- Можно вызвать только после успешного `getUpdate()`
+- WebView перезагружается автоматически через ~1 секунду
+- После перезагрузки **обязательно** вызовите `canary()`
+
+---
+
+## 3. canary() - Подтвердить успешную загрузку
+
+Подтверждает, что обновление загрузилось без ошибок. **ОБЯЗАТЕЛЕН при каждом старте!**
+
+```javascript
+window.flasher.canary(version, callback)
+```
+
+### Параметры:
+
+| Параметр | Тип | Обязательный | Описание |
+|----------|-----|--------------|----------|
+| version | string | ✅ | Текущая версия приложения |
+| callback | function | ⚠️ | Не используется, можно передать null |
+
+### Пример:
+
+```javascript
+document.addEventListener('deviceready', function() {
+    // ОБЯЗАТЕЛЬНО при каждом старте приложения!
+    window.flasher.canary('2.7.8', function() {
+        console.log('Canary confirmed');
+    });
+});
+```
+
+### Как получить версию:
+
+```javascript
+// Способ 1: Динамическая загрузка из native (рекомендуется)
+cordova.exec(function(info) {
+    const currentVersion = info.installedVersion || info.appBundleVersion;
+    window.flasher.canary(currentVersion, null);
+}, null, 'HotUpdates', 'getVersionInfo', []);
+
+// Способ 2: Статическая (нужно обновлять вручную)
+window.APP_VERSION = "2.7.8";
+window.flasher.canary(window.APP_VERSION, null);
+```
+
+### Важно:
+
+- **ОБЯЗАТЕЛЬНО** вызывать при каждом старте приложения
+- Если не вызвать в течение 20 секунд → автоматический откат на предыдущую версию
+- Версия должна быть строкой (не числом!)
+
+---
+
+## 4. getIgnoreList() - Получить черный список версий
+
+Возвращает список версий, которые вызвали проблемы и были откачены.
+
+```javascript
+window.flasher.getIgnoreList(callback)
+```
+
+### Параметры:
+
+| Параметр | Тип | Обязательный | Описание |
+|----------|-----|--------------|----------|
+| callback | function | ✅ | Получает список версий |
+
+### Callback:
+
+```javascript
+function callback(result) {
+    const badVersions = result.versions; // ["2.7.5", "2.7.6"]
+}
+```
+
+### Пример:
+
+```javascript
+window.flasher.getIgnoreList(function(result) {
+    const ignoredVersions = result.versions;
+
+    // Проверяем новую версию перед скачиванием
+    if (ignoredVersions.includes(newVersion)) {
+        console.log('Эта версия в черном списке, не скачиваем');
+        return;
+    }
+
+    // Версия безопасна, можно скачивать
+    window.flasher.getUpdate({url: updateUrl}, ...);
+});
+```
+
+### Важно:
+
+- Список управляется **только native кодом**
+- JavaScript может только **читать** список
+- Версии добавляются автоматически при откате (rollback)
+- Вы сами решаете, скачивать версию из списка или нет
+
+---
+
+## 📋 Полный сценарий работы
+
+```javascript
+document.addEventListener('deviceready', function() {
+    // 1. ОБЯЗАТЕЛЬНО подтверждаем canary
+    loadCurrentVersion(function(currentVersion) {
+        window.flasher.canary(currentVersion, function() {
+            console.log('✅ Canary OK');
+        });
+    });
+
+    // 2. Получаем черный список
+    window.flasher.getIgnoreList(function(result) {
+        const ignoredVersions = result.versions;
+
+        // 3. Проверяем обновления на сервере
+        checkServerForUpdates(function(updateInfo) {
+            if (!updateInfo.hasUpdate) {
+                console.log('Обновлений нет');
+                return;
+            }
+
+            // 4. Проверяем черный список
+            if (ignoredVersions.includes(updateInfo.version)) {
+                console.log('Версия в черном списке, пропускаем');
+                return;
+            }
+
+            // 5. Скачиваем обновление
+            window.flasher.getUpdate({
+                url: updateInfo.downloadUrl,
+                version: updateInfo.version
+            }, function(error) {
+                if (error) {
+                    console.error('Ошибка загрузки:', error.error.message);
+                    return;
+                }
+
+                // 6. Показываем popup
+                if (confirm('Обновить до версии ' + updateInfo.version + '?')) {
+                    // 7. Устанавливаем
+                    window.flasher.forceUpdate(function(error) {
+                        if (error) {
+                            console.error('Ошибка установки:', error.error.message);
+                        }
+                        // WebView перезагружается автоматически
+                    });
+                }
+                // Если пользователь нажал "Отмена" - обновление установится
+                // автоматически при следующем запуске приложения
+            });
+        });
+    });
+});
+
+// Вспомогательная функция для получения версии
+function loadCurrentVersion(callback) {
+    cordova.exec(
+        function(info) {
+            callback(info.installedVersion || info.appBundleVersion);
+        },
+        function(error) {
+            console.error('Не удалось получить версию');
+            callback('2.7.7'); // fallback
+        },
+        'HotUpdates',
+        'getVersionInfo',
+        []
+    );
+}
+
+// Вспомогательная функция для проверки обновлений
+function checkServerForUpdates(callback) {
+    fetch('https://api.example.com/updates/check?version=' + currentVersion)
+        .then(r => r.json())
+        .then(callback)
+        .catch(err => console.error('Ошибка проверки обновлений:', err));
+}
+```
+
+---
+
+## ⚠️ Важные особенности
+
+### Автоустановка
+
+Если пользователь **проигнорировал popup** (закрыл приложение), обновление автоматически установится при следующем запуске.
+
+### Откат (Rollback)
+
+Если после обновления приложение крашится или не вызывается `canary()` в течение 20 секунд:
+1. Автоматический откат на предыдущую версию
+2. Сбойная версия добавляется в ignore list
+3. Приложение продолжает работать на старой версии
+
+### Черный список (Ignore List)
+
+- **Не блокирует** установку (вы сами решаете)
+- Служит для **информирования** о проблемных версиях
+- Управляется только native кодом
+- Можно установить версию из списка, если хотите (например, исправленную)
+
+### Формат callback
+
+```javascript
+// ✅ Успех
+callback()           // null или undefined
+callback(null)       // null
+
+// ❌ Ошибка
+callback({
+    error: {
+        message: "текст ошибки"  // может отсутствовать
+    }
+})
+```
+
+---
+
+## 🔗 Дополнительные файлы
+
+- **README.md** - быстрый старт и примеры
+- **hot-updates-admin.html** - тестовый интерфейс для отладки
+- **BUGFIXES_2025-11-04.md** - список исправленных багов
+- **QUICK_REFERENCE.md** - краткая справка
+
+---
+
+**Версия API:** 2.1.0 (Bugfix Update 2025-11-04)