native-update 1.0.0

package/docs/REMAINING_FEATURES.md

@@ -0,0 +1,139 @@
+# Remaining Features for Production Readiness
+
+This document tracks all remaining work needed to make this package fully production-ready.
+
+## ✅ Recently Completed
+
+### Testing & Tools
+- [x] Basic test structure with Vitest
+- [x] Bundle creation utility (`tools/bundle-creator.js`)
+- [x] Bundle signing tool (`tools/bundle-signer.js`)
+- [x] Minimal backend server template
+
+## 🔴 Critical Missing Components
+
+### 1. Backend Infrastructure
+- [ ] Production-grade update server
+- [ ] Database integration (PostgreSQL/MongoDB)
+- [ ] CDN integration for bundle distribution
+- [ ] API authentication and rate limiting
+- [ ] Admin dashboard for managing updates
+- [ ] Monitoring and analytics
+
+### 2. Native Platform Implementation
+- [ ] Complete iOS implementation verification
+- [ ] Complete Android implementation verification
+- [ ] Platform-specific error handling
+- [ ] Background update services
+- [ ] Native UI components for updates
+- [ ] App store integration testing
+
+### 3. Testing Suite
+- [ ] Complete unit tests for TypeScript code
+- [ ] Unit tests for iOS native code
+- [ ] Unit tests for Android native code
+- [ ] Integration tests across platforms
+- [ ] E2E testing scenarios
+- [ ] Security vulnerability testing
+- [ ] Performance benchmarking
+
+### 4. Security Implementation
+- [ ] Client-side signature verification
+- [ ] Certificate pinning
+- [ ] Encryption for sensitive data
+- [ ] Secure key storage on device
+- [ ] Anti-tampering measures
+
+### 5. Developer Tools
+- [ ] Complete CLI package
+- [ ] Version management system
+- [ ] Migration scripts
+- [ ] Debug utilities
+- [ ] Production deployment tools
+
+## 🟡 Enhancement Features
+
+### 1. Advanced Update Features
+- [ ] Delta updates implementation
+- [ ] Partial bundle updates
+- [ ] Update rollback mechanism
+- [ ] A/B testing support
+- [ ] Staged rollouts
+- [ ] Update scheduling
+
+### 2. Monitoring & Analytics
+- [ ] Update success tracking
+- [ ] Error reporting system
+- [ ] Performance metrics
+- [ ] User adoption tracking
+- [ ] Crash reporting integration
+- [ ] Update analytics dashboard
+
+### 3. Developer Experience
+- [ ] Comprehensive error messages
+- [ ] Better TypeScript types
+- [ ] Framework-specific adapters
+- [ ] Plugin hooks system
+- [ ] Event system improvements
+- [ ] Debug mode enhancements
+
+## 🟢 Documentation & Examples
+
+### 1. Missing Documentation
+- [ ] Complete API reference
+- [ ] Platform-specific guides
+- [ ] Troubleshooting guide
+- [ ] Performance optimization guide
+- [ ] Security implementation guide
+- [ ] Migration from v1 guide
+
+### 2. Example Implementations
+- [ ] React example app
+- [ ] Vue example app
+- [ ] Angular example app
+- [ ] Backend server examples (Node, Python, Java)
+- [ ] CI/CD integration examples
+- [ ] Production deployment guide
+
+### 3. Video Tutorials
+- [ ] Getting started video
+- [ ] Backend setup tutorial
+- [ ] Security implementation
+- [ ] Production deployment
+- [ ] Troubleshooting common issues
+
+## 📊 Implementation Priority
+
+### Phase 1: Core Functionality (2-3 months)
+1. Complete native implementations
+2. Basic backend server
+3. Essential testing
+4. Security basics
+
+### Phase 2: Production Features (1-2 months)
+1. Advanced update features
+2. Monitoring system
+3. Developer tools
+4. Performance optimization
+
+### Phase 3: Polish & Scale (1-2 months)
+1. Complete documentation
+2. Example apps
+3. Enterprise features
+4. Community tools
+
+## 🎯 Next Steps
+
+1. **Verify Native Code**: Test iOS and Android implementations
+2. **Build Minimal Backend**: Create basic update server
+3. **Add Core Tests**: Unit tests for critical paths
+4. **Implement Security**: Basic signing and verification
+5. **Create CLI Tools**: Bundle creation and management
+
+## 📝 Notes
+
+- Each item should be completed with tests
+- Documentation should be updated as features are added
+- Security should be considered in every component
+- Performance impact should be measured
+- Backward compatibility must be maintained

package/docs/api/app-review-api.md

@@ -0,0 +1,259 @@
+# App Review API Reference
+
+Complete API documentation for in-app review functionality.
+
+## Methods
+
+### requestReview(options?)
+
+Request an in-app review dialog.
+
+```typescript
+const result = await CapacitorNativeUpdate.requestReview({
+  force?: boolean;  // Bypass rate limiting (testing only)
+});
+// Returns:
+{
+  displayed: boolean;         // Was review dialog shown?
+  reason?: string;           // Why not displayed
+  platform: string;          // Platform used
+  lastRequestDate?: number;  // Last request timestamp
+  requestCount?: number;     // Total request count
+}
+```
+
+### canRequestReview()
+
+Check if a review can be requested (respects rate limits).
+
+```typescript
+const result = await CapacitorNativeUpdate.canRequestReview();
+// Returns:
+{
+  canRequest: boolean;
+  reason?: string;           // Why not available
+  lastRequestDate?: number;  // Last request timestamp
+  requestCount?: number;     // Times requested
+  daysUntilNext?: number;   // Days until can request
+}
+```
+
+### openStoreReview()
+
+Open the app store review page directly.
+
+```typescript
+await CapacitorNativeUpdate.openStoreReview();
+// Opens app store with review section focused
+```
+
+### getStoreReviewUrl()
+
+Get the store review URL without opening it.
+
+```typescript
+const result = await CapacitorNativeUpdate.getStoreReviewUrl();
+// Returns:
+{
+  url: string;  // Direct review URL
+  platform: 'ios' | 'android' | 'web';
+}
+```
+
+### resetReviewPrompts()
+
+Reset review request history (testing only).
+
+```typescript
+await CapacitorNativeUpdate.resetReviewPrompts();
+```
+
+### setReviewConditions(conditions)
+
+Set conditions for when to show review prompts.
+
+```typescript
+await CapacitorNativeUpdate.setReviewConditions({
+  minimumDaysSinceInstall?: number;    // Default: 3
+  minimumDaysSinceLastPrompt?: number; // Default: 90
+  minimumAppLaunches?: number;         // Default: 5
+  minimumSignificantEvents?: number;   // Default: 3
+});
+```
+
+### trackSignificantEvent(eventName)
+
+Track significant events for review timing.
+
+```typescript
+await CapacitorNativeUpdate.trackSignificantEvent(eventName: string);
+// Examples: 'purchase_completed', 'level_completed', 'content_shared'
+```
+
+## Events
+
+### reviewPromptDisplayed
+
+Fired when review prompt is shown.
+
+```typescript
+CapacitorNativeUpdate.addListener('reviewPromptDisplayed', (event) => {
+  console.log('Review prompt shown on:', event.platform);
+  analytics.track('review_prompt_displayed');
+});
+```
+
+### reviewPromptDismissed
+
+Fired when review prompt is dismissed.
+
+```typescript
+CapacitorNativeUpdate.addListener('reviewPromptDismissed', (event) => {
+  console.log('Review prompt dismissed');
+  analytics.track('review_prompt_dismissed');
+});
+```
+
+## Platform Implementation
+
+### iOS (StoreKit)
+
+- Uses `SKStoreReviewController.requestReview()`
+- Limited to 3 prompts per 365-day period
+- No callback for user action
+- Shows native iOS review dialog
+- Requires iOS 10.3+
+
+### Android (Google Play)
+
+- Uses Play Core In-App Review API
+- No specific rate limits documented
+- Shows native Play Store review flow
+- Requires Play Core Library
+- Android 5.0+ (API 21+)
+
+### Web
+
+- Shows custom review prompt
+- Redirects to review URL
+- No rate limiting
+- Customizable UI
+
+## Best Practices
+
+### 1. Time Review Requests Appropriately
+
+```typescript
+// After positive interaction
+async function onPurchaseComplete() {
+  await processPayment();
+  await showThankYouMessage();
+  
+  // Wait a bit, then request review
+  setTimeout(async () => {
+    const { canRequest } = await CapacitorNativeUpdate.canRequestReview();
+    if (canRequest) {
+      await CapacitorNativeUpdate.requestReview();
+    }
+  }, 2000);
+}
+```
+
+### 2. Track Significant Events
+
+```typescript
+// Define what counts as significant
+const SIGNIFICANT_EVENTS = [
+  'tutorial_completed',
+  'first_purchase',
+  'level_10_reached',
+  'friend_invited',
+  'content_created'
+];
+
+async function trackUserAction(action: string) {
+  if (SIGNIFICANT_EVENTS.includes(action)) {
+    await CapacitorNativeUpdate.trackSignificantEvent(action);
+  }
+}
+```
+
+### 3. Implement Smart Conditions
+
+```typescript
+// Configure smart conditions
+await CapacitorNativeUpdate.setReviewConditions({
+  minimumDaysSinceInstall: 7,      // Week after install
+  minimumDaysSinceLastPrompt: 120, // 4 months between
+  minimumAppLaunches: 10,           // Regular user
+  minimumSignificantEvents: 5       // Engaged user
+});
+```
+
+### 4. Fallback Strategy
+
+```typescript
+async function requestReviewSmart() {
+  try {
+    const { displayed } = await CapacitorNativeUpdate.requestReview();
+    
+    if (!displayed) {
+      // Fallback: Show custom UI with store link
+      const response = await showCustomReviewDialog();
+      if (response === 'yes') {
+        await CapacitorNativeUpdate.openStoreReview();
+      }
+    }
+  } catch (error) {
+    console.error('Review request failed:', error);
+  }
+}
+```
+
+## Rate Limiting
+
+### iOS Limits
+- Maximum 3 prompts per 365 days
+- No prompt if user has already rated
+- System decides when to show
+
+### Android Guidelines
+- No hard limits specified
+- Don't prompt during onboarding
+- Don't prompt after errors
+- Respect user choice
+
+### Custom Implementation
+```typescript
+class ReviewManager {
+  private readonly MAX_REQUESTS_PER_YEAR = 3;
+  private readonly DAYS_BETWEEN_PROMPTS = 120;
+  
+  async canRequestReview(): Promise<boolean> {
+    const history = await this.getRequestHistory();
+    const now = Date.now();
+    const oneYearAgo = now - (365 * 24 * 60 * 60 * 1000);
+    
+    const recentRequests = history.filter(date => date > oneYearAgo);
+    
+    if (recentRequests.length >= this.MAX_REQUESTS_PER_YEAR) {
+      return false;
+    }
+    
+    const lastRequest = Math.max(...history);
+    const daysSinceLastRequest = (now - lastRequest) / (24 * 60 * 60 * 1000);
+    
+    return daysSinceLastRequest >= this.DAYS_BETWEEN_PROMPTS;
+  }
+}
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| `RATE_LIMITED` | Too many recent requests |
+| `CONDITIONS_NOT_MET` | Review conditions not satisfied |
+| `PLATFORM_NOT_SUPPORTED` | Feature not available on platform |
+| `USER_CANCELLED` | User dismissed the prompt |
+| `ALREADY_RATED` | User has already rated the app |

package/docs/api/app-update-api.md

@@ -0,0 +1,238 @@
+# App Update API Reference
+
+Complete API documentation for native app store update functionality.
+
+## Methods
+
+### checkAppUpdate()
+
+Check if a native app update is available in the app store.
+
+```typescript
+const result = await CapacitorNativeUpdate.checkAppUpdate();
+// Returns:
+{
+  updateAvailable: boolean;
+  currentVersion: string;
+  availableVersion?: string;
+  updatePriority?: 'LOW' | 'MEDIUM' | 'HIGH' | 'IMMEDIATE';
+  releaseNotes?: string;
+  updateSize?: number;
+  
+  // Android specific
+  immediateUpdateAllowed?: boolean;
+  flexibleUpdateAllowed?: boolean;
+  clientVersionStalenessDays?: number;
+  
+  // iOS specific
+  updateURL?: string;
+}
+```
+
+### startImmediateUpdate()
+
+Start an immediate (blocking) update. Android only - shows full-screen update UI.
+
+```typescript
+try {
+  await CapacitorNativeUpdate.startImmediateUpdate();
+  // App will restart after update
+} catch (error) {
+  // User cancelled or update failed
+}
+```
+
+### startFlexibleUpdate()
+
+Start a flexible (background) update. Android only - downloads in background.
+
+```typescript
+await CapacitorNativeUpdate.startFlexibleUpdate();
+// Monitor progress with appUpdateProgress event
+```
+
+### completeFlexibleUpdate()
+
+Complete a flexible update installation. Android only.
+
+```typescript
+await CapacitorNativeUpdate.completeFlexibleUpdate();
+// App will restart
+```
+
+### getVersionInfo()
+
+Get detailed version information.
+
+```typescript
+const info = await CapacitorNativeUpdate.getVersionInfo();
+// Returns:
+{
+  currentVersion: string;      // e.g., "1.2.3"
+  buildNumber: string;         // e.g., "123"
+  packageName: string;         // e.g., "com.example.app"
+  platform: 'ios' | 'android' | 'web';
+  availableVersion?: string;   // From app store
+  minimumVersion?: string;     // Minimum required version
+}
+```
+
+### isMinimumVersionMet()
+
+Check if the app meets minimum version requirements.
+
+```typescript
+const result = await CapacitorNativeUpdate.isMinimumVersionMet();
+// Returns:
+{
+  isMet: boolean;
+  currentVersion: string;
+  minimumVersion: string;
+  updateRequired: boolean;
+}
+```
+
+### openAppStore()
+
+Open the app store page for updates.
+
+```typescript
+await CapacitorNativeUpdate.openAppStore();
+```
+
+### getAppStoreUrl()
+
+Get the app store URL without opening it.
+
+```typescript
+const result = await CapacitorNativeUpdate.getAppStoreUrl();
+// Returns:
+{
+  url: string;  // e.g., "https://apps.apple.com/app/id123456789"
+  platform: 'ios' | 'android' | 'web';
+}
+```
+
+### getUpdateInstallState()
+
+Get the current install state of a flexible update. Android only.
+
+```typescript
+const state = await CapacitorNativeUpdate.getUpdateInstallState();
+// Returns:
+{
+  installStatus: number;    // Android InstallStatus code
+  bytesDownloaded: number;
+  totalBytesToDownload: number;
+  percentComplete: number;
+}
+```
+
+## Events
+
+### appUpdateStateChanged
+
+Fired when app update state changes. Android only.
+
+```typescript
+CapacitorNativeUpdate.addListener('appUpdateStateChanged', (state) => {
+  console.log('Install status:', state.installStatus);
+  // InstallStatus codes:
+  // 0: Unknown
+  // 1: Pending
+  // 2: Downloading
+  // 3: Installing
+  // 4: Installed
+  // 5: Failed
+  // 6: Canceled
+  // 11: Downloaded
+});
+```
+
+### appUpdateProgress
+
+Fired during flexible update download. Android only.
+
+```typescript
+CapacitorNativeUpdate.addListener('appUpdateProgress', (progress) => {
+  console.log(`Downloaded: ${progress.bytesDownloaded}/${progress.totalBytesToDownload}`);
+  console.log(`Progress: ${progress.percentComplete}%`);
+});
+```
+
+## Platform Differences
+
+### Android (Google Play)
+
+- Supports in-app updates via Play Core Library
+- Two update modes: Immediate and Flexible
+- Can force critical updates
+- Shows native update UI
+- Handles download and installation
+
+### iOS (App Store)
+
+- No in-app update API available
+- Can only check version and open App Store
+- Version checking requires backend service
+- Updates handled entirely by App Store app
+
+### Web
+
+- Shows update notification only
+- Can redirect to web app URL
+- Version checking via backend
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| `UPDATE_NOT_AVAILABLE` | No update available |
+| `UPDATE_IN_PROGRESS` | Update already downloading |
+| `UPDATE_FAILED` | Update download/install failed |
+| `USER_CANCELLED` | User cancelled the update |
+| `PLATFORM_NOT_SUPPORTED` | Feature not supported on platform |
+| `STORE_NOT_FOUND` | App store app not installed |
+| `NETWORK_ERROR` | Network connection failed |
+
+## Best Practices
+
+1. **Check for updates on app start**
+   ```typescript
+   async function checkOnStart() {
+     const result = await CapacitorNativeUpdate.checkAppUpdate();
+     if (result.updateAvailable && result.updatePriority === 'IMMEDIATE') {
+       await CapacitorNativeUpdate.startImmediateUpdate();
+     }
+   }
+   ```
+
+2. **Handle flexible updates**
+   ```typescript
+   // Start download
+   await CapacitorNativeUpdate.startFlexibleUpdate();
+   
+   // Monitor progress
+   const listener = CapacitorNativeUpdate.addListener('appUpdateProgress', (progress) => {
+     updateProgressBar(progress.percentComplete);
+   });
+   
+   // Complete when ready
+   const stateListener = CapacitorNativeUpdate.addListener('appUpdateStateChanged', (state) => {
+     if (state.installStatus === 11) { // Downloaded
+       showUpdateReadyPrompt();
+     }
+   });
+   ```
+
+3. **Fallback for iOS**
+   ```typescript
+   if (platform === 'ios') {
+     const result = await CapacitorNativeUpdate.checkAppUpdate();
+     if (result.updateAvailable) {
+       showUpdateDialog(() => {
+         CapacitorNativeUpdate.openAppStore();
+       });
+     }
+   }
+   ```