native-update 1.4.9 → 2.0.0

package/docs/project-knowledge-base/02-routes-pages-forms-users.md

@@ -0,0 +1,346 @@
+# Native Update Routes, Pages, Forms, and Users
+
+## Metadata
+
+- **Reference Date:** 2026-03-16
+- **Last Updated:** 2026-03-16
+
+## Route Inventory
+
+### Public Marketing and Info Routes
+
+| Route | Page | Access | Purpose |
+|------|------|--------|---------|
+| `/` | HomePage | Public | Main landing page and primary product pitch |
+| `/features` | FeaturesPage | Public | Feature breakdown across OTA, app updates, and reviews |
+| `/pricing` | PricingPage | Public | Pricing/beta/commercial positioning page |
+| `/docs` | DocsPage | Public | Docs hub and guided docs entry |
+| `/docs/*` | DocsMarkdownPage | Public | Render markdown docs pages from public docs set |
+| `/about` | AboutPage | Public | Mission, project story, differentiators, creator profile |
+| `/contact` | ContactPage | Public | Contact methods, support info, FAQ |
+| `/privacy` | PrivacyPage | Public | Privacy policy |
+| `/terms` | TermsPage | Public | Terms of service |
+| `/data-deletion` | DataDeletionPage | Public | Data/account deletion policy |
+| `/cookies` | CookiePolicyPage | Public | Cookie policy |
+| `/security` | SecurityPage | Public | Security messaging and practices |
+| `/sitemap` | SitemapPage | Public | Human-friendly route explorer/search |
+| `/feed` | FeedPage | Public | Human-facing public content feed/search |
+
+### Auth Routes
+
+| Route | Page | Access | Purpose |
+|------|------|--------|---------|
+| `/login` | LoginPage | Public | Sign in with Google |
+| `/signup` | SignupPage | Public | Sign up with Google / beta onboarding |
+
+### Protected Dashboard Routes
+
+| Route | Page | Access | Purpose |
+|------|------|--------|---------|
+| `/dashboard` | DashboardOverview | Authenticated user | Main dashboard metrics and quick actions |
+| `/dashboard/apps` | AppsPage | Authenticated user | Create, edit, delete, and browse owned apps |
+| `/dashboard/apps/:appId` | AppDetailPage | Authenticated user | Per-app details, builds, channels, and rollout state |
+| `/dashboard/builds` | BuildsPage | Authenticated user | Browse/filter builds |
+| `/dashboard/builds/:buildId` | BuildDetailPage | Authenticated user | Detailed build record view |
+| `/dashboard/upload` | UploadPage | Authenticated user | Publish ZIP bundle and update manifests |
+| `/dashboard/drive` | GoogleDrivePage | Authenticated user | Connect/disconnect Drive and review storage footprint |
+| `/dashboard/config` | ConfigPage | Authenticated user | Show recommended backend/config integration guidance |
+| `/dashboard/settings` | SettingsPage | Authenticated user | Account preferences, password flow, account deletion |
+| `/dashboard/rollouts` | RolloutsPage | Authenticated user | Manage rollout percentages and pause/resume rollouts |
+| `/dashboard/analytics` | AnalyticsPage | Authenticated user | View aggregated update analytics |
+
+### Admin Routes
+
+| Route | Page | Access | Purpose |
+|------|------|--------|---------|
+| `/admin` | AdminOverview | Admin only | Admin overview metrics |
+| `/admin/users` | AdminUsersPage | Admin only | Search/browse user accounts |
+| `/admin/apps` | AdminAppsPage | Admin only | Search/browse all apps |
+| `/admin/builds` | AdminBuildsPage | Admin only | Search/filter all builds |
+
+## Access and Guard Behavior
+
+### ProtectedRoute
+
+- Requires authenticated user
+- Computes email verification from Firebase auth state or Google provider context
+- Redirects unauthenticated users to `/login`
+- If email verification is required and not satisfied, redirects to `/verify-email`
+
+### AdminRoute
+
+- Requires authenticated user
+- loads the Firestore user document
+- allows access only when `isAdmin === true`
+- redirects non-admin users to `/dashboard`
+
+## User Types and Permissions
+
+### Public Visitor
+
+- Can view product, docs, legal, sitemap, feed, and contact pages
+- Cannot access dashboard or admin
+
+### Signed-In Product User
+
+- Signs in via Google popup
+- has a Firestore `users/{uid}` document
+- can manage their own apps/builds/settings
+- can connect Google Drive
+
+### Admin User
+
+- Same as signed-in user plus `isAdmin: true`
+- can access admin metrics and cross-user inventories
+
+### App Runtime Consumer
+
+- Uses plugin APIs and manifest endpoints
+- not a website operator account
+
+## Page-Level Notes
+
+### HomePage
+
+- Hero positioning: complete update solution for Capacitor
+- Calls to action: get started, view docs
+- Highlights three core pillars: OTA updates, native app updates, in-app reviews
+
+### FeaturesPage
+
+- Feature cards for OTA, native app updates, and reviews
+- Messaging includes delta updates, rollback, channels, encryption, analytics, priority levels, and rate limiting
+
+### AboutPage
+
+- Includes project mission
+- explains why project exists
+- highlights open-source positioning
+- includes creator profile and contact links
+
+### ContactPage
+
+- No typed form submission flow
+- Uses direct contact methods: email, WhatsApp, LinkedIn, portfolio, docs, NPM link
+- Includes support-hour information and FAQ
+
+### DocsPage / DocsMarkdownPage
+
+- DocsPage acts as a rich docs landing surface
+- DocsMarkdownPage renders markdown docs pages from the public docs payload
+
+### SitemapPage and FeedPage
+
+- Search/filter style discovery experiences
+- use `Input` fields for route/content lookup
+- intended as human-friendly content navigation surfaces
+
+### DashboardOverview
+
+- Shows owned app/build summary state
+- includes CTA to upload first build
+
+### AppsPage
+
+- Central app management page
+- create/edit/delete dialog workflows
+- stores package id, description, platforms, and generates API key on creation
+
+### AppDetailPage
+
+- per-app management view
+- shows builds and rollout state
+- links to upload and rollout workflows
+
+### BuildsPage / BuildDetailPage
+
+- list and inspect build history
+- filter by app/channel/status/platform
+- build detail includes upload time, uploader, duration, and release metadata
+
+### UploadPage
+
+- Core publish UI
+- requires Google Drive connection
+- uploads ZIP bundle and file manifest
+- publishes Firestore manifest data
+
+### GoogleDrivePage
+
+- connects/disconnects Drive
+- shows Drive connection status, connected email, folder list, file count, and total size
+
+### ConfigPage
+
+- instructional/configuration surface
+- presents recommended production path: browser upload to Google Drive + Firestore metadata publishing + app-side reads
+
+### SettingsPage
+
+- account profile details
+- preferences
+- appearance
+- password change for email/password providers
+- account deletion confirmation flow
+
+### RolloutsPage
+
+- percentage controls
+- pause/resume actions
+- edit modal with numeric and range input
+- rollout best practices guidance
+
+### AnalyticsPage
+
+- filters by app and channel
+- aggregates analytics batch data across time range
+- intended for download/install/error/rollback analysis
+
+### Admin Pages
+
+- AdminOverview aggregates cross-system metrics
+- AdminUsersPage supports user search/filtering
+- AdminAppsPage supports app search/filtering
+- AdminBuildsPage supports build search/filtering by multiple fields
+
+## Form and Input Inventory
+
+### LoginPage
+
+- **Action:** Google sign-in button
+- **Inputs:** No text input fields
+- **Errors handled:** popup closed, popup blocked, generic auth failure
+
+### SignupPage
+
+- **Action:** Google sign-up button
+- **Inputs:** No text input fields
+- **Purpose:** fast account creation for beta onboarding
+
+### AppsPage Create/Edit App Dialog
+
+- **Fields:**
+  - App name
+  - Package ID
+  - Description
+  - Platforms: Android, iOS, Web
+- **Validation:**
+  - app name required, minimum length
+  - package ID required and regex-validated
+  - at least one platform required
+- **Side effects on create:**
+  - creates app doc
+  - generates API key
+  - creates `apiKeys/{apiKey}` doc
+  - increments user `appsCount`
+
+### AppsPage Delete Dialog
+
+- **Purpose:** destructive app deletion
+- **Effects:** deletes manifests under app API key, deletes API key doc, deletes app doc, decrements user `appsCount`
+
+### UploadPage Publish Form
+
+- **Fields:**
+  - file picker / drag-drop ZIP
+  - app select
+  - channel select
+  - platform select
+  - version input
+  - build number input
+  - release notes textarea
+- **Validation:**
+  - app required
+  - version required
+  - build number required
+  - ZIP file required
+  - Drive connection required
+- **Flow:**
+  - validate file
+  - calculate SHA-256
+  - generate file manifest
+  - upload ZIP to Drive
+  - upload manifest JSON to Drive
+  - write build doc
+  - update Firestore manifest docs
+  - navigate to app detail
+
+### SettingsPage Preferences
+
+- **Fields:**
+  - email notifications toggle
+  - update notifications toggle
+  - theme select
+  - language select
+- **Action:** save preferences to user doc
+
+### SettingsPage Change Password
+
+- **Fields:**
+  - current password
+  - new password
+  - confirm new password
+- **Validation:**
+  - required fields
+  - minimum new password length
+  - confirmation match
+- **Special note:** only shown for email/password provider, not Google-only users
+
+### SettingsPage Delete Account
+
+- **Field:** confirmation input requiring exact `DELETE`
+- **Action:** delete Firestore user doc and Firebase auth user
+
+### RolloutsPage Edit Modal
+
+- **Fields:**
+  - rollout percentage numeric input
+  - rollout percentage range slider
+- **Action:** update `rollout.percentage`
+
+### BuildsPage Filters
+
+- search input
+- app filter
+- channel filter
+- platform filter
+- status filter
+
+### AdminBuildsPage Filters
+
+- search input
+- app filter
+- user filter or owner-related filtering
+- channel/status/platform filters
+
+### AdminUsersPage Filters
+
+- search input
+
+### AdminAppsPage Filters
+
+- search input
+
+### FeedPage and SitemapPage
+
+- search input for route/content discovery
+
+## Contact and Support Surfaces
+
+### ContactPage URLs
+
+- `mailto:aoneahsan@gmail.com`
+- `https://www.npmjs.com/package/native-update`
+- `https://wa.me/923046619706`
+- `https://linkedin.com/in/aoneahsan`
+- `https://aoneahsan.com`
+- internal docs link: `/docs`
+
+## Important UX and Product Notes
+
+- Dashboard is clearly owner/operator tooling, not consumer UI
+- Google sign-in is primary auth path
+- Google Drive is central to the no-cost publishing workflow
+- App creation is a prerequisite for upload
+- Drive connection is a prerequisite for upload
+- Rollouts are edited from manifest data, not from a separate dedicated rollout service

package/docs/project-knowledge-base/03-tech-stack-modules-services.md

@@ -0,0 +1,347 @@
+# Native Update Tech Stack, Modules, and Services
+
+## Metadata
+
+- **Reference Date:** 2026-03-16
+- **Last Updated:** 2026-03-16
+
+## Monorepo Structure
+
+| Path | Purpose |
+|------|---------|
+| `src/` | Main TypeScript plugin implementation |
+| `android/` | Android native plugin implementation in Kotlin |
+| `ios/` | iOS native plugin implementation in Swift |
+| `cli/` | CLI package and commands |
+| `website/` | Marketing site and dashboard application |
+| `website/functions/` | Legacy Firebase Functions backend/reference backend |
+| `example-apps/` | Example frontend and backend projects |
+| `docs/` | Public docs, planning, reports, and knowledge artifacts |
+
+## Root Package Tech Stack
+
+- Node.js `>=24.13.0`
+- TypeScript
+- Rollup
+- Capacitor 8 ecosystem packages
+- Vitest
+- ESLint
+- Prettier
+- Commander
+- Express
+- Archiver
+- Chalk
+- Ora
+- Prompts
+
+## Website Tech Stack
+
+- React 19
+- TypeScript
+- Vite 7
+- Tailwind CSS v4
+- Firebase Auth
+- Firestore
+- Google Identity Services
+- Google Drive API
+- Zustand
+- Framer Motion
+- Radix UI primitives
+- D3
+- React Router
+- React Markdown
+
+## CLI Package
+
+### Entry
+
+- `cli/index.js`
+
+### Commands
+
+- `init`
+- `bundle-create`
+- `bundle-sign`
+- `bundle-verify`
+- `keys-generate`
+- `backend-create`
+- `server-start`
+- `monitor`
+
+### CLI Value
+
+- scaffolds projects
+- generates bundles
+- signs and verifies release artifacts
+- generates keys
+- starts local server flow
+- supports deployment monitoring
+
+## Core Plugin Module Inventory
+
+### `src/live-update/`
+
+- `bundle-manager.ts`
+- `certificate-pinning.ts`
+- `delta-processor.ts`
+- `download-manager.ts`
+- `rollout-checker.ts`
+- `update-manager.ts`
+- `version-manager.ts`
+
+**Purpose:** runtime live update logic, version checks, download/install handling, delta support, and rollout-aware decisions.
+
+### `src/app-update/`
+
+- `app-update-checker.ts`
+- `app-update-installer.ts`
+- `app-update-manager.ts`
+- `app-update-notifier.ts`
+- `platform-app-update.ts`
+- `types.ts`
+- `index.ts`
+
+**Purpose:** native binary update checks, install flows, platform-specific update behavior, and notifications.
+
+### `src/app-review/`
+
+- `app-review-manager.ts`
+- `platform-review-handler.ts`
+- `review-conditions-checker.ts`
+- `review-rate-limiter.ts`
+- `types.ts`
+- `index.ts`
+
+**Purpose:** smart in-app review prompting, timing/eligibility checks, platform-specific review invocation.
+
+### `src/background-update/`
+
+- `background-scheduler.ts`
+- `notification-manager.ts`
+- `index.ts`
+
+**Purpose:** scheduling, notifications, and background update orchestration.
+
+### `src/core/`
+
+- `analytics.ts`
+- `cache-manager.ts`
+- `config.ts`
+- `errors.ts`
+- `event-emitter.ts`
+- `logger.ts`
+- `performance.ts`
+- `plugin-manager.ts`
+- `security.ts`
+
+**Purpose:** shared foundations for config, events, logging, analytics, errors, caching, and general plugin behavior.
+
+### `src/security/`
+
+- `crypto.ts`
+- `validator.ts`
+
+**Purpose:** cryptographic helpers and validation utilities.
+
+### `src/firestore/`
+
+- `firestore-client.ts`
+- `manifest-reader.ts`
+- `schema.ts`
+- `index.ts`
+- rules/indexes files
+
+**Purpose:** Firestore-backed manifest access and schema definition for update metadata.
+
+### Root Entry Files
+
+- `src/index.ts`
+- `src/plugin.ts`
+- `src/definitions.ts`
+- `src/web.ts`
+
+**Purpose:** export surface, Capacitor plugin bindings, typings, and web fallback behavior.
+
+## Native Android Modules
+
+| File | Role |
+|------|------|
+| `NativeUpdatePlugin.kt` | Main Android plugin entry |
+| `LiveUpdatePlugin.kt` | OTA/live update Android implementation |
+| `AppUpdatePlugin.kt` | App update Android integration |
+| `AppReviewPlugin.kt` | In-app review Android integration |
+| `BackgroundUpdatePlugin.kt` | Background update orchestration |
+| `BackgroundUpdateManager.kt` | Background scheduling/management logic |
+| `BackgroundUpdateWorker.kt` | Worker-based background task execution |
+| `BackgroundNotificationManager.kt` | Notification support |
+| `NotificationActionReceiver.kt` | Notification action handling |
+| `SecurityManager.kt` | Android security helpers |
+
+## Native iOS Modules
+
+| File | Role |
+|------|------|
+| `NativeUpdatePlugin.swift` | Main iOS plugin entry |
+| `NativeUpdatePlugin.m` | Objective-C bridge/registration layer |
+| `LiveUpdatePlugin.swift` | OTA/live update implementation |
+| `WebViewConfiguration.swift` | web view config support for live updates |
+| `AppUpdatePlugin.swift` | App update iOS behavior |
+| `AppReviewPlugin.swift` | StoreKit review handling |
+| `BackgroundUpdatePlugin.swift` | background update behavior |
+| `BackgroundNotificationManager.swift` | notification support |
+| `SecurityManager.swift` | iOS security helpers |
+
+## Frontend Services
+
+### `auth-service.ts`
+
+- Google sign-in via Firebase popup
+- first-login user doc creation
+- existing-user last-login update
+- admin flag refresh for owner email
+- logout support
+
+### `google-drive-service.ts`
+
+- load Google Identity Services SDK
+- request Drive scopes
+- connect/disconnect Drive
+- persist token metadata in Firestore
+- fetch user info from Google
+- list files
+- create folder hierarchy
+- upload files
+- make files public
+- maintain Drive connection status
+
+### `bundle-upload-service.ts`
+
+- validate bundle file
+- calculate SHA-256 checksum
+- generate file manifest from ZIP
+- upload bundle and manifest to Drive
+- write build document
+- update manifest document
+- track progress stages
+
+### `manifest-generator.ts`
+
+- derive per-file manifest from ZIP
+- compare old/new manifests
+- estimate delta size
+- decide if delta is worthwhile
+- extract files from ZIP
+
+### Other Frontend Services
+
+- `auth-service.ts`
+- `bundle-upload-service.ts`
+- `google-drive-service.ts`
+- `manifest-generator.ts`
+- capacitor service wrappers under `website/src/services/capacitor/`
+
+## Frontend State Stores
+
+### `appsStore`
+
+- fetch user apps
+- fetch app by ID
+- create/update/delete app
+- manage selected app and errors
+
+### `buildsStore`
+
+- fetch builds per app/user/channel
+- fetch build by ID
+- fetch latest builds
+- update build status
+- delete builds
+
+### `rolloutsStore`
+
+- fetch rollout state from manifests
+- fetch rollout by app/channel
+- update rollout config
+- pause/resume/start rollout
+
+### `analyticsStore`
+
+- fetch analytics batches
+- aggregate downloads, installs, errors, rollbacks
+- build platform/version summaries
+- manage date range
+
+## Website Backend Reference (`website/functions`)
+
+### Main Areas
+
+- `config/firebase.ts`
+- `middleware/auth.ts`
+- `middleware/validation.ts`
+- `routes/apps.ts`
+- `routes/builds.ts`
+- `routes/users.ts`
+- `utils/errors.ts`
+- `utils/validators.ts`
+- `index.ts`
+
+**Purpose:** a Firebase Functions + Express reference backend retained in the repo.
+
+## Example Apps
+
+### `example-apps/react-capacitor/`
+
+- frontend example demonstrating plugin use in a Capacitor app
+
+### `example-apps/node-express/`
+
+- backend example using Node.js + Express
+
+### `example-apps/firebase-backend/`
+
+- Firebase-based backend example
+
+## Testing Modules Present
+
+### TypeScript Tests
+
+- bundle manager
+- config
+- delta processor
+- firestore schema
+- integration
+- manifest reader
+- rollout checker
+- security
+- version manager
+
+### iOS Tests
+
+- app update tests
+- app review tests
+- background update tests
+- live update tests
+- security tests
+
+### Android Tests
+
+- app review plugin tests
+- app update plugin tests
+- background notification manager tests
+- background worker tests
+- live update plugin tests
+- security manager tests
+
+### E2E
+
+- OTA update flow
+- download progress
+- channel switching
+- error handling
+
+## Important Architectural Direction
+
+- Treat the plugin as runtime infrastructure.
+- Treat the website as management and distribution tooling.
+- Treat Firestore manifests as a key source of truth for client update checks.
+- Treat Google Drive as the preferred no-cost storage destination for uploaded artifacts in the website flow.