Phase 6 (mobile release readiness) — gen side. Spec: nomad-mobile
`docs/superpowers/specs/2026-10-25-mobile-phase6-release-readiness-design.md`
(§4 payments, §5 push, §6 deletion, §9 demo account).
## What
- **`/me` app fields:** opaque `app_user_id` (UUID, used for
RevenueCat/Sentry — no email to third parties),
`capabilities.account_deletion`, `push_prefs`.
- **In-app purchases:** `POST /api/users/webhooks/revenuecat` (shared
Authorization header). Exactly-once grants keyed by
`{store}:{transaction_id}` inside the same Firestore transaction as the
balance change; refunds (REFUND / CANCELLATION with CUSTOMER_SUPPORT or
negative price) debit the granted account, refund tombstones block late
grants; other cancellations ignored. `store_payments` for accounting +
revenue sums; referral earnings on **net** proceeds; sandbox grants but
excluded from revenue/referrals. Credit packages gain `store_product_id`
+ server-driven `web_link` (iOS US only for now).
- **Push:** `POST/DELETE /api/push/expo-token` (token moves between
users atomically), `PATCH /api/users/me/push-prefs` (ready / review /
problems, gates Expo **and** Web Push), Expo sender (batched,
DeviceNotRegistered cleanup), new FAILED / AWAITING_AUDIO_SELECTION
triggers.
- **Account deletion** (`ACCOUNT_DELETION_ENABLED`, **off in prod**
until Andrew's manual pass): `GET /api/users/me/deletion-preview`,
`DELETE /api/users/me`. Refuses admin / unpaid referral balance / Stripe
Connect / made-for-you in progress (409). Cancels active jobs, deletes
decide data (partner call, twice), RevenueCat subscriber, revokes Sign
in with Apple (when a code is given), queues kjbox
(`/api/kjbox/account-deletions` pull + ack), deletes **inputs only**
(uploads, input/, audio_edit/, style/, staged instrumentals) — **never
published outputs** — strips personal fields, anonymises
jobs/referrals/song requests/show-credit records, keeps payment records.
Every step idempotent; failures → 503 retry; sessions revoked last.
- **Web:** `/account/delete` page (Google Play web deletion path),
hidden while the flag is off.
- **App Review demo login:** fixed code for one configured email — inert
until `APP_REVIEW_DEMO_EMAIL` is set (not set in prod).
- **CI:** mounts `REVENUECAT_WEBHOOK_AUTH`, `REVENUECAT_SECRET_API_KEY`,
`APP_REVIEW_DEMO_CODE` (secrets exist; runtime SA already has accessor).
## Tests
6838 backend unit tests pass (emulator suite needs emulators;
iap/deletion emulator tests pass locally), frontend jest 1785/1785.
Per-task reviews + local CodeRabbit review (5 minor findings fixed).
@coderabbitai ignore
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01CZf1cM9vefnNw5djARRhyA
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Karaoke Generator Frontend
Next.js frontend for the Karaoke Generator application.
Quick Start
# Install dependencies
npm install
# Run development server
npm run dev
The app will be available at http://localhost:3000
Development Setup
Connecting to the Cloud Backend
In development, the frontend proxies API requests to the cloud backend (api.nomadkaraoke.com) via Next.js rewrites. This avoids CORS issues and allows local development without running a local backend.
The proxy is configured in next.config.mjs:
- All
/api/*requests are forwarded to the cloud backend - You can override the backend URL with
BACKEND_URLenvironment variable
Authentication
The backend requires authentication. To authenticate:
-
Create a
.env.localfile in the frontend directory:KARAOKE_ACCESS_TOKEN=your-token-here -
The token is automatically loaded by Playwright tests
-
In the browser, the token is stored in
localStorageaskaraoke_access_token
Testing
Unit Tests (Jest)
# Run tests in watch mode
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in CI mode
npm run test:ci
E2E Tests (Playwright)
E2E tests run against the local dev server connected to the real cloud backend.
# Run all E2E tests
npm run test:e2e
# Run with UI (interactive mode)
npm run test:e2e:ui
# Run in headed mode (see the browser)
npm run test:e2e:headed
# Run in debug mode
npm run test:e2e:debug
Authentication for E2E Tests
E2E tests require a valid access token. Set it in .env.local:
KARAOKE_ACCESS_TOKEN=your-token-here
The Playwright config (playwright.config.ts) automatically loads this file.
Test Structure
Tests are located in e2e/:
karaoke-generation.spec.ts- Main test suite covering:- Homepage loading and form display
- Search tab functionality
- Audio search submission
- Audio selection dialog flow
- API health checks
Test Architecture
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ Playwright │────▶│ Next.js Dev │────▶│ Cloud Backend │
│ Browser │ │ Server (:3000) │ │ api.nomadkaraoke │
└─────────────────┘ └──────────────────┘ └─────────────────────┘
│
▼
API Proxy
/api/* → backend
Debugging Test Failures
- Screenshots: Failed tests save screenshots to
test-results/ - Videos: First retry captures video (when retries enabled)
- Traces: View detailed traces with
npx playwright show-trace <trace.zip> - HTML Report: After running tests, view
npx playwright show-report
Common Issues
- 401 Unauthorized: Token missing or invalid - check
.env.local - Socket hang up: Backend operation taking too long - some operations (like audio download) can take minutes
- Element outside viewport: Dialog scrolling issues - tests use JavaScript click to handle this
Project Structure
frontend/
├── app/ # Next.js app router pages
├── components/ # React components
│ ├── ui/ # shadcn/ui components
│ └── audio-search/ # Audio search feature components
├── lib/ # Utilities and API client
│ └── api.ts # Backend API client
├── e2e/ # Playwright E2E tests
├── playwright.config.ts # Playwright configuration
└── next.config.mjs # Next.js configuration
Scripts
| Script | Description |
|---|---|
npm run dev |
Start development server |
npm run build |
Build for production |
npm run start |
Start production server |
npm run lint |
Run ESLint |
npm test |
Run unit tests (watch mode) |
npm run test:ci |
Run unit tests (CI mode with coverage) |
npm run test:e2e |
Run E2E tests |
npm run test:e2e:ui |
Run E2E tests with interactive UI |