Files
karaoke-gen/.claude/plans/job-email-notifications.plan.md
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

9.1 KiB

Plan: Job Email Notifications & Admin Message Tools

Created: 2026-01-06 Branch: feat/sess-20260106-0116-add-email-button Status: Draft

Overview

Add comprehensive email notification system for karaoke-gen that:

  1. Auto-sends emails when jobs complete or need user input (after 5-minute idle threshold)
  2. Uses cloud-stored templates for the job completion message
  3. Provides admin tools to copy/send completion messages manually (for Fiverr, etc.)

Requirements

Functional Requirements

  • Auto-send job completion email to user (CC: gen@nomadkaraoke.com)
  • Auto-send "action needed" reminder emails when user is idle for 5+ minutes at blocking states (lyrics review, instrumental selection)
  • Store email templates in GCS (editable without code deploy)
  • Admin button: "Copy Message" - copies templated completion message to clipboard
  • Admin button: "Send Email" - prompts for email address, then sends completion message

Non-Functional Requirements

  • Email sending must not block job completion (async/background)
  • Idle detection via Cloud Tasks scheduled task (not polling)
  • Template changes should take effect without restart (no long-term caching)

Technical Approach

1. Template Storage (GCS)

Store templates in gs://karaoke-gen-storage/templates/:

  • job-completion.txt - Plain text template for job completion
  • job-completion.html - HTML version (optional, for rich emails)
  • action-needed-lyrics.txt - Reminder for lyrics review
  • action-needed-instrumental.txt - Reminder for instrumental selection

Template Variables:

  • {name} - User's display name or "there" if unknown
  • {youtube_url} - YouTube video URL
  • {dropbox_url} - Dropbox folder URL
  • {artist} - Artist name
  • {title} - Song title
  • {job_id} - Job ID
  • {review_url} - Lyrics review URL (for action-needed emails)
  • {instrumental_url} - Instrumental selection URL
  • {feedback_url} - Feedback form URL (for completion emails)

2. Email Service Extensions

Extend backend/services/email_service.py:

  • Add send_job_completion() method with CC support
  • Add send_action_reminder() method
  • Add render_template() helper to fetch & render GCS templates

3. Auto-Email Triggers

Job Completion:

  • Trigger point: When job enters COMPLETE status in job_manager.transition_to_state()
  • Implementation: Call email service async in background task

Action Reminders (5-min idle detection):

  • When job enters AWAITING_REVIEW or AWAITING_INSTRUMENTAL_SELECTION:
    • Record blocking_state_entered_at timestamp in state_data
    • Schedule a Cloud Tasks task for 5 minutes later
  • The scheduled task checks if job is still in blocking state and user hasn't started review
  • If idle, send reminder email and set reminder_sent flag to prevent duplicates
  • Only one reminder per job - if reminder_sent is true, skip sending

4. Admin UI (Frontend)

Add admin-only buttons to completed jobs in OutputLinks.tsx:

  • "Copy Message" button - fetches rendered template, copies to clipboard
  • "Send Email" button - opens dialog for email input, calls API to send

5. Backend API Endpoints

New endpoints in backend/api/routes/admin.py:

  • GET /api/admin/jobs/{job_id}/completion-message - Returns rendered completion message
  • POST /api/admin/jobs/{job_id}/send-completion-email - Sends email to specified address

New internal endpoint for scheduled reminder:

  • POST /api/internal/jobs/{job_id}/check-idle-reminder - Called by Cloud Tasks

Implementation Steps

Phase 1: Template Infrastructure

  1. Upload initial template to GCS from user's existing template file
  2. Create template_service.py to fetch/render templates from GCS
  3. Add unit tests for template rendering

Phase 2: Email Extensions

  1. Extend email_service.py with CC support in send_email()
  2. Add send_job_completion() method
  3. Add send_action_reminder() method
  4. Add unit tests for new email methods

Phase 3: Auto-Email on Completion

  1. Modify job_manager.py to trigger completion email when entering COMPLETE
  2. Add integration test for completion email trigger

Phase 4: Idle Reminder System

  1. Add blocking_state_entered_at field tracking to job state transitions
  2. Create Cloud Tasks queue for idle reminders (idle-reminder-queue)
  3. Schedule 5-minute delayed task when entering blocking states
  4. Implement /api/internal/jobs/{job_id}/check-idle-reminder endpoint
  5. Add tests for idle reminder flow

Phase 5: Admin API

  1. Add GET /api/admin/jobs/{job_id}/completion-message endpoint
  2. Add POST /api/admin/jobs/{job_id}/send-completion-email endpoint
  3. Add tests for admin endpoints

Phase 6: Admin UI

  1. Add isAdmin check to OutputLinks.tsx component
  2. Add "Copy Message" button (admin-only) with loading state
  3. Add "Send Email" button (admin-only) with email input dialog
  4. Add E2E test for admin buttons

Phase 7: Documentation

  1. Document template management in docs/DEVELOPMENT.md
  2. Update docs/API.md with new endpoints

Files to Create/Modify

File Action Description
backend/services/template_service.py Create GCS template fetching and rendering
backend/services/email_service.py Modify Add CC support, completion/reminder methods
backend/services/job_manager.py Modify Trigger emails on state transitions
backend/services/worker_service.py Modify Add idle reminder task scheduling
backend/api/routes/admin.py Modify Add completion message/email endpoints
backend/api/routes/internal.py Modify Add idle reminder check endpoint
backend/models/job.py Modify Add blocking_state_entered_at, reminder_sent_at to state_data docs
infrastructure/__main__.py Modify Add idle-reminder-queue Cloud Tasks queue
frontend/components/job/OutputLinks.tsx Modify Add admin-only Copy/Send buttons
frontend/lib/api.ts Modify Add API methods for admin endpoints
tests/unit/test_template_service.py Create Template rendering tests
tests/unit/test_email_service_completion.py Create Completion email tests

Testing Strategy

Unit Tests:

  • Template rendering with all variable combinations
  • Email service CC support
  • Completion/reminder email generation
  • Idle detection logic

Integration Tests:

  • Full flow: job completion → email sent
  • Idle reminder: job enters blocking state → 5 min → reminder sent
  • Admin endpoint authentication

Manual Testing:

  • Verify emails render correctly in Gmail/Outlook
  • Test admin buttons on completed job
  • Test clipboard copy works across browsers

Open Questions

  • Where to store templates? → GCS bucket: gs://karaoke-gen-storage/templates/
  • Should we rate-limit reminder emails? → Max 1 reminder per job (send once after 5 min idle, then stop)
  • Should completion emails also include a feedback request link? → Yes, for all users

Rollback Plan

  1. Email sending failures - All email sends are async/fire-and-forget; job completion unaffected
  2. Template fetch failures - Fall back to hardcoded template in code
  3. Idle reminder failures - Jobs continue normally; users can still access review UI manually
  4. Feature flag - Add ENABLE_AUTO_EMAILS=true/false env var for quick disable

Template Content

Initial template (from user's file, with feedback link added):

Hi {name},

Thanks for your order!

Here's the link for the karaoke video published to YouTube:
{youtube_url}

Here's the dropbox folder with all the finished files and source files, including:
- "(Final Karaoke Lossless).mkv": combined karaoke video in 4k H264 with lossless FLAC audio
- "(Final Karaoke).mp4": combined karaoke video with title/end screen in 4k H264/AAC
- "(Final Karaoke 720p).mp4": combined karaoke video in 720p H264/AAC (smaller file for older systems)
- "(With Vocals).mp4": sing along video in 4k H264/AAC with original vocals
- "(Karaoke).mov": karaoke video output from MidiCo (no title/end screen)
- "(Title).mov"/"(End).mov": title card and end screen videos
- "(Final Karaoke CDG).zip": CDG+MP3 format for older/commercial karaoke systems
- "(Final Karaoke TXT).zip": TXT+MP3 format for Power Karaoke
- stems/*.flac: various separated instrumental and vocal audio stems in lossless format
- lyrics/*.txt song lyrics from various sources in plain text format

{dropbox_url}

Let me know if anything isn't perfect and I'll happily tweak / fix, or if you need it in any other format I can probably convert it for you!

If you have a moment, I'd really appreciate your feedback (takes 2 minutes):
{feedback_url}

Thanks again and have a great day!
-Andrew

Note: The {feedback_url} placeholder will be populated with the feedback form URL. If no feedback URL is configured, this section can be omitted from the rendered output.

Updating Templates

To update email templates after deployment:

# Upload new template
gsutil cp my-template.txt gs://karaoke-gen-storage/templates/job-completion.txt

# Templates are fetched fresh on each use (no caching in code)
# Changes take effect immediately