native-update 1.2.0 → 1.3.0

package/Readme.md

@@ -1,17 +1,17 @@
 # Capacitor Native Update Plugin
 
 > ⚠️ **IMPORTANT: Production-Ready with Complete Examples** ⚠️
-> 
+>
 > This package is now **feature-complete** with significant improvements:
-> 
-> - ✅ **Production Backend Example Included** - Full server implementation in `production-backend/`
-> - ✅ **Complete Example App** - React + Firebase Functions in `example-app/`
+>
+> - ✅ **pnpm Workspace Monorepo** - Seamless development with workspace:* references
+> - ✅ **3 Complete Examples** - React+Capacitor frontend, Node.js+Express and Firebase backends in `example-apps/`
 > - ✅ **Native Implementations Complete** - iOS (Swift) and Android (Kotlin) fully implemented
 > - ✅ **Comprehensive Test Suite** - Unit and integration tests with Vitest
 > - ✅ **Development Tools Included** - Bundle creator, signer, and CLI tools
 > - ✅ **Security Features Implemented** - HTTPS enforcement, signatures, checksums
-> 
-> **🚀 Try the complete example app in `example-app/` to see all features in action!**
+>
+> **🚀 Try the example apps in `example-apps/` to see all features in action!**
 
 ## 📚 Documentation
 
@@ -288,30 +288,44 @@ This plugin implements multiple security layers:
 - **Checksum validation** before applying updates
 - **Certificate pinning** support for enhanced security
 
-## 🎯 Complete Example Implementation
+## 🎯 Complete Example Implementations
 
-### Full-Featured Example App
+This repository uses **pnpm workspace** for seamless development. All examples reference the local plugin via `workspace:*` - no need to publish to npm for testing!
 
-The **[example-app](./example-app)** directory contains a complete, production-ready implementation:
+### Frontend Example: React + Capacitor
 
-#### Frontend (React + Capacitor)
-- ✅ All plugin features demonstrated
-- ✅ Live update management UI
-- ✅ App store update integration
-- ✅ In-app review prompts
-- ✅ Security implementation
-- ✅ Analytics dashboard
-- ✅ Error handling & recovery
+**[example-apps/react-capacitor](./example-apps/react-capacitor)**
 
-#### Backend (Firebase Functions)
-- ✅ Complete update server
+- ✅ Simple, focused demonstration of OTA updates
+- ✅ Single-page app with "change this text and deploy" example
+- ✅ Capacitor integration (iOS + Android)
+- ✅ TypeScript + Vite for modern development
+- ✅ Uses local plugin via workspace reference
+
+### Backend Examples
+
+#### 1. Node.js + Express Backend
+
+**[example-apps/node-express](./example-apps/node-express)**
+
+- ✅ Production-ready update server
 - ✅ Bundle management API
+- ✅ SQLite database for bundle tracking
 - ✅ Authentication & security
-- ✅ Analytics collection
-- ✅ Firestore + Storage integration
+- ✅ Rate limiting and compression
+- ✅ Signature verification
+
+#### 2. Firebase Functions Backend
+
+**[example-apps/firebase-backend](./example-apps/firebase-backend)**
+
+- ✅ Serverless architecture with Firebase
+- ✅ Cloud Functions for bundle management
+- ✅ Firestore for bundle metadata
+- ✅ Firebase Storage for bundle hosting
 - ✅ Auto-scaling infrastructure
 
-**🚀 Get started:** See [example-app/README.md](./example-app/README.md) for setup instructions.
+**🚀 Get started:** Each example app has its own README with setup instructions.
 
 ## Contributing
 

package/docs/CHANGELOG.md

@@ -0,0 +1,168 @@
+# Changelog
+
+All notable changes to this project 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).
+
+## [1.0.7] - 2025-01-15
+
+### Fixed
+- **Critical Android Build Issues**:
+  - Fixed Google Play app-update library dependencies by using explicit version 2.1.0 instead of variable
+  - Resolved kotlinVersion resolution issues by hardcoding version in gradle plugin
+  - Made all Google Play Services dependencies use explicit versions to prevent resolution errors
+  - Added variables.gradle file for better variable management
+  - Ensured no manual intervention is required by users
+
+### Changed
+- Updated package version to 1.0.7
+- Hardcoded critical dependency versions in Android build.gradle to prevent resolution issues
+
+## [1.0.6] - 2025-01-15
+
+### Fixed
+- **Android Build Issues**:
+  - Fixed Google Play app-update library version error (changed from non-existent 18.2.0 to correct 2.1.0)
+  - Fixed `kotlinVersion` MissingPropertyException by properly defining it in buildscript ext block
+  - Added missing Kotlin stdlib dependency
+  - Reorganized build.gradle structure to ensure proper variable scope
+
+### Documentation Fixes
+- Corrected all API method references to match TypeScript definitions
+- Fixed method signatures and parameters across all documentation
+- Updated event names to match the 4 defined events (downloadProgress, updateStateChanged, backgroundUpdateProgress, backgroundUpdateNotification)
+- Removed references to non-existent methods
+- Fixed broken documentation links
+
+### Android Configuration
+- kotlinVersion: 1.9.22 (stable version)
+- playAppUpdateVersion: 2.1.0 (correct Google Play version)
+- playReviewVersion: 2.0.1
+- All dependencies now use proper version variables
+
+## [1.4.0] - 2025-01-02
+
+### Added
+
+- Complete TypeScript implementation with strict typing
+- Core plugin architecture with modular design
+- Comprehensive error handling system
+- Security validation framework
+- Bundle management system
+- Download manager with retry logic
+- Version management capabilities
+- Configuration manager
+- Logging system with multiple log levels
+- Cache management
+- Background update support
+- Plugin initialization system
+
+### Changed
+
+- Migrated from class-based to functional architecture
+- Improved type definitions and interfaces
+- Enhanced security with input validation
+- Better error messages and error codes
+
+### Fixed
+
+- Removed circular dependencies
+- Fixed TypeScript compilation issues
+- Proper exclusion of test files in tsconfig
+- Removed console.log statements in favor of Logger
+
+## [0.0.2] - 2024-12-01
+
+### Added
+
+- Comprehensive documentation for all features
+- Bundle signing and security utilities
+- CI/CD pipeline with GitHub Actions
+- Example update server implementation
+- TypeScript strict mode
+- ESLint v9 flat config support
+
+### Fixed
+
+- Security vulnerabilities in update process
+- TypeScript compilation errors
+- Path traversal prevention
+
+### Security
+
+- Enforced HTTPS for all update downloads
+- Added RSA signature verification
+- Implemented checksum validation
+- Added certificate pinning support
+
+## [0.0.1] - 2024-01-08
+
+### Added
+
+- Initial release of Capacitor Native Update plugin
+- Live/OTA update functionality
+  - Bundle download and management
+  - Multiple update strategies (immediate, background, manual)
+  - Delta update support
+  - Automatic rollback on failed updates
+  - Update channels (production, staging, development)
+  - End-to-end encryption and signature verification
+  - Bundle integrity checks with SHA-256/512 checksums
+- Native app update functionality
+  - App store version checking
+  - Immediate and flexible update flows (Android)
+  - Direct app store navigation
+  - Version comparison and update priority
+- App review functionality
+  - In-app review prompts using native APIs
+  - Smart triggering with configurable conditions
+  - Rate limiting to respect platform quotas
+- Security features
+  - HTTPS enforcement by default
+  - Certificate pinning support
+  - Public key signature verification
+  - Input validation and sanitization
+  - Secure storage using platform keystores
+- Platform support
+  - iOS implementation using Swift
+  - Android implementation using Kotlin
+  - Web fallback implementation
+- Comprehensive TypeScript definitions
+- Example application demonstrating all features
+- Extensive documentation
+  - API reference
+  - Security guidelines
+  - Migration guide
+  - Feature overview
+
+### Security
+
+- Enforced HTTPS for all update operations by default
+- Required checksum validation for all bundle downloads
+- Implemented path traversal prevention
+- Added secure storage for sensitive configuration
+
+### Known Issues
+
+- ESLint configuration needs update for v9 compatibility
+- Certificate pinning requires manual certificate configuration
+- Delta updates require server-side implementation
+
+## Future Releases
+
+### [0.1.0] - Planned
+
+- Add delta update server reference implementation
+- Improve offline update handling
+- Add update scheduling APIs
+- Enhanced progress reporting with ETA
+- Batch update support
+
+### [0.2.0] - Planned
+
+- Machine learning for optimal update timing
+- Peer-to-peer update distribution
+- Advanced A/B testing framework
+- Custom update UI components
+- Differential compression algorithms

package/docs/EXAMPLE_APPS_SIMPLIFICATION_PLAN.md

@@ -0,0 +1,384 @@
+# Example Apps Simplification Plan
+
+**Created:** 2025-12-27
+**Status:** Planning Phase
+**Goal:** Simplify all example apps to minimal, focused demonstrations of the native-update plugin
+
+---
+
+## 🎯 Objectives
+
+### Primary Goal
+Create **ultra-simple** example apps that demonstrate ONLY the native-update plugin functionality with zero unnecessary complexity.
+
+### Key Principles
+1. **One clear purpose per app** - Show the plugin working, nothing else
+2. **Minimal dependencies** - Only what's absolutely required
+3. **Simple code structure** - Easy to understand and modify
+4. **Clear demonstrations** - "Change this text and deploy" approach
+5. **No side features** - No routing, state management libraries, complex UI components
+
+---
+
+## 📱 App 1: react-capacitor (Frontend Example)
+
+### Current State Analysis
+**Location:** `example-apps/react-capacitor/`
+
+**Current Issues:**
+- May have complex component structure
+- Possibly using advanced React features unnecessarily
+- Multiple pages/routes when we only need one
+- Advanced state management when simple useState would work
+- Complex UI when we just need a demo
+
+### Target State
+
+**Single Page Application:**
+```
+┌────────────────────────────────────┐
+│ Native Update Demo                 │
+│                                    │
+│ Current Version: 1.0.0             │
+│ ┌────────────────────────────┐   │
+│ │ Change This Text and       │   │
+│ │ Deploy to Test OTA Updates │   │
+│ │                            │   │
+│ │ [This text will update     │   │
+│ │  when you deploy a new     │   │
+│ │  version via OTA]          │   │
+│ └────────────────────────────┘   │
+│                                    │
+│ [Check for Updates]                │
+│ [Download Update]                  │
+│ [Apply Update]                     │
+│                                    │
+│ Status: Connected to server        │
+│ Last Check: 2 minutes ago          │
+└────────────────────────────────────┘
+```
+
+**File Structure:**
+```
+react-capacitor/
+├── src/
+│   ├── App.tsx              # Single component, all demo logic
+│   ├── main.tsx             # Entry point
+│   └── native-update.ts     # Plugin integration wrapper
+├── public/
+│   └── index.html
+├── capacitor.config.ts
+├── package.json             # Minimal dependencies
+├── tsconfig.json
+├── vite.config.ts
+└── README.md                # Clear setup instructions
+```
+
+**Dependencies (Minimal):**
+- @capacitor/core, @capacitor/android, @capacitor/ios
+- native-update (workspace:*)
+- react, react-dom
+- vite, @vitejs/plugin-react
+- typescript
+
+**NO:**
+- ❌ React Router
+- ❌ Redux/Zustand/Context (use simple useState)
+- ❌ UI component libraries
+- ❌ Multiple pages
+- ❌ Complex styling (simple CSS only)
+- ❌ Advanced features
+
+**Implementation Steps:**
+
+1. **Analyze current structure** (10 min)
+   - Review current files and complexity
+   - Identify what to keep vs remove
+
+2. **Simplify App.tsx** (30 min)
+   - Single component with all logic
+   - Basic useState for status tracking
+   - Clear button handlers for update operations
+   - Simple inline styles or minimal CSS
+
+3. **Remove unnecessary files** (15 min)
+   - Remove extra components
+   - Remove routing if present
+   - Remove complex state management
+   - Keep only App.tsx and main.tsx
+
+4. **Update package.json** (10 min)
+   - Remove all non-essential dependencies
+   - Keep only core Capacitor, React, Vite, TypeScript
+   - Verify workspace:* reference to native-update
+
+5. **Create simple README** (15 min)
+   - Quick setup (3 steps)
+   - How to test OTA updates
+   - Backend server requirement
+
+6. **Test the app** (20 min)
+   - Verify build works
+   - Test in browser
+   - Test basic plugin calls
+
+**Total Time Estimate:** ~1.5 hours
+
+---
+
+## 🔥 App 2: firebase-backend (Backend Example)
+
+### Current State Analysis
+**Location:** `example-apps/firebase-backend/`
+
+**Current Issues:**
+- May have complex routing structure
+- Multiple features beyond OTA updates
+- Advanced authentication when simple API keys would work
+- Complex database queries
+- Unnecessary middleware
+
+### Target State
+
+**Minimal API Endpoints:**
+```
+POST   /bundles/upload          # Upload new bundle
+GET    /bundles/latest          # Get latest bundle info
+GET    /bundles/:version        # Download specific bundle
+GET    /health                  # Health check
+```
+
+**File Structure:**
+```
+firebase-backend/
+├── src/
+│   ├── index.ts             # Main Cloud Function entry
+│   └── utils/
+│       └── validation.ts    # Basic version validation only
+├── firebase.json
+├── .firebaserc
+├── package.json             # Minimal dependencies
+├── tsconfig.json
+└── README.md                # Setup and deployment guide
+```
+
+**Dependencies (Minimal):**
+- firebase-admin
+- firebase-functions
+- express (for routing)
+- cors (for CORS handling)
+- multer (for file uploads)
+
+**NO:**
+- ❌ Complex authentication (use simple API key check)
+- ❌ Advanced analytics
+- ❌ Multiple routes files
+- ❌ Complex validation beyond version checking
+- ❌ Unnecessary middleware
+
+**Implementation Steps:**
+
+1. **Analyze current structure** (10 min)
+   - Review routes and middleware
+   - Identify essential vs non-essential
+
+2. **Consolidate to index.ts** (45 min)
+   - Move all routes into single file
+   - Simplify authentication (API key check only)
+   - Keep only bundle upload/download endpoints
+   - Basic CORS and error handling
+
+3. **Remove unnecessary files** (15 min)
+   - Remove separate route files
+   - Remove complex middleware
+   - Remove advanced features
+
+4. **Simplify validation** (15 min)
+   - Keep only version number validation
+   - Basic file type checking
+   - Remove complex business logic
+
+5. **Update package.json** (10 min)
+   - Remove unnecessary dependencies
+   - Keep only core Firebase, Express, CORS, Multer
+
+6. **Update README** (20 min)
+   - Firebase setup (project creation)
+   - Deployment steps
+   - API usage examples
+
+7. **Test deployment** (25 min)
+   - Deploy to Firebase
+   - Test endpoints
+   - Verify bundle upload/download
+
+**Total Time Estimate:** ~2 hours
+
+---
+
+## 🚀 App 3: node-express (Backend Example)
+
+### Current State Analysis
+**Location:** `example-apps/node-express/`
+
+**Current Issues:**
+- Production-ready features (too complex for example)
+- Database setup scripts
+- Complex authentication
+- Rate limiting and security features (good but too much)
+- Multiple database options
+
+### Target State
+
+**Minimal API Server:**
+```
+POST   /bundles/upload          # Upload new bundle
+GET    /bundles/latest          # Get latest bundle info
+GET    /bundles/:version        # Download specific bundle
+GET    /health                  # Health check
+```
+
+**File Structure:**
+```
+node-express/
+├── src/
+│   ├── index.js             # Main server file (all routes)
+│   └── bundles/             # Folder to store uploaded bundles
+├── package.json             # Minimal dependencies
+├── .env.example
+└── README.md                # Quick setup guide
+```
+
+**Dependencies (Minimal):**
+- express
+- cors
+- multer (file uploads)
+- dotenv (environment variables)
+
+**NO:**
+- ❌ SQLite/database (use file system storage)
+- ❌ JWT authentication (simple API key)
+- ❌ Rate limiting (remove for simplicity)
+- ❌ Helmet, compression (production features)
+- ❌ Complex logging (console.log is fine)
+- ❌ Database migration scripts
+
+**Implementation Steps:**
+
+1. **Analyze current structure** (10 min)
+   - Review complexity level
+   - Identify production features to remove
+
+2. **Simplify index.js** (60 min)
+   - Single file with all routes
+   - Remove database (use file system)
+   - Simple API key check (if needed)
+   - Basic CORS
+   - Store bundles as files in /bundles folder
+
+3. **Remove unnecessary files** (20 min)
+   - Remove database setup scripts
+   - Remove separate route files
+   - Remove middleware files
+   - Remove complex logging
+
+4. **Update package.json** (10 min)
+   - Remove all production dependencies
+   - Keep only: express, cors, multer, dotenv
+
+5. **Create simple storage** (15 min)
+   - File system based bundle storage
+   - JSON file for bundle metadata
+   - Simple version tracking
+
+6. **Update README** (20 min)
+   - Quick start (3 commands)
+   - API examples
+   - Testing instructions
+
+7. **Test the server** (20 min)
+   - Start server
+   - Test all endpoints
+   - Verify file uploads
+
+**Total Time Estimate:** ~2.5 hours
+
+---
+
+## 📋 Success Criteria
+
+### For Each Example App
+
+✅ **Simplicity**
+- Single file for main logic (or max 2-3 files)
+- No unnecessary abstractions
+- Easy to read and understand in 5 minutes
+
+✅ **Functionality**
+- Demonstrates plugin working correctly
+- Clear "change and deploy" workflow
+- All basic operations functional
+
+✅ **Documentation**
+- README with quick start (< 5 steps)
+- Clear API examples
+- Troubleshooting section
+
+✅ **Dependencies**
+- Minimal package.json
+- Only essential dependencies
+- No bloat
+
+✅ **Testing**
+- Build succeeds
+- Basic functionality verified
+- Integration with plugin confirmed
+
+---
+
+## 🔄 Execution Order
+
+1. **react-capacitor** (Frontend) - 1.5 hours
+   - Most visible to users
+   - Sets the tone for simplicity
+
+2. **node-express** (Backend) - 2.5 hours
+   - Simpler than Firebase
+   - Good for quick local testing
+
+3. **firebase-backend** (Backend) - 2 hours
+   - More complex due to Firebase setup
+   - Alternative for users preferring serverless
+
+**Total Estimated Time:** 6 hours
+
+---
+
+## 📊 Risk Assessment
+
+### Potential Issues
+
+1. **Breaking existing functionality**
+   - **Mitigation:** Test each simplification step
+   - **Rollback plan:** Git commits for each major change
+
+2. **Over-simplification**
+   - **Mitigation:** Ensure core plugin features still demonstrated
+   - **Balance:** Simple but functional
+
+3. **Documentation gaps**
+   - **Mitigation:** Create README before simplifying code
+   - **Verification:** Test setup from README
+
+---
+
+## 📝 Notes
+
+- Keep this plan updated as we discover complexity during execution
+- Track actual time vs estimated time
+- Document any deviations from plan
+- User requested "as simple as possible, no side bullshit" - this is our north star
+
+---
+
+**Next Step:** Create tracking document and begin execution with react-capacitor