native-update 1.4.9 → 3.1.0

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

@@ -0,0 +1,379 @@
+# Native Update Tech Stack, Modules, and Services
+
+## Metadata
+
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
+
+## 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 (React 19 + Vite + Capacitor wrapper) |
+| `backend/` | Laravel 11 + Nova 5 SaaS backend (only backend; canonical persistence layer) |
+| `example-apps/` | Example frontend (`react-capacitor/`) and backend (`node-express/`) projects |
+| `docs/` | Public docs, planning, reports, and knowledge artifacts |
+
+## Root Package Tech Stack
+
+- Node.js `>=24.13.0`
+- TypeScript
+- Rollup
+- Capacitor 8 ecosystem packages
+- ESLint (`@typescript-eslint/*` flat config; `@eslint/js` is BANNED)
+- Prettier
+- Commander
+- Express
+- Archiver
+- Chalk
+- Ora
+- Prompts
+
+## Website Tech Stack
+
+- React 19 + TypeScript
+- Vite 7
+- Tailwind CSS v4
+- Google OAuth via Laravel Socialite (backend-driven; no Firebase Auth in the SPA)
+- Sanctum bearer tokens persisted via `@capacitor/preferences` (native) / `localStorage` (web)
+- TanStack Query (data plane with hierarchical keys + URL-state pagination + keepPreviousData)
+- Axios (`src/lib/api.ts` with 401-clear-and-redirect interceptor)
+- Zustand (local UI state)
+- Framer Motion (animations)
+- Radix UI primitives (Dialog, Tooltip, etc.)
+- D3 (charts)
+- React Router
+- React Markdown
+- Capacitor 8 (mobile wrapper for the dashboard)
+
+## Backend Tech Stack
+
+- Laravel 11
+- Laravel Nova 5 (admin UI at `/nova`)
+- Laravel Socialite (Google OAuth)
+- Laravel Sanctum (personal access tokens for the SPA)
+- `spatie/laravel-permission` (RBAC; `sanctum` guard; roles `super-admin`, `admin`, `user`)
+- MySQL (single source of persistence — no Firestore branch)
+- PHP 8.2+
+- Composer
+- Pest / PHPUnit (~136 tests at last finalization audit)
+- Google Drive PHP SDK (server-side OAuth; tokens encrypted via Laravel's encrypter)
+
+## CLI Package
+
+### Entry
+
+- `cli/index.js`
+
+### Commands
+
+- `init`
+- `bundle-create`
+- `bundle-sign`
+- `bundle-verify`
+- `keys-generate`
+- `backend-create` (emits scaffolds with `TODO[SCAFFOLD-IMPLEMENT-BEFORE-DEPLOY]` markers)
+- `server-start`
+- `monitor`
+
+### CLI Value
+
+- scaffolds projects
+- generates bundles
+- signs and verifies release artifacts (RSA-2048 / RSA-4096 / EC P-256 / EC P-384)
+- generates keypairs
+- starts local server flow
+- supports deployment monitoring (interval+spinner cleanup, signal handlers, failure bail)
+
+## 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 (SHA-256, RSA-SHA256 verify).
+
+### 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.
+
+Note: `src/firestore/` was removed in v3.0.0 (2026-05-04). The plugin no longer carries any Firestore code; manifest reads happen over plain HTTPS against any user-controlled endpoint.
+
+## Native Android Modules
+
+| File | Role |
+|------|------|
+| `NativeUpdatePlugin.kt` | Main Android plugin entry |
+| `LiveUpdatePlugin.kt` | OTA/live update Android implementation |
+| `AppUpdatePlugin.kt` | App update Android integration (Play Core) |
+| `AppReviewPlugin.kt` | In-app review Android integration (Play Review) |
+| `BackgroundUpdatePlugin.kt` | Background update orchestration |
+| `BackgroundUpdateManager.kt` | Background scheduling/management logic |
+| `BackgroundUpdateWorker.kt` | WorkManager-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 `SKStoreReviewController` handling |
+| `BackgroundUpdatePlugin.swift` | BGTaskScheduler background update behavior |
+| `BackgroundNotificationManager.swift` | notification support |
+| `SecurityManager.swift` | iOS security helpers |
+
+## Frontend Services (`website/src/services/`)
+
+### `auth-service.ts`
+
+- Initiates Laravel Socialite redirect for Google sign-in
+- handles `/auth/callback` token persistence via `lib/auth-token.ts`
+- logout flow (deletes Sanctum token, broadcasts event, clears Drive cache)
+
+### `apps-api-service.ts`
+
+- TanStack Query hooks for App CRUD against `/api/dashboard/apps/*`
+
+### `google-drive-service.ts`
+
+- starts the server-side Drive OAuth flow (no browser SDK)
+- requests Drive auth URL from the backend
+- posts callback code back to the backend
+- reads Drive connection status from `/api/dashboard/me`
+- lists files via backend proxy endpoints
+
+### `bundle-upload-service.ts`
+
+- validates ZIP file (size, type)
+- multipart POST to `/api/dashboard/apps/{app}/builds` with progress tracking
+- triggers TanStack Query cache invalidation on success
+
+### `manifest-generator.ts`
+
+- derives per-file manifest from ZIP (client-side, for delta hints)
+- compares old/new manifests
+- estimates delta size
+- decides if delta is worthwhile
+
+### `themeSync.ts`
+
+- syncs theme preferences to `users.preferences` JSON via `/api/dashboard/preferences`
+
+### Other Frontend Services
+
+- capacitor service wrappers under `website/src/services/capacitor/`
+
+## Frontend State Stores
+
+### `appsStore`
+
+- TanStack-Query-backed cache for user apps (hierarchical keys)
+- selected-app tracking + error surface
+
+### `buildsStore`
+
+- TanStack-Query-backed cache for builds per app/user/channel
+- pagination + filter state encoded in URL search params
+
+### `rolloutsStore`
+
+- fetches rollout state from Build rows
+- pause/resume/percentage mutations
+
+### `analyticsStore`
+
+- fetches aggregated events from `/api/dashboard/analytics`
+- builds platform/version summaries
+- manages date range
+
+## Backend Source Tree (`backend/`)
+
+### Controllers (`app/Http/Controllers/`)
+
+- `Auth/OAuthController` (Socialite redirect + callback + Sanctum token issuance)
+- `Dashboard/AnalyticsDashboardController`
+- `Dashboard/ApiKeyController`
+- `Dashboard/AppController`
+- `Dashboard/BuildController`
+- `Dashboard/GoogleDriveController`
+- `Dashboard/MeController`
+- `Dashboard/PreferencesController`
+- `Dashboard/RolloutController`
+- `Dashboard/SigningKeyController`
+- `Dashboard/SubscriptionController`
+- `Api/UpdateController` (mobile `/api/v1/updates/check`)
+- `Api/BundleController` (signed `/api/v1/bundles/{build}/download`)
+- `Api/AnalyticsController` (mobile `/api/v1/analytics/*`)
+
+### Eloquent Models (`app/Models/`)
+
+- `User`
+- `App`
+- `ApiKey`
+- `SigningKey`
+- `Build`
+- `Subscription`
+- `DeviceActivity`
+- `AnalyticsEvent`
+
+### FormRequest Validators (`app/Http/Requests/`)
+
+- `UpdateBuildRequest` and related Create/Update FormRequests for App, ApiKey, SigningKey
+
+### Routes
+
+- `routes/api.php` (all `/api/*` routes)
+- `routes/web.php` (Nova mounts + OAuth callback HTML stubs)
+- `routes/console.php` (Artisan commands including `native-update:role-assign`)
+
+### Policies + Gates
+
+- `User`, `App`, `Build`, `ApiKey`, `SigningKey` policies registered in `AuthServiceProvider`
+- `Gate::before` returns `true` for `super-admin` (full bypass)
+- `Nova/User.php` carries `canSee` guards for admin-only resources
+
+## Example Apps
+
+### `example-apps/react-capacitor/`
+
+- frontend example demonstrating plugin use in a Capacitor app
+- React 18 (stable downstream target; explained in its README "React 18 vs React 19" section)
+- capability cards: OTA basic, app-update (`getAppUpdateInfo`/`openAppStore`), app-review (`canRequestReview`/`requestReview`), background-update (toggle with `allowMeteredConnection`/`nextCheckTime`)
+
+### `example-apps/node-express/`
+
+- minimal Node.js + Express backend example
+- ~160 lines, dissected in `docs/backend/node-express-minimal.md`
+- demonstrates the manifest-endpoint contract without a full SaaS
+
+Note: `example-apps/firebase-backend/` was removed in v3.0.0 (2026-05-04).
+
+## Testing Modules Present
+
+### TypeScript Tests (root plugin)
+
+- bundle manager
+- config
+- delta processor
+- integration (live-update flow)
+- manifest reader
+- rollout checker
+- security
+- version manager
+- 62/62 passing at last verification
+
+### Backend Tests (`backend/tests/`)
+
+- OAuth + Sanctum + Spatie + UpdateBuildRequest FormRequest + PayPal webhook + BundleUpload + UserLicense
+- ~136 tests passing (`php artisan test`)
+
+### 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 (`e2e/`)
+
+- OTA update flow
+- download progress
+- channel switching
+- error handling
+
+### Microbenchmarks (`tools/bench/`)
+
+- `verify-checksum.bench.ts` (SHA-256 over 1/5/20 MB)
+- `verify-signature.bench.ts` (RSA-2048 + RSA-4096 SHA-256 verify over 5 MB)
+
+## Important Architectural Direction
+
+- Treat the plugin as runtime infrastructure.
+- Treat the website as management and distribution tooling.
+- Treat Laravel + MySQL as the single source of truth for App, Build, and User data.
+- Treat Sanctum personal access tokens as the only credential the SPA holds; the dashboard reads its identity from `/api/dashboard/me`.
+- Treat Google Drive as the canonical storage destination for uploaded bundle ZIPs (server-side OAuth tokens, encrypted at rest).
+- Treat the mobile API plane (`/api/v1/*`) as a separate auth surface (per-app API keys, not Sanctum).

package/docs/project-knowledge-base/04-data-models-integrations.md

@@ -0,0 +1,244 @@
+# Native Update Data Models and Integrations
+
+## Metadata
+
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
+
+## Main Integration Surfaces
+
+- Google OAuth via Laravel Socialite (auth provider)
+- Laravel Sanctum (token plane for the SPA)
+- `spatie/laravel-permission` (RBAC inside MySQL)
+- Google Drive API (server-side OAuth; bundle storage)
+- FilesHub (`https://fileshub.zaions.com`) for miscellaneous user-uploaded assets
+- PayPal (webhook for subscription events)
+- Capacitor runtime APIs
+- Android native APIs (Play Core update, Play Review, WorkManager)
+- iOS native APIs (StoreKit SKStoreReviewController, BGTaskScheduler)
+
+## Authentication Model
+
+### Sign-In Method
+
+- Only auth flow is Google OAuth via Laravel Socialite
+- SPA navigates to `${VITE_API_URL}/auth/google/redirect`
+- Laravel's `OAuthController` redirects to Google, receives the callback, exchanges the code, and creates/updates the `users` row keyed by `google_id`
+- On success, Laravel issues a Sanctum personal access token and redirects to `${FRONTEND_URL}/auth/callback?token=…`
+- SPA's `CallbackPage` stores the plain-text token (shown once) via `setAuthToken()` and navigates to `/dashboard`
+
+### Role Assignment
+
+- First sign-in → assigns the `user` role (default)
+- Emails in `ADMIN_EMAILS` env → auto-assigned `super-admin`
+- Manual: `php artisan native-update:role-assign <email> <role>` (revokes existing tokens to force re-login with new role)
+- Seeder: `php artisan db:seed --class=RolesPermissionsSeeder` (idempotent)
+
+### Token Lifecycle
+
+- Default TTL: 7 days (configurable via `SANCTUM_TOKEN_EXPIRATION`)
+- Stored as `Bearer` header on every `/api/dashboard/*` and `/api/admin/*` request
+- 401 from any endpoint → axios interceptor clears the token, broadcasts a logout event, redirects to `/login`
+- Logout: `DELETE /api/dashboard/me/token` revokes the current token; on multi-device logout, all of the user's tokens are revoked
+
+## MySQL Schema (Laravel migrations)
+
+Migrations live in `backend/database/migrations/`. The following tables exist:
+
+### `users`
+
+- Standard Laravel fields plus:
+- `google_id` (unique; primary identity key)
+- `name`, `email`, `avatar_url`
+- `google_drive_access_token`, `google_drive_refresh_token`, `google_drive_token_expires_at` (encrypted via Laravel encrypter)
+- `google_drive_email`, `google_drive_connected_at`
+- `preferences` (JSON: email notifications, update notifications, theme, language, accent color, etc.)
+- admin-control flags (block, suspend, notes)
+- `apps_count`, `builds_count`, `storage_used` (denormalized counters)
+- standard timestamps + soft-delete
+
+### `apps`
+
+- `user_id` (foreign key to `users`)
+- `name`, `package_id` (unique per user), `description`, `icon_url`
+- `platforms` (JSON array: android/ios/web)
+- `channels` (JSON config)
+- `total_builds`, `active_users`, `last_build_at`
+- standard timestamps + soft-delete
+
+### `api_keys`
+
+- `app_id` (foreign key)
+- `key` (random token; used for mobile `/api/v1/*` plane)
+- `name`, `is_active`, `last_used_at`
+- standard timestamps
+
+### `signing_keys`
+
+- `app_id` (foreign key)
+- `name`
+- `algorithm` (RSA-2048 / RSA-4096 / EC P-256 / EC P-384)
+- `public_key` (PEM)
+- `private_key` (encrypted; backend-side only — never sent to the SPA)
+- `is_active`, `rotated_at`
+- standard timestamps
+
+### `builds`
+
+- `id`
+- `user_id`, `app_id`
+- `version`, `build_number`
+- `channel`, `platform`
+- `file_name`, `file_size`, `mime_type`
+- `checksum` (SHA-256)
+- `signature` (RSA-SHA256 base64)
+- `drive_file_id`, `drive_file_url`, `drive_folder_id`
+- `fileshub_object_id` (when FilesHub used instead of Drive)
+- `file_manifest` (JSON: per-entry checksums for delta hints)
+- `release_notes`, `release_type`, `is_pre_release`
+- `min_native_version`
+- `uploaded_at`, `uploaded_by`, `upload_duration`
+- `status` (uploading / processing / active / archived / failed)
+- `processing_steps` (JSON; multi-step state)
+- `analytics` (JSON snapshot)
+- rollout config inline:
+  - `rollout_enabled`
+  - `rollout_percentage`
+  - `rollout_start_time`, `rollout_end_time`
+  - `target_segments` (JSON; optional)
+- standard timestamps + soft-delete
+
+### `subscriptions` + `subscription_items`
+
+- billing model (Stripe-style + PayPal provider added 2026-04-18)
+- `provider` (stripe / paypal), `provider_id`
+- `status`, `current_period_start`, `current_period_end`
+- per-item quantities + plan refs
+
+### `device_activities`
+
+- mobile-side telemetry (one row per active device)
+- last-seen, version installed, channel, platform metadata
+
+### `analytics_events`
+
+- per-event analytics (update checks, downloads, installs, rollbacks, errors)
+- `app_id`, `channel`, `platform`, `event_type`, `payload` (JSON)
+- aggregated by `AnalyticsDashboardController` for the dashboard
+
+### `personal_access_tokens` (Sanctum)
+
+- Sanctum's default token table
+- `tokenable_type`, `tokenable_id`, `name`, `token` (hashed), `abilities`, `last_used_at`, `expires_at`
+
+### Spatie permission tables
+
+- `roles`, `permissions`, `model_has_roles`, `model_has_permissions`, `role_has_permissions`
+- guard name: `sanctum`
+
+## Build Status Values
+
+- `uploading`
+- `processing`
+- `active`
+- `archived`
+- `failed`
+
+## Manifest Shape (returned by `/api/v1/updates/check`)
+
+Returned for each `appId + channel` combination, derived from the active Build row:
+
+```jsonc
+{
+  "appId": "com.example.myapp",
+  "channel": "production",
+  "current": {
+    "version": "1.2.0",
+    "bundleId": "<build uuid>",
+    "bundleUrl": "https://<signed-drive-or-fileshub-url>",
+    "manifestUrl": "<self-link>",
+    "checksum": "sha256-…",
+    "signature": "<base64 RSA-SHA256>",
+    "size": 1234567,
+    "releaseNotes": "…",
+    "releaseDate": "ISO-8601",
+    "mandatory": false,
+    "minNativeVersion": "1.0.0"
+  },
+  "deltas": [],
+  "rollout": {
+    "enabled": true,
+    "percentage": 25,
+    "startTime": "ISO-8601",
+    "endTime": null,
+    "targetSegments": null
+  },
+  "previousVersions": [],
+  "updatedAt": "ISO-8601",
+  "updatedBy": "<user id>"
+}
+```
+
+## Rollout Config
+
+- `enabled` (boolean)
+- `percentage` (0–100)
+- `startTime` / `endTime` (ISO-8601; optional bounds)
+- `targetSegments` (optional JSON; reserved for future segmentation)
+- `schedule` strategy (immediate / gradual / scheduled)
+
+## Delta Shape
+
+Used when the plugin asks for an incremental patch between two known versions:
+
+- `appId`
+- `fromVersion`, `toVersion`
+- `channel`
+- `patchUrl`, `patchSize`, `patchChecksum`
+- `sourceChecksum`, `targetChecksum`
+- `algorithm`, `compressionRatio`
+- `status`
+
+## Google Drive Integration Flow (server-side)
+
+### Connect Flow
+
+1. User clicks "Connect Google Drive" on `/dashboard/drive`
+2. SPA calls `GET /api/dashboard/google-drive/auth-url` → backend returns Google OAuth URL with Drive scope
+3. Browser does full-window redirect to Google
+4. Google redirects to `${FRONTEND_URL}/oauth/google-drive/callback?code=…`
+5. SPA `DriveCallbackPage` POSTs the code to `POST /api/dashboard/google-drive/callback`
+6. Backend exchanges the code, encrypts access + refresh tokens, persists on the `users` row
+7. Backend writes `google_drive_email` + `google_drive_connected_at` for UI display
+
+### Upload Flow (Laravel-driven)
+
+1. User selects ZIP on `/dashboard/upload`
+2. SPA multipart-POSTs to `POST /api/dashboard/apps/{app}/builds`
+3. `UpdateBuildRequest` FormRequest validates app ownership, version, build_number, file presence, file size, Drive-connected precondition
+4. Laravel computes SHA-256 of the uploaded ZIP
+5. Laravel signs the checksum with the app's active signing key (RSA-SHA256)
+6. Laravel uploads the ZIP to the user's Drive folder via encrypted tokens
+7. Laravel inserts the Build row in MySQL with `status='active'`
+8. Laravel returns the Build resource to the SPA
+9. TanStack Query invalidates the relevant cache keys → UploadPage navigates to app detail
+
+## App-Facing Manifest Paths
+
+- `GET /api/v1/updates/check?appId=…&channel=…&apiKey=…` → returns the active manifest
+- `GET /api/v1/bundles/{build}/download` → returns a short-lived signed URL to the bundle (default 30 min)
+
+## Security-Relevant Data Points
+
+- SHA-256 checksums are stored on every Build and verified on every download
+- RSA-SHA256 signatures are stored alongside checksums; plugin verifies against the configured public key (or array of public keys during a key rotation window)
+- Signing-key private keys never leave the Laravel host
+- Drive OAuth tokens are encrypted at rest using Laravel's encrypter (per-row, not per-app)
+- Sanctum token strings are hashed in the DB; the plain-text token is shown to the SPA exactly once at issuance
+
+## Data Ownership Notes
+
+- The website messaging emphasizes that user build files are stored in the user's Google Drive
+- All other data (account, app metadata, builds, analytics, signing keys, subscriptions) lives in the Laravel MySQL database
+- Account deletion soft-deletes the User row, revokes all Sanctum tokens, clears encrypted Drive tokens, cascades to apps/builds, and surfaces a confirmation page documenting what was removed
+- Privacy policy + data-deletion page reflect this exact architecture