Commit Graph
57 Commits
Author SHA1 Message Date
Andrew Beveridge ☄️andClaude Opus 4.6 591c050545 feat: Reference lyrics search with relevance filtering (#632)
## Summary

- Add relevance filtering to the correction pipeline — automatically
rejects wrong-song reference lyrics (below 30% word match threshold,
validated against 168 prod source pairs)
- New `POST /api/review/{job_id}/search-lyrics` endpoint lets users
search with alternate artist/title from the review UI, with force-add
override for edge cases
- Redesigned Add Reference Lyrics modal with Search (default) and Paste
tabs, plus inline empty state when no valid sources exist

## Changes

### Backend
- **Relevance filtering** (`correction/relevance.py`): Per-source
scoring based on anchor sequence word coverage. Integrated into
`LyricsCorrector.run()` after anchor finding — sources below threshold
removed before corrections computed
- **Search endpoint** (`routes/review.py`): Queries all providers
(Genius, Spotify, Musixmatch, LRCLIB) with user-supplied artist/title,
auto-filters results, returns added/rejected/not-found breakdown
- **Provider factory** (`operations.py`): `create_lyrics_providers()`
reads env vars, `search_lyrics_sources()` orchestrates
fetch+filter+correct
- **Force override**: `add-lyrics` and `search-lyrics` support `force`
flag to bypass threshold

### Frontend
- **Tabbed modal**: `AddLyricsModal` rewritten with Search (default) and
Paste tabs
- **SearchLyricsTab**: Artist/title inputs, provider search, rejected
source cards with force-add checkboxes
- **ReferenceEmptyState**: Inline search/paste UI when no valid
reference sources exist
- **API client**: New `searchLyrics()` method with
`SearchLyricsResponse` types

### Analysis
- Empirical threshold analysis script
(`scripts/analyze_reference_relevance.py`) + visual review tool
- 168 source pairs from 81 prod jobs: wrong-song max 3.5%, correct-song
min 26.8% → 30% threshold

## Testing
- 35 new backend tests (relevance scoring, filtering, corrector
integration, search operation, API endpoint)
- 717 existing frontend tests passing (no regressions)
- Edge case: all sources filtered out handled gracefully

## Review
- [x] Local CodeRabbit review completed (3 issues fixed: response
contract, force param coercion, null checks)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-30 00:25:47 +00:00
Andrew Beveridge ☄️andClaude Opus 4.6 6577babfea Reduce free credits from 2 to 1 per grant (#592)
## Summary

- Welcome credits: 2 → 1 (granted on first email verification)
- Feedback credits: 2 → 1 (granted for submitting product feedback)
- Total possible free credits per account: 4 → 2

## Changes

**Backend:** `NEW_USER_FREE_CREDITS` constant, feedback credit grant, AI
evaluation prompt, model defaults
**Frontend:** Landing page, dashboard banner, feedback dialog, auth
dropdown menu text
**Tests:** Updated all assertions and mock values (115 backend + 712
frontend tests pass)
**Docs:** AI-CREDIT-GATING.md, API.md, README.md,
PRODUCT-COMMUNICATION-GUIDE.md

## Test plan

- [x] Backend tests pass (115 passed)
- [x] Frontend Jest tests pass (712 passed)
- [ ] CI pipeline passes
- [ ] Verify landing page shows "1 Free Credit" after deploy
- [ ] Verify new user signup grants 1 credit (not 2)

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-24 21:30:38 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 c9e434037b feat: admin feedback visibility — page + email notification (#581)
<!-- @coderabbitai ignore -->

## Summary

- **Admin feedback page** at `/admin/feedback` — browse all user
feedback submissions with star ratings, text fields, search, pagination,
and aggregate stats
- **Email notification** to admin@nomadkaraoke.com whenever a user
submits new feedback (configurable via `ADMIN_NOTIFICATION_EMAIL` env
var)
- **Admin API endpoint** `GET /api/admin/feedback` with pagination,
search, test-data filtering, and average ratings

## Context

User feedback was stored in Firestore (`user_feedback` collection) but
completely invisible to the admin — the admin panel only showed a
boolean "Feedback Submitted: Yes/No" badge per user. This PR closes that
gap.

## Changes

**Backend:**
- `GET /api/admin/feedback` endpoint with pagination, search,
`exclude_test` filter, aggregate rating averages
- `send_feedback_notification()` method on `EmailService` — sends HTML
email with star ratings, all text fields, link to admin page
- Wired into `submit_user_feedback` as fire-and-forget (won't block user
response)

**Frontend:**
- New admin page with aggregate stat cards, searchable/paginated table,
visual star ratings, expandable rows for text detail
- "Feedback" sidebar nav item with MessageSquare icon
- `adminApi.listFeedback()` client method + TypeScript types

**Tests:** 14 tests covering endpoint (pagination, search, filtering,
aggregates, empty state, datetime edge cases), email (content, subject,
custom admin, failure), and caller-callee contract integration

## Test plan

- [x] `make test` — 712 tests pass (39 suites)
- [x] 14 new tests in `test_admin_feedback.py`
- [ ] Manual: verify admin page renders at `/admin/feedback` after
deploy
- [ ] Manual: submit feedback → verify email arrives at
admin@nomadkaraoke.com

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-23 16:18:32 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 376008fc8f Anti-abuse: credits on verification, IP + fingerprint rate limiting (#552)
## Summary

Three-layer defense against free credit abuse (disposable email bypass):

- **Credits on verification**: Welcome credits granted on first magic
link verification, not account creation. Unverified accounts get 0
credits.
- **Per-IP rate limiting**: Max 2 new accounts per IP per 24 hours.
Silent reject (anti-enumeration).
- **Device fingerprinting**: FingerprintJS (open source) sends browser
fingerprint with magic link request. Combined with IP — either signal
hitting 2/day triggers block. Graceful degradation if fingerprinting
fails.

## Changes

### Backend
- `get_or_create_user()` creates users with 0 credits, stores
`signup_ip` and `device_fingerprint`
- New `grant_welcome_credits_if_eligible()` with
`welcome_credits_granted` flag for idempotency
- Verify endpoint grants credits and returns `credits_granted` in
response
- `count_recent_signups_from_ip()` and
`count_recent_signups_from_fingerprint()` query Firestore
- `is_signup_rate_limited()` combines IP + fingerprint signals
- `send_magic_link` endpoint checks rate limit before creating magic
link (new users only)
- New fields: `User.signup_ip`, `User.device_fingerprint`,
`User.welcome_credits_granted`, `MagicLinkToken.device_fingerprint`,
`SendMagicLinkRequest.device_fingerprint`,
`VerifyMagicLinkResponse.credits_granted`

### Frontend
- New `fingerprint.ts` lib (lazy-loaded FingerprintJS)
- `sendMagicLink` sends `device_fingerprint` with request
- Verify page shows "You received N free credits to get started!" on
first login
- `VerifyMagicLinkResponse` type updated with `credits_granted`

### Tests
- 33 unit + integration tests in `test_anti_abuse.py`
- Covers: credit granting, idempotency, rate limiting (IP +
fingerprint), error paths, caller-callee contracts, model fields,
endpoint integration

## Testing
- [x] All backend tests pass (33 new + existing)
- [x] All frontend tests pass (707 tests)
- [x] `make test` passes

## Review
- [x] CodeRabbit CLI review completed locally
- [x] Review feedback addressed (added `welcome_credits_granted` flag
for idempotency)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-21 01:51:44 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 05cb7a9bec feat: auto-sync disposable email blocklist from community repo (#546)
## Summary

- Add daily auto-sync of disposable email domains from the
[disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains)
community repo (~4,800 domains vs previous 160 hardcoded)
- Restructure Firestore blocklist into three layers: external
(auto-synced), manual (admin-added), allowlisted (admin overrides)
- Admin UI updated with separate sections for each domain source + "Sync
Now" button

## Changes

### Backend
- New `disposable_domain_sync_service.py` — fetch, parse, and sync
external blocklist with migration support
- Updated `email_validation_service.py` — effective set = (external +
manual) - allowlisted, new allowlist CRUD, backward-compatible
`get_blocklist_config()`
- New API endpoints: `POST /blocklists/sync`, `POST/DELETE
/blocklists/allowlisted-domains`, `POST
/internal/sync-disposable-domains`
- Updated `GET /blocklists` response with `external_domains`,
`manual_domains`, `allowlisted_domains`, `last_sync_at`,
`last_sync_count`

### Frontend
- Admin rate-limits page: three sub-sections (external/manual/allowlist)
with sync status bar
- Updated API client types and methods

### Infrastructure
- Cloud Scheduler job for daily sync at 3:00 AM UTC (Pulumi)

### Migration
- First sync automatically migrates from old `disposable_domains` field
- Hardcoded `DEFAULT_DISPOSABLE_DOMAINS` replaced with empty set
(external sync takes over)

## Testing
- 47 new/updated tests across 3 test files (54 total for email
validation + sync)
- 2584 tests pass in full suite
- CodeRabbit CLI: no findings

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 18:45:51 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 6b17a1c748 feat: review reminder emails and auto-expiry for stale jobs (#544)
## Summary

- Hourly cron detects jobs stuck in review (`awaiting_review` /
`in_review`) and takes action
- **24h**: sends gentle reminder email with review link, help offer, and
expiry warning
- **48h**: auto-cancels job, refunds credit, sends expiry notification
with balance

## Changes

- **New:** `backend/workers/stale_review_processor.py` — core processor
logic
- **New:** `EmailService.send_review_reminder()` and
`send_review_expired()` email methods
- **New:** `POST /api/internal/process-stale-reviews` endpoint (Cloud
Scheduler target)
- **New:** Cloud Scheduler job `stale-review-hourly` (hourly, Pulumi)
- **New:** 24 unit tests (14 processor + 10 email)
- **Fix:** `make test` no longer hangs on frontend Playwright E2E tests
- Excludes made-for-you and tenant jobs
- Uses separate `expiry_reminder_sent` flag (independent of existing
idle reminder)
- Version bump: 0.142.4 → 0.143.0

## Testing

- [x] 24 new unit tests, all passing
- [x] Full backend test suite: 2578 passed
- [x] Full frontend unit tests: 704 passed
- [x] `make test` completes without hanging

## Review

- [x] Local CodeRabbit review completed (5 findings, 4 fixed, 1
correctly skipped)
- [x] Spec review completed (critical `reminder_sent` flag collision
caught and fixed)

## Design

See `docs/archive/2026-03-19-review-reminder-autoexpiry.plan.md` for
full spec.

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 16:15:01 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 51cd0eadc5 Extend search session TTL to 7 days and handle expiry gracefully (#510)
## Summary
- Extended search session TTL from 30 minutes to 7 days so users who
leave a tab open mid-flow don't hit "Search expired"
- Added graceful frontend handling when sessions do expire — redirects
to re-search with a friendly message instead of raw error
- Updated API docs and tests to match

## Changes
- `backend/api/routes/audio_search.py`: TTL `timedelta(minutes=30)` →
`timedelta(days=7)`
- `frontend/components/job/GuidedJobFlow.tsx`: Catch 404/"Search
expired" errors, clear stale session, redirect to Step 2 with friendly
message preserving song info
- `backend/tests/test_standalone_search.py`: Updated test helper TTL to
match
- `docs/API.md`: Updated TTL reference from "30-min" to "7-day"

## Testing
- [x] All 31 search-specific tests pass
- [x] Full backend suite passes (2212 passed)

## Review
- [x] Local CodeRabbit review completed (no issues with these changes)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 03:23:46 -04:00
Andrew Beveridge ☄️andClaude Opus 4.6 f1ec70924e Add lyrics review session backup/restore system (#509)
## Summary

- Server-side auto-save of lyrics review sessions (every 60s if dirty,
on preview, on page hide) with SHA-256 deduplication
- Split-pane restore UI with session browser, edit diff preview, and
cross-job search
- Auto-prompts on load if saved sessions exist; falls back to
localStorage for local mode

## Changes

### Backend
- **New model**: `ReviewSession` + `ReviewSessionSummary` dataclasses
with Firestore serialization
- **5 new API endpoints** under `/api/review/`: save, list, get, delete
sessions + cross-job search
- **Firestore**: 8 new methods for review session CRUD using
subcollection pattern (`jobs/{jobId}/review_sessions/{sessionId}`)
- **GCS storage**: Correction data stored in GCS (can exceed Firestore's
1MB doc limit); metadata in Firestore
- **Deduplication**: SHA-256 hash comparison skips saving identical data

### Frontend
- **`useReviewSessionAutoSave` hook**: 60s interval auto-save,
visibilitychange save, exposed `saveSession()` for manual/preview
triggers
- **`SessionRestoreDialog`**: Split-pane modal with session list + edit
diff preview, "This Job"/"All Jobs" tabs, cross-job search, duration
mismatch warning
- **`LyricsAnalyzer` integration**: Auto-checks for saved sessions on
load, "Save Progress" and "Session History" toolbar buttons, triggers
save on preview

### Docs
- API.md: 5 new review session endpoints documented
- README.md: Feature added to Current State table + Recent Changes
- LESSONS-LEARNED.md: GCS + Firestore metadata pattern

### Also included (from #508)
- Job observability improvements: timeline metadata, `log_to_job()`
helper

## Testing
- [x] 18 backend unit tests (model serialization, all API endpoints,
deduplication, auth, 404s)
- [x] 10 auto-save hook tests (triggers, deduplication tracking,
interval, read-only, error handling, summary computation)
- [x] 16 SessionRestoreDialog tests (rendering, restore flow, tab
switching, cross-job search, empty states)
- [x] All 607 frontend tests pass
- [x] All 2409 backend tests pass

## Review
- [x] CodeRabbit CLI review completed locally (1 fix applied:
beforeunload → visibilitychange)
- [x] Test review completed (26 new frontend tests added)
- [x] Docs review completed

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 00:23:42 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 e04337fa5d Fix broken notification and CLI review URLs (#507)
## Summary
- Push notifications were sending users to `/review/{id}` and
`/instrumental/{id}` which 404 on Cloudflare Pages static hosting
- Remote CLI was opening browser to path-based URLs missing the `#/`
hash fragment
- Documentation referenced incorrect URL formats

All URLs now correctly use hash-based routing: `/app/jobs#/{id}/review`
and `/app/jobs#/{id}/instrumental`

## Changes
- **backend/services/push_notification_service.py** — Fixed notification
click URLs
- **backend/api/routes/jobs.py** — Fixed edit track response
`review_url`
- **karaoke_gen/utils/remote_cli.py** — Fixed CLI browser open URLs
- **karaoke_gen/utils/cli_args.py** — Fixed help text
- **Tests** — Updated assertions in push notification and remote CLI
tests
- **Docs** — Fixed URL examples in API.md, README.md, TESTING.md
- **pyproject.toml** — Bump version 0.137.0 → 0.137.1

## Test plan
- [x] Backend push notification tests pass (35 tests)
- [x] Remote CLI tests pass (174 tests)
- [x] Full backend test suite passes (103 tests)
- [x] Frontend unit tests pass (581 tests)

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-07 21:22:28 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 3f568373fd Add edit completed tracks feature (#506)
## Summary

- Add ability to edit completed karaoke tracks: cleans up existing
outputs (YouTube, Dropbox, GDrive, GCS), recycles brand code, resets
state to AWAITING_REVIEW
- Support optional artist/title metadata updates during edit (triggers
screens regeneration)
- New `POST /api/jobs/{job_id}/edit` endpoint with cleanup tracking and
review URL response
- Edit button in OutputLinks for completed jobs with confirmation modal
explaining implications

## Changes

### Backend
- `backend/api/routes/jobs.py` - New edit endpoint with full output
cleanup (YouTube, Dropbox, GDrive, GCS finals), brand code recycling,
state transition, and optional metadata update
- `backend/models/job.py` - Added COMPLETE → AWAITING_REVIEW state
transition and `edit_count` field
- `backend/tests/test_edit_completed_track.py` - 14 unit tests covering
success, metadata updates, validation, and cleanup

### Frontend
- `frontend/components/job/EditTrackModal.tsx` - Confirmation modal with
optional artist/title editing
- `frontend/components/job/OutputLinks.tsx` - Edit button (amber) for
completed jobs with outputs
- `frontend/lib/api.ts` - `editCompletedTrack()` API method and
`EditTrackResponse` type
- `frontend/components/__tests__/OutputLinks.test.tsx` - 3 new tests for
Edit button visibility

### Docs
- `docs/API.md` - Documented new endpoint
- `docs/README.md` - Added recent changes entry
- `docs/archive/2026-03-06-edit-completed-tracks-plan.md` -
Implementation plan

## Test plan

- [x] 14 backend unit tests for edit endpoint (success, metadata,
validation, cleanup)
- [x] 3 frontend tests for Edit button visibility (complete job, deleted
outputs, non-complete)
- [x] All 576 frontend unit tests passing
- [ ] Manual: Edit a completed track, verify outputs are cleaned up and
review reopens
- [ ] Manual: Edit with metadata change, verify screens regenerate

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-07 02:23:38 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 c2b2aec5fe feat: add Change Visibility button for completed jobs (#501)
## Summary

- Add "Make Public" / "Make Private" button on completed job cards
allowing users to toggle visibility
- Two distinct backend flows: Public→Private (fast redistribution ~1-2
min) and Private→Public (full re-processing ~15-30 min)
- Confirmation modal with direction-specific explanations of what will
happen

## Changes

### Backend
- **New service:** `visibility_change_service.py` — validation, two
change flows, distributed output cleanup (YouTube/Dropbox/GDrive/GCS),
brand code recycling
- **New endpoint:** `POST /api/jobs/{job_id}/change-visibility` with
proper 404/403/400 status codes
- **Video worker:** Added `redistribute_video()` for fast public→private
path (reuses existing finals)
- **Screens worker:** Added render worker trigger after screen regen for
private→public pipeline
- **State machine:** Added `COMPLETE → LYRICS_COMPLETE` transition for
re-processing flow
- **Version:** 0.135.2 → 0.136.0

### Frontend
- **OutputLinks:** "Make Public"/"Make Private" button with Lock/Globe
icons
- **AlertDialog:** Confirmation modal with direction-specific content
explaining consequences
- **API client:** `changeVisibility()` method and response type

### Tests
- 22 backend tests: validation (11), change_to_private (3),
change_to_public (3), output cleanup (4), state transitions (1)
- Frontend OutputLinks test updated for new visibility button

## Testing
- [x] All 22 new backend tests pass
- [x] 2164/2165 backend tests pass (1 pre-existing failure unrelated)
- [x] 573/573 frontend tests pass (30 suites)

## Review
- [x] CodeRabbit CLI review completed locally
- [x] Fixed: Dropbox folder name sanitization mismatch
- [x] Fixed: HTTP status codes (404 for missing job, 403 for ownership)
- [x] Skipped: Screens worker direct DB update (acceptable for simple
restore)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 19:06:51 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 04950345bc Remove legacy per-user job rate limiting (#475)
@coderabbitai ignore

## Summary
- Remove the "5 jobs per day" per-user rate limiting system, which is no
longer needed since credits now control usage
- Delete `rate_limit_service.py` and all associated tests
- Remove `RateLimitExceededError` exception and all references across
backend routes
- Remove rate limit config fields (`enable_rate_limiting`,
`rate_limit_jobs_per_day`)
- Clean up frontend admin page: remove Overview tab (rate limit stats)
and User Overrides tab
- Keep all blocklist management (domain/email/IP blocking) and YouTube
queue features intact
- Update API and README docs to reflect the change

## Changes
- **3 files deleted**: `rate_limit_service.py`,
`test_rate_limit_service.py`, `test_rate_limits_api.py`
- **13 files edited** across backend and frontend
- **Net**: ~56 insertions, ~2,465 deletions

## Test plan
- [x] All backend tests pass (1086 core + unit tests)
- [x] All frontend tests pass (176 tests)
- [x] Verified no remaining references to `RateLimitExceededError` or
`rate_limit_service`
- [x] Blocklist endpoints preserved and tested
- [x] YouTube queue endpoints preserved and tested
- [x] Credit enforcement tests updated (removed rate limit fixtures)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 14:41:18 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 33667a6852 feat: custom video styling for private delivery jobs (#471)
@coderabbitai ignore

## Summary
- Private-delivery users can now customize their karaoke video styling:
upload custom background images (karaoke + title card) and change
artist/title text colors via color pickers with live canvas previews
- Backend: 2 new endpoints (`style-upload-urls`,
`style-uploads-complete`) that validate ownership, cutoff status, and
merge custom assets into the theme's `style_params.json`
- Frontend: `ImageUploadField` component, `KaraokeBackgroundPreview`
canvas, extended `TitleCardPreview` with custom bg/colors,
`CustomizeStep` styling section (visible when private), `GuidedJobFlow`
upload orchestration
- Also: skip `take-screenshots` spec by default (manual helper, not a
real test)

## Test plan
- [x] 15 backend tests covering both new endpoints (auth, validation,
cutoff, asset merging, color overrides)
- [x] 14 CustomizeStep tests (conditional visibility, color pickers,
previews, form interactions)
- [x] 9 ImageUploadField tests (drag-and-drop, validation, file
type/size rejection)
- [x] 2 TitleCardPreview tests (custom colors, custom background URL)
- [x] 6 guided-flow API contract tests (style upload methods)
- [x] All 181 existing Playwright E2E tests pass
- [ ] Manual: create a private job, upload custom backgrounds, verify
colors render in video

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 11:44:23 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 937f8f7ec1 feat: YouTube quota GCP monitoring + legacy beta cleanup (#460)
## Summary
- Remove the deprecated beta enrollment system (endpoints, models, email
templates, admin UI, rate limits) — ~20 files cleaned
- Remove legacy count-based YouTube upload tracking from
rate_limit_service and dead blocklist methods
- Add GCP Cloud Monitoring integration to cross-reference YouTube API
quota usage with Firestore tracking
- Add drift detection (alerts when GCP reported vs Firestore tracked
differs >10%)
- Display GCP quota data in admin rate-limits dashboard

## Changes

### Backend (15 files)
- **Removed:** 5 beta endpoints, `BetaTesterStatus` enum, beta User
fields, beta email templates, `validate_email_for_beta()`, deprecated
YouTube/beta rate limit methods, dead blocklist CRUD methods
- **Added:** `get_gcp_quota_usage()` to `YouTubeQuotaService` with Cloud
Monitoring API query, 5-min cache, and drift detection
- **Updated:** Rate limits API response model with GCP quota fields
(`gcp_quota_available`, `gcp_quota_units_consumed`, `quota_drift`,
`quota_drift_alert`)

### Frontend (11 files)
- **Deleted:** `frontend/app/admin/beta/page.tsx` (entire beta admin
page)
- **Removed:** Beta sidebar nav, layout breadcrumb, admin stats card,
beta types/API methods, legacy YouTube stats cards
- **Added:** GCP Cloud Monitoring section in rate-limits page showing
reported usage, delay, and drift alerts

### Tests (4 files)
- Removed 8 obsolete tests for deprecated methods
- Created `test_gcp_quota_monitor.py` with 10 tests covering GCP quota
querying, caching, fallbacks, and drift detection
- Updated mock data and assertions across test files

### Docs (3 files)
- Removed beta endpoint docs from API.md, added GCP quota fields
- Updated ARCHITECTURE.md with Cloud Monitoring integration
- Removed beta program section from PRODUCT-VISION.md

## Test plan
- [x] All 2265 backend tests pass (1 pre-existing failure unrelated)
- [x] All 516 frontend Jest tests pass
- [x] New GCP quota monitor tests cover success, caching, fallbacks,
drift alerts
- [ ] Verify admin rate-limits page no longer shows beta/legacy cards
- [ ] Verify GCP quota section shows "unavailable" gracefully when
monitoring data not yet populated

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-03 20:48:07 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 98b6590658 feat: YouTube quota-aware upload system with deferred queue (#456)
## Summary

- Replace hard-coded 10 uploads/day limit with YouTube API quota unit
tracking (10,000 units/day, ~33 uploads)
- Queue uploads when quota is exhausted instead of silently skipping
them
- Process queued uploads hourly via Cloud Scheduler, notify users via
email when complete
- Add admin dashboard for quota monitoring and queue management

## Changes

### Backend - New Services
- `youtube_quota_service.py` — Tracks YouTube API quota units per day in
Firestore (`youtube_quota` collection, date-keyed by Pacific Time)
- `youtube_upload_queue_service.py` — Manages deferred upload queue in
Firestore (`youtube_upload_queue` collection) with atomic claiming,
retry logic, and failure handling
- `youtube_queue_processor.py` — Worker that processes queued uploads
when quota available (downloads from GCS, uploads to YouTube, sends
notification)

### Backend - Modified
- `video_worker_orchestrator.py` — Queue on quota exhaustion instead of
skip; record quota units after each API call
- `rate_limit_service.py` — Deprecated YouTube methods delegate to new
quota service with legacy fallback
- `job_notification_service.py` + `template_service.py` +
`email_service.py` — Follow-up email when deferred upload completes
- `rate_limits.py` — 3 new admin endpoints: GET queue, POST retry, POST
process
- `internal.py` — Internal endpoint for Cloud Scheduler to trigger queue
processing
- `config.py` — New settings: `youtube_quota_daily_limit`,
`youtube_quota_upload_cost`, `youtube_quota_safety_margin`

### Frontend
- `rate-limits/page.tsx` — YouTube Queue tab with quota progress bar,
queued uploads table, retry/process buttons
- `api.ts` — Types and API methods for queue management

### Infrastructure (Pulumi)
- Cloud Tasks queue `youtube-upload-queue`
- Cloud Scheduler job: hourly, Pacific Time, calls internal process
endpoint

### Tests (90 passing)
- `test_youtube_quota_service.py` — 16 tests
- `test_youtube_upload_queue_service.py` — 15 tests
- `test_youtube_queue_processor.py` — 14 tests (async)
- `test_rate_limits_api.py` — 4 new endpoint tests
- `test_rate_limit_service.py` — 5 updated/new delegation tests

### Docs
- Updated ARCHITECTURE.md, API.md, README.md, LESSONS-LEARNED.md

## Motivation

4 jobs on 2026-03-03 had YouTube uploads silently skipped because the
hard-coded rate limit of 10 uploads/day was reached. Users expected
uploads but got none with no notification. The actual YouTube API quota
(10,000 units/day) supports ~33 uploads — the rate limit was overly
conservative.

## Testing
- [x] 90 targeted backend tests pass (4.03s)
- [x] Frontend Jest tests pass (503 tests)
- [x] CodeRabbit CLI review completed, feedback addressed

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-03 20:19:26 +00:00
Andrew Beveridge ☄️andClaude Opus 4.6 a75384fb6f docs: complete Singa tenant documentation (#455)
Follow-up docs for PR #453 (Singa tenant). Adds React hydration lesson,
tenant asset endpoint docs, local tenant testing guide, and archive
entry.

<!-- @coderabbitai ignore -->

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-03 14:31:26 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 e788187351 docs: catalog API, community detection, and autocomplete (#452)
## Summary
- Documentation for the song lookup autocomplete and community version
detection feature shipped in PR #451

## Changes
- **docs/README.md**: Added feature status rows (song lookup
autocomplete, community version detection) and recent changes entry
- **docs/API.md**: New "Catalog (Song Lookup)" section documenting all 3
endpoints (`/api/catalog/artists`, `/api/catalog/tracks`,
`/api/catalog/community-check`) with request/response examples
- **docs/ARCHITECTURE.md**: Added karaoke-decide and KaraokeNerds to
external services table, added `catalog_proxy_service.py` and
`karaokenerds_service.py` to service modules table
- **docs/LESSONS-LEARNED.md**: Added "Autocomplete UX: Less Is More"
pattern (single autocomplete that overwrites both fields > dual
autocompletes)

## Test plan
- Docs-only change, no code modifications

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-03 18:15:07 +00:00
Andrew Beveridge ☄️andClaude Opus 4.6 e44b5f6543 fix: recent jobs UX - cancel→delete, date sort, hide-completed fix, admin controls (#447)
@coderabbitai ignore

## Summary

- **Cancel → Delete**: The Cancel button now permanently deletes jobs
(Firestore doc + GCS files) via the existing `DELETE /api/jobs/{job_id}`
endpoint. Cancelled jobs no longer exist as a concept in the user-facing
flow.
- **Hide completed fix**: The "Hide completed" toggle now only hides
successful completions (`complete`, `prep_complete`). Failed jobs remain
visible so users always see jobs that need attention.
- **Date-only sorting**: Removed priority-based sorting that buried
failed jobs below completed ones. Jobs now sort purely by `created_at`
descending — newest first, always.
- **Admin controls toggle**: Admins see a Shield toggle in the header
that reveals inline admin action buttons (reset, restart, delete, regen
screens, etc.) on each job card — no need to switch to the admin
dashboard.

## Test plan

- [x] Frontend tests pass (496 tests)
- [x] Backend route tests pass (8 tests)
- [x] `next build` succeeds
- [x] New AdminJobActions component has unit tests
- [x] JobCard admin controls rendering tested
- [x] JobActions cancel→delete behavior tested
- [x] E2E regression test updated for delete flow
- [ ] Visual verification: failed job appears at top of Recent Jobs
- [ ] Visual verification: "Hide completed" keeps failed jobs visible
- [ ] Visual verification: Admin shield toggle shows/hides admin actions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-02 23:28:41 -05:00
Andrew Beveridge ☄️andClaude Sonnet 4.6 f17bc931d0 feat: decouple audio search from job creation (search sessions) (#444)
## Summary

- Fixes 4 UX problems caused by the guided wizard creating a backend job
at Step 2 (audio search), before the user has set `is_private`, display
overrides, or confirmed they want a job at all
- Adds `POST /api/audio-search/search-standalone` — runs search
synchronously, stores results in a 30-minute Firestore session, returns
`search_session_id + results` (no job created)
- Adds `POST /api/jobs/create-from-search` — creates job at Step 3 with
all correct values from the start; atomically consumes the session to
prevent duplicate job creation

## Problems Solved

**A) Orphan job records** — abandoned searches left job records in
Firestore; back button `deleteJob` cleanup was best-effort
**B) Wrong field values at creation** — job existed briefly with
`is_private: false` and no display overrides
**C) Jobs in Recent Jobs list** — `AWAITING_AUDIO_SELECTION` jobs
appeared in the list before user confirmed
**D) Notification chime fired** — state transitions on the temporary job
triggered the action-required chime during search

## Changes

- `backend/routers/audio_search.py` — new `POST
/api/audio-search/search-standalone` endpoint (synchronous, no job)
- `backend/routers/jobs.py` — new `POST /api/jobs/create-from-search`
endpoint with validate-then-consume session pattern
- `backend/services/firestore_service.py` — `create_search_session`,
`get_search_session`, `consume_search_session` (atomic transaction),
`delete_search_session`
- `infrastructure/modules/database.py` — Firestore TTL policy for
`search_sessions` collection (30-min auto-expiry)
- `frontend/lib/api.ts` — `searchStandalone`, `createJobFromSearch`
methods
- `frontend/components/job/steps/AudioSourceStep.tsx` — uses standalone
search; no polling; no job state
- `frontend/components/job/GuidedJobFlow.tsx` — defers job creation to
Step 3 confirm; no `deleteJob` on back

**Unchanged:** old `POST /api/audio-search/search` (CLI backward
compat), upload/URL paths, `AWAITING_AUDIO_SELECTION` status.

## Testing

- [x] 26 new backend unit tests
(`backend/tests/test_standalone_search.py`) covering session CRUD, both
new endpoints, ownership/tenant/TTL/index validation, atomic consumption
- [x] 13 new frontend Jest tests
(`frontend/__tests__/guided-flow.test.tsx`) covering API contract,
component exports, behavioral invariants
- [x] Full test suite passes: 2167 backend + 507 frontend

## Review

- [x] CodeRabbit CLI review completed (3 cycles, 0 remaining findings)
- [x] Atomic session consumption via Firestore transaction (prevents
duplicate jobs on concurrent requests)
- [x] Validate-before-consume pattern (4xx errors leave session intact
for user retry)
- [x] Tenant consistency check added

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-02 18:54:38 -05:00
Andrew Beveridge ☄️andClaude 7e3e247858 feat: improve audio upload UX + signed URL flow for large files (#442)
@coderabbitai ignore

## Summary

- **Better no-results UX**: Replace bare "No audio sources found" text
with a contextual `NoResultsSection` card explaining why results might
be missing (unreleased tracks, independent music, unusual characters)
and what to try
- **Softer timeout styling**: Timeout errors now show amber
(`text-amber-400 bg-amber-500/10`) instead of red — it's a delay, not a
failure. Credit/API errors remain red
- **Larger fallback buttons** when no results: `h-12` height and `w-4
h-4` icons (vs `h-9`/`w-3.5 h-3.5`) since upload/URL are the primary
actions
- **Fix file input text overlap**: Replace `opacity-0` absolute
`<Input>` with `<label>` + `<input className="sr-only">` — eliminates
browser "Browse..." bleed-through, adds "Click to browse or drag a file"
helper text
- **Signed URL upload flow** for large files (≥25MB): Bypasses Cloud
Run's 32MB body limit; files <25MB still use the existing direct upload
- **Upload progress bar**: Phase labels (Preparing / Uploading X/Y MB /
Finalizing) + animated progress bar during signed URL uploads
- **Large file warning** (>100MB): Amber amber notice about expected
upload time
- **GCS CORS config**: Add Pulumi CORS rule for `PUT` from
`gen.nomadkaraoke.com` and `localhost:3000` — required for
browser-to-GCS signed URL uploads to work

⚠️ **Deploy order matters**: The GCS CORS config (infrastructure change)
must be deployed before the signed URL upload path will work in
production. Both changes are in this PR so they deploy together on
merge.

## Test plan

- [x] 492 Jest tests passing (9 new tests for `createJobWithUploadUrls`,
`uploadToSignedUrl`, `completeJobUpload`, `uploadJobSmart`)
- [x] `npx next build` succeeds
- [x] CodeRabbit CLI: no findings
- [ ] **Manual**: Search for a nonexistent track → verify
`NoResultsSection` appears with guidance text and larger buttons
- [ ] **Manual**: Trigger a timeout (slow network) → verify amber banner
(not red)
- [ ] **Manual**: Open upload form → verify no "Browse..." text
bleed-through, see "Click to browse or drag a file"
- [ ] **Manual** (post-deploy): Upload a file ≥25MB → verify progress
bar appears and upload completes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-03-02 15:40:05 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 0ba5193601 fix: recycle brand codes on delete-outputs and job deletion (#437)
## Summary

- E2E happy path test now uses **private mode** (NOMADNP prefix) so test
jobs never consume public NOMAD brand codes or upload to GDrive/YouTube
- `delete-outputs` admin endpoint now **recycles brand codes** after
successful Dropbox + GDrive cleanup
- `DELETE /api/jobs/{id}` endpoint now **recycles brand codes** before
deleting the job record
- Frontend delete-outputs dialog accurately shows brand code recycling
status (recycled/skipped/failed)

## Context

Test jobs ("piri - dog") consumed NOMAD-1275 and NOMAD-1276 brand codes.
When manually deleted via `delete-outputs`, the brand codes were not
recycled back to the counter. This caused the GDrive validator to detect
sequence gaps at 1275/1276 when NOMAD-1277 was later uploaded.

## Test plan

- [x] 7 new unit tests for brand code recycling in both endpoints
- [x] All 490 existing tests pass (483 frontend + backend)
- [x] Frontend builds successfully (TypeScript types updated)
- [ ] Manual: run E2E test, verify job uses NOMADNP prefix
- [ ] Manual: delete-outputs on a test job, verify brand code recycled
in response

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-02 11:25:04 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 e11a5976e3 docs: update for feedback-for-credits and beta deprecation (#432)
## Summary
- Update docs to reflect feedback-for-credits feature (PR #431) and beta
program removal (PR #430)
- Add `user_feedback` Firestore collection to architecture docs
- Mark beta program section as deprecated in API reference
- Add archive entry for the feedback-for-credits feature

## Changes
| File | Update |
|------|--------|
| `docs/README.md` | Replace beta with feedback-for-credits in status
table, add recent changes entries |
| `docs/API.md` | Mark beta section deprecated, document
`feedback_eligible` in `/me`, link from credit enforcement |
| `docs/ARCHITECTURE.md` | Add `user_feedback` collection, mark
`beta_feedback` as deprecated |
| `docs/archive/2026-03-01-feedback-for-credits.md` | New archive entry
|

## Test plan
- [x] Docs-only change, no code modified
- [x] Verified all internal doc links are valid

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-01 23:35:54 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 fc659d0357 feat: feedback-for-credits mechanism for all users (#431)
## Summary

- Users who complete 2+ karaoke videos can submit product feedback to
earn 2 free credits
- Replaces beta-only feedback flow — available to ALL users
- PR 2 of 2: follows #430 which removed the beta program from homepage

## Changes

**Backend:**
- New `POST /api/users/feedback` endpoint with eligibility checks,
validation (>50 char text), credit granting
- New `GET /api/users/feedback/eligibility` endpoint
- `feedback_eligible` field added to `/api/users/me` response
- `UserFeedback` model + `user_feedback` Firestore collection
- Welcome email updated with prominent credit display and feedback
teaser

**Frontend:**
- `FeedbackDialog` component: 4 star ratings, 3 text fields, 2
checkboxes, submit/success states
- Dismissible banner on dashboard when user is eligible
- "Earn 2 Free Credits" menu item in user dropdown (green Gift icon)
- Auto-refreshes user data after submission to hide prompts

**Docs:**
- API.md updated with new endpoints

## Test plan

- [ ] Backend Python syntax verified (ast.parse)
- [ ] Frontend builds successfully (`npx next build`)
- [ ] Version bumped to 0.121.0
- [ ] Manual flow: sign up → create 2 jobs → see banner → submit
feedback → credits granted → banner disappears
- [ ] Edge cases: duplicate submission blocked, ineligible users don't
see prompts

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-01 23:05:45 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 221f26b0d8 UX overhaul: guidance & simplification across all 4 review stages (#421)
## Summary

Complete UX overhaul of the karaoke video generation review flow,
spanning 4 phases:

- **Phase 1 - Job Creation**: Guided audio source selection with 3-tier
confidence system, responsive stepper, renamed "Find Audio" to "Choose
Audio"
- **Phase 2 - Audio Selection**: Production E2E tests for guided job
creation flow
- **Phase 3 - Lyrics Review**: Guidance panel with workflow steps, gap
navigation scoped to visible lines, simplified review UI with edit
tracking and low-friction feedback
- **Phase 4 - Instrumental Review**: Responsive layout (waveform no
longer disappears on short viewports), canvas-rendered time ruler,
hover-to-highlight waveform regions, dedicated Alternate Instrumental
upload section with duration explanation, dismissable guidance panel

### Key changes
- Root layout switches from viewport-locked (`h-screen overflow-hidden`)
to scrollable (`min-h-screen`) — fixes waveform disappearing on short
viewports
- Bottom section stacks vertically on mobile/tablet, side-by-side on
desktop
- Time ruler rendered directly on canvas with auto-scaling tick
intervals
- Hovering mute region or segment buttons highlights the corresponding
waveform range
- Upload button moved from toolbar to dedicated section with context and
duration requirement
- 21 unit tests added for instrumental review components
- Guidance panels with dismissable tips across lyrics and instrumental
review

## Test plan
- [x] `npx next build` — no errors
- [x] `npx jest --testPathPattern="instrumental-review/__tests__"` —
21/21 pass
- [x] Visual testing at 4 viewports: desktop (1280x800), tablet
(768x1024), mobile (375x667), short (1280x400)
- [x] Hover highlight verified with Playwright MCP
- [x] Time ruler scales correctly at 1x and 2x zoom

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-01 02:58:50 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 d7e12e3443 Add custom instrumental upload endpoint with duration validation (#409)
## Summary
- Add missing `POST /api/jobs/{job_id}/upload-instrumental` endpoint
(was returning 404 in production)
- Validate uploaded audio duration matches original ±0.5s using ffprobe
on GCS signed URLs
- Fix frontend bug: map "uploaded" → "custom" selection type at submit
time (API only accepts "custom")

## Changes
- **backend/api/routes/jobs.py**: New upload endpoint +
`_get_audio_duration_ffprobe_signed` helper
- **frontend/components/instrumental-review/InstrumentalSelector.tsx**:
Selection type mapping fix
- **backend/tests/test_custom_instrumental_route.py**: 22 new tests
(upload endpoint, ffprobe helper, contract)
- **docs/API.md**: Document new endpoint
- **docs/README.md**: Add to recent changes
- **pyproject.toml**: Bump version 0.119.2 → 0.119.3

## Test plan
- [x] 22 new tests covering success, auth, state validation, duration
mismatch, boundary cases
- [x] All 33 existing tests continue to pass
- [ ] Manual verification: upload custom instrumental in review UI

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-25 23:59:59 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 20453a877c Enforce credit system for karaoke video generation (#404)
## Summary

- Wire up the existing credits system to actually gate job creation -
previously, credits were tracked but never enforced
- Add credit check before job creation, atomic deduction after, and
auto-refund on job failure
- New users now receive 2 welcome credits (was 1)
- Frontend shows zero-credit warning banner, disables submit, and
handles 402 errors with "Buy Credits" link
- Clean up dead credit deduction code from auth_service

## Changes

**Backend:**
- `InsufficientCreditsError` exception with 402 handler
- Credit check + deduction in `JobManager.create_job()` (admin bypass,
atomic deduction, rollback on failure)
- Auto-refund in `JobManager.fail_job()` (skipped for admins,
error-isolated)
- Welcome credits bumped 1 → 2
- Removed dead credit deduction path from
`auth_service.increment_token_usage()`

**Frontend:**
- Zero-credit warning banner at top of job submission form
- Submit buttons disabled when credits = 0
- 402 error handling with "Buy Credits" link
- Boolean state `isCreditError` (not string matching) for credit error
display

**Tests:**
- 13 new backend unit tests covering enforcement, refunds, admin bypass,
atomicity
- 3 new Playwright E2E tests for frontend credit UX
- Tests for 402 exception handler and auth_service cleanup

## Test plan

- [x] Backend unit tests: `pytest tests/test_credit_enforcement.py -v`
(13 tests)
- [x] 402 handler test in `test_main.py`
- [x] Auth service test in `test_auth_firestore.py`
- [x] Frontend E2E tests: `npx playwright test
e2e/regression/credit-enforcement.spec.ts`
- [x] Full suite: `make test` (1928 tests passed)
- [ ] Manual: Create test user with 0 credits → verify 402
- [ ] Manual: Create test user with 1 credit → verify deduction
- [ ] Manual: Fail a job → verify credit refund

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-25 01:00:06 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 fa9bc8eeeb Add private (non-published) tracks option (#403)
@coderabbitai ignore

## Summary

- Add `is_private` flag to jobs that changes distribution behavior for
non-published tracks
- Private jobs upload to Dropbox `Tracks-NonPublished` folder with
`NOMADNP` brand prefix
- Private jobs skip YouTube and Google Drive uploads entirely
- Completion emails omit YouTube section for private jobs
- Available to all users at job creation; admin can toggle on existing
jobs
- When admin toggles completed job to private, existing outputs are
auto-deleted

## Changes

### Backend
- **Job model**: Added `is_private: bool = False` to `Job` and
`JobCreate`
- **Config**: Added `DEFAULT_PRIVATE_DROPBOX_PATH` and
`DEFAULT_PRIVATE_BRAND_PREFIX` settings
- **Distribution helper**: New `get_effective_distribution_for_job()` in
`job_defaults_service.py` applies private overrides at runtime
- **Orchestrator + native paths**: Both distribution code paths use the
helper (per "Fix Both Sides" lesson)
- **Email template**: YouTube section conditionally removed when
`is_private=True`
- **Credential pre-validation**: Skip YouTube/GDrive credential checks
for private jobs
- **API endpoints**: All 4 job creation endpoints accept `is_private`;
admin can PATCH it
- **Admin auto-delete**: Toggling completed job to private triggers
output deletion

### Frontend
- **Job creation form**: "Private (Non-Published)" checkbox on all 3
tabs (upload, URL, search)
- **Admin dashboard**: Private toggle in job configuration section
- **API interfaces**: Updated TypeScript interfaces and API methods

### Tests
- 23 unit tests covering model, distribution overrides, email template,
notification service, request models, admin toggle, and orchestrator
config
- Fixed MagicMock truthiness issue in existing tests

## Test plan

- [x] All 23 private tracks tests pass
- [x] All 1794 existing backend tests pass (1 flaky unrelated test)
- [x] CodeRabbit review: credential pre-validation issue found and fixed
- [ ] Manual: Create private job end-to-end, verify Dropbox folder
- [ ] Manual: Verify completion email has Dropbox link but no YouTube
section
- [ ] Manual: Admin toggle on completed job deletes outputs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-24 18:07:57 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 d22f1893f8 fix: add missing create-custom-instrumental endpoint and prevent oversized Firestore docs (#400)
## Summary
- Add missing `POST /api/jobs/{id}/create-custom-instrumental` endpoint
that was lost during the unified review UI migration. The endpoint
creates a custom instrumental by muting selected backing vocal regions
and returns a signed audio URL for playback.
- Strip `reference_lyrics` from corrections data before saving to
Firestore `state_data`, preventing 1MB document size limit errors when
Genius fetches non-lyrics content (e.g. screenplays). Full data is
preserved in GCS.
- Update frontend `InstrumentalSelector` to use the signed audio URL
returned from the create endpoint instead of a non-existent stream
endpoint.

## Test plan
- [x] 11 new backend tests covering both fixes (happy path, auth,
validation, error handling, Firestore stripping, GCS preservation)
- [x] Full test suite passes (1912 backend, 168 frontend)
- [ ] Manual test: create custom instrumental on a job in review
- [ ] Manual test: submit corrections for a job with oversized Genius
lyrics

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-23 01:25:02 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 3ea48e487f feat: server-side jobs filtering with field projection (#397)
## Summary
- Add `fields=summary` query param to `GET /api/jobs` — uses Firestore
`select()` to return only ~12 dashboard-required fields instead of 50+
full Job fields, reducing payload from ~16MB to <500KB
- Add `hide_completed=true` query param for server-side filtering of
terminal statuses (complete, prep_complete, failed, cancelled)
- Safety-net prune helpers strip extra keys from `state_data` and
`file_urls` nested dicts
- Backward compatible: without `fields=summary`, endpoint returns full
`List[Job]` as before (admin pages unaffected)

## Test plan
- [x] 8 backend unit tests covering prune helpers, hide_completed,
exclude_test with dicts, backward compatibility
- [x] 5 frontend Jest tests covering query param serialization and
partial summary response handling
- [x] All 2412 existing tests pass (`make test`)
- [ ] Deploy to staging, verify network tab shows reduced payload size
- [ ] Verify JobCard renders correctly with summary data (title, status,
progress, download links, error)
- [ ] Toggle hide-completed — verify server re-fetch with
`hide_completed=true`
- [ ] Verify admin jobs page (`/admin/jobs`) still works (doesn't send
`fields=summary`)

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 09:06:23 -05:00
Andrew Beveridge ☄️andClaude Opus 4.6 0cecc86b79 feat: eager audio transcoding for review UI (#395)
## Summary
- Add `AudioTranscodingService` that transcodes FLAC audio to OGG Opus
128kbps (~3 MB vs 35+ MB), cached in GCS at `review-audio/*.ogg`
- Eager transcoding in `screens_worker` before `AWAITING_REVIEW` so
files are cached before the user opens the review UI
- All 3 review audio paths (`_stream_audio`, `get_correction_data`,
`get_instrumental_analysis`) now serve transcoded OGG URLs with FLAC
fallback
- Admin endpoint `POST /admin/jobs/{job_id}/prepare-review-audio` for
backfilling existing jobs

## Test plan
- [x] 21 unit tests at 100% coverage on `AudioTranscodingService`
- [x] 229 existing review tests pass with 0 regressions
- [ ] Deploy and use admin endpoint to backfill job `4bed6f80`
- [ ] Open review UI — verify audio loads fast, Network tab shows ~3 MB
OGG
- [ ] Check GCS for cached files at `jobs/4bed6f80/review-audio/*.ogg`

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-20 13:24:59 -05:00
Andrew Beveridge ☄️andClaude Sonnet 4.5 2b1e4ead00 fix(admin): perform audio search in override-audio-source endpoint (#374)
## Summary

Fixes the override-audio-source endpoint which was transitioning jobs to
`awaiting_audio_selection` without actually performing the search,
leaving jobs stuck with no results to select from.

## Changes

- Now performs actual audio search after clearing state
- Stores search results in state_data before transitioning
- Updated response model to include `search_results_count` and `error`
fields
- Updated API docs to reflect new behavior

## Test plan

- [x] Ran test_admin_job_reset.py - all 39 tests pass
- [x] Manually tested on job 284ed6a6 (populated search results)

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-04 22:22:41 -08:00
Andrew Beveridge ☄️andClaude Sonnet 4.5 b7b5d5c814 feat(admin): add MFY restart and override admin tools (#373)
## Summary

Add three new admin endpoints for better Made-For-You order management,
plus clean up the admin toolbar to remove confusing low-level buttons.

### New Endpoints

1. **`POST /api/admin/jobs/{job_id}/regenerate-screens`**
   - Regenerates title/end screens with current artist/title metadata
- Use after editing artist/title to update screens without full
reprocessing

2. **`POST /api/admin/jobs/{job_id}/restart`**
- Full restart that actually triggers workers (fixes the "stuck in
pending" issue)
   - Option to preserve audio stems for faster restart
   - Handles YouTube, audio search, and file upload jobs appropriately

3. **`POST /api/admin/jobs/{job_id}/override-audio-source`**
   - Switch from YouTube URL to audio search mode
   - Allows finding higher quality audio for MFY orders

### Frontend Changes

- Add new toolbar buttons: **Regen Screens**, **Full Restart**, **Audio
Search**
- Remove confusing low-level buttons that could leave jobs in broken
states:
  - "Reset to Start" (replaced by "Full Restart")
  - "Clear Workers" (low-level escape hatch)
  - "Trigger" (low-level escape hatch)
- Add confirmation dialogs with clear explanations

### Use Case

When a customer submits a Made-For-You order with:
- Wrong artist/title → Edit fields, click "Regen Screens"
- Low-quality YouTube URL → Click "Audio Search" to switch to audio
search mode
- Job stuck after reset → Click "Full Restart" to actually trigger
workers

## Test plan

- [ ] Verify new endpoints return proper responses
- [ ] Verify "Regen Screens" regenerates screens with updated metadata
- [ ] Verify "Full Restart" with preserve_audio_stems=true triggers
screens worker
- [ ] Verify "Full Restart" with preserve_audio_stems=false re-downloads
YouTube audio
- [ ] Verify "Audio Search" transitions job to awaiting_audio_selection
- [ ] Verify old confusing buttons are removed from toolbar

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

@coderabbitai ignore

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-04 18:57:17 -08:00
Andrew Beveridge ☄️andClaude Sonnet 4.5 20b75dcdf5 feat: add flacfetch version and health indicator to frontend footer (#353)
## Summary
Add flacfetch service health monitoring to the frontend footer,
displaying version and status alongside the existing encoding worker
indicator.

## Changes
- **Backend**: Added `/api/health/flacfetch` endpoint for lightweight
health checks
- **Frontend**: Added flacfetch health display in version footer with
green/red status indicator
- **Tests**: Added 6 comprehensive unit tests for health endpoints
(flacfetch + encoding worker)
- **Docs**: Updated API.md with new endpoint documentation

## Implementation Details
The footer now displays:
```
Frontend: v0.114.8 | Backend: v0.114.8 | ● Encoder: v0.95.1 | ● Flacfetch: v1.2.3
```

Health indicators:
- Green dot (●) = service healthy
- Red dot (○) = service offline
- Hidden if service not configured

## Testing
- [x] All 1749 tests pass (including 6 new health endpoint tests)
- [x] Manual code review completed (CodeRabbit CLI couldn't handle large
diff)
- [x] API endpoint tested for all states (not_configured, offline, ok)

## Review
- [x] Code quality verified - follows existing patterns
- [x] Tests comprehensive - all response states covered
- [x] Documentation updated - API.md includes new endpoint

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-25 15:53:28 -08:00
Andrew Beveridge ☄️andClaude Opus 4.5 29be83cb56 Combined review flow: lyrics + instrumental selection in one session (#351)
## Summary

Merges the two-step human review process (lyrics review → instrumental
selection) into a single unified flow. Users now review lyrics AND
select instrumental track in one session.

**Benefits:**
- Better UX (one interaction vs two)
- Reduced drop-off between steps
- Single email notification instead of two
- Simpler workflow

## Changes

### Backend
- `complete_review` endpoint now accepts optional
`instrumental_selection` in request body
- Backing vocals analysis moved from `render_video_worker` to
`screens_worker` (runs before review)
- Removed standalone instrumental selection endpoints (now part of
combined review)
- Added `CompleteReviewRequest` model with validation

### Frontend
- New `InstrumentalSelectorEmbedded` component for combined review UI
- `LyricsAnalyzer` updated to proceed to instrumental review
- `ReviewChangesModal` shows "Proceed to Instrumental Review" button
- Mock data updated in E2E tests

### Local CLI
- `gen_cli.py` refactored to use `run_combined_review()` instead of
separate `run_instrumental_review()`
- `ReviewServer` extended with instrumental options and analysis
- Deleted standalone `InstrumentalReviewServer`

### Documentation
- Updated `docs/README.md` with recent changes entry
- Updated `docs/ARCHITECTURE.md` with new pipeline diagram
- Updated `docs/API.md` with endpoint changes
- Added lesson to `docs/LESSONS-LEARNED.md`

## Test plan

- [x] Backend unit tests: 1742 passed
- [x] Frontend unit tests: 234 passed
- [x] New integration tests: 5 tests for combined flow
- [x] New backend tests: 7 tests for CompleteReviewRequest and
state_data
- [x] New frontend E2E tests: 6 tests for combined flow UI

🤖 Generated with [Claude Code](https://claude.com/claude-code)

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 11:49:51 -08:00
Andrew Beveridge ☄️andClaude Opus 4.5 3413afc722 feat(admin): improve reset job feedback and add manual worker trigger (#344)
## Summary

- Improve admin reset job feedback with transparent worker trigger
status
- Add manual trigger endpoint as fallback when auto-trigger fails
- Enhance frontend UI with detailed result dialogs and loading states

**Problem:** When using the admin "Reprocess" button (reset to
`instrumental_selected`), the job status reset correctly but the video
worker was NOT automatically triggered, leaving jobs stuck. The
auto-trigger could fail silently with no user feedback.

## Changes

### Backend (`backend/api/routes/admin.py`)
- Add `worker_triggered` and `worker_trigger_error` fields to
`JobResetResponse`
- Add try/except error handling around worker trigger in `reset_job()`
- Add new `POST /api/admin/jobs/{job_id}/trigger-worker` endpoint for
manual triggering

### Frontend (`frontend/app/admin/jobs/page.tsx`, `frontend/lib/api.ts`)
- Add "Trigger" button in admin toolbar for manual worker triggering
- Add detailed Reset Result Dialog showing:
  - Status change (from → to)
  - State data keys that were cleared
  - Worker trigger status (for instrumental_selected)
  - "What happens next" guidance
  - "Trigger Now" button if worker wasn't triggered
- Add loading spinners for all async operations

### Tests (`backend/tests/test_admin_job_reset.py`)
- Add 14 new tests for worker trigger response fields and trigger-worker
endpoint
- All 38 tests pass

### Documentation
- Update `docs/API.md` with new endpoint and response fields
- Update `docs/README.md` recent changes

## Test plan

- [x] Backend tests pass (1756 passed)
- [x] TypeScript compiles without errors
- [ ] Manual: Reset a job to `instrumental_selected` via admin UI
- [ ] Manual: Verify response shows worker trigger status
- [ ] Manual: If trigger fails, verify error shown in UI
- [ ] Manual: Click "Trigger Worker" button and verify job starts
processing

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-24 13:39:22 -08:00
Andrew Beveridge ☄️andClaude Opus 4.5 9470a0801f fix: clear worker progress keys when re-reviewing or resetting jobs (#341)
## Summary

- **Fix critical bug**: When completed jobs are re-reviewed or reset,
worker progress keys were not cleared, causing workers to skip with
"already complete, skipping"
- **Add Clear Workers button**: Escape hatch in admin UI to manually
clear all worker progress markers
- **Add new API endpoint**: `POST
/api/admin/jobs/{job_id}/clear-workers` for programmatic access
- **Fix E2E test suite**: Update admin-job-detail.spec.ts tests to match
current UI patterns

## Test plan

- [x] Backend unit tests for new `delete_state_data_key(s)` methods pass
- [x] Backend tests for review re-submission and admin reset pass
- [x] Frontend E2E tests for Clear Workers button pass
- [x] All admin-job-detail E2E tests now pass (fixed 9 pre-existing
failures)

## Root cause

Jobs have worker progress keys like `render_progress: {stage:
'complete'}` in `state_data`. Workers check these for idempotency. When
re-reviewing a completed job:
1. Review interface only changed `status` to `in_review`
2. Worker progress keys remained with `stage: 'complete'`
3. Triggered workers saw "complete" and skipped execution

## Solution

- Clear worker progress keys in `review.py` when re-reviewing jobs that
were previously completed
- Add `job_manager.delete_state_data_key(s)` helpers
- Add admin UI button and API endpoint for manual intervention

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-24 10:27:04 -08:00
Andrew Beveridge ☄️andClaude Opus 4.5 4e7f8bb3d8 feat(admin): add job reprocess option for re-encoding after output deletion (#329)
## Summary

- Add "Reprocess" button to admin job reset toolbar
- Enables re-encoding and re-distributing jobs with existing settings
after deleting outputs
- Automatically triggers video worker when resetting to
`instrumental_selected` state

## Changes

### Backend (`backend/api/routes/admin.py`)
- Add `instrumental_selected` to allowed reset states
- Configure state data clearing (video_progress, encoding_progress,
distribution, brand_code, etc.)
- Auto-trigger video worker via WorkerService after reset

### Frontend (`frontend/app/admin/jobs/page.tsx`)
- Add "Reprocess" button with RefreshCw icon to reset toolbar
- Add tooltip explaining the action

### Tests (`backend/tests/test_admin_job_reset.py`)
- Test successful reset to instrumental_selected
- Test video worker trigger after reset
- Test message reflects worker trigger success/failure
- Test state data clearing

## Test plan

- [x] Unit tests pass for new reset target
- [x] All existing admin reset tests still pass
- [x] CodeRabbit review completed

## Use case

1. Job completes but has quality issues
2. Admin uses "Delete Outputs" to remove YouTube/Dropbox/GDrive files
3. Admin clicks "Reprocess" button
4. Job re-encodes and re-distributes with same settings

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-21 23:31:30 -08:00
Andrew Beveridge ☄️andClaude Opus 4.5 85db864207 feat(admin): Add delete outputs button for quality issue remediation (#272)
## Summary

Add admin functionality to delete all distributed outputs (YouTube,
Dropbox, Google Drive) for a completed job while preserving the job
record. This enables quality issue remediation by deleting outputs,
resetting to review, and re-generating.

## Changes

- Add `outputs_deleted_at` and `outputs_deleted_by` fields to Job model
- Add `POST /api/admin/jobs/{job_id}/delete-outputs` endpoint
- Add auto-clear of outputs_deleted_at flag when outputs are re-uploaded
after re-processing
- Add "Delete All Outputs" button and confirmation dialog in admin job
detail page
- Add "Outputs Deleted" badge when flag is set
- Add 13 unit tests for the new endpoint

## Testing

- [x] Backend unit tests pass (1546 passed)
- [x] Frontend unit tests pass (163 passed)
- [x] Frontend build succeeds
- [x] New endpoint tests pass (13 tests)

## Review

- [x] CodeRabbit CLI review completed locally
- [x] Review feedback addressed (2 issues fixed)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-10 15:32:12 -05:00
Andrew Beveridge ☄️andClaude Opus 4.5 e78cc83abd feat: Add per-day rate limits and abuse prevention (#265)
## Summary

- Add per-user job rate limiting (5 jobs/day default, configurable)
- Add system-wide YouTube upload limiting (10/day default)
- Add beta enrollment abuse prevention (email normalization, disposable
domain blocklist, IP rate limiting)
- Add admin UI for managing blocklists and user overrides at
`/admin/rate-limits`
- Add comprehensive test coverage (40 backend tests, 18 Jest tests, 7
E2E tests)

## Changes

### Backend
- New `RateLimitService` for job and YouTube upload tracking
- New `EmailValidationService` for email normalization and blocklist
checking
- New admin API routes at `/api/admin/rate-limits/*`
- 429 exception handler with detailed rate limit info
- Rate limit checks in job creation and beta enrollment flows

### Frontend
- New admin page at `/admin/rate-limits` with tabs for:
  - Overview (stats and configuration)
  - Blocklists (disposable domains, blocked emails, IPs)
  - User Overrides (bypass permissions, custom limits)

### Configuration
```bash
RATE_LIMIT_JOBS_PER_DAY=5
RATE_LIMIT_YOUTUBE_UPLOADS_PER_DAY=10
RATE_LIMIT_BETA_IP_PER_DAY=1
ENABLE_RATE_LIMITING=true
```

## Test plan

- [x] Backend unit tests pass (40 rate limit tests)
- [x] Frontend Jest tests pass (18 tests)
- [x] E2E smoke tests pass (7 tests)
- [x] Full backend test suite passes (`make test`)

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 23:30:40 -05:00
Andrew Beveridge ☄️andClaude Opus 4.5 81398d01d5 feat(preview): Add fast black background option for lyrics review preview (#263)
## Summary
- Add toggle to render preview videos with black background (~10s) vs
theme background (~30-60s)
- Default to fast black background for better UX during iterative review
- User can enable theme background via checkbox when needed

## Changes
- **Backend**: `backend/api/routes/review.py` - Accept
`use_background_image` param, conditionally skip background image lookup
- **Frontend API**: `api.ts` - Add `PreviewOptions` interface with
`use_background_image` option
- **Frontend UI**: `PreviewVideoSection.tsx` - Add checkbox toggle with
explanatory helper text
- **Docs**: Updated API.md and README.md with feature documentation
- **Version**: Bump to 0.101.0

## Testing
- [x] All tests pass locally (`make test` - 90 E2E + unit tests)
- [x] TypeScript compiles successfully

## Review
- [x] CodeRabbit CLI review completed locally (no issues found)
- [x] Documentation reviewed and updated

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 21:34:53 -05:00
Andrew Beveridge ☄️andClaude 7cfac407e3 feat(admin): Enhanced admin job detail page with files, edit, and reset (#261)
## Summary
- Add comprehensive job management features to admin job detail view
- Enable file downloads with signed GCS URLs grouped by category
- Add inline editing of job fields (artist, title, theme, etc.)
- Add job reset actions to re-process from workflow checkpoints

## Changes

### Backend (39 new tests)
- `GET /api/admin/jobs/{job_id}/files` - Get all job files with signed
URLs (2-hour expiry)
- `PATCH /api/admin/jobs/{job_id}` - Update editable job fields with
whitelist validation
- `POST /api/admin/jobs/{job_id}/reset` - Reset job to specific workflow
checkpoint

### Frontend (13 E2E tests)
- **Files accordion** - Download job files grouped by category (input,
stems, lyrics, outputs)
- **Configuration section** - Inline editing for artist, title,
theme_id, brand_prefix, customer_email
- **Admin Actions section** - Reset buttons for pending, audio
selection, review, instrumental selection
- **Enhanced timeline** - Color-coded stages (green=complete,
blue=processing, orange=waiting, red=failed)

### Documentation
- Updated `docs/API.md` with new endpoint documentation
- Updated `docs/README.md` with feature summary
- Added lesson learned about AuthResult tuple unpacking gotcha

## Test Plan
- [x] Backend tests pass (39 new tests for files, update, reset
endpoints)
- [x] Frontend E2E tests pass (13 tests for admin job detail page)
- [x] Frontend unit tests pass (150 tests)
- [x] Frontend builds successfully
- [x] CodeRabbit review passed (2 cycles, all issues fixed)

## Screenshots
See updated admin job detail page at `/admin/jobs?id={job_id}`

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-09 21:11:58 -05:00
Andrew Beveridge ☄️andClaude Opus 4.5 98b4636006 docs: Document admin login token feature (#260)
## Summary

- Document the admin login token feature added in PR #258
- Add README entry for one-click admin login via email
- Document admin_token URL parameter in API.md verify endpoint

## Changes

- **docs/README.md**: Added "Recent Changes" entry for admin login token
feature
- **docs/API.md**: Added note about admin_token parameter to verify
endpoint docs

## Test Plan

- [x] Documentation builds correctly
- [x] Links are valid

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 20:27:21 -05:00
Andrew Beveridge ☄️andClaude 5fd7d8ae55 feat(api): Add made-for-you audio selection flow (#252)
## Summary

Refactor made-for-you order processing to pause at audio selection like
regular search jobs, giving admin control over audio source selection
before processing.

- Made-for-you orders now pause at `AWAITING_AUDIO_SELECTION` for admin
review
- Admin receives notification email with link to select audio source
- Customer receives professional order confirmation email
- On completion, ownership transfers from admin to customer for delivery

## Changes

### Backend
- Add model fields: `made_for_you`, `customer_email`, `customer_notes`
to Job and JobCreate
- Add email templates: `send_made_for_you_order_confirmation()` and
`send_made_for_you_admin_notification()`
- Add email suppression for intermediate reminders on made-for-you jobs
(internal.py)
- Add ownership transfer on job completion (video_worker.py - not in
this commit, was in prior session)

### Tests
- Add `backend/tests/test_made_for_you.py` with 50+ test cases
- Add made-for-you email tests to `test_email_service.py`
- Add model field tests to `test_models.py`

### Documentation
- Update `docs/API.md` with full made-for-you order flow
- Add "Admin-Owned Jobs with Ownership Transfer" pattern to
`docs/LESSONS-LEARNED.md`
- Add recent changes entry to `docs/README.md`

## Testing

- [x] All Python files pass syntax validation
- [x] Frontend unit tests pass (150 tests)
- [x] Email methods validated via direct Python script
- [x] Model fields validated via direct Python script
- [ ] Backend pytest has pre-existing environment issue
(lyrics_transcriber import)

## Review

- [x] Local CodeRabbit review completed
- [x] Review feedback addressed (hardcoded URL → self.frontend_url)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-09 04:01:22 +00:00
Andrew Beveridge ☄️andClaude Opus 4.5 686b53a9d3 refactor(api): Rename 'done for you' to 'made for you' + enhance checkout UX (#250)
## Summary

- Rename all "done for you" / "done_for_you" / "DoneForYou" references
to "made for you" variants throughout the codebase
- Enhance the Stripe checkout experience with richer product details and
more payment options

## Changes

### Naming Refactor
- Rename `DONE_FOR_YOU_PACKAGE` → `MADE_FOR_YOU_PACKAGE`
- Rename endpoint `/done-for-you/checkout` → `/made-for-you/checkout`
- Rename `DoneForYouCheckoutRequest` → `MadeForYouCheckoutRequest`
- Update Stripe metadata `order_type` from `done_for_you` →
`made_for_you`
- Update all email subjects, log messages, and documentation

### Checkout UX Improvements
- Product name now shows song info: "Karaoke Video: Artist - Title"
- Description shows service details: "Professional 4K karaoke video with
perfectly synced lyrics, delivered to your email within 24 hours"
- Added product image (Nomad Karaoke logo)
- Enabled all payment methods (Apple Pay, Google Pay, Link, Cash App,
Klarna, etc.) by removing `payment_method_types=['card']` restriction

## Test plan

- [x] Tested checkout flow locally with production Stripe keys
- [x] Verified product image displays correctly
- [x] Verified additional payment methods appear (Cash App, Klarna
shown; Apple Pay/Google Pay show on compatible devices)
- [ ] Backend tests pass

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 00:58:30 +00:00
Andrew Beveridge ☄️andClaude Opus 4.5 1110d02519 feat(admin): Add user impersonation feature (#249)
## Summary
- Add user impersonation feature for admins to view the app as any user
- Replace "Make Admin" button with "Impersonate" button in admin users
page
- Display amber impersonation banner when viewing as another user

## Changes
- **Backend**: Add `POST /api/admin/users/{email}/impersonate` endpoint
that creates a session token for the target user
- **Frontend Auth**: Add `startImpersonation` / `endImpersonation`
methods to auth store with token rollback on failure and nested
impersonation prevention
- **Admin UI**: Replace role toggle button with impersonate button
(disabled for self)
- **Banner Component**: New `ImpersonationBanner` component showing
"Viewing as {email}" with Stop button
- **Tests**: 7 backend unit tests + 4 E2E tests (2 skipped - require
stateful mocks)
- **Docs**: Updated API.md with new endpoint, added testing lesson to
LESSONS-LEARNED.md

## Testing
- [x] Backend unit tests pass (7/7 impersonation tests)
- [x] Frontend E2E tests pass (4 pass, 2 skipped)
- [x] Manual testing needed for full flow

## Review
- [x] CodeRabbit CLI review completed locally
- [x] Review feedback addressed (token rollback, nested impersonation
guard)

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-08 19:13:48 -05:00
Andrew Beveridge ☄️andClaude Opus 4.5 42c304dcdf feat(multitenancy): Implement white-label B2B portal infrastructure (#241)
## Summary

Adds multi-tenant white-label portal infrastructure for B2B customers.
Vocal Star is the first tenant at `vocalstar.nomadkaraoke.com`.

## Changes

### Backend
- **Tenant Models** (`backend/models/tenant.py`): Pydantic models for
TenantConfig with branding, features, defaults, and auth settings
- **Tenant Service** (`backend/services/tenant_service.py`): GCS-backed
config loading with 5-min cache, signed URL generation for logos
- **Tenant API** (`backend/api/routes/tenant.py`): `GET
/api/tenant/config` and `GET /api/tenant/config/{tenant_id}` endpoints
- **Tenant Middleware** (`backend/middleware/tenant.py`): Extracts
tenant from X-Tenant-ID header, query param (dev only), or Host
subdomain
- **Auth Updates**: Email domain validation for tenant-restricted auth,
sender email override
- **Feature Enforcement**: Audio search endpoint checks
`features.audio_search`, returns 403 if disabled
- **Job Scoping**: Added `tenant_id` field to JobCreate

### Frontend
- **Tenant Store** (`frontend/lib/tenant.ts`): Zustand store with tenant
state, `useTenant()` hook, CSS variable application
- **TenantProvider** (`frontend/components/tenant-provider.tsx`):
Hydration-safe initialization via useEffect
- **TenantLogo** (`frontend/components/tenant-logo.tsx`): Dynamic logo
with fallback to Nomad Karaoke
- **Feature-Flagged UI**: Tabs conditionally rendered based on tenant
features, active tab sync
- **Locked Themes**: `defaults.locked_theme` hides theme selector and
enforces specific theme
- **Output Links**: Filtered based on distribution features

### Security
- Query param tenant detection disabled in production (prevents
spoofing)
- Strict subdomain patterns: only `{tenant}.nomadkaraoke.com` or
`{tenant}.gen.nomadkaraoke.com`
- PII masking in logs (`an***@vo***.com`)
- `is_active` check prevents inactive tenants from being used

### Documentation
- ARCHITECTURE.md: New Multitenancy section
- API.md: Tenant Config endpoints
- LESSONS-LEARNED.md: 3 new lessons on multitenancy patterns
- Archive: Comprehensive implementation document

### Setup
- `scripts/setup-vocalstar-tenant.py`: Uploads theme assets, creates
tenant/theme configs in GCS

## Vocal Star Configuration

- **Subdomain**: `vocalstar.nomadkaraoke.com`
- **Features**: File upload only (no audio search, no YouTube URL)
- **Distribution**: Download only (no YouTube/Dropbox/GDrive)
- **Theme**: Locked to "vocalstar" (yellow/blue)
- **Auth**: Restricted to `@vocal-star.com` and `@vocalstarmusic.com`
emails

## Testing

- [x] Frontend TypeScript build passes
- [x] CodeRabbit CLI review completed (3 cycles, all issues fixed)
- [x] Manual testing with `?tenant=vocalstar` query param

## Next Steps (post-merge)

1. Configure DNS: CNAME for `vocalstar.nomadkaraoke.com`
2. Update Cloudflare Pages for subdomain
3. Run setup script to upload Vocal Star assets to GCS
4. Test at `https://vocalstar.nomadkaraoke.com`

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-08 16:39:56 -05:00
Andrew Beveridge ☄️andClaude 80b8d9c5ae feat(admin): Add toggle to hide/show test data in admin dashboard (#239)
## Summary

- Filter out E2E test data from admin dashboard by default (emails
ending in `@inbox.testmail.app`)
- Add "Show test data" toggle in admin header that persists to
localStorage
- Add `exclude_test` query parameter to all admin list/stats endpoints
(defaults to `true`)
- Add streaming limits with warnings to prevent memory issues on large
datasets

## Changes

**Backend:**
- New `backend/utils/test_data.py` with `is_test_email()` utility
- Updated admin stats endpoint with test data filtering
- Updated users list, jobs list, beta stats, and audio searches
endpoints
- Added USERS_STREAM_LIMIT (2000) and JOBS_STREAM_LIMIT (10000) with
warning logs

**Frontend:**
- New `frontend/lib/admin-settings.ts` zustand store for admin
preferences
- Toggle switch in admin layout header
- All admin pages pass `exclude_test: !showTestData` to API calls

**Docs:**
- Updated API.md with exclude_test parameter documentation

## Test Plan

- [x] Backend tests pass (68 passed)
- [x] Frontend tests pass (128 passed)
- [x] Frontend build succeeds
- [x] CodeRabbit review passed
- [ ] Manual: Visit `/admin` - stats should show lower numbers by
default
- [ ] Manual: Toggle "Show test data" ON - counts should increase
- [ ] Manual: Toggle persists across page refreshes

<!-- @coderabbitai ignore -->

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-08 16:21:34 +00:00
Andrew Beveridge ☄️andClaude Opus 4.5 8e602a8173 feat(frontend): Add encoding worker status to footer (#228)
## Summary

Display encoding worker health and version in the footer alongside
frontend and backend versions, providing visibility into whether the
high-performance encoder is healthy and up-to-date.

## Changes

- **Backend**: Add `GET /health/encoding-worker` lightweight endpoint
for frontend consumption
- **Encoding Worker**: Enhance `/health` endpoint to include
`wheel_version` (karaoke-gen package version)
- **Frontend**: Update `VersionFooter` to fetch and display encoder
status with visual indicator
- **Version**: Bump to 0.95.1

## Footer Display

When healthy:
```
Frontend: v0.95.1 | Backend: v0.95.1 | ● Encoder: v0.95.1
```

With active jobs:
```
Frontend: v0.95.1 | Backend: v0.95.1 | ● Encoder: v0.95.1 (2 active)
```

When offline:
```
Frontend: v0.95.1 | Backend: v0.95.1 | ○ Encoder offline
```

## Testing

- [x] Frontend builds successfully
- [x] Backend tests pass (1071 passed)
- [x] TypeScript compiles without errors in changed files

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-06 23:18:25 -05:00
Andrew Beveridge ☄️andClaude 2783c2cfcf feat(audio-search): Add display artist/title override for search (#227)
## Summary
- Add optional "Display As" fields to audio search, allowing users to
search for audio by one artist/title but display a different
artist/title on title screens and filenames
- Useful for Broadway casts, covers, remixes where tracker metadata
differs from desired display

## Changes
- Add `display_artist`/`display_title` fields to `AudioSearchRequest`
model
- Update job creation to use display values for output (title screens,
filenames, YouTube, distribution)
- Add "Display As" optional fields to frontend search UI
- Update API documentation

## Example Use Case
- **Search For**: Artist = "Jeremy Kushnier", Title = "I Can't Stand
Still"
- **Display As**: Artist = "Footloose (Broadway Cast)"
- **Result**: Audio found using "Jeremy Kushnier", but title screen
shows "Footloose (Broadway Cast) - I Can't Stand Still"

## Test plan
- [ ] Search with display override → verify title screen shows display
values
- [ ] Search without display override → verify search values used
(backwards compatible)
- [ ] Verify filenames use display values

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-06 22:36:27 -05:00
Andrew Beveridge ☄️andClaude 560c3e4904 feat: Add email notification system with admin controls (#220)
## Summary

- Add automated email notification system for job completion and action
reminders
- Admin UI buttons to copy completion message or send email directly
- Comprehensive test suite (81 new tests)
- **Email subjects include release ID and song info** for easy
identification

## Changes

### Backend
- **Email Service** (`email_service.py`): Extended with SendGrid CC
support, `send_job_completion()` and `send_action_reminder()` methods
- **Job Notification Service** (`job_notification_service.py`): New
service orchestrating completion emails and action reminder scheduling
- **Template Service** (`template_service.py`): GCS-backed HTML email
templates with fallback defaults
- **Worker Service** (`worker_service.py`): Cloud Tasks integration for
delayed idle reminders (5-min delay)
- **Job Manager** (`job_manager.py`): State transition triggers for
automated notifications
- **Admin Routes** (`admin.py`): New endpoints `GET
/api/admin/jobs/{id}/completion-message` and `POST
/api/admin/jobs/{id}/send-completion-email`
- **Internal Routes** (`internal.py`): Idle reminder check endpoint for
Cloud Tasks

### Email Subject Format
Email subjects now include brand code and song info for easy
identification:
- With brand code: `NOMAD-1178: Seether - Tonight (Your karaoke video is
ready!)`
- Without brand code: `Seether - Tonight (Your karaoke video is ready!)`
- Without song info: `Your karaoke video is ready!`

### Frontend
- **OutputLinks Component**: Admin-only "Copy Message" and "Send Email"
buttons with dialog UI
- **E2E Helpers** (`email-testing.ts`): `waitForCompletionEmail()` and
`isCompletionEmail()` methods for testmail.app integration
- **Happy Path Test**: Step 9.5 verifies completion email arrives after
job completion

### Documentation
- Updated API.md with new endpoints
- Updated ARCHITECTURE.md with notification system architecture
- Updated README.md Recent Changes

## Testing

- [x] 81 new unit tests covering:
- `test_email_service.py` (27 tests) - providers, CC support, job
completion/reminder methods
- `test_job_notification_service.py` (21 tests) - URL building, message
generation
- `test_job_manager_notifications.py` (15 tests) - state transition
triggers
  - `test_admin_email_endpoints.py` (12 tests) - admin API endpoints
- `test_template_service.py` (6 tests) - GCS template loading, fallbacks
- [x] E2E test extended to verify completion email delivery
- [x] All backend tests pass (`make test`)
- [x] TypeScript compiles

## Feature Flags

- `ENABLE_AUTO_EMAILS` (default: `false`) - Controls automatic email
sending on job state changes

## Review

- [x] Local CodeRabbit review completed (3 cycles)
- [x] Review feedback addressed:
  - Fixed potential None state_data in internal.py
  - Masked user emails in logs (PII protection)
  - Fixed React setTimeout memory leak
  - Changed placeholder URL default to empty
  - Added CC email deduplication

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-01-06 11:53:11 -05:00