native-update 1.4.9 → 2.0.0

package/docs/features/laravel-nova-backend/progress-tracker.json

@@ -0,0 +1,184 @@
+{
+  "feature": "Laravel + Nova Backend for Native Update",
+  "created": "2026-03-28",
+  "lastUpdated": "2026-03-28",
+  "status": "in_progress",
+  "estimatedWeeks": 5,
+  "currentPhase": 3,
+  "phases": [
+    {
+      "id": 1,
+      "name": "Laravel Project Setup",
+      "status": "completed",
+      "completedAt": "2026-03-28",
+      "estimatedDays": 5,
+      "tasks": [
+        { "task": "Create Laravel 11 project", "status": "completed" },
+        { "task": "Install and configure Nova 5", "status": "completed" },
+        { "task": "Configure MySQL database", "status": "completed", "note": "Using SQLite for dev, MySQL for production" },
+        { "task": "Set up Firebase token validation middleware", "status": "completed" },
+        { "task": "Configure S3/Cloudflare R2 storage", "status": "partial", "note": "Config added, needs keys" },
+        { "task": "Set up development environment (.env)", "status": "completed" }
+      ]
+    },
+    {
+      "id": 2,
+      "name": "Database Schema & Models",
+      "status": "completed",
+      "completedAt": "2026-03-28",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Create users migration and model", "status": "completed" },
+        { "task": "Create apps migration and model", "status": "completed" },
+        { "task": "Create builds migration and model", "status": "completed" },
+        { "task": "Create api_keys migration and model", "status": "completed" },
+        { "task": "Create subscriptions migration and model", "status": "completed" },
+        { "task": "Create device_activities migration and model", "status": "completed" },
+        { "task": "Create signing_keys migration and model", "status": "completed" },
+        { "task": "Set up model relationships", "status": "completed" }
+      ]
+    },
+    {
+      "id": 3,
+      "name": "API Endpoints",
+      "status": "in_progress",
+      "estimatedDays": 5,
+      "tasks": [
+        { "task": "Create ValidateApiKey middleware", "status": "completed" },
+        { "task": "Create ValidateFirebaseToken middleware", "status": "completed" },
+        { "task": "Create UpdateController (check for updates)", "status": "completed" },
+        { "task": "Create BundleController (upload, download)", "status": "completed" },
+        { "task": "Create AnalyticsController (MAU ping)", "status": "completed" },
+        { "task": "Create AppController (dashboard CRUD)", "status": "pending" },
+        { "task": "Create ApiKeyController (key management)", "status": "pending" },
+        { "task": "Create SubscriptionController (billing)", "status": "pending" },
+        { "task": "Set up API routes", "status": "completed" },
+        { "task": "Add rate limiting", "status": "pending" }
+      ]
+    },
+    {
+      "id": 4,
+      "name": "Stripe Integration",
+      "status": "partial",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Install Laravel Cashier", "status": "completed" },
+        { "task": "Configure Stripe API keys", "status": "pending", "note": "Config added, needs keys" },
+        { "task": "Create pricing plans in Stripe", "status": "pending" },
+        { "task": "Implement checkout session creation", "status": "pending" },
+        { "task": "Implement customer portal redirect", "status": "pending" },
+        { "task": "Create webhook handler", "status": "pending" },
+        { "task": "Handle subscription lifecycle events", "status": "pending" },
+        { "task": "Implement MAU overage billing", "status": "pending" }
+      ]
+    },
+    {
+      "id": 5,
+      "name": "Bundle Signing & Security",
+      "status": "completed",
+      "completedAt": "2026-03-28",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Create BundleSigningService", "status": "completed", "note": "In SigningKey model" },
+        { "task": "Implement RSA key pair generation", "status": "completed" },
+        { "task": "Implement RSA-PSS signing", "status": "completed" },
+        { "task": "Create SignedUrlService", "status": "completed", "note": "Using Laravel's built-in signed URLs" },
+        { "task": "Implement time-limited download URLs", "status": "completed" },
+        { "task": "Add device binding to URLs", "status": "completed" },
+        { "task": "Implement one-time download tokens", "status": "pending" },
+        { "task": "Add request signature validation (replay protection)", "status": "pending" }
+      ]
+    },
+    {
+      "id": 6,
+      "name": "Nova Admin Panel",
+      "status": "pending",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Create User Nova resource", "status": "completed", "note": "Auto-generated by Nova install" },
+        { "task": "Create App Nova resource", "status": "pending" },
+        { "task": "Create Build Nova resource", "status": "pending" },
+        { "task": "Create Subscription Nova resource", "status": "pending" },
+        { "task": "Create ApiKey Nova resource", "status": "pending" },
+        { "task": "Create Main dashboard (revenue, usage)", "status": "pending" },
+        { "task": "Add admin actions (suspend, adjust plan)", "status": "pending" },
+        { "task": "Add metrics cards and charts", "status": "pending" }
+      ]
+    },
+    {
+      "id": 7,
+      "name": "Plugin Updates",
+      "status": "pending",
+      "estimatedDays": 3,
+      "tasks": [
+        { "task": "Add apiKey to PluginInitConfig in definitions.ts", "status": "pending" },
+        { "task": "Add X-API-Key header to HTTP requests in plugin.ts", "status": "pending" },
+        { "task": "Add MAU ping endpoint call", "status": "pending" },
+        { "task": "Update iOS SecureStorage for API key", "status": "pending" },
+        { "task": "Update Android SecureStorage for API key", "status": "pending" },
+        { "task": "Update documentation", "status": "pending" }
+      ]
+    },
+    {
+      "id": 8,
+      "name": "Migration & Testing",
+      "status": "pending",
+      "estimatedDays": 5,
+      "tasks": [
+        { "task": "Write unit tests for API key validation", "status": "pending" },
+        { "task": "Write unit tests for bundle signing", "status": "pending" },
+        { "task": "Write unit tests for MAU calculation", "status": "pending" },
+        { "task": "Write integration tests for upload flow", "status": "pending" },
+        { "task": "Write integration tests for download flow", "status": "pending" },
+        { "task": "Write integration tests for Stripe flow", "status": "pending" },
+        { "task": "Create Firebase user sync script", "status": "pending" },
+        { "task": "Deploy to staging environment", "status": "pending" },
+        { "task": "Perform end-to-end testing", "status": "pending" },
+        { "task": "Deploy to production", "status": "pending" },
+        { "task": "Monitor and fix issues", "status": "pending" }
+      ]
+    }
+  ],
+  "decisions": {
+    "keepFirebaseAuth": true,
+    "keepGoogleDrive": "optional-free-tier",
+    "primaryStorage": "s3-or-r2",
+    "adminPanel": "laravel-nova",
+    "paymentProcessor": "stripe",
+    "mauTracking": "device-hash-monthly"
+  },
+  "pricingTiers": [
+    { "name": "Free", "price": 0, "mauLimit": 1000, "appsLimit": 1 },
+    { "name": "Pro", "price": 29, "mauLimit": 10000, "appsLimit": 5 },
+    { "name": "Enterprise", "price": 199, "mauLimit": 100000, "appsLimit": -1 }
+  ],
+  "securityFeatures": [
+    "api-key-authentication",
+    "firebase-token-validation",
+    "rsa-pss-bundle-signing",
+    "signed-download-urls",
+    "device-binding",
+    "rate-limiting",
+    "replay-attack-prevention"
+  ],
+  "completedToday": [
+    "Laravel 11 + Nova 5 project created in /backend",
+    "All database migrations created and run",
+    "All models with relationships created",
+    "API key validation middleware created",
+    "Firebase token validation middleware created",
+    "Update check API endpoint created",
+    "Bundle download API with signed URLs created",
+    "Analytics/MAU tracking API created",
+    "RSA key generation and signing in SigningKey model",
+    "Laravel Cashier, Firebase SDK, AWS SDK installed"
+  ],
+  "blockers": [],
+  "notes": [
+    "Nova license configured globally",
+    "Stripe API keys needed",
+    "Firebase service account JSON needed",
+    "S3/R2 bucket and keys needed",
+    "Current plugin already supports HTTP backend - minimal changes needed"
+  ]
+}

package/docs/project-knowledge-base/01-system-overview.md

@@ -0,0 +1,218 @@
+# Native Update System Overview
+
+## Metadata
+
+- **Reference Date:** 2026-03-16
+- **Last Updated:** 2026-03-16
+
+## Project Identity
+
+- **Name:** Native Update
+- **Package:** `native-update`
+- **Type:** Open-source Capacitor plugin plus update management platform
+- **Primary Creator:** Ahsan Mahmood
+- **Primary Contact:** aoneahsan@gmail.com
+- **License:** MIT
+
+## Core Mission
+
+Native Update exists to reduce the operational complexity of shipping updates in Capacitor apps. It unifies OTA updates, native app update flows, in-app reviews, release manifests, rollout controls, and management tooling into one ecosystem.
+
+## Core Product Layers
+
+### 1. Plugin Layer
+
+The plugin provides the runtime capabilities inside a Capacitor app:
+
+- OTA/live update checks and bundle handling
+- app update checks and prompts
+- in-app review requests
+- background update scheduling
+- security validation logic
+- Firestore-backed manifest reading support
+
+### 2. Dashboard Layer
+
+The website provides a management surface for:
+
+- user auth
+- app creation and app management
+- build uploads
+- rollout visibility and control
+- analytics review
+- Google Drive connection and storage management
+- configuration generation
+- admin-only oversight pages
+
+### 3. Docs Layer
+
+The docs explain:
+
+- installation and setup
+- features and APIs
+- examples and advanced scenarios
+- security, deployment, testing, and troubleshooting
+- migration from other approaches
+- planning, tracking, roadmap, audit, and report history
+
+### 4. Tooling Layer
+
+The project includes:
+
+- CLI commands
+- bundle creation/signing/verification utilities
+- backend templates and examples
+- local development scripts
+
+## What The Product Solves
+
+Capacitor teams often need several disconnected systems to handle:
+
+- web asset updates
+- store version upgrades
+- review prompts
+- release rollout control
+- security verification
+- app/build administration
+
+Native Update consolidates those concerns into one project with a common mental model.
+
+## Main Feature Areas
+
+### Live / OTA Updates
+
+- Deliver JavaScript, HTML, and CSS changes without app store review
+- Support update channels
+- Manage version checks and bundle downloads
+- Support checksum and signature validation
+- Enable rollback-aware update flows
+- Support delta patch concepts and file manifests
+
+### Native App Updates
+
+- Check for newer native binary versions
+- Support immediate and flexible update strategies
+- Integrate with Android and iOS update behavior
+
+### In-App Reviews
+
+- Request native reviews
+- respect timing/rate limiting logic
+- support user-experience-aware prompting
+
+### Background Updates
+
+- Schedule checks while app is not active
+- support native notification behavior
+- provide background configuration hooks
+
+### Security
+
+- signing
+- checksum verification
+- HTTPS-first posture
+- certificate pinning support
+- validation helpers
+
+### Release Operations
+
+- upload build ZIPs
+- generate file manifests
+- publish app-facing manifests
+- configure rollout percentages
+- manage app/channel/build metadata
+
+## Current Product Surfaces
+
+### Public Website
+
+- `/`
+- `/features`
+- `/pricing`
+- `/docs`
+- `/docs/*`
+- `/about`
+- `/contact`
+- `/privacy`
+- `/terms`
+- `/data-deletion`
+- `/cookies`
+- `/security`
+- `/sitemap`
+- `/feed`
+
+### Auth Pages
+
+- `/login`
+- `/signup`
+
+### Protected Dashboard
+
+- `/dashboard`
+- `/dashboard/apps`
+- `/dashboard/apps/:appId`
+- `/dashboard/builds`
+- `/dashboard/builds/:buildId`
+- `/dashboard/upload`
+- `/dashboard/drive`
+- `/dashboard/config`
+- `/dashboard/settings`
+- `/dashboard/rollouts`
+- `/dashboard/analytics`
+
+### Admin Area
+
+- `/admin`
+- `/admin/users`
+- `/admin/apps`
+- `/admin/builds`
+
+## User Types
+
+### Public Visitor
+
+Can browse marketing, docs, legal, contact, sitemap, and feed pages.
+
+### Authenticated User
+
+Can access dashboard pages and manage their own apps, builds, Drive connection, settings, and release operations.
+
+### Admin User
+
+An authenticated user whose Firestore user document has `isAdmin: true`. Admins can access `/admin` pages for broader oversight.
+
+### Mobile App Client
+
+Not a dashboard user, but an app-side runtime consumer of manifests, update metadata, and plugin APIs.
+
+### Developer / Maintainer
+
+Works in the codebase, docs, CLI, native code, example apps, and release infrastructure.
+
+## Access Model
+
+- Public routes are open.
+- Dashboard routes are wrapped by `ProtectedRoute`.
+- Admin routes are wrapped by `AdminRoute`.
+- Google sign-in is the primary auth flow.
+- Admin is currently determined by email/user doc logic, including `aoneahsan@gmail.com`.
+
+## Product Positioning Notes
+
+- The repo positions Native Update as more than a plugin; it is a platform direction.
+- The website presents a complete update solution with dashboard and docs.
+- The repo also contains older historical docs from pre-production phases. These should be treated as timeline artifacts, not always the newest truth.
+
+## Recommended Decision Assumptions For AI Tools
+
+- Treat the project as a cross-platform mobile infrastructure product.
+- Treat the website as both a marketing site and operations dashboard.
+- Treat Google Drive + Firestore as the preferred no-cost production backend path for the website flow.
+- Treat the dashboard as owner/operator tooling, not end-user mobile UI.
+- Treat security, rollout control, and documentation quality as important project values.
+
+## Important Known Context
+
+- The project contains current docs plus historical reports and planning files.
+- Some documents disagree on production readiness because they were written at different times.
+- For technical state, prefer current source code, route definitions, type definitions, package files, and newer roadmap/report files.