{"_id":"@capa-build/live-updates-plugin","name":"@capa-build/live-updates-plugin","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@capa-build/live-updates-plugin","version":"1.0.0","description":"Official capa.build plugin for CapacitorJS. Secure, atomic, and telemetry-integrated Over-The-Air (OTA) updates.","main":"dist/plugin.cjs.js","module":"dist/esm/index.js","types":"dist/esm/index.d.ts","unpkg":"dist/plugin.js","author":{"name":"Continuous Labs"},"license":"MIT","homepage":"https://capa.build","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Continuous-Labs/capa.build-live-updates-plugin.git"},"bugs":{"url":"https://github.com/Continuous-Labs/capa.build-live-updates-plugin/issues"},"keywords":["capacitor","plugin","native","ota","live-updates","hot-code-push","continuous-delivery","capa","capa.build"],"scripts":{"verify":"npm run verify:ios && npm run verify:android && npm run verify:web","verify:ios":"cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin && cd ..","verify:android":"cd android && ./gradlew clean build test && cd ..","verify:web":"npm run build","lint":"npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint","fmt":"npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- autocorrect","eslint":"eslint . --ext ts","prettier":"prettier \"**/*.{css,html,ts,js,json}\"","swiftlint":"node-swiftlint","docgen":"docgen <package.json> --api LiveUpdatePlugin --output-readme README.md","build":"npm run clean && tsc","clean":"rimraf ./dist","watch":"tsc --watch","prepublishOnly":"npm run build"},"devDependencies":{"@capacitor/android":"^8.0.0","@capacitor/core":"^8.0.0","@capacitor/docgen":"^0.2.2","@capacitor/ios":"^8.0.0","@ionic/eslint-config":"^0.4.0","@ionic/prettier-config":"^4.0.0","@ionic/swiftlint-config":"^2.0.0","eslint":"^8.57.0","prettier":"~3.2.5","prettier-plugin-java":"~2.6.0","rimraf":"^5.0.5","rollup":"^4.12.0","typescript":"~5.4.2"},"peerDependencies":{"@capacitor/core":"^6.0.0 || ^7.0.0 || ^8.0.0"},"prettier":"@ionic/prettier-config","swiftlint":"@ionic/swiftlint-config","eslintConfig":{"extends":"@ionic/eslint-config/recommended"},"capacitor":{"ios":{"src":"ios"},"android":{"src":"android"}},"_id":"@capa-build/live-updates-plugin@1.0.0","_nodeVersion":"20.18.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-E7lBeumUp3Fq4aTAFBNljiH2hJgRhV30PKnYBBWi10SlBCXBmL4fu9YWx+RttalXJUWjUTG2Ss5oyQwoQgRiXg==","shasum":"b1e9a07f5441ee12339181dad005d0db39c68126","tarball":"https://registry.npmjs.org/@capa-build/live-updates-plugin/-/live-updates-plugin-1.0.0.tgz","fileCount":126,"unpackedSize":416215,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICA1oQrYANhcU7zrfQ5XgTwq+iykWdZXoi1Lnsf9ulZJAiEA9yAzCuQO6WkrH7rQh4cRacEoIJ1vJyY+CW6eagirxdM="}]},"_npmUser":{"name":"felix-clabs","email":"felix@clabs.tech"},"directories":{},"maintainers":[{"name":"felix-clabs","email":"felix@clabs.tech"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/live-updates-plugin_1.0.0_1780250750477_0.05747877540715973"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-31T18:05:50.221Z","1.0.0":"2026-05-31T18:05:50.637Z","modified":"2026-05-31T18:05:50.905Z"},"maintainers":[{"name":"felix-clabs","email":"felix@clabs.tech"}],"description":"Official capa.build plugin for CapacitorJS. Secure, atomic, and telemetry-integrated Over-The-Air (OTA) updates.","homepage":"https://capa.build","keywords":["capacitor","plugin","native","ota","live-updates","hot-code-push","continuous-delivery","capa","capa.build"],"repository":{"type":"git","url":"git+https://github.com/Continuous-Labs/capa.build-live-updates-plugin.git"},"author":{"name":"Continuous Labs"},"bugs":{"url":"https://github.com/Continuous-Labs/capa.build-live-updates-plugin/issues"},"license":"MIT","readme":"# @capa-build/live-updates-plugin\n\nThe official **capa.build** plugin for CapacitorJS. It enables secure, atomic, and telemetry-integrated Over-The-Air (OTA) updates for your mobile applications.\n\n## 🚀 Features\n\n- 🔋 **iOS & Android Support**: Native bundle management for Capacitor 6, 7, and 8.\n- ⚡️ **Atomic Updates**: Bundles are fully downloaded and verified before activation to prevent partial updates.\n- 🛡️ **Rollback Mechanism**: Automatically restores a known working version if a new bundle fails to initialize.\n- 📡 **Real-time Telemetry**: Automatic reporting of version adoption and health metrics to the Capa console.\n- 📦 **Delta Updates**: Optimized per-file downloads for faster and lighter updates.\n- 🔒 **Security**: File integrity verification using SHA-256 hashes and optional signature verification.\n\n## 📦 Installation\n\n```bash\nnpm install @capa-build/live-updates-plugin\nnpx cap sync\n```\n\n## ⚙️ Configuration\n\nAdd the plugin configuration to your `capacitor.config.json` (or `capacitor.config.ts`):\n\n```json\n{\n  \"plugins\": {\n    \"CapaLiveUpdates\": {\n      \"appId\": \"YOUR_APP_ID_FROM_CAPA_BUILD\",\n      \"autoUpdateStrategy\": \"background\",\n      \"readyTimeout\": 10000,\n    }\n  }\n}\n```\n\n### Configuration Options\n\n| Property | Type | Description |\n| :--- | :--- | :--- |\n| `appId` | `string` | Your application's unique ID in the capa.build platform. |\n| `autoUpdateStrategy` | `string` | Update strategy: `none`, `background` (at startup), `foreground` (when app returns from background). |\n| `readyTimeout` | `number` | Max time (ms) the plugin waits for the `ready()` call before triggering a rollback. Default: `10000`. |\n| `publicKey` | `string` | (Optional) Public key for bundle signature verification. |\n| `serverDomain` | `string` | (Optional) The domain of the Capa API. Default: `api.capa.build`. |\n\n## 📖 Usage\n\n### Initialization (Ready Protocol)\n\nIt is **critical** to call the `ready()` method once your application has successfully loaded (e.g., after your framework—Vue, React, Angular—is mounted). If `ready()` is not called within the `readyTimeout`, the plugin assumes the bundle is faulty and triggers an automatic rollback.\n\n```typescript\nimport { CapaLiveUpdates } from '@capa-build/live-updates-plugin';\n\n// Inside your App's initialization lifecycle\nonMounted(async () => {\n  try {\n    const result = await CapaLiveUpdates.ready();\n    console.log('App ready. Current Bundle:', result.currentBundleId);\n    \n    if (result.rollback) {\n      console.warn('A failure was detected and an automatic rollback was performed.');\n    }\n  } catch (e) {\n    console.error('Error notifying ready:', e);\n  }\n});\n```\n\n### Manual Synchronization\n\nYou can trigger an update check and download at any time:\n\n```typescript\nconst result = await CapaLiveUpdates.sync();\nif (result.updateAvailable) {\n  console.log('New version downloaded:', result.bundleId);\n  // You can prompt the user to reload now or later\n}\n```\n\n### Advanced Synchronization (Check without Download)\n\nIf you want to check if an update exists before downloading it:\n\n```typescript\nconst result = await CapaLiveUpdates.fetchLatestBundle();\nif (result.updateAvailable) {\n  console.log('Update found:', result.versionName);\n  \n  // Later, download it manually\n  await CapaLiveUpdates.downloadBundle({\n    bundleId: result.bundleId!,\n    url: result.url!,\n    artifactType: result.artifactType\n  });\n}\n```\n\n### Apply Changes (Reload)\n\nTo apply a newly downloaded bundle immediately without waiting for the next app restart:\n\n```typescript\nawait CapaLiveUpdates.reload();\n```\n\n## 🛠 API Reference\n\n### Methods\n\n| Method | Parameters | Returns | Description |\n| :--- | :--- | :--- | :--- |\n| `sync` | `options?: SyncOptions` | `Promise<SyncResult>` | Checks, downloads and sets the latest bundle. |\n| `fetchLatestBundle` | `options?: SyncOptions` | `Promise<FetchLatestBundleResult>` | Checks for updates without downloading. |\n| `downloadBundle` | `options: DownloadBundleOptions` | `Promise<void>` | Manually downloads a specific bundle. |\n| `setBundle` | `options: SetBundleOptions` | `Promise<void>` | Assigns a bundle for the next reload. |\n| `getBundles` | - | `Promise<GetBundlesResult>` | Lists all downloaded bundle IDs. |\n| `getDownloadedBundles`| - | `Promise<GetDownloadedBundlesResult>` | Lists detail of downloaded bundles. |\n| `getCurrentBundle` | - | `Promise<BundleInfo>` | Returns info about the active bundle. |\n| `getNextBundle` | - | `Promise<{ bundleId: string \\| null }>` | Returns info about the bundle for the next reload. |\n| `getChannel` | - | `Promise<ChannelResult>` | Gets current configured channel. |\n| `setChannel` | `options: SetChannelOptions` | `Promise<void>` | Sets active channel (e.g., 'production'). |\n| `fetchChannels` | - | `Promise<FetchChannelsResult>` | Lists available channels from server. |\n| `ready` | - | `Promise<ReadyResult>` | Notifies app is loaded correctly. |\n| `reload` | - | `Promise<void>` | Reloads the webview with the next bundle. |\n| `reset` | - | `Promise<void>` | Restores the original app version. |\n| `setCustomId` | `options: { customId: string }` | `Promise<void>` | Sets a custom user ID for segmentation. |\n\n### Interfaces\n\n#### SyncResult\n- `updateAvailable`: `boolean`\n- `bundleId`: `string | null`\n\n#### FetchLatestBundleResult\n- `updateAvailable`: `boolean`\n- `bundleId`: `string | null`\n- `url`: `string | null`\n- `versionCode`: `string | null`\n- `versionName`: `string | null`\n- `artifactType`: `'manifest' | 'zip'`\n\n#### BundleInfo\n- `bundleId`: `string | null`\n- `versionName`: `string | null`\n- `versionCode`: `string | null`\n\n## 📡 Events\n\nThe plugin emits events to provide feedback to your users:\n\n```typescript\n// Download progress\nCapaLiveUpdates.addListener('onDownloadProgress', (event) => {\n  const progress = (event.bytesReceived / event.totalBytes) * 100;\n  console.log(`Downloading update: ${progress.toFixed(0)}%`);\n});\n\n// Update applied (ready for reload)\nCapaLiveUpdates.addListener('onUpdateApplied', (event) => {\n  console.log('Bundle is ready in local storage.');\n});\n```\n\n## 📊 Automatic Telemetry\n\nThe plugin automatically reports the following data to **capa.build** every time `ready()` is called:\n- `deviceId`: An anonymous unique identifier for the device.\n- `bundleId`: The ID of the currently running bundle.\n- `platform`: `ios` or `android`.\n- `pluginVersion`: The version of the plugin being used.\n\nThis enables real-time visualization of version adoption and health metrics in the Capa Dashboard.\n\n## ⚖️ License\n\nProprietary of Continuous Labs. All rights reserved. For exclusive use by capa.build customers.\n","readmeFilename":"README.md","_rev":"1-11658e33b0b2db1048356558c0d4caa5"}