native-update 1.0.0

package/docs/examples/advanced-scenarios.md

@@ -0,0 +1,410 @@
+# Advanced Scenarios
+
+This guide covers complex use cases and advanced patterns for the Capacitor Native Update plugin.
+
+## Delta Updates
+
+Minimize download sizes by only downloading changed files:
+
+```typescript
+import { CapacitorNativeUpdate } from 'capacitor-native-update';
+
+async function checkForDeltaUpdate() {
+  const currentManifest = await CapacitorNativeUpdate.getCurrentManifest();
+  
+  const result = await CapacitorNativeUpdate.checkForUpdate({
+    updateUrl: 'https://your-update-server.com/api/check',
+    currentVersion: currentManifest.version,
+    currentChecksum: currentManifest.checksum,
+    supportsDelta: true
+  });
+  
+  if (result.updateAvailable && result.deltaAvailable) {
+    console.log(`Delta update available: ${result.deltaSize} bytes`);
+    await downloadDeltaUpdate(result.deltaUrl);
+  }
+}
+
+async function downloadDeltaUpdate(deltaUrl: string) {
+  const download = await CapacitorNativeUpdate.downloadUpdate({
+    url: deltaUrl,
+    isDelta: true
+  });
+  
+  // Apply delta patch
+  await CapacitorNativeUpdate.applyDelta({
+    bundleId: download.bundleId,
+    baseVersion: getCurrentVersion()
+  });
+}
+```
+
+## Update Channels
+
+Manage different release tracks:
+
+```typescript
+// Configure update channels
+enum UpdateChannel {
+  PRODUCTION = 'production',
+  BETA = 'beta',
+  DEVELOPMENT = 'development'
+}
+
+async function setupUpdateChannel(channel: UpdateChannel) {
+  await CapacitorNativeUpdate.configure({
+    updateChannel: channel,
+    updateUrl: `https://updates.example.com/api/${channel}/check`
+  });
+}
+
+// Switch channels based on user preference
+async function switchToBetaChannel() {
+  await setupUpdateChannel(UpdateChannel.BETA);
+  
+  // Check for updates in the new channel
+  const result = await CapacitorNativeUpdate.checkForUpdate({
+    currentVersion: await getCurrentVersion()
+  });
+  
+  if (result.updateAvailable) {
+    console.log(`Beta update ${result.version} available`);
+  }
+}
+```
+
+## Staged Rollouts
+
+Implement gradual update deployment:
+
+```typescript
+async function checkStagedUpdate() {
+  const deviceId = await getDeviceId();
+  const rolloutPercentage = hashDeviceId(deviceId) % 100;
+  
+  const result = await CapacitorNativeUpdate.checkForUpdate({
+    updateUrl: 'https://your-update-server.com/api/check',
+    currentVersion: '1.0.0',
+    metadata: {
+      deviceId,
+      rolloutGroup: rolloutPercentage
+    }
+  });
+  
+  if (result.updateAvailable && result.rolloutPercentage >= rolloutPercentage) {
+    // Device is eligible for update
+    await downloadAndInstall(result);
+  }
+}
+```
+
+## Background Updates
+
+Download updates in the background without interrupting users:
+
+```typescript
+async function setupBackgroundUpdates() {
+  // Configure background update behavior
+  await CapacitorNativeUpdate.configure({
+    backgroundUpdateMode: 'wifi-only',
+    autoInstallMode: 'on-restart'
+  });
+  
+  // Schedule background update checks
+  await CapacitorNativeUpdate.scheduleBackgroundCheck({
+    interval: 14400000, // 4 hours
+    requiresWifi: true,
+    requiresCharging: false
+  });
+}
+
+// Handle background update events
+CapacitorNativeUpdate.addListener('backgroundUpdateReady', (event) => {
+  // Notify user that update is ready
+  showUpdateNotification({
+    version: event.version,
+    releaseNotes: event.releaseNotes
+  });
+});
+```
+
+## Rollback Strategies
+
+Implement automatic rollback on update failures:
+
+```typescript
+async function safeUpdate() {
+  // Save current version info before update
+  const backup = await CapacitorNativeUpdate.createBackup();
+  
+  try {
+    // Attempt update
+    await CapacitorNativeUpdate.installUpdate({
+      bundleId: 'new-update-id',
+      validateAfterInstall: true
+    });
+    
+    // Verify update success
+    const health = await performHealthCheck();
+    if (!health.passed) {
+      throw new Error('Health check failed');
+    }
+    
+    // Confirm successful update
+    await CapacitorNativeUpdate.confirmUpdate();
+  } catch (error) {
+    console.error('Update failed, rolling back:', error);
+    
+    // Automatic rollback
+    await CapacitorNativeUpdate.rollback({
+      backupId: backup.id
+    });
+    
+    // Report failure to analytics
+    reportUpdateFailure(error);
+  }
+}
+
+async function performHealthCheck(): Promise<{ passed: boolean }> {
+  // Custom health check logic
+  try {
+    // Test critical functionality
+    await testApiConnection();
+    await testDatabaseAccess();
+    await testUIComponents();
+    
+    return { passed: true };
+  } catch {
+    return { passed: false };
+  }
+}
+```
+
+## Multi-Bundle Management
+
+Handle multiple update bundles for A/B testing:
+
+```typescript
+interface ABTestConfig {
+  testId: string;
+  variants: {
+    control: string;
+    treatment: string;
+  };
+}
+
+async function setupABTest(config: ABTestConfig) {
+  const variant = await determineVariant(config.testId);
+  
+  // Download appropriate bundle
+  const bundleUrl = variant === 'treatment' 
+    ? config.variants.treatment 
+    : config.variants.control;
+    
+  const download = await CapacitorNativeUpdate.downloadUpdate({
+    url: bundleUrl,
+    metadata: {
+      testId: config.testId,
+      variant
+    }
+  });
+  
+  // Install with test metadata
+  await CapacitorNativeUpdate.installUpdate({
+    bundleId: download.bundleId,
+    preserveData: true
+  });
+}
+```
+
+## Custom Update UI
+
+Create sophisticated update experiences:
+
+```typescript
+class UpdateManager {
+  private updateState: UpdateState = { status: 'idle' };
+  
+  async checkAndPromptUpdate() {
+    // Check for update
+    const result = await CapacitorNativeUpdate.checkForUpdate({
+      updateUrl: 'https://your-update-server.com/api/check',
+      currentVersion: await this.getCurrentVersion()
+    });
+    
+    if (!result.updateAvailable) return;
+    
+    // Show custom update dialog
+    const userChoice = await this.showUpdateDialog({
+      version: result.version,
+      releaseNotes: result.releaseNotes,
+      size: result.size,
+      criticalUpdate: result.priority === 'critical'
+    });
+    
+    if (userChoice === 'update') {
+      await this.performUpdate(result);
+    } else if (userChoice === 'remind') {
+      await this.scheduleReminder();
+    }
+  }
+  
+  private async performUpdate(updateInfo: UpdateInfo) {
+    this.updateState = { status: 'downloading', progress: 0 };
+    
+    // Download with progress tracking
+    const downloadListener = CapacitorNativeUpdate.addListener(
+      'downloadProgress',
+      (progress) => {
+        this.updateState = {
+          status: 'downloading',
+          progress: progress.percent
+        };
+        this.updateUI();
+      }
+    );
+    
+    try {
+      const download = await CapacitorNativeUpdate.downloadUpdate({
+        url: updateInfo.downloadUrl
+      });
+      
+      this.updateState = { status: 'installing' };
+      this.updateUI();
+      
+      await CapacitorNativeUpdate.installUpdate({
+        bundleId: download.bundleId
+      });
+      
+      this.updateState = { status: 'ready' };
+      await this.promptRestart();
+    } finally {
+      downloadListener.remove();
+    }
+  }
+}
+```
+
+## Security-Enhanced Updates
+
+Implement advanced security measures:
+
+```typescript
+async function secureUpdateCheck() {
+  // Generate request signature
+  const timestamp = Date.now();
+  const nonce = generateNonce();
+  const signature = await signRequest({
+    timestamp,
+    nonce,
+    version: getCurrentVersion()
+  });
+  
+  const result = await CapacitorNativeUpdate.checkForUpdate({
+    updateUrl: 'https://your-update-server.com/api/check',
+    currentVersion: getCurrentVersion(),
+    headers: {
+      'X-Timestamp': timestamp.toString(),
+      'X-Nonce': nonce,
+      'X-Signature': signature
+    },
+    certificatePins: [
+      'sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA='
+    ]
+  });
+  
+  // Verify response signature
+  if (!await verifyUpdateSignature(result)) {
+    throw new Error('Invalid update signature');
+  }
+  
+  return result;
+}
+
+async function downloadWithIntegrityCheck(url: string, expectedHash: string) {
+  const download = await CapacitorNativeUpdate.downloadUpdate({
+    url,
+    validateChecksum: true,
+    expectedChecksum: expectedHash,
+    algorithm: 'sha256'
+  });
+  
+  // Additional verification
+  const verified = await CapacitorNativeUpdate.verifyBundle({
+    bundleId: download.bundleId,
+    publicKey: await getPublicKey()
+  });
+  
+  if (!verified.valid) {
+    throw new Error('Bundle verification failed');
+  }
+  
+  return download;
+}
+```
+
+## Performance Monitoring
+
+Track update performance and success rates:
+
+```typescript
+class UpdateMetrics {
+  async trackUpdateCycle() {
+    const startTime = Date.now();
+    const metrics: UpdateMetrics = {
+      checkStarted: startTime,
+      downloadStarted: 0,
+      downloadCompleted: 0,
+      installStarted: 0,
+      installCompleted: 0,
+      errors: []
+    };
+    
+    try {
+      // Check phase
+      const result = await CapacitorNativeUpdate.checkForUpdate({
+        updateUrl: 'https://your-update-server.com/api/check',
+        currentVersion: getCurrentVersion()
+      });
+      
+      if (!result.updateAvailable) {
+        metrics.checkCompleted = Date.now();
+        await this.reportMetrics(metrics);
+        return;
+      }
+      
+      // Download phase
+      metrics.downloadStarted = Date.now();
+      const download = await CapacitorNativeUpdate.downloadUpdate({
+        url: result.downloadUrl
+      });
+      metrics.downloadCompleted = Date.now();
+      metrics.downloadSize = download.size;
+      
+      // Install phase
+      metrics.installStarted = Date.now();
+      await CapacitorNativeUpdate.installUpdate({
+        bundleId: download.bundleId
+      });
+      metrics.installCompleted = Date.now();
+      
+      metrics.success = true;
+    } catch (error) {
+      metrics.errors.push({
+        phase: this.getCurrentPhase(metrics),
+        error: error.message,
+        timestamp: Date.now()
+      });
+      metrics.success = false;
+    }
+    
+    await this.reportMetrics(metrics);
+  }
+}
+```
+
+## Next Steps
+
+- Review [Integration Examples](./integration-examples.md) for framework-specific implementations
+- See the [API Reference](../api/README.md) for detailed method documentation
+- Check [Basic Usage](./basic-usage.md) for simpler examples

package/docs/examples/basic-usage.md

@@ -0,0 +1,185 @@
+# Basic Usage Examples
+
+This guide demonstrates basic usage patterns for the Capacitor Native Update plugin.
+
+## Installation
+
+```bash
+yarn add capacitor-native-update
+npx cap sync
+```
+
+## Simple Live Update Check
+
+```typescript
+import { CapacitorNativeUpdate } from 'capacitor-native-update';
+
+// Check for updates on app startup
+async function checkForUpdates() {
+  try {
+    const result = await CapacitorNativeUpdate.checkForUpdate({
+      updateUrl: 'https://your-update-server.com/api/check',
+      currentVersion: '1.0.0'
+    });
+    
+    if (result.updateAvailable) {
+      console.log(`Update available: ${result.version}`);
+      // Download and install the update
+      await downloadAndInstall(result.downloadUrl);
+    }
+  } catch (error) {
+    console.error('Update check failed:', error);
+  }
+}
+
+async function downloadAndInstall(downloadUrl: string) {
+  // Download the update
+  const download = await CapacitorNativeUpdate.downloadUpdate({
+    url: downloadUrl
+  });
+  
+  // Monitor download progress
+  CapacitorNativeUpdate.addListener('downloadProgress', (progress) => {
+    console.log(`Download progress: ${progress.percent}%`);
+  });
+  
+  // Install the update
+  await CapacitorNativeUpdate.installUpdate({
+    bundleId: download.bundleId
+  });
+  
+  // Reload the app with new bundle
+  await CapacitorNativeUpdate.reloadApp();
+}
+```
+
+## Basic App Store Update Check
+
+```typescript
+// Check if a native app update is available
+async function checkAppStoreUpdate() {
+  const result = await CapacitorNativeUpdate.checkAppUpdate();
+  
+  if (result.updateAvailable) {
+    // Show update prompt to user
+    const shouldUpdate = confirm(
+      `Version ${result.availableVersion} is available. Update now?`
+    );
+    
+    if (shouldUpdate) {
+      // Open app store for update
+      await CapacitorNativeUpdate.openAppStore();
+    }
+  }
+}
+```
+
+## Simple App Review Request
+
+```typescript
+// Request app review after positive user action
+async function requestReview() {
+  try {
+    const result = await CapacitorNativeUpdate.requestReview();
+    
+    if (result.displayed) {
+      console.log('Review dialog was shown');
+      // Track that review was requested
+    }
+  } catch (error) {
+    console.error('Could not request review:', error);
+  }
+}
+
+// Example: Request review after successful task completion
+async function onTaskCompleted() {
+  // Your task logic here
+  
+  // Check if it's a good time to ask for review
+  const completedTasks = getCompletedTaskCount();
+  if (completedTasks === 5) {
+    await requestReview();
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+// Initialize with custom configuration
+CapacitorNativeUpdate.configure({
+  // Live update settings
+  autoCheckOnStart: true,
+  updateCheckInterval: 3600000, // 1 hour
+  updateChannel: 'production',
+  
+  // Security settings
+  enableSignatureVerification: true,
+  publicKey: 'your-public-key',
+  
+  // App review settings
+  minimumDaysSinceInstall: 3,
+  minimumDaysSinceLastPrompt: 30
+});
+```
+
+## Error Handling
+
+```typescript
+// Comprehensive error handling
+async function safeUpdateCheck() {
+  try {
+    const result = await CapacitorNativeUpdate.checkForUpdate({
+      updateUrl: 'https://your-update-server.com/api/check',
+      currentVersion: '1.0.0'
+    });
+    
+    if (result.updateAvailable) {
+      await handleUpdate(result);
+    }
+  } catch (error) {
+    if (error.code === 'NETWORK_ERROR') {
+      console.log('No internet connection');
+    } else if (error.code === 'INVALID_RESPONSE') {
+      console.error('Invalid server response');
+    } else {
+      console.error('Unexpected error:', error);
+    }
+  }
+}
+```
+
+## Event Listeners
+
+```typescript
+// Set up event listeners
+function setupUpdateListeners() {
+  // Download progress
+  CapacitorNativeUpdate.addListener('downloadProgress', (event) => {
+    updateProgressBar(event.percent);
+  });
+  
+  // Update installed
+  CapacitorNativeUpdate.addListener('updateInstalled', (event) => {
+    console.log(`Update ${event.version} installed successfully`);
+  });
+  
+  // Update failed
+  CapacitorNativeUpdate.addListener('updateFailed', (event) => {
+    console.error(`Update failed: ${event.error}`);
+    // Optionally rollback
+    CapacitorNativeUpdate.rollback();
+  });
+}
+
+// Clean up listeners when done
+function cleanup() {
+  CapacitorNativeUpdate.removeAllListeners();
+}
+```
+
+## Next Steps
+
+- See [Advanced Scenarios](./advanced-scenarios.md) for more complex use cases
+- Check [Integration Examples](./integration-examples.md) for framework-specific implementations
+- Read the [API Reference](../api/README.md) for complete method documentation