native-update 1.0.0

package/docs/getting-started/quick-start.md

@@ -0,0 +1,379 @@
+# Quick Start Guide
+
+> **⚠️ IMPORTANT: Backend Infrastructure Required**
+>
+> This plugin is a **client-side SDK only** and requires significant backend infrastructure to function:
+>
+> - **Update Server**: You must build and host your own server to manage and serve update bundles
+> - **Bundle Generation**: You need a CI/CD pipeline to create, sign, and deploy update bundles
+> - **Security Infrastructure**: Implement bundle signing, verification, and secure distribution
+> - **Version Management**: Handle versioning, channels, and rollback mechanisms
+> - **Analytics & Monitoring**: Track update success rates and handle failures
+>
+> **This is NOT a complete solution** - it's a foundation that requires substantial additional development. See our [Server Requirements](../server-requirements.md) guide for detailed backend implementation requirements.
+
+Get up and running with Capacitor Native Update in just a few minutes! This guide covers the most common use cases.
+
+## Basic Setup
+
+### 1. Import and Configure
+
+```typescript
+import { CapacitorNativeUpdate } from 'native-update';
+
+// Initialize the plugin with your configuration
+async function initializeUpdates() {
+  await CapacitorNativeUpdate.configure({
+    liveUpdate: {
+      appId: 'com.yourcompany.app',
+      serverUrl: 'https://updates.yourserver.com',
+      channel: 'production',
+      autoUpdate: true,
+      updateStrategy: 'IMMEDIATE',
+    },
+    appUpdate: {
+      checkOnAppStart: true,
+      minimumVersion: '1.0.0',
+    },
+    appReview: {
+      minimumDaysSinceInstall: 7,
+      minimumLaunchCount: 3,
+    },
+  });
+}
+
+// Call this when your app starts
+initializeUpdates();
+```
+
+## Live Updates (OTA)
+
+### Check and Apply Updates Automatically
+
+```typescript
+// Sync with server and apply updates if available
+async function syncUpdates() {
+  try {
+    const result = await CapacitorNativeUpdate.LiveUpdate.sync();
+
+    if (result.status === 'UPDATE_INSTALLED') {
+      console.log('Update installed:', result.bundle.version);
+      // Update will be applied based on your updateStrategy
+    } else if (result.status === 'UP_TO_DATE') {
+      console.log('App is up to date');
+    }
+  } catch (error) {
+    console.error('Sync failed:', error);
+  }
+}
+```
+
+### Manual Update Control
+
+```typescript
+// Check for updates without downloading
+async function checkForUpdates() {
+  const latest = await CapacitorNativeUpdate.LiveUpdate.getLatest();
+  const current = await CapacitorNativeUpdate.LiveUpdate.current();
+
+  if (latest.version !== current.version) {
+    console.log(`Update available: ${latest.version}`);
+    return true;
+  }
+  return false;
+}
+
+// Download and install update manually
+async function downloadAndInstallUpdate() {
+  try {
+    // Download the latest version
+    const bundle = await CapacitorNativeUpdate.LiveUpdate.download({
+      version: 'latest',
+    });
+
+    // Set it as active
+    await CapacitorNativeUpdate.LiveUpdate.set(bundle);
+
+    // Reload the app to apply
+    await CapacitorNativeUpdate.LiveUpdate.reload();
+  } catch (error) {
+    console.error('Update failed:', error);
+  }
+}
+```
+
+### Listen for Download Progress
+
+```typescript
+// Add download progress listener
+const progressListener = await CapacitorNativeUpdate.LiveUpdate.addListener(
+  'downloadProgress',
+  (progress) => {
+    console.log(`Download: ${progress.percent}% complete`);
+    console.log(`${progress.bytesDownloaded} / ${progress.totalBytes} bytes`);
+  }
+);
+
+// Remember to remove listener when done
+// progressListener.remove();
+```
+
+## Native App Updates
+
+### Check for App Store Updates
+
+```typescript
+async function checkAppStoreUpdate() {
+  try {
+    const updateInfo = await CapacitorNativeUpdate.AppUpdate.getAppUpdateInfo();
+
+    if (updateInfo.updateAvailable) {
+      console.log(`New version available: ${updateInfo.availableVersion}`);
+
+      if (updateInfo.updatePriority >= 4) {
+        // High priority - immediate update
+        await CapacitorNativeUpdate.AppUpdate.performImmediateUpdate();
+      } else {
+        // Optional update
+        showUpdateDialog(updateInfo);
+      }
+    }
+  } catch (error) {
+    console.error('App update check failed:', error);
+  }
+}
+
+function showUpdateDialog(updateInfo) {
+  // Show your custom update UI
+  if (userAcceptsUpdate) {
+    CapacitorNativeUpdate.AppUpdate.openAppStore();
+  }
+}
+```
+
+### Flexible Updates (Android)
+
+```typescript
+// Start downloading in background
+async function startFlexibleUpdate() {
+  await CapacitorNativeUpdate.AppUpdate.startFlexibleUpdate();
+
+  // Listen for download completion
+  const listener = await CapacitorNativeUpdate.AppUpdate.addListener(
+    'flexibleUpdateStateChanged',
+    (state) => {
+      if (state.status === 'DOWNLOADED') {
+        // Prompt user to restart
+        showRestartPrompt();
+      }
+    }
+  );
+}
+
+// Complete the update
+async function completeUpdate() {
+  await CapacitorNativeUpdate.AppUpdate.completeFlexibleUpdate();
+  // App will restart with new version
+}
+```
+
+## App Reviews
+
+### Request Review at the Right Time
+
+```typescript
+async function requestReviewIfAppropriate() {
+  try {
+    // Check if we can request a review
+    const canRequest = await CapacitorNativeUpdate.AppReview.canRequestReview();
+
+    if (canRequest.allowed) {
+      // Request the review
+      const result = await CapacitorNativeUpdate.AppReview.requestReview();
+
+      if (result.shown) {
+        console.log('Review dialog was shown');
+      }
+    } else {
+      console.log('Cannot request review:', canRequest.reason);
+    }
+  } catch (error) {
+    console.error('Review request failed:', error);
+  }
+}
+
+// Call after positive user actions
+// e.g., after completing a task, making a purchase, etc.
+requestReviewIfAppropriate();
+```
+
+## Common Patterns
+
+### Initialize on App Start
+
+```typescript
+// In your main app component
+import { App } from '@capacitor/app';
+import { CapacitorNativeUpdate } from 'native-update';
+
+App.addListener('appStateChange', async ({ isActive }) => {
+  if (isActive) {
+    // Check for updates when app becomes active
+    await CapacitorNativeUpdate.LiveUpdate.sync({
+      installMode: 'ON_NEXT_RESUME',
+    });
+  }
+});
+```
+
+### Handle Update Lifecycle
+
+```typescript
+class UpdateManager {
+  async initialize() {
+    // Configure plugin
+    await CapacitorNativeUpdate.configure({
+      liveUpdate: {
+        appId: 'your-app-id',
+        serverUrl: 'https://your-server.com',
+        autoUpdate: true,
+      },
+    });
+
+    // Set up listeners
+    this.setupListeners();
+
+    // Initial sync
+    await this.checkForUpdates();
+  }
+
+  setupListeners() {
+    // Listen for update state changes
+    CapacitorNativeUpdate.LiveUpdate.addListener(
+      'updateStateChanged',
+      (event) => {
+        console.log('Update state:', event.status);
+        this.handleUpdateState(event);
+      }
+    );
+  }
+
+  async checkForUpdates() {
+    try {
+      const result = await CapacitorNativeUpdate.LiveUpdate.sync();
+
+      if (result.status === 'UPDATE_INSTALLED') {
+        // Notify user about update
+        this.notifyUpdateInstalled(result.bundle.version);
+      }
+    } catch (error) {
+      console.error('Update check failed:', error);
+    }
+  }
+
+  handleUpdateState(event) {
+    switch (event.status) {
+      case 'DOWNLOADING':
+        // Show progress indicator
+        break;
+      case 'READY':
+        // Update downloaded, ready to install
+        break;
+      case 'FAILED':
+        // Handle failure
+        break;
+    }
+  }
+}
+```
+
+### Error Handling Best Practices
+
+```typescript
+import { CapacitorNativeUpdateError } from 'capacitor-native-update';
+
+async function safeUpdateCheck() {
+  try {
+    await CapacitorNativeUpdate.LiveUpdate.sync();
+  } catch (error) {
+    if (error instanceof CapacitorNativeUpdateError) {
+      switch (error.code) {
+        case 'NETWORK_ERROR':
+          // Handle network issues
+          console.log('No internet connection');
+          break;
+        case 'SERVER_ERROR':
+          // Server issues
+          console.log('Update server unavailable');
+          break;
+        case 'VERIFICATION_ERROR':
+          // Security validation failed
+          console.log('Update verification failed');
+          break;
+        default:
+          console.error('Update error:', error.message);
+      }
+    }
+  }
+}
+```
+
+## Testing Your Implementation
+
+### Development Tips
+
+1. **Use staging channel for testing**:
+
+   ```typescript
+   await CapacitorNativeUpdate.LiveUpdate.setChannel('staging');
+   ```
+
+2. **Enable debug mode for app reviews**:
+
+   ```typescript
+   await CapacitorNativeUpdate.configure({
+     appReview: {
+       debugMode: true, // Bypass time restrictions
+     },
+   });
+   ```
+
+3. **Force update check**:
+   ```typescript
+   // Clear cache and check
+   await CapacitorNativeUpdate.LiveUpdate.sync({
+     forceCheck: true,
+   });
+   ```
+
+## Next Steps
+
+Now that you have the basics working:
+
+1. Set up your [Update Server](../examples/server-setup.md)
+2. Implement [Security Best Practices](../guides/security-best-practices.md)
+3. Configure [Advanced Options](./configuration.md)
+4. Explore [API Reference](../api/live-update-api.md) for all available methods
+
+## Quick Reference
+
+### Essential Methods
+
+| Method                         | Purpose                         |
+| ------------------------------ | ------------------------------- |
+| `configure()`                  | Initialize plugin with settings |
+| `LiveUpdate.sync()`            | Check and apply updates         |
+| `LiveUpdate.current()`         | Get current bundle info         |
+| `AppUpdate.getAppUpdateInfo()` | Check app store updates         |
+| `AppReview.requestReview()`    | Request user review             |
+
+### Key Events
+
+| Event                | Description              |
+| -------------------- | ------------------------ |
+| `downloadProgress`   | Update download progress |
+| `updateStateChanged` | Bundle state changes     |
+
+---
+
+Made with ❤️ by Ahsan Mahmood

package/docs/guides/deployment-guide.md

@@ -0,0 +1,333 @@
+# Deployment Guide
+
+This guide covers deploying the Capacitor Native Update plugin to production.
+
+## Prerequisites
+
+- Capacitor Native Update plugin configured
+- Update server deployed
+- SSL certificates configured
+- CDN setup (optional but recommended)
+
+## Server Deployment
+
+### 1. Environment Setup
+
+```bash
+# Clone production backend
+cd production-backend
+
+# Install dependencies
+npm install
+
+# Set environment variables
+cp .env.example .env
+# Edit .env with production values
+```
+
+### 2. Database Setup
+
+```bash
+# Initialize production database
+npm run db:init
+
+# For PostgreSQL (recommended for production)
+# Update DB_PATH in .env to PostgreSQL connection string
+```
+
+### 3. Security Configuration
+
+```env
+# .env production settings
+NODE_ENV=production
+JWT_SECRET=<generate-strong-secret>
+ADMIN_PASSWORD=<strong-password>
+
+# Enable HTTPS only
+ALLOWED_ORIGINS=https://your-app.com,capacitor://localhost
+
+# Rate limiting
+RATE_LIMIT_WINDOW=15
+RATE_LIMIT_MAX=100
+```
+
+### 4. Deploy to Cloud
+
+#### Option A: Docker Deployment
+
+```dockerfile
+# Dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+```bash
+# Build and run
+docker build -t update-server .
+docker run -p 3000:3000 update-server
+```
+
+#### Option B: PM2 Deployment
+
+```bash
+# Install PM2
+npm install -g pm2
+
+# Start server
+pm2 start src/index.js --name update-server
+
+# Save PM2 config
+pm2 save
+pm2 startup
+```
+
+## App Configuration
+
+### 1. Production Keys
+
+```typescript
+// Generate RSA keys for production
+const keys = await generateKeyPair();
+// Store private key securely on server
+// Embed public key in app
+```
+
+### 2. Configure Plugin
+
+```typescript
+await CapacitorNativeUpdate.configure({
+  serverUrl: 'https://updates.your-domain.com',
+  publicKey: PRODUCTION_PUBLIC_KEY,
+  channel: 'production',
+  autoCheck: true,
+  checkInterval: 3600000, // 1 hour
+});
+```
+
+## CDN Setup
+
+### 1. CloudFront Configuration
+
+```json
+{
+  "Origins": [{
+    "DomainName": "update-server.your-domain.com",
+    "OriginPath": "/api/bundles"
+  }],
+  "DefaultCacheBehavior": {
+    "TargetOriginId": "update-bundles",
+    "ViewerProtocolPolicy": "https-only",
+    "CachePolicyId": "658327ea-f89e-4fab-a63d-7e88639e58f6"
+  }
+}
+```
+
+### 2. Update Server Config
+
+```javascript
+// Return CDN URLs for bundles
+const cdnUrl = process.env.CDN_URL;
+bundle.downloadUrl = `${cdnUrl}/${bundle.id}`;
+```
+
+## Monitoring Setup
+
+### 1. Application Monitoring
+
+```bash
+# Install monitoring dependencies
+npm install @opentelemetry/api @opentelemetry/sdk-node
+
+# Configure in server
+const { NodeSDK } = require('@opentelemetry/sdk-node');
+const sdk = new NodeSDK();
+sdk.start();
+```
+
+### 2. Health Checks
+
+```bash
+# Monitor endpoints
+curl https://updates.your-domain.com/api/health
+curl https://updates.your-domain.com/api/health/detailed
+```
+
+### 3. Alerts Configuration
+
+```yaml
+# CloudWatch alarms example
+HighErrorRate:
+  MetricName: 4XXError
+  Threshold: 10
+  Period: 300
+
+ServerDown:
+  MetricName: HealthCheck
+  Threshold: 1
+  Period: 60
+```
+
+## Release Process
+
+### 1. Create Update Bundle
+
+```bash
+# Build your app
+npm run build
+
+# Create bundle
+node tools/bundle-creator.js create ./www
+
+# Sign bundle
+node tools/bundle-signer.js sign bundle.zip private-key.pem
+```
+
+### 2. Upload to Server
+
+```bash
+# Create update record
+curl -X POST https://updates.your-domain.com/api/updates/create \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "appId": "com.your.app",
+    "platform": "web",
+    "version": "1.1.0",
+    "channel": "production",
+    "description": "Bug fixes and improvements"
+  }'
+
+# Upload bundle
+curl -X POST https://updates.your-domain.com/api/bundles/upload/$UPDATE_ID \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "bundle=@bundle.zip" \
+  -F "signature=@bundle.sig"
+```
+
+### 3. Gradual Rollout
+
+```bash
+# Start with 10% rollout
+curl -X PUT https://updates.your-domain.com/api/updates/$UPDATE_ID \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"rolloutPercentage": 10}'
+
+# Monitor metrics, then increase
+# 10% -> 25% -> 50% -> 100%
+```
+
+## Security Checklist
+
+- [ ] HTTPS enforced on all endpoints
+- [ ] API authentication configured
+- [ ] Rate limiting enabled
+- [ ] CORS properly configured
+- [ ] Bundle signatures verified
+- [ ] SSL certificates valid
+- [ ] Secrets stored securely
+- [ ] Database backups configured
+- [ ] Access logs enabled
+- [ ] Security headers configured
+
+## Performance Optimization
+
+### 1. Enable Compression
+
+```javascript
+// Already included in production server
+app.use(compression());
+```
+
+### 2. Database Indexing
+
+```sql
+-- Ensure indexes exist
+CREATE INDEX idx_updates_lookup 
+  ON updates(app_id, platform, channel, enabled);
+```
+
+### 3. Bundle Optimization
+
+```bash
+# Compress bundles before upload
+zip -r -9 bundle.zip www/
+
+# Consider differential updates
+# Only include changed files
+```
+
+## Backup Strategy
+
+### 1. Database Backups
+
+```bash
+# Daily backups
+0 2 * * * pg_dump update_db > backup_$(date +\%Y\%m\%d).sql
+
+# Keep 30 days of backups
+find ./backups -name "*.sql" -mtime +30 -delete
+```
+
+### 2. Bundle Storage
+
+```bash
+# Sync bundles to S3
+aws s3 sync ./storage/bundles s3://your-backup-bucket/bundles
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **SSL Certificate Errors**
+   - Verify certificate chain
+   - Check certificate expiration
+   - Ensure proper domain configuration
+
+2. **CORS Issues**
+   - Add app origin to ALLOWED_ORIGINS
+   - Check preflight requests
+
+3. **Download Failures**
+   - Check CDN configuration
+   - Verify bundle permissions
+   - Monitor server logs
+
+### Debug Mode
+
+```typescript
+// Enable debug logging in production
+CapacitorNativeUpdate.configure({
+  debug: process.env.NODE_ENV !== 'production',
+  serverUrl: 'https://updates.your-domain.com',
+});
+```
+
+## Maintenance
+
+### Regular Tasks
+
+- [ ] Weekly: Check server health
+- [ ] Monthly: Review analytics
+- [ ] Monthly: Clean old bundles
+- [ ] Quarterly: Update dependencies
+- [ ] Yearly: Rotate certificates
+
+### Update Server
+
+```bash
+# Update dependencies
+npm update
+
+# Restart server
+pm2 restart update-server
+
+# Check logs
+pm2 logs update-server
+```