native-update 1.3.7 → 1.4.1

package/AI-INTEGRATION-GUIDE.md

@@ -0,0 +1,290 @@
+# AI Integration Guide - Native Update
+
+Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate native-update into Capacitor projects.
+
+## Installation
+
+```bash
+yarn add native-update
+# or
+npm install native-update
+```
+
+## Core Concepts
+
+Native Update provides three main features:
+1. **Live Updates (OTA)** - Deploy JS/HTML/CSS updates without app store approval
+2. **App Updates** - Native app store update management (Google Play, App Store)
+3. **App Reviews** - In-app review prompts
+
+## Quick Start
+
+### Basic Setup
+
+```typescript
+import { NativeUpdate } from 'native-update';
+
+// Configure the plugin
+await NativeUpdate.configure({
+  appId: 'your-app-id',
+  channel: 'production', // 'development' | 'staging' | 'production'
+  updateUrl: 'https://your-update-server.com/api',
+  autoCheck: true,
+  checkInterval: 3600000, // 1 hour in ms
+});
+```
+
+### Live Updates (OTA)
+
+```typescript
+import { NativeUpdate } from 'native-update';
+
+// Check and apply updates
+const result = await NativeUpdate.sync();
+if (result.updateAvailable) {
+  console.log('Update applied, reload required');
+  await NativeUpdate.reload();
+}
+
+// Manual update flow
+const latest = await NativeUpdate.getLatest();
+if (latest.available) {
+  const bundle = await NativeUpdate.download({ version: latest.version });
+  await NativeUpdate.set(bundle);
+  await NativeUpdate.reload();
+}
+
+// Notify app is stable after update (prevents auto-rollback)
+await NativeUpdate.notifyAppReady();
+```
+
+### App Store Updates
+
+```typescript
+import { NativeUpdate } from 'native-update';
+
+// Check for app store updates
+const updateInfo = await NativeUpdate.getAppUpdateInfo();
+if (updateInfo.updateAvailable) {
+  if (updateInfo.updatePriority >= 4) {
+    // Critical update - force immediate
+    await NativeUpdate.performImmediateUpdate();
+  } else {
+    // Flexible update - download in background
+    await NativeUpdate.startFlexibleUpdate();
+    // Later, when ready to install
+    await NativeUpdate.completeFlexibleUpdate();
+  }
+}
+```
+
+### App Reviews
+
+```typescript
+import { NativeUpdate } from 'native-update';
+
+// Request review at appropriate moment
+const canRequest = await NativeUpdate.canRequestReview();
+if (canRequest.eligible) {
+  const result = await NativeUpdate.requestReview();
+  // Note: Actual review submission not guaranteed (platform controls)
+}
+```
+
+## API Reference
+
+### Live Update Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `sync(options?)` | Check and apply updates | `Promise<SyncResult>` |
+| `download(options)` | Download specific version | `Promise<BundleInfo>` |
+| `set(bundle)` | Set active bundle | `Promise<void>` |
+| `reload()` | Reload app with current bundle | `Promise<void>` |
+| `reset()` | Reset to original bundle | `Promise<void>` |
+| `current()` | Get current bundle info | `Promise<BundleInfo>` |
+| `list()` | List all downloaded bundles | `Promise<BundleInfo[]>` |
+| `delete(options)` | Delete bundles | `Promise<void>` |
+| `notifyAppReady()` | Mark update as stable | `Promise<void>` |
+| `getLatest()` | Check for latest version | `Promise<LatestVersion>` |
+| `setChannel(channel)` | Switch update channel | `Promise<void>` |
+| `setUpdateUrl(url)` | Set update server URL | `Promise<void>` |
+
+### App Update Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `getAppUpdateInfo()` | Get app store update info | `Promise<AppUpdateInfo>` |
+| `performImmediateUpdate()` | Force immediate update | `Promise<void>` |
+| `startFlexibleUpdate()` | Start background download | `Promise<void>` |
+| `completeFlexibleUpdate()` | Install downloaded update | `Promise<void>` |
+| `openAppStore(options?)` | Open app store page | `Promise<void>` |
+
+### App Review Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `requestReview()` | Request in-app review | `Promise<ReviewResult>` |
+| `canRequestReview()` | Check review eligibility | `Promise<CanRequestReviewResult>` |
+
+## Configuration Options
+
+```typescript
+interface NativeUpdateConfig {
+  appId: string;                    // Your app identifier
+  channel?: string;                 // Update channel (default: 'production')
+  updateUrl?: string;               // Update server URL
+  autoCheck?: boolean;              // Auto-check for updates (default: true)
+  checkInterval?: number;           // Check interval in ms (default: 3600000)
+  autoDownload?: boolean;           // Auto-download updates (default: false)
+  autoInstall?: boolean;            // Auto-install after download (default: false)
+  requireWifi?: boolean;            // Only download on WiFi (default: true)
+  minBatteryLevel?: number;         // Min battery % for updates (default: 20)
+  publicKey?: string;               // Public key for signature verification
+  checksumAlgorithm?: 'sha256' | 'sha512'; // Checksum algorithm (default: 'sha256')
+}
+```
+
+## Event Listeners
+
+```typescript
+import { NativeUpdate } from 'native-update';
+
+// Listen for update events
+NativeUpdate.addListener('updateAvailable', (info) => {
+  console.log('Update available:', info.version);
+});
+
+NativeUpdate.addListener('downloadProgress', (progress) => {
+  console.log(`Download: ${progress.percent}%`);
+});
+
+NativeUpdate.addListener('downloadComplete', (bundle) => {
+  console.log('Download complete:', bundle.version);
+});
+
+NativeUpdate.addListener('updateFailed', (error) => {
+  console.error('Update failed:', error.message);
+});
+
+NativeUpdate.addListener('updateInstalled', (bundle) => {
+  console.log('Update installed:', bundle.version);
+});
+```
+
+## Update Channels
+
+| Channel | Purpose | Auto-Update | Check Interval |
+|---------|---------|-------------|----------------|
+| `development` | Internal testing | Yes | 1 minute |
+| `staging` | QA/Beta testing | Configurable | 1 hour |
+| `production` | Live users | No (consent) | Daily |
+
+## Backend Requirements
+
+Your update server must implement these endpoints:
+
+### GET /api/check
+```json
+{
+  "available": true,
+  "version": "1.2.0",
+  "url": "https://cdn.example.com/bundles/1.2.0.zip",
+  "checksum": "sha256:abc123...",
+  "signature": "base64signature...",
+  "releaseNotes": "Bug fixes and improvements"
+}
+```
+
+### GET /api/download/:version
+Returns the bundle zip file.
+
+## CLI Tools
+
+```bash
+# Create a bundle from your build
+npx native-update bundle create ./dist --version 1.2.0 --output ./bundles
+
+# Sign a bundle
+npx native-update bundle sign ./bundles/1.2.0.zip --key ./private.key
+
+# Verify a bundle
+npx native-update bundle verify ./bundles/1.2.0.zip --key ./public.key
+
+# Upload to server
+npx native-update bundle upload ./bundles/1.2.0.zip --server https://api.example.com
+```
+
+## Platform-Specific Setup
+
+### Android
+
+Add to `android/app/build.gradle`:
+```gradle
+dependencies {
+    implementation 'com.google.android.play:core:1.10.3'
+}
+```
+
+### iOS
+
+No additional setup required. Uses native APIs.
+
+### Web (Limited Support)
+
+Web platform supports checking for updates only. Actual OTA updates require native platforms.
+
+## Security Best Practices
+
+1. **Always use HTTPS** for update URLs
+2. **Enable signature verification** with RSA/ECDSA keys
+3. **Use checksums** to verify bundle integrity
+4. **Test rollback** scenarios before production
+5. **Implement `notifyAppReady()`** to prevent auto-rollback on stable updates
+
+## Common Patterns
+
+### Check on App Start
+
+```typescript
+import { App } from '@capacitor/app';
+import { NativeUpdate } from 'native-update';
+
+App.addListener('appStateChange', async ({ isActive }) => {
+  if (isActive) {
+    const result = await NativeUpdate.sync({ silent: true });
+    if (result.updateAvailable && result.updateReady) {
+      // Show user prompt to reload
+    }
+  }
+});
+```
+
+### Review After Positive Action
+
+```typescript
+async function handlePurchaseComplete() {
+  // After successful purchase
+  const canRequest = await NativeUpdate.canRequestReview();
+  if (canRequest.eligible) {
+    await NativeUpdate.requestReview();
+  }
+}
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Update not applying | Call `notifyAppReady()` after successful update |
+| Rollback on restart | Previous update crashed; check error logs |
+| Download fails | Verify network, check server response format |
+| Signature invalid | Regenerate keys, re-sign bundle |
+
+## Links
+
+- [Full Documentation](./docs/)
+- [API Reference](./docs/api/)
+- [Example Apps](./example-apps/)
+- [CLI Reference](./docs/cli-reference.md)
+- [Security Guide](./docs/guides/security-best-practices.md)

package/Readme.md

@@ -15,6 +15,8 @@
 
 ## 📚 Documentation
 
+- **[AI Integration Guide](./AI-INTEGRATION-GUIDE.md)** - Quick reference for AI development agents (Claude, Cursor, Copilot)
+
 ### Getting Started
 
 - **[Installation Guide](./docs/getting-started/installation.md)** - Step-by-step installation instructions

package/dist/esm/config/support.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Support configuration for native-update package
+ * Help keep this package free and improving
+ */
+export declare const SUPPORT_CONFIG: {
+    readonly url: "https://aoneahsan.com/payment?project-id=native-update&project-identifier=native-update";
+    readonly label: "Support the Project";
+    readonly description: "Help us keep native-update free and improving";
+};

package/dist/esm/config/support.js

@@ -0,0 +1,10 @@
+/**
+ * Support configuration for native-update package
+ * Help keep this package free and improving
+ */
+export const SUPPORT_CONFIG = {
+    url: 'https://aoneahsan.com/payment?project-id=native-update&project-identifier=native-update',
+    label: 'Support the Project',
+    description: 'Help us keep native-update free and improving',
+};
+//# sourceMappingURL=support.js.map

package/dist/esm/config/support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"support.js","sourceRoot":"","sources":["../../../src/config/support.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,GAAG,EAAE,yFAAyF;IAC9F,KAAK,EAAE,qBAAqB;IAC5B,WAAW,EAAE,+CAA+C;CACpD,CAAC"}