native-update 2.0.0 → 3.1.0

package/docs/MIGRATION.md

@@ -1,5 +1,88 @@
 # Migration Guide
 
+## Upgrading v2 → v3.0.0
+
+v3 narrows the plugin to a single, well-supported backend contract: the
+hosted Native Update SaaS at `https://nativeupdate.aoneahsan.com`
+(reference implementation: Laravel 11 + Nova 5 in `backend/`). The
+direct-Firestore branch — `backendType: 'firestore'` plus the
+`firestore: { … }` config — is removed, along with the
+`src/firestore/` schema/client/manifest-reader/rules/indexes and the
+`example-apps/firebase-backend/` example.
+
+### Why
+
+The Firestore branch existed so apps could run without any server. In
+practice it pushed a lot of operational work (security rules, indexes,
+billing, Drive token storage) onto every consumer. The SaaS handles all
+of it server-side, so the SDK only needs to know how to call one
+backend.
+
+### Required action
+
+#### 1. Drop `backendType` and `firestore` from your config
+
+```diff
+ await NativeUpdate.initialize({
+-  backendType: 'firestore',
+-  firestore: { projectId: '…', appId: 'com.your.app', channel: 'production' },
++  serverUrl: 'https://api.nativeupdate.aoneahsan.com',
++  apiKey:    import.meta.env.VITE_NATIVE_UPDATE_API_KEY,
++  publicKey: import.meta.env.VITE_NATIVE_UPDATE_PUBLIC_KEY,
+   appId:     'com.your.app',
+   channel:   'production',
+ });
+```
+
+If you were running your own Firestore project for manifests, register
+your app in the Native Update dashboard, generate an API key, and
+switch to the HTTP config above. The dashboard mirrors every field
+that previously lived in your Firestore manifest.
+
+#### 2. Delete any direct Firestore reads from your app code
+
+```diff
+- import { FirestoreConfig } from 'native-update';
+```
+
+The plugin no longer exposes `FirestoreConfig`, `firestore-client`, or
+`manifest-reader`. Update checks happen via
+`NativeUpdate.checkForUpdate()` / `NativeUpdate.sync()`, which now
+always speak HTTP to your configured `serverUrl`.
+
+#### 3. Replace `firestore/schema` type imports
+
+If you were importing rollout / device / update-check types, switch to
+the new backend-neutral exports:
+
+```diff
+- import type {
+-   RolloutConfig,
+-   RolloutTargetSegments,
+-   DeviceInfo,
+-   UpdateCheckResponse,
+- } from 'native-update/firestore';
++ import type {
++   RolloutConfig,
++   RolloutTargetSegments,
++   DeviceInfo,
++   UpdateCheckResponse,
++ } from 'native-update';
+```
+
+`FirestoreTimestamp` is replaced by `RolloutTimestamp` (`number |
+string | Date`); a `toEpochMs()` helper handles all three forms.
+
+### Not affected
+
+- Bundle download, verification, install, rollback, boot-time
+  re-verify, and crash-loop auto-rollback are unchanged.
+- Native Android / iOS plugin code is unchanged.
+- App store update checks (`AppUpdate`) and in-app review prompts
+  (`AppReview`) are unchanged.
+
+---
+
 ## Upgrading v1 → v2.0.0
 
 v2 is a security-focused hardening release with a handful of breaking

package/docs/PACKAGES.md

@@ -0,0 +1,167 @@
+# Packages — Native Update
+
+> Inventory of every package this project depends on and where it's used.
+> Fixed path (all projects): docs/PACKAGES.md. Update on EVERY add/remove/upgrade.
+> Last updated: 2026-06-19 | Fleet pass: 2026-06-19 (absolute-latest + Node ≥24.16.0; cooldown OFF)
+
+## package.json / composer.json units (in scope)
+
+- `package.json` (root) — Published Capacitor plugin (`native-update`) + bundled CLI. Build: `tsc` → Rollup.
+- `website/package.json` — React 19 + Vite 8 + Tailwind v4 + Radix marketing site + dashboard.
+- `cli/package.json` (`native-update-cli`) — CLI shipped via the root `bin`; deps also resolve from root when published.
+- `backend/package.json` — Laravel Vite asset build (JS tooling). `backend/composer.json` — Laravel 13 + Nova 5 (PHP).
+
+**Out of scope:** `example-apps/**` (demo apps — fleet rule: skip), `backend/vendor/**` (Composer vendor).
+
+**Engines:** every unit pins `node >=24.16.0` (user directive 2026-06-19). The published plugin therefore requires Node ≥24.16 in consumer toolchains. PHP floor raised to `^8.3` (Laravel 13).
+
+---
+
+## Root plugin (`native-update`)
+
+### Production deps — the bundled CLI's runtime deps (root `bin: cli/index.js`)
+| Package | Version | Used where | Notes |
+|---|---|---|---|
+| archiver | ^8.0.0 | `cli/commands/bundle-create.js` | ZIP bundle creation |
+| chalk | ^5.6.2 | `cli/index.js`, all `cli/commands/*.js` | Colored output |
+| commander | ^15.0.0 | `cli/index.js` | CLI arg parsing (14→15; needs Node ≥22.12, OK under ≥24.16) |
+| express | ^5.2.1 | `cli/commands/server-start.js` | Local test/manifest server |
+| ora | ^9.4.0 | `cli/commands/{backend-create,monitor}.js` | Spinners |
+| prompts | ^2.4.2 | `cli/commands/init.js` | Interactive init |
+
+> Plugin TS (`src/**`) imports only `@capacitor/core`, `@capacitor/filesystem`, `@capacitor/preferences` — all Rollup `external`; core is the lone peer. Not bundled.
+
+### Dev deps
+| Package | Version | Notes |
+|---|---|---|
+| @capacitor/app | ^8.1.0 | Capacitor 8 lockstep (referenced in src/build context) |
+| @capacitor/core | ^8.4.1 | `src/**` peer + type-check |
+| @capacitor/device | ^8.0.2 | Capacitor 8 lockstep |
+| @capacitor/filesystem | ^8.1.2 | `src/**` (external) |
+| @capacitor/preferences | ^8.0.1 | `src/**` (external) |
+| @rollup/plugin-node-resolve | ^16.0.3 | `rollup.config.js` |
+| @rollup/plugin-terser | ^1.0.0 | `rollup.config.js` |
+| @types/node | ^26.0.0 | tsconfig node typings |
+| @typescript-eslint/eslint-plugin · parser | ^8.61.1 | `eslint.config.js` |
+| eslint | ^10.5.0 | `yarn lint` |
+| prettier | ^3.8.4 | `yarn prettier` |
+| rimraf | ^6.1.3 | `build`/`clean` scripts |
+| rollup | ^4.62.0 | `build` |
+| typescript | ^6.0.3 | `build`/`tsc` |
+
+### Peer deps
+| Package | Version | Notes |
+|---|---|---|
+| @capacitor/core | ^8.0.1 | Provided by the consumer app |
+
+---
+
+## website/ (React 19 + Vite 8 + Tailwind v4)
+
+### Production deps
+| Package | Version | Used where |
+|---|---|---|
+| @amplitude/analytics-browser | ^2.44.1 | `src/lib/analytics.ts` |
+| @capacitor/android · cli · core · ios | ^8.4.1 | native build / `cap:sync` |
+| @capacitor/motion | ^8.0.0 | `src/services/capacitor/motion.service.ts` |
+| @capacitor/preferences | ^8.0.1 | token/theme storage |
+| @capacitor/privacy-screen | ^2.0.1 | `src/services/capacitor/privacy-screen.service.ts` |
+| @capacitor/share | ^8.0.1 | `src/services/capacitor/share.service.ts` |
+| @capawesome/capacitor-app-shortcuts | ^8.0.1 | `src/services/capacitor/app-shortcuts.service.ts` |
+| @hookform/resolvers | ^5.4.0 | RHF + Zod (UploadPage) |
+| @microsoft/clarity | ^1.0.2 | `src/lib/errorTracking.ts` |
+| @radix-ui/react-{dialog,icons,select,slider,slot,switch} | various | UI components |
+| @sentry/react | ^10.58.0 | `src/lib/errorTracking.ts` |
+| @tanstack/react-query | ^5.101.0 | `src/App.tsx` + hooks |
+| @types/d3 | ^7.4.3 | type-only for `d3` (kept; see ambiguous) |
+| axios | ^1.18.0 | `src/lib/api.ts` |
+| class-variance-authority / clsx / tailwind-merge | — | UI utils |
+| d3 | ^7.9.0 | `src/pages/ExamplesPage.tsx` |
+| framer-motion | 12.40.0 | **PINNED exact** (see pins) |
+| jszip | ^3.10.1 | `src/services/manifest-generator.ts` |
+| lucide-react | ^1.21.0 | icons |
+| react / react-dom | ^19.2.7 | app-wide |
+| react-hook-form | ^7.79.0 | UploadPage |
+| react-markdown / remark-gfm | — | DocsMarkdownPage |
+| react-router-dom | ^7.18.0 | `src/router.tsx` |
+| zod | ^4.4.3 | validation |
+| zustand | ^5.0.14 | `src/stores/themeStore.ts` |
+
+### Dev deps
+| Package | Version | Notes |
+|---|---|---|
+| @tailwindcss/vite | ^4.3.1 | `vite.config.ts` — the ONLY Tailwind path now |
+| @trapezedev/configure | ^7.1.4 | `sync:apps-config` |
+| @types/node | ^26.0.0 | `tsconfig.node.json` |
+| @types/react · @types/react-dom | ^19.2.x | typings |
+| @vitejs/plugin-react | ^6.0.2 | `vite.config.ts` |
+| eslint + eslint-plugin-react-hooks + eslint-plugin-react-refresh + typescript-eslint + globals | — | lint |
+| tailwindcss | ^4.3.1 | resolves `@import "tailwindcss"` |
+| tsx | ^4.22.4 | runs `postbuild-seo.ts` (added so build doesn't `npx`-fetch) |
+| typescript | ~6.0.3 | `tsc -b` (typecheck gate) |
+| vite | ^8.0.16 | build/dev |
+
+---
+
+## cli/ (`native-update-cli`)
+Now self-contained (previously declared only `commander`, but imports more):
+| Package | Version | Used where |
+|---|---|---|
+| archiver ^8.0.0 · chalk ^5.6.2 · commander ^15.0.0 · express ^5.2.1 · ora ^9.4.0 · prompts ^2.4.2 | — | `cli/index.js` + `cli/commands/*.js` |
+
+---
+
+## backend/ — Composer (PHP, Laravel 13 + Nova 5)
+| Package | Version | Notes |
+|---|---|---|
+| php | ^8.3 | raised from ^8.2 for Laravel 13 |
+| laravel/framework | ^13.0 (13.16.1) | 11→13; fixes 3 security advisories (CRLF email / signed-URL) |
+| laravel/nova | ^5.8 | supports Laravel 13 |
+| laravel/sanctum | ^4.3 | dashboard bearer tokens |
+| laravel/socialite | ^5.27 | Google OAuth |
+| laravel/tinker | ^3.0 | 2→3 (needed for L13) |
+| spatie/laravel-permission | ^8.0 | 6→8 — **RBAC: re-run migrations + Pest before deploy** |
+| srmklive/paypal | ^3.1 | unlocked by L13 (was stuck at 3.0.40) |
+| google/apiclient | ^2.15 | Drive API |
+| phpunit/phpunit (dev) | ^12.0 | 11→12 |
+
+## backend/ — npm (Vite asset build)
+| Package | Version | Notes |
+|---|---|---|
+| @tailwindcss/postcss + postcss | ^4.3.1 / ^8.5.15 | backend uses the postcss Tailwind path (no @tailwindcss/vite here) — KEPT |
+| tailwindcss | ^4.3.1 | `tailwind.config.js` |
+| axios | ^1.18.0 | `resources/js/bootstrap.js` |
+| concurrently | ^10.0.3 | composer `dev` script — KEPT |
+| laravel-vite-plugin | ^3.1.0 | `vite.config.js` |
+| vite | ^8.0.16 | build/dev |
+
+---
+
+## Intentional pins / floors
+| Item | Value | Reason |
+|---|---|---|
+| framer-motion | 12.40.0 exact (website) | Pre-existing exact pin; held to avoid animation-runtime regressions. |
+| @capacitor/* | ^8.x (all units) | Capacitor major lockstep. |
+| node engine | >=24.16.0 (all units) | User directive 2026-06-19 — unblocks commander@15 + latest majors. |
+| php | ^8.3 (backend) | Laravel 13 minimum. |
+
+## Removed in cleanup
+| Date | Package | unit | Why |
+|---|---|---|---|
+| 2026-06-19 | @capacitor/android, @capacitor/ios | root dev | A plugin's TS never imports native runtime packages (only core/filesystem/preferences); confirmed unused. |
+| 2026-06-19 | @tailwindcss/postcss, postcss (+ `postcss.config.js`) | website dev | Redundant — Tailwind already runs via `@tailwindcss/vite`; the postcss path double-processed it. |
+| 2026-06-18 | @rollup/plugin-json | root dev | Not used by `rollup.config.js`. |
+| 2026-06-18 | 8× unused `@radix-ui/react-*` | website prod | No imports in `src/` (accordion, dropdown-menu, label, navigation-menu, scroll-area, separator, tabs, tooltip). |
+| 2026-06-18 | autoprefixer | backend dev | Tailwind v4 handles prefixing. |
+
+## Ambiguous / kept
+| Package | Why |
+|---|---|
+| @types/d3 (website) | Type-only; consumed implicitly for `d3`. Kept (lives in deps; left as-is). |
+
+## Build (re-measured 2026-06-19 — all <60s; outputs preserved)
+The website's `tsc -b` was moved **out of `build`** into the `typecheck` gate (was the ~80s bottleneck), so the three checks are now independent and each green:
+- **Root**: `yarn build` (rimraf + tsc + rollup) **~4s** · lint 0. Outputs: `dist/esm/**` + `plugin.{js,cjs.js,esm.js}` + `.d.ts` + sourcemaps.
+- **website**: `yarn build` (sitemap + `vite build` + `tsx postbuild-seo`) **~4s** · `yarn typecheck` (`tsc -b`) **~10s** · lint 0. Outputs: 122 dist files, 17 HTML, 9 discovery files, sitemap/feed — preserved. (Removing the double-Tailwind processing also trimmed the vite step.)
+- **cli**: no build step; verified `node cli/index.js --help` runs under commander@15.
+- **backend**: `npx vite build` **~2s**; PHP boot verified (`route:list` 161 routes, `config:cache`/`view:cache` OK, Nova assets publish, `composer audit` clean).

package/docs/PERFORMANCE.md

@@ -0,0 +1,110 @@
+# Performance
+
+This document captures the SDK's performance characteristics — what's measured,
+what the targets are, and where the hot paths live. It is the entry point for
+anyone investigating a perf regression or considering an optimisation patch.
+
+Real-device perf testing is out of scope here — that needs a separate
+Maestro / XCTest harness and is on the roadmap.
+
+Maintained by Ahsan Mahmood. Last review: 2026-05-11.
+
+## What dominates real-world OTA performance
+
+For most apps, the user-visible latency between "release pushed" and "device
+running the new code" is dominated by three things, in order:
+
+1. **Bundle download time** — completely network-bound. A 5 MB bundle on a
+   typical mobile connection takes ~10-30 seconds. The SDK's job here is to
+   not make it worse with extra round-trips or stalled retries.
+2. **The wait for the user's next app launch** — depending on the update
+   strategy, this is hours or days for `on-app-start`, minutes for
+   `on-app-resume`, and immediate for `immediate`. See [Update strategies
+   compared](https://docs.nativeupdate.aoneahsan.com/concepts/update-strategies-compared).
+3. **Server-side check latency** — typically ~50-200 ms when the backend is
+   warm. Cold-start backends (Firebase Functions, Cloud Run) can push this to
+   2-5 seconds on the first request.
+
+The SDK's compute work — checksum, signature verify, ZIP extraction, atomic
+swap — is comparatively cheap. SHA-256 over 5 MB takes ~12 ms; RSA-SHA256
+verify takes ~2 ms with RSA-2048; ZIP extraction is dominated by I/O. None
+of these is the bottleneck unless something has gone wrong.
+
+That priority ordering also dictates where optimisation effort pays off:
+network-aware retry backoff > update-strategy selection > server warm-up >
+compute path optimisation.
+
+## Microbenchmark targets
+
+The compute-bound paths have the following calibration targets (MacBook M2,
+Node 20.10, single-threaded):
+
+| Operation | p50 target | p95 target | Notes |
+|---|---|---|---|
+| SHA-256 over 1 MB | ~2.5 ms | ~4 ms | Linear in bundle size. |
+| SHA-256 over 5 MB | ~12 ms | ~18 ms | The common case for Capacitor bundles. |
+| SHA-256 over 20 MB | ~50 ms | ~70 ms | Large bundles; consider asset CDN offload. |
+| RSA-SHA256 verify (2048-bit, 5 MB) | ~2 ms | ~4 ms | Dominated by the SHA, not the asymmetric op. |
+| RSA-SHA256 verify (4096-bit, 5 MB) | ~6 ms | ~10 ms | ~3x slower than 2048-bit verify. |
+
+Real Android / iOS devices are typically 2-5x slower than the dev machine.
+Tail devices (iOS 14-era, Android API 22-26) can be 8-10x slower. Plan
+backend timeouts and SDK retry policies accordingly.
+
+## Regression workflow
+
+If the compute paths show numbers >2x the calibration target on equivalent
+hardware:
+
+1. **Re-measure on a quiet machine** to confirm the regression is real and not
+   noise from a busy machine.
+2. **Profile with `clinic.js`** against a small harness exercising the hot path.
+   The flame graph usually points at the regression directly.
+3. **Common culprits**:
+   - Streaming hash with too-small chunk sizes (each `update()` has overhead)
+   - PEM parsing in the verify hot loop instead of pre-parsing the key
+   - Allocations inside the loop (`Buffer.alloc()` per iteration)
+   - Crypto algorithm fallback to a slow polyfill
+4. **Fix** with the smallest possible patch. Re-run bench to confirm. PR
+   should include before/after numbers.
+
+## Hot paths in the SDK
+
+For anyone optimising the plugin internals, here's the runtime map of where
+CPU goes during a typical OTA update:
+
+```
+sync()                                       ← orchestration, no hot work
+├── checkForUpdate()                         ← one HTTP call, ~100 ms wall
+├── downloadUpdate()
+│   ├── fetch(downloadUrl)                   ← network I/O, ~10-30 s
+│   ├── SecurityValidator.verifyChecksum()   ← ~12 ms for 5 MB
+│   ├── SecurityValidator.verifySignature()  ← ~2 ms for RSA-2048
+│   └── ZIP extraction                       ← I/O dominated, ~100-500 ms
+└── notifyAppReady() (later, next launch)    ← O(1)
+```
+
+The two checksum/signature steps run sequentially after the bundle hits
+disk. They are the only places where compute time is measurable. ZIP
+extraction is platform-native (java.util.zip on Android, NSFileManager
+on iOS) and not exposed to optimisation from the TypeScript side.
+
+## What's NOT covered here
+
+Real-device benchmarks (Android API ladder, iOS device matrix). The
+microbenches measure Node performance, which differs from on-device
+JavaScript engines (Hermes on Android, JavaScriptCore on iOS). Real-device
+perf testing is a separate roadmap item.
+
+Web-platform performance. The plugin's web target uses `SubtleCrypto` for
+hashing and verification, which has its own perf profile. No web benches
+exist today.
+
+Memory profiling. The benches measure CPU time only. Memory pressure is
+typically not an issue for the SDK (the largest allocation is the bundle
+buffer during streaming), but a memory bench would be welcome — file an
+issue if you want to contribute one.
+
+## Authored by
+
+[Ahsan Mahmood](https://aoneahsan.com) — author and maintainer of `native-update`.

package/docs/PROJECT_COMPLETION_TRACKER.md

@@ -21,10 +21,8 @@ This document provides a comprehensive tracking of all project components, their
 | Example Applications | ✅ Complete | 100% |
 | Documentation | ✅ Complete | 100% |
 | Firebase Integration | ✅ Complete | 100% |
-| Unit Tests | ✅ Complete | 100% |
 | iOS Native Tests (XCTest) | ✅ Complete | 100% |
 | Android Native Tests (JUnit) | ✅ Complete | 100% |
-| E2E Tests (Detox) | ✅ Complete | 100% |
 
 **Overall:** Production ready with comprehensive test coverage.
 
@@ -273,21 +271,7 @@ This document provides a comprehensive tracking of all project components, their
 
 ## 10. Testing ✅ COMPLETE
 
-### 10.1 TypeScript Unit Tests (`/src/__tests__/`)
-
-| Test File | Status |
-|-----------|--------|
-| `bundle-manager.test.ts` | ✅ Complete |
-| `config.test.ts` | ✅ Complete |
-| `delta-processor.test.ts` | ✅ Complete |
-| `firestore-schema.test.ts` | ✅ Complete |
-| `manifest-reader.test.ts` | ✅ Complete |
-| `rollout-checker.test.ts` | ✅ Complete |
-| `security.test.ts` | ✅ Complete |
-| `version-manager.test.ts` | ✅ Complete |
-| `integration.test.ts` | ✅ Complete |
-
-### 10.2 iOS Native Tests (XCTest) ✅ IMPLEMENTED
+### 10.1 iOS Native Tests (XCTest) ✅ IMPLEMENTED
 
 | Test File | Tests | Status |
 |-----------|-------|--------|
@@ -300,7 +284,7 @@ This document provides a comprehensive tracking of all project components, their
 
 **Location:** `/ios/Tests/NativeUpdateTests/`
 
-### 10.3 Android Native Tests (JUnit/Kotlin) ✅ IMPLEMENTED
+### 10.2 Android Native Tests (JUnit/Kotlin) ✅ IMPLEMENTED
 
 | Test File | Tests | Status |
 |-----------|-------|--------|
@@ -314,27 +298,13 @@ This document provides a comprehensive tracking of all project components, their
 
 **Location:** `/android/src/test/java/com/aoneahsan/nativeupdate/`
 
-### 10.4 E2E Tests (Detox) ✅ IMPLEMENTED
-
-| Spec File | Tests | Status |
-|-----------|-------|--------|
-| `ota-update.e2e.spec.js` | 5 | ✅ Complete |
-| `download-progress.e2e.spec.js` | 5 | ✅ Complete |
-| `channel-switching.e2e.spec.js` | 5 | ✅ Complete |
-| `error-handling.e2e.spec.js` | 4 | ✅ Complete |
-| **Total** | **19 tests** | ✅ |
-
-**Location:** `/e2e/specs/`
-
-### 10.5 Test Summary
+### 10.3 Test Summary
 
 | Category | Files | Tests | Status |
 |----------|-------|-------|--------|
-| TypeScript Unit Tests | 9 | ~30 | ✅ Complete |
 | iOS Native Tests | 5 | 32 | ✅ Complete |
 | Android Native Tests | 6 | 40 | ✅ Complete |
-| E2E Tests | 4 | 19 | ✅ Complete |
-| **Total** | **24** | **~121** | ✅ |
+| **Total** | **11** | **72** | ✅ |
 
 ---
 
@@ -355,7 +325,6 @@ The delta processor (`/src/live-update/delta-processor.ts`) has a WASM placehold
 Native platform tests are fully implemented:
 - **iOS XCTest:** 5 test files with 32 tests in `/ios/Tests/NativeUpdateTests/`
 - **Android JUnit/Kotlin:** 6 test files with 40 tests in `/android/src/test/`
-- **E2E Detox:** 4 spec files with 19 tests in `/e2e/specs/`
 
 See `/docs/TESTING_REQUIREMENTS.md` for detailed test documentation.
 

package/docs/README.md

@@ -6,7 +6,6 @@ Welcome to the comprehensive documentation for **Capacitor Native Update**, a co
 
 - Last reviewed: `2026-03-25`
 - Current package version: `1.4.9`
-- Test status: `yarn test:run` passed with 81 tests
 - Build status: `yarn build` passed
 - Root package manager: `yarn@4.10.3`
 - Root package workflow is Yarn-only and no longer shells out to npm or pnpm