native-update 2.0.0 → 3.1.0

package/docs/TESTING_REQUIREMENTS.md

@@ -6,10 +6,8 @@ This document outlines the testing requirements for the native-update plugin.
 
 - **Plugin testing**: Handled in actual/live applications using the plugin
 - **Example apps**: Demonstrate functionality for manual testing
-- **Unit tests (TypeScript)**: ✅ Implemented in `/src/__tests__/`
 - **iOS Native Tests (XCTest)**: ✅ Implemented in `/ios/Tests/NativeUpdateTests/`
 - **Android Native Tests (JUnit/Kotlin)**: ✅ Implemented in `/android/src/test/`
-- **E2E Tests (Detox)**: ✅ Implemented in `/e2e/`
 
 ---
 
@@ -162,107 +160,6 @@ testImplementation 'org.robolectric:robolectric:4.11.1'
 
 ---
 
-## End-to-End Tests (Detox) ✅ IMPLEMENTED
-
-The E2E tests are implemented in `/e2e/` using Detox framework.
-
-### Framework
-- **Detox** for React Native + Capacitor apps
-
-### Test Coverage
-
-| Spec File | Tests | Status |
-|-----------|-------|--------|
-| `ota-update.e2e.spec.js` | 5 tests | ✅ |
-| `download-progress.e2e.spec.js` | 5 tests | ✅ |
-| `channel-switching.e2e.spec.js` | 5 tests | ✅ |
-| `error-handling.e2e.spec.js` | 4 tests | ✅ |
-| **Total** | **19 tests** | ✅ |
-
-### Running E2E Tests
-
-```bash
-cd e2e
-yarn install
-yarn build:android  # or yarn build:ios
-yarn test:android   # or yarn test:ios
-```
-
-### Mock Server
-
-Start the mock update server for E2E tests:
-```bash
-yarn start-mock-server
-```
-
-### Test Scenarios
-
-#### OTA Update Flow
-```
-1. App starts with version 1.0.0
-2. Server has version 1.1.0 available
-3. App checks for update → receives update info
-4. App downloads bundle → shows progress
-5. App applies update → restarts
-6. App shows version 1.1.0
-```
-
-#### Rollback Flow
-```
-1. App has version 1.1.0 applied
-2. New update 1.2.0 has critical bug
-3. App applies 1.2.0 → crashes on start
-4. App automatically rolls back to 1.1.0
-5. App reports rollback to server
-```
-
-#### Native Update Flow
-```
-1. App version 1.0.0 installed from store
-2. Store has version 2.0.0 (native update required)
-3. App detects native update available
-4. User shown update prompt
-5. User redirected to app store
-```
-
-#### Channel Switching
-```
-1. App configured for 'production' channel
-2. Developer switches to 'staging' channel
-3. App receives staging bundle
-4. App applies staging updates
-```
-
-### E2E Test File Structure
-```
-e2e/
-├── specs/
-│   ├── ota-update.spec.js
-│   ├── rollback.spec.js
-│   ├── native-update.spec.js
-│   └── channel-switching.spec.js
-├── helpers/
-│   └── server-mock.js
-└── setup.js
-```
-
----
-
-## Test Server for E2E
-
-A mock update server should provide:
-
-```javascript
-// Mock endpoints
-GET /api/updates/check?appId=xxx&version=1.0.0&channel=production
-POST /api/updates/download/:bundleId
-POST /api/updates/report
-```
-
-The CLI already provides `npx native-update server start` for local testing.
-
----
-
 ## Security Testing Checklist
 
 - [ ] Test with malformed bundle files (corrupted ZIP)
@@ -282,26 +179,18 @@ All test categories have been implemented as of 2026-01-16:
 
 | Category | Location | Tests | Status |
 |----------|----------|-------|--------|
-| TypeScript Unit Tests | `/src/__tests__/` | 9 test files | ✅ Complete |
 | iOS Native Tests | `/ios/Tests/NativeUpdateTests/` | 5 test files, 32 tests | ✅ Complete |
 | Android Native Tests | `/android/src/test/.../nativeupdate/` | 6 test files, 40 tests | ✅ Complete |
-| E2E Tests | `/e2e/specs/` | 4 spec files, 19 tests | ✅ Complete |
-| **Total** | | **~100 tests** | ✅ Complete |
+| **Total** | | **72 tests** | ✅ Complete |
 
 ## Running All Tests
 
 ```bash
-# TypeScript Unit Tests
-yarn test
-
 # iOS Native Tests
 cd ios && xcodebuild test -scheme NativeUpdate -destination 'platform=iOS Simulator,name=iPhone 15'
 
 # Android Native Tests
 cd android && ./gradlew test
-
-# E2E Tests
-cd e2e && yarn install && yarn test:android  # or yarn test:ios
 ```
 
 ## Additional Testing

package/docs/ai-knowledge-base/00-project-profile.md

@@ -0,0 +1,38 @@
+# Native Update — Project Profile
+
+**Last Updated:** 2026-04-25
+
+## What this is
+
+Native Update is a Capacitor plugin that delivers three update flows for hybrid mobile apps in a single API surface:
+
+1. **Live (OTA) updates** — push JavaScript/CSS/HTML bundles to a running app without going through the app store. Bundle is downloaded, verified by checksum + signature, applied on next launch.
+2. **Native app updates** — prompt users to update through Google Play / Apple App Store when a new native binary is available. Uses platform-native dialogs (Play Core In-App Update on Android, App Store deep-link on iOS).
+3. **In-app reviews** — request a Play Store / App Store review at the right moment using each platform's native review UI.
+
+## Why this exists
+
+Building Capacitor apps that ship updates quickly is hard. Apple and Google review processes take days. For non-native bundles (the JS/CSS that ships with most Capacitor apps), there's no reason to wait — the changes don't touch native code. Native Update lets developers ship hot fixes and small features in minutes via OTA, while still using the official app-store rails for native binary updates and review requests. The plugin exists to remove that friction without forcing developers to build their own bundle pipeline, signing flow, and rollback mechanism.
+
+## Distribution
+
+- **npm:** `native-update` (current version 2.0.0)
+- **Source:** https://github.com/aoneahsan/native-update (MIT)
+- **Marketing site + dashboard:** https://nativeupdate.aoneahsan.com
+- **Docs:** Surfaced at the marketing site under `/docs/...` and in `/docs` of this repo
+
+## Audience
+
+Capacitor app developers and small-to-mid-size product teams who:
+- Ship hybrid mobile apps (React/Vue/Angular + Capacitor)
+- Need rapid iteration without app-store review delays for non-native fixes
+- Want a self-hostable update server (Firestore / Node / Laravel templates included) to keep costs low and data sovereign
+- Want native review prompts and store-update prompts working out of the box
+
+## Core value props
+
+- One package for three flows (OTA + native update + review)
+- Multiple backend templates (Firestore, Node + Express, Laravel + Nova) — pick what fits your stack
+- Channel-based rollouts (alpha, beta, production) with percentage rollout support
+- Bundle integrity (SHA-256 checksum + signature verification)
+- Background download + apply-on-restart for low-friction updates

package/docs/ai-knowledge-base/01-features.md

@@ -0,0 +1,46 @@
+# Native Update — Feature Inventory
+
+**Last Updated:** 2026-04-25
+
+## Live updates (OTA)
+
+- Channel-based bundle delivery (`alpha`, `beta`, `production` by default; custom channels supported)
+- Manifest-driven version pinning per channel
+- SHA-256 checksum verification on every download
+- RSA signature verification with developer-provided public key (optional but recommended)
+- Background download with progress events
+- Apply-on-restart strategy (no mid-session bundle swap)
+- Rollback to last-known-good bundle on integrity failure
+- Forced vs optional updates (manifest flag)
+- Percentage rollouts (manifest field), client-side gated by stable hash of `installId`
+- Minimum native version constraint (don't deliver a bundle that requires a newer native binary)
+
+## Native app updates
+
+- Android: Google Play Core In-App Update (immediate + flexible flows)
+- iOS: App Store version check via app-store API + deep link to update
+- Manifest-driven minimum version (force-update threshold)
+- Optional update prompt copy override per app
+
+## In-app reviews
+
+- Android: Play In-App Review API
+- iOS: `SKStoreReviewController` (StoreKit)
+- Throttling guard so the prompt doesn't fire too often per user
+
+## Backend templates
+
+Three reference backends ship with the plugin so users can pick one:
+
+- **Firestore-only** (`example-apps/firebase-backend`) — zero-cost on Firestore free tier; manifest stored as a Firestore document; bundles uploaded to user-controlled storage (e.g., the developer's Google Drive).
+- **Node + Express** (`example-apps/node-express`) — vanilla Node REST server with on-disk bundles; good for self-hosted setups.
+- **Laravel + Nova** (`backend/`) — full SaaS-grade backend with admin UI, multi-tenant API keys, channel management, rollout controls, signed download URLs.
+
+## CLI tool
+
+The `native-update` CLI (`cli/index.js`) helps with:
+- Creating bundle ZIPs from a built web app
+- Signing bundles with the developer's private key
+- Computing checksums
+- Uploading to one of the supported backends
+- Rolling back a published manifest entry

package/docs/ai-knowledge-base/02-routes.md

@@ -0,0 +1,72 @@
+# Native Update Website — Route Map
+
+**Last Updated:** 2026-04-25
+
+This is the public-facing marketing site + authenticated dashboard at https://nativeupdate.aoneahsan.com.
+
+## Marketing routes (public, indexed)
+
+| Path | Page | Purpose |
+|---|---|---|
+| `/` | HomePage | Hero, value props, social proof, CTA |
+| `/features` | FeaturesPage | OTA, native update, in-app review feature deep dives |
+| `/pricing` | PricingPage | Self-host (free) and SaaS tier copy |
+| `/docs` | DocsPage | Docs landing — links to package docs tree |
+| `/docs/*` | DocsMarkdownPage | Markdown-rendered package docs (mirrored from repo `docs/`) |
+| `/about` | AboutPage | Project background and ethos |
+| `/contact` | ContactPage | Developer contact info, support email |
+| `/sitemap` | SitemapPage | Human-readable sitemap with category cards + fuzzy search |
+| `/feed` | FeedPage | Public content/changelog feed |
+| `/permissions` | PermissionsPage | Permission disclosures for app stores |
+
+## Legal / info routes (public, indexed)
+
+| Path | Page | Purpose |
+|---|---|---|
+| `/privacy` | PrivacyPage | GDPR/CCPA privacy policy |
+| `/terms` | TermsPage | Terms of service |
+| `/security` | SecurityPage | Data security disclosures |
+| `/cookies` | CookiePolicyPage | Cookie usage |
+| `/data-deletion` | DataDeletionPage | Account/data deletion (Play / App Store requirement) |
+
+## Auth routes (public, NOINDEX)
+
+| Path | Page | Purpose |
+|---|---|---|
+| `/login` | LoginPage | Google sign-in only |
+| `/signup` | SignupPage | Same Google flow, separate landing |
+
+## Dashboard routes (authenticated, NOINDEX)
+
+| Path | Page | Purpose |
+|---|---|---|
+| `/dashboard` | DashboardOverview | Workspace overview |
+| `/dashboard/apps` | AppsPage | Manage apps |
+| `/dashboard/apps/:id` | AppDetailPage | Single app view |
+| `/dashboard/builds` | BuildsPage | Build/bundle history |
+| `/dashboard/builds/:id` | BuildDetailPage | Single bundle |
+| `/dashboard/upload` | UploadPage | Upload a new bundle |
+| `/dashboard/google-drive` | GoogleDrivePage | Google Drive connection |
+| `/dashboard/config` | ConfigPage | Per-app config |
+| `/dashboard/settings` | SettingsPage | Account settings |
+| `/dashboard/rollouts` | RolloutsPage | Channel/rollout controls |
+| `/dashboard/analytics` | AnalyticsPage | Update delivery metrics |
+
+## Admin routes (super-admin only, NOINDEX)
+
+| Path | Page | Purpose |
+|---|---|---|
+| `/admin` | AdminOverview | Admin landing |
+| `/admin/users` | AdminUsersPage | User management |
+| `/admin/apps` | AdminAppsPage | All apps across users |
+| `/admin/builds` | AdminBuildsPage | All builds |
+
+## Catch-all
+
+| Path | Page | Purpose |
+|---|---|---|
+| `*` | NotFoundPage | Branded 404 with home + back CTAs |
+
+## Discovery files (public, served at root by Vite)
+
+`/robots.txt`, `/sitemap.xml`, `/feed.xml`, `/llms.txt`, `/llms-full.txt`, `/ai.txt`, `/humans.txt`, `/.well-known/security.txt`, `/manifest.json`, `/og-image.svg`.

package/docs/ai-knowledge-base/03-tech-stack.md

@@ -0,0 +1,57 @@
+# Native Update — Tech Stack
+
+**Last Updated:** 2026-04-25
+
+## Plugin (root)
+
+- TypeScript 5+
+- Rollup (ESM + CJS dual build, `dist/`)
+- ESLint flat config (`@typescript-eslint`)
+- Capacitor 8 plugin API
+- Native: Kotlin (Android), Swift (iOS)
+
+## Marketing site + dashboard (`website/`)
+
+- React 19 + TypeScript
+- Vite 8
+- Tailwind CSS v4
+- Radix UI primitives (`@radix-ui/react-*`)
+- `lucide-react` icons
+- `framer-motion` for marketing-page animations
+- React Router 7
+- Firebase Auth (Google popup) + Firestore + Firebase Analytics
+- Google Drive API (browser-side OAuth) for bundle storage
+- `react-hook-form` + `zod` + `@hookform/resolvers` for all forms
+- `zustand` for cross-component state
+- `d3` for analytics charts
+- `jszip` for bundle ZIP authoring
+- `react-markdown` + `remark-gfm` for in-site markdown rendering
+- Capacitor 8 for hybrid mobile distribution of the dashboard
+- Capawesome `app-shortcuts` plugin
+
+## CLI (`cli/`)
+
+- Node 18+
+- `commander` for CLI surface
+- `chalk`, `ora` for terminal UX
+- `axios` for HTTP
+- `archiver` for ZIP generation
+
+## Backend templates
+
+- Firestore-only template — pure browser → Firestore writes
+- Node + Express — vanilla REST server
+- Laravel 11 + Nova 5 — full SaaS backend
+
+## Infra
+
+- Firebase Hosting (website + dashboard)
+- Firestore for manifest metadata
+- Google Drive (user-owned) for bundle ZIP storage
+- GitHub for source + issues
+- npm registry for plugin distribution
+
+## Build outputs
+
+- Plugin: `dist/esm/`, `dist/plugin.cjs.js`, `dist/plugin.js`, `dist/plugin.esm.js`
+- Website: `website/dist/` (per-route static HTML prerendered for SEO)

package/docs/ai-knowledge-base/README.md

@@ -0,0 +1,23 @@
+# AI Knowledge Base
+
+Comprehensive project documentation for AI tools and onboarding contributors. Maintained per R-016 — review every 14 days.
+
+| File | Topic |
+|---|---|
+| `00-project-profile.md` | What Native Update is, why it exists, audience, value props |
+| `01-features.md` | Feature inventory: live updates, native updates, in-app reviews, backends, CLI |
+| `02-routes.md` | Marketing site + dashboard route map |
+| `03-tech-stack.md` | Languages, frameworks, libs, infra |
+
+## When to update
+
+- Significant feature addition or removal
+- Route added or removed (always sync `02-routes.md` with `website/src/router.tsx`)
+- Tech stack change (library replaced, major version bump)
+- Distribution change (npm publish, hosting move)
+
+## Update procedure
+
+1. Edit the relevant file directly
+2. Bump the `Last Updated` date at the top
+3. Update `docs/rules-tracker.md` R-016 row date

package/docs/analytics-tracking.md

@@ -0,0 +1,37 @@
+# Analytics Tracking (R-024)
+
+This registry lists every meaningful user action and where it is tracked.
+
+**Service:** `website/src/lib/analytics.ts`
+**Destinations:** Firebase Analytics (always on if Firebase config present) + Microsoft Clarity / Amplitude (off until their env keys are set)
+
+**Last audited:** 2026-04-25
+
+## Event vocabulary
+
+| Event name | Where fired | Params |
+|---|---|---|
+| `page_view` | `usePageSEO` hook on every public page mount | `page_path`, `page_title` |
+| `click` | High-intent CTAs in `Header`, `HomePage`, marketing CTAs | `element_name`, `location` |
+| `form_submit` | UploadPage, SettingsPage, AppsPage, ContactPage | `form_name`, `success` |
+| `external_link_click` | Footer social links, npm link, GitHub link | `url`, `link_text` |
+| `download` | Bundle/manifest exports, sample-app download | `file_name`, `file_type` |
+| `error` | `trackErrorEvent` for non-fatal flows | `error_message`, `error_location` |
+| `app_error` | `trackError` from `errorTracking.ts` | `name`, `message`, plus context |
+
+## Wiring guidance
+
+```ts
+import { trackEvent, trackClick, trackFormSubmit } from '@/lib/analytics';
+
+trackEvent('upload_started', { app_id, channel });
+trackClick('cta_view_pricing', 'home_hero');
+trackFormSubmit('contact_form', true);
+```
+
+## Env keys
+
+- `VITE_CLARITY_PROJECT_ID` — when set, calls `window.clarity('event', ...)` if the Clarity script is loaded
+- `VITE_AMPLITUDE_API_KEY` — when set, calls `window.amplitude.track(...)` if the Amplitude SDK is loaded
+
+When neither is set, the dual-write is a silent no-op — Firebase Analytics still receives the event so the dashboard does not go blind.

package/docs/capacitor-official-plugins.md

@@ -0,0 +1,46 @@
+# Capacitor Official Plugins (R-035)
+
+Status of official `@capacitor/*` plugins in the `website/` app (the only Capacitor consumer in this monorepo besides example-apps).
+
+**Last verified:** 2026-04-25
+
+## Installed
+
+| Plugin | Status | Notes |
+|---|---|---|
+| `@capacitor/android` | ✅ | Platform |
+| `@capacitor/ios` | ✅ | Platform |
+| `@capacitor/core` | ✅ | Required |
+| `@capacitor/cli` | ✅ | DevDep — sync/open commands |
+| `@capacitor/motion` | ✅ | Used for parallax-style marketing-page interactions |
+| `@capacitor/preferences` | ✅ | Used in place of localStorage where needed |
+| `@capacitor/privacy-screen` | ✅ | Hides sensitive content during app switcher |
+
+## Deliberately not installed
+
+The website is a marketing site + dashboard. Many plugins from the global rule list don't apply:
+
+| Plugin | Reason for skip |
+|---|---|
+| `@capacitor/app-launcher` | No deep-linking to other apps |
+| `@capacitor/app` | Available implicitly; can be added when an explicit lifecycle handler is needed |
+| `@capacitor/barcode-scanner` | No scanner UX |
+| `@capacitor/browser` | All external links go through anchor `target="_blank"` — works in webview |
+| `@capacitor/camera` | No camera feature |
+| `@capacitor/clipboard` | Use `navigator.clipboard.writeText` (works on web + capacitor) |
+| `@capacitor/device` | Add only if device-specific UX is required |
+| `@capacitor/dialog` | Native confirms not needed; we use Radix dialogs |
+| `@capacitor/geolocation` | No geo feature |
+| `@capacitor/haptics` | Add when there's a flow that warrants haptic feedback (e.g. successful upload) |
+| `@capacitor/network` | Add when offline state UX is implemented |
+| `@capacitor/screen-orientation` | Web app, no orientation lock needed |
+| `@capacitor/share` | `navigator.share` works; add native plugin if mobile share sheet is required |
+| `@capacitor/splash-screen` | Configured via Capacitor config plugin block; no extra package needed |
+| `@capacitor/toast` | We use Radix-based in-app toasts (`src/lib/toast.ts`) |
+
+## Adding a new plugin (procedure)
+
+1. Add to `website/package.json` (`yarn add @capacitor/<plugin>`).
+2. Run `yarn cap:sync` to wire native code into Android + iOS.
+3. Update this registry's "Installed" table.
+4. If the plugin needs runtime permissions (camera, geolocation, contacts, etc.), update the merged manifest, privacy policy, data-safety form, and per the global rules — declare the permission AT REQUEST TIME, not at app launch.

package/docs/capawesome-plugins.md

@@ -0,0 +1,29 @@
+# Capawesome Plugins (R-036)
+
+Status of `@capawesome/*` plugins in the `website/` Capacitor app.
+
+**Last verified:** 2026-04-25
+
+## Installed
+
+| Plugin | Status | Notes |
+|---|---|---|
+| `@capawesome/capacitor-app-shortcuts` | ✅ | Long-press app icon shortcuts (e.g., "Upload bundle") |
+
+## Pending — required before any Play Store / App Store submission
+
+Per the global R-036 rule, these are recommended for hybrid apps targeting current Android + iOS versions. The website is not yet submitted to either store; once a store submission is planned, install and wire the items below.
+
+| Plugin | When to add | Why |
+|---|---|---|
+| `@capawesome/capacitor-android-edge-to-edge-support` | Before Play Store submission | Android 15 mandates edge-to-edge layouts. |
+| `@capawesome/capacitor-app-update` | Before stores | In-app prompt when a newer native binary exists. |
+| `@capawesome/capacitor-app-review` | Before stores | Native review prompt at high-engagement moments. |
+| `@capawesome/capacitor-badge` | Optional | Icon badge count — only useful with notifications. |
+
+## Adding procedure
+
+1. `yarn add @capawesome/<plugin>` in `website/`.
+2. `yarn cap:sync` to wire Android + iOS.
+3. Configure as documented at https://capawesome.io/plugins/ — most need an Android `MainActivity` registration line (auto-handled by `cap sync` for current Capacitor versions).
+4. Update this registry.