native-update 1.4.9 → 2.0.0

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

@@ -0,0 +1,307 @@
+# Native Update Data Models and Integrations
+
+## Metadata
+
+- **Reference Date:** 2026-03-16
+- **Last Updated:** 2026-03-16
+
+## Main Integration Surfaces
+
+- Firebase Authentication
+- Firestore
+- Google Identity Services
+- Google Drive API
+- Capacitor runtime APIs
+- Android native APIs / Play-related update capabilities
+- iOS native APIs / StoreKit-related review and update capabilities
+
+## Authentication Model
+
+### Sign-In Method
+
+- Primary auth flow is Google sign-in via Firebase popup
+- user records are created on first login
+- admin privilege is stored in Firestore and seeded from owner email logic
+
+### User Document (`users/{uid}`)
+
+Key fields visible in types and auth flow:
+
+- `uid`
+- `email`
+- `displayName`
+- `photoURL`
+- `provider`
+- `emailVerified`
+- `createdAt`
+- `lastLogin`
+- `driveConnected`
+- `driveEmail`
+- `driveConnectedAt`
+- `plan`
+- `planStartDate`
+- `planEndDate`
+- `appsCount`
+- `buildsCount`
+- `storageUsed`
+- `preferences`
+- `isAdmin`
+- `updatedAt`
+
+### User Preferences
+
+- `emailNotifications`
+- `updateNotifications`
+- `theme`
+- `language`
+
+## App Model
+
+### App Document (`apps/{appId}`)
+
+- `userId`
+- `name`
+- `packageId`
+- `icon`
+- `description`
+- `platforms`
+- `channels`
+- `apiKey`
+- `totalBuilds`
+- `activeUsers`
+- `lastBuildDate`
+- `createdAt`
+- `updatedAt`
+
+### Channel Config
+
+Per channel:
+
+- `enabled`
+- `autoUpdate`
+- `updateStrategy`
+- `requireUserConsent`
+- `minVersion`
+
+Default observed behavior:
+
+- production enabled
+- staging enabled
+- development enabled and auto-update true
+
+## API Key Model
+
+### API Key Document (`apiKeys/{apiKey}`)
+
+Used so mobile apps can query manifests using an API key rather than dashboard auth. Observed fields include:
+
+- `appId`
+- `packageId`
+- `userId`
+- `createdAt`
+
+There is also an app-facing manifests subcollection under this API key path.
+
+## Build Model
+
+### Build Document (`builds/{buildId}`)
+
+Observed/typed fields include:
+
+- `id`
+- `userId`
+- `appId`
+- `version`
+- `buildNumber`
+- `channel`
+- `platform`
+- `fileName`
+- `fileSize`
+- `mimeType`
+- `checksum`
+- `signature`
+- `driveFileId`
+- `driveFileUrl`
+- `driveFolderId`
+- `fileManifest`
+- `manifestDriveId`
+- `releaseNotes`
+- `releaseType`
+- `isPreRelease`
+- `minNativeVersion`
+- `uploadedAt`
+- `uploadedBy`
+- `uploadDuration`
+- `status`
+- `processingSteps`
+- `analytics`
+- `updatedAt`
+
+### Build Status Values
+
+- `uploading`
+- `processing`
+- `active`
+- `archived`
+- `failed`
+
+## Manifest Model
+
+### Manifest Document (`manifests/{appId}_{channel}`)
+
+This is the primary document used for update checks.
+
+Fields:
+
+- `appId`
+- `channel`
+- `current`
+- `deltas`
+- `rollout`
+- `previousVersions`
+- `updatedAt`
+- `updatedBy`
+
+### Current Version Block
+
+- `version`
+- `bundleId`
+- `bundleUrl`
+- `manifestUrl`
+- `checksum`
+- `signature`
+- `size`
+- `releaseNotes`
+- `releaseDate`
+- `mandatory`
+- `minNativeVersion`
+
+### Rollout Config
+
+- `enabled`
+- `percentage`
+- `startTime`
+- `endTime`
+- optional `targetSegments`
+- optional `schedule`
+
+### Rollout Schedule
+
+- `immediate`
+- `gradual`
+- `scheduled`
+
+## Delta Model
+
+### Delta Document
+
+Used for pre-computed patch information:
+
+- `appId`
+- `fromVersion`
+- `toVersion`
+- `channel`
+- `patchDriveId`
+- `patchUrl`
+- `patchSize`
+- `patchChecksum`
+- `sourceChecksum`
+- `targetChecksum`
+- `generatedAt`
+- `generationDuration`
+- `algorithm`
+- `compressionRatio`
+- `status`
+
+## Analytics Model
+
+### Analytics Batch Document (`analytics_batch/{batchId}`)
+
+- `appId`
+- `channel`
+- `windowStart`
+- `windowEnd`
+- `events`
+- `versionStats`
+- `platformStats`
+- `errorSamples`
+- `createdAt`
+
+### Events Aggregated
+
+- update checks
+- downloads
+- installs
+- rollbacks
+- errors
+
+## Drive Token Model
+
+### Drive Token Document (`drive_tokens/{userId}`)
+
+Observed fields include:
+
+- `userId`
+- `accessToken`
+- `refreshToken`
+- `tokenType`
+- `scope`
+- `expiresAt`
+- Google account metadata such as email/name/picture/id/locale
+- `encryptionMethod`
+- `iv`
+- `authTag`
+- `createdAt`
+- `updatedAt`
+
+## Google Drive Integration Flow
+
+### Connect Flow
+
+1. Load Google Identity Services script
+2. Request Drive and profile scopes
+3. Exchange response into usable access token
+4. Fetch Google user profile info
+5. Store token metadata in Firestore
+6. Update `users/{uid}` Drive connection fields
+
+### Upload Flow
+
+1. User selects ZIP
+2. Validate file
+3. Calculate SHA-256 checksum
+4. Generate file manifest from ZIP contents
+5. Upload ZIP to Drive
+6. Upload manifest JSON to Drive
+7. Make Drive files publicly retrievable as needed
+8. Write build record in Firestore
+9. Update channel manifest document
+
+## No-Cost Backend Operating Model
+
+The intended website publishing model is:
+
+- browser-based uploads
+- Google Drive for bundle storage
+- Firestore for metadata and app-facing manifests
+- no paid compute required for core publish/check/download flow
+
+This is a central strategic assumption in the repo’s website guidance.
+
+## App-Facing Manifest Paths Mentioned In CLAUDE Guidance
+
+- `/apiKeys/{apiKey}/manifests/{channel}`
+- `/manifests/{appId}_{channel}`
+
+## Security-Relevant Data Points
+
+- checksums are stored and used for validation
+- signature support exists
+- manifest and build docs carry release metadata
+- bundle file manifests support file-level integrity and delta logic
+
+## Data Ownership Notes
+
+- The website messaging emphasizes that user build files are stored in the user’s Google Drive
+- user account data and release metadata live in Firebase/Firestore
+- deletion/account settings pages document data handling expectations for legal/compliance messaging

package/docs/project-knowledge-base/05-docs-corpus-inventory.md

@@ -0,0 +1,193 @@
+# Native Update Docs Corpus Inventory
+
+## Metadata
+
+- **Reference Date:** 2026-03-16
+- **Last Updated:** 2026-03-16
+- **Goal:** Enumerate the current `/docs` folder so AI tools know what documentation already exists before planning, writing, or duplicating work
+
+## Coverage Note
+
+This file inventories the docs currently present in `/docs`. It is a high-context index, not a replacement for reading the source documents when exact wording or implementation detail is needed.
+
+## Root-Level Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/README.md` | Main docs landing page and public docs overview |
+| `docs/APP_REVIEW_GUIDE.md` | Review-related guide content |
+| `docs/BUNDLE_SIGNING.md` | Signing workflow and bundle security guidance |
+| `docs/CHANGELOG.md` | Project change history |
+| `docs/COMPREHENSIVE_AUDIT_REPORT.md` | Broad audit/reporting artifact |
+| `docs/EXAMPLE_APPS_SIMPLIFICATION_PLAN.md` | Plan for simplifying example apps |
+| `docs/EXAMPLE_APPS_SIMPLIFICATION_TRACKER.md` | Tracking file for example-app simplification |
+| `docs/FIREBASE_INTEGRATION_TRACKER.md` | Firebase integration tracking/status notes |
+| `docs/FIREBASE_QUERIES_AND_INDEXES_AUDIT.md` | Firestore query/index audit reference |
+| `docs/KNOWN_LIMITATIONS.md` | Explicit limitations and caveats |
+| `docs/LIVE_UPDATES_GUIDE.md` | OTA/live update guidance |
+| `docs/MARKETING_WEBSITE_PLAN.md` | Marketing website planning document |
+| `docs/MARKETING_WEBSITE_TRACKER.md` | Marketing website progress tracker |
+| `docs/MIGRATION.md` | Migration information |
+| `docs/NATIVE_UPDATES_GUIDE.md` | Native app update guidance |
+| `docs/PROJECT_COMPLETION_TRACKER.md` | Completion/progress tracker |
+| `docs/QUICK_START.md` | Fast-start implementation guidance |
+| `docs/REMAINING_FEATURES.md` | Remaining or planned feature notes |
+| `docs/ROADMAP.md` | Roadmap/status file |
+| `docs/SECURITY.md` | High-level security documentation |
+| `docs/TESTING_REQUIREMENTS.md` | Testing expectations and requirements |
+| `docs/background-updates.md` | Background update feature guide |
+| `docs/cli-reference.md` | CLI usage reference |
+| `docs/play-console-rejection-rules.json` | Policy/rules reference JSON |
+| `docs/production-readiness.md` | Production readiness checklist/context |
+| `docs/server-requirements.md` | Backend/server requirement notes |
+
+## API Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/api/API.md` | Top-level API overview |
+| `docs/api/FEATURES.md` | Feature-oriented API/behavior summary |
+| `docs/api/app-review-api.md` | App review API surface |
+| `docs/api/app-update-api.md` | App update API surface |
+| `docs/api/background-update-api.md` | Background update API surface |
+| `docs/api/events-api.md` | Event listener and event model reference |
+| `docs/api/live-update-api.md` | OTA/live update API reference |
+
+## Getting Started Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/getting-started/configuration.md` | Config options and setup details |
+| `docs/getting-started/installation.md` | Installation steps |
+| `docs/getting-started/quick-start.md` | Quick implementation guide |
+
+## Feature Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/features/app-reviews.md` | In-app review feature details |
+| `docs/features/app-updates.md` | Native app update feature details |
+| `docs/features/live-updates.md` | OTA/live update feature details |
+
+## Guide Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/guides/BACKEND_TEMPLATES_GUIDE.md` | How backend templates are intended to be used |
+| `docs/guides/admin-panel.md` | Admin panel/dashboard usage |
+| `docs/guides/channel-management.md` | Channel setup and usage |
+| `docs/guides/dashboard-guide.md` | Dashboard usage guide |
+| `docs/guides/deployment-guide.md` | Deployment guidance |
+| `docs/guides/end-to-end-workflow.md` | Full workflow from setup to production |
+| `docs/guides/key-management.md` | Key generation and management |
+| `docs/guides/migration-from-codepush.md` | CodePush migration guide |
+| `docs/guides/no-cost-backend-implementation-plan.md` | Planning file for no-cost backend path |
+| `docs/guides/no-cost-firestore-google-drive-backend.md` | Key recommended backend architecture guide |
+| `docs/guides/security-best-practices.md` | Secure update implementation guidance |
+| `docs/guides/testing-guide.md` | Testing procedures and expectations |
+| `docs/guides/troubleshooting.md` | Troubleshooting and issue resolution guide |
+
+## Examples Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/examples/advanced-scenarios.md` | More advanced use cases and patterns |
+| `docs/examples/android-manifest-example.xml` | Android manifest example |
+| `docs/examples/basic-usage.md` | Basic implementation examples |
+| `docs/examples/firebase-backend-example.md` | Firebase backend example |
+| `docs/examples/node-express-backend-example.md` | Node/Express backend example |
+| `docs/examples/react-capacitor-example.md` | React + Capacitor frontend example |
+
+## Plans
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/plans/PLANNING_COMPLETE_SUMMARY.md` | Summary of planning phase |
+| `docs/plans/TASK_1_ANDROID_EXAMPLE_APP.md` | Android example-app planning task |
+| `docs/plans/TASK_2_API_ENDPOINTS.md` | API endpoint planning |
+| `docs/plans/TASK_2_DASHBOARD_UI_UX.md` | Dashboard UX planning |
+| `docs/plans/TASK_2_DATABASE_SCHEMA.md` | Database schema planning |
+| `docs/plans/TASK_2_GOOGLE_DRIVE_INTEGRATION.md` | Drive integration planning |
+| `docs/plans/TASK_2_SAAS_ARCHITECTURE.md` | SaaS architecture planning |
+| `docs/plans/TASK_2_USER_AUTHENTICATION.md` | Auth planning |
+
+## Reports
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/reports/AUDIT_SUMMARY_2025-12-26.md` | Historical audit summary |
+| `docs/reports/CLAUDE-CODE-COMPLETION-PROMPT.md` | Internal prompt/report artifact |
+| `docs/reports/CLAUDE_CODE_PROMPT.md` | Internal prompt/report artifact |
+| `docs/reports/CODEBASE_STATUS_REPORT.md` | Codebase status report |
+| `docs/reports/COMPLETE_VERIFICATION.md` | Verification report |
+| `docs/reports/COMPREHENSIVE-PROJECT-AUDIT-2026-02-24.md` | Detailed later audit report |
+| `docs/reports/EVENT_FLOW_VERIFICATION.md` | Event flow verification notes |
+| `docs/reports/EXAMPLE_APPS_SIMPLIFICATION_COMPLETE.md` | Completion note for example-app simplification |
+| `docs/reports/FINAL_STATUS.md` | Status summary |
+| `docs/reports/FINAL_VERIFICATION_CHECKLIST.md` | Release/readiness checklist |
+| `docs/reports/MARKETING_WEBSITE_COMPLETE.md` | Website completion report |
+| `docs/reports/PACKAGE_COMPLETENESS_REPORT.md` | Package completeness analysis |
+| `docs/reports/PRODUCTION_STATUS.md` | Historical production-status report; contains older readiness framing |
+| `docs/reports/PROJECT_RESTRUCTURE_2025-12-27.md` | Restructure report |
+| `docs/reports/PROJECT_RESTRUCTURE_FINAL_SUMMARY.md` | Final restructure summary |
+| `docs/reports/PUBLISHING_VERIFICATION.md` | Publishing/release verification |
+| `docs/reports/RELEASE_READY_SUMMARY.md` | Release readiness summary |
+| `docs/reports/claude-completion.json` | JSON status/report artifact |
+
+## Security Subfolder
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/security/certificate-pinning.md` | Certificate pinning details |
+
+## Tracking Subfolder
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/tracking/IMPLEMENTATION_TRACKER.md` | Implementation tracking |
+| `docs/tracking/capacitor-rollout-note-2026-03-01.md` | Rollout note / dated tracking artifact |
+| `docs/tracking/completion-tracker-2026-02-24.json` | JSON completion tracker |
+
+## Existing Project Profile and AI-Oriented Docs
+
+| Path | Purpose / Notes |
+|------|------------------|
+| `docs/project-profiles/native-update-capacitor-update-platform-project-profile-last-updated-2026-03-16.md` | Portfolio/resume/social-facing project profile |
+
+## How AI Should Use The Docs Corpus
+
+### For Implementation
+
+- Start with `docs/getting-started/*`, `docs/api/*`, `docs/features/*`, and `docs/guides/*`
+
+### For Product Positioning
+
+- Use `docs/README.md`, feature docs, dashboard guides, website pages, and the project profile
+
+### For Architecture or Backend Planning
+
+- Use no-cost backend guides, schema planning docs, API endpoint plans, Firestore audit docs, and website config pages
+
+### For Testing
+
+- Use `docs/TESTING_REQUIREMENTS.md`, testing guide, verification reports, and test files in source
+
+### For Historical Context
+
+- Use `docs/plans/*`, `docs/reports/*`, and tracking files
+
+### For Legal / Compliance / Security
+
+- Use `docs/SECURITY.md`, security-best-practices guide, certificate pinning doc, website legal pages, and production-readiness docs
+
+## Important Interpretation Rule
+
+The `/docs` folder mixes:
+
+- user-facing docs
+- implementation docs
+- planning artifacts
+- historical reports
+- status snapshots
+
+AI tools should not treat all documents as equally current. For current technical truth, validate against source code and the most recent files.

package/docs/project-knowledge-base/06-operations-testing-legal-content.md

@@ -0,0 +1,170 @@
+# Native Update Operations, Testing, Legal, and Content Context
+
+## Metadata
+
+- **Reference Date:** 2026-03-16
+- **Last Updated:** 2026-03-16
+
+## Operations Context
+
+### Release and Delivery Model
+
+- Plugin code ships via npm as `native-update`
+- Dashboard supports browser-driven ZIP upload workflows
+- Google Drive stores release bundles and manifest JSON files in the recommended no-cost path
+- Firestore stores manifest metadata, rollout settings, app records, and analytics batches
+
+### Channel Model
+
+- production
+- staging
+- development
+
+Observed product messaging and docs position these as the primary update channels.
+
+### Rollout Model
+
+- percentage-based rollout
+- pause/resume support
+- gradual or scheduled rollout concepts in schema/docs
+- rollout configuration stored in manifest docs
+
+## Testing Context
+
+### Test Layers Present In Repo
+
+- TypeScript unit and integration tests under `src/__tests__/`
+- iOS XCTest files under `ios/Tests/NativeUpdateTests/`
+- Android JUnit/Kotlin tests under `android/src/test/java/com/aoneahsan/nativeupdate/`
+- E2E tests under `e2e/specs/`
+
+### E2E Areas Mentioned
+
+- OTA update lifecycle
+- error handling
+- download progress
+- channel switching
+
+### Testing Documentation Present
+
+- `docs/TESTING_REQUIREMENTS.md`
+- `docs/guides/testing-guide.md`
+- verification and audit reports under `docs/reports/`
+
+## Security Context
+
+### Security Themes Repeated Across Repo
+
+- checksum validation
+- signing and verification
+- HTTPS enforcement
+- certificate pinning support
+- manifest/file integrity
+- secure update delivery
+
+### Security Docs Present
+
+- `docs/SECURITY.md`
+- `docs/BUNDLE_SIGNING.md`
+- `docs/security/certificate-pinning.md`
+- `docs/guides/security-best-practices.md`
+- SecurityPage on website
+
+## Legal and Compliance Surfaces
+
+### Website Legal Pages
+
+- `/privacy`
+- `/terms`
+- `/cookies`
+- `/data-deletion`
+- `/security`
+- `/contact`
+
+These pages are explicitly called out in `website/CLAUDE.md` as important and app-store-relevant.
+
+### Legal Messaging Themes In Website
+
+- privacy handling
+- no third-party analytics tracking emphasis in some legal copy
+- account deletion path
+- support/contact identity
+- security positioning
+- ownership/control messaging around Google Drive files
+
+## Content and SEO Context
+
+### Built-In Public Content Surfaces
+
+- Home page
+- Features page
+- About page
+- Docs page
+- Examples page
+- Feed page
+- Sitemap page
+- Contact page
+
+### Social/Portfolio Context Already Added
+
+- Project profile exists under `docs/project-profiles/`
+- this knowledge base should support future content generation with technical accuracy
+
+### Best Content Angles
+
+- open-source Capacitor infrastructure
+- OTA update engineering
+- secure mobile release workflows
+- dashboard and release-ops UX
+- no-cost backend architecture with Firestore + Google Drive
+- cross-platform engineering across TypeScript, Swift, Kotlin, and React
+- AI-ready docs and developer enablement
+
+## Planning and Decision-Making Rules For AI
+
+- Do not invent user counts, stars, revenue, or adoption metrics.
+- Prefer current source code and route definitions over older historical reports.
+- Treat roadmap items as future-facing unless code confirms they are already shipped.
+- When recommending changes for the website, consider sitemap/feed/legal page maintenance.
+- When recommending backend changes for the website, preserve the no-cost Firestore + Google Drive path unless a stronger requirement forces a different architecture.
+
+## Known Constraints and Notes
+
+- The repo contains both current and historical status documents.
+- Some legacy docs describe earlier incomplete states.
+- Route guards reference `/verify-email`, but that route is not visible in the current router file; this is a project-context note worth re-checking before auth-related changes.
+- The dashboard is optimized for authenticated operators, not end users.
+- Admin access is currently determined through Firestore `isAdmin` state.
+
+## AI Usage Recommendations By Category
+
+### For Development
+
+- Use this knowledge base first
+- then inspect source modules and exact docs files tied to the feature
+
+### For Testing
+
+- map the feature to its page/module/native component
+- use testing docs plus test files to derive coverage strategy
+
+### For Legal or Policy Work
+
+- review legal pages and security/privacy docs together
+- do not rely only on marketing copy
+
+### For Marketing or Social Content
+
+- use product profile + this knowledge base + current website messaging
+- avoid unsupported performance or adoption claims
+
+### For Planning
+
+- check roadmap, remaining-features docs, plans, and code reality together
+
+## Maintenance Rule For This Knowledge Base
+
+- Update this folder every 2 weeks while the project is active
+- Update sooner when routes, forms, data models, docs, modules, legal pages, or backend assumptions change
+- Keep `Reference Date` and `Last Updated` current in each file
+- Keep this folder aligned with actual repo state, not just historical docs