diff --git a/.claude/plans/job-email-notifications.plan.md b/.claude/plans/job-email-notifications.plan.md new file mode 100644 index 00000000..fe9823d1 --- /dev/null +++ b/.claude/plans/job-email-notifications.plan.md @@ -0,0 +1,218 @@ +# 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 +4. [ ] Extend `email_service.py` with CC support in `send_email()` +5. [ ] Add `send_job_completion()` method +6. [ ] Add `send_action_reminder()` method +7. [ ] Add unit tests for new email methods + +### Phase 3: Auto-Email on Completion +8. [ ] Modify `job_manager.py` to trigger completion email when entering COMPLETE +9. [ ] Add integration test for completion email trigger + +### Phase 4: Idle Reminder System +10. [ ] Add `blocking_state_entered_at` field tracking to job state transitions +11. [ ] Create Cloud Tasks queue for idle reminders (`idle-reminder-queue`) +12. [ ] Schedule 5-minute delayed task when entering blocking states +13. [ ] Implement `/api/internal/jobs/{job_id}/check-idle-reminder` endpoint +14. [ ] Add tests for idle reminder flow + +### Phase 5: Admin API +15. [ ] Add `GET /api/admin/jobs/{job_id}/completion-message` endpoint +16. [ ] Add `POST /api/admin/jobs/{job_id}/send-completion-email` endpoint +17. [ ] Add tests for admin endpoints + +### Phase 6: Admin UI +18. [ ] Add `isAdmin` check to `OutputLinks.tsx` component +19. [ ] Add "Copy Message" button (admin-only) with loading state +20. [ ] Add "Send Email" button (admin-only) with email input dialog +21. [ ] Add E2E test for admin buttons + +### Phase 7: Documentation +22. [ ] Document template management in docs/DEVELOPMENT.md +23. [ ] 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 + +- [x] Where to store templates? → **GCS bucket: `gs://karaoke-gen-storage/templates/`** +- [x] Should we rate-limit reminder emails? → **Max 1 reminder per job** (send once after 5 min idle, then stop) +- [x] 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: + +```bash +# 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 +``` diff --git a/backend/api/routes/admin.py b/backend/api/routes/admin.py index 6c4f35db..0403d3e5 100644 --- a/backend/api/routes/admin.py +++ b/backend/api/routes/admin.py @@ -579,4 +579,159 @@ async def get_flacfetch_cache_stats( status_code=502, detail=f"Failed to get cache stats: {e}" ) -# Trigger deployment + + +# ============================================================================= +# Job Completion Message Endpoints (for admin copy/send functionality) +# ============================================================================= + +class CompletionMessageResponse(BaseModel): + """Response containing the rendered completion message.""" + job_id: str + message: str + subject: str + youtube_url: Optional[str] = None + dropbox_url: Optional[str] = None + + +class SendCompletionEmailRequest(BaseModel): + """Request to send a completion email.""" + to_email: str + cc_admin: bool = True + + +class SendCompletionEmailResponse(BaseModel): + """Response from sending a completion email.""" + success: bool + job_id: str + to_email: str + message: str + + +@router.get("/jobs/{job_id}/completion-message", response_model=CompletionMessageResponse) +async def get_job_completion_message( + job_id: str, + auth_data: Tuple[str, UserType, int] = Depends(require_admin), +): + """ + Get the rendered completion message for a job. + + Returns the plain text message that would be sent to the user, + rendered using the job completion template with the job's details. + + This is useful for: + - Copying the message to clipboard (e.g., for Fiverr) + - Previewing the email before sending + + Requires admin authentication. + """ + from backend.services.job_notification_service import get_job_notification_service + + job_manager = JobManager() + job = job_manager.get_job(job_id) + + if not job: + raise HTTPException(status_code=404, detail=f"Job {job_id} not found") + + # Get youtube, dropbox URLs, and brand_code from state_data (may be None) + state_data = job.state_data or {} + youtube_url = state_data.get('youtube_url') + dropbox_url = state_data.get('dropbox_link') + brand_code = state_data.get('brand_code') + + # Render the completion message + notification_service = get_job_notification_service() + message = notification_service.get_completion_message( + job_id=job.job_id, + user_name=None, # Use default "there" + artist=job.artist, + title=job.title, + youtube_url=youtube_url, + dropbox_url=dropbox_url, + ) + + # Build subject: "NOMAD-1178: Artist - Title (Your karaoke video is ready!)" + if brand_code and job.artist and job.title: + subject = f"{brand_code}: {job.artist} - {job.title} (Your karaoke video is ready!)" + elif job.artist and job.title: + subject = f"{job.artist} - {job.title} (Your karaoke video is ready!)" + else: + subject = "Your karaoke video is ready!" + + return CompletionMessageResponse( + job_id=job_id, + message=message, + subject=subject, + youtube_url=youtube_url, + dropbox_url=dropbox_url, + ) + + +@router.post("/jobs/{job_id}/send-completion-email", response_model=SendCompletionEmailResponse) +async def send_job_completion_email( + job_id: str, + request: SendCompletionEmailRequest, + auth_data: Tuple[str, UserType, int] = Depends(require_admin), +): + """ + Send a completion email for a job to a specified email address. + + This allows admins to manually send (or re-send) completion emails, + useful for: + - Sending to customers who didn't have an email on file + - Re-sending if the original email was lost + - Sending to alternate email addresses + + Requires admin authentication. + """ + from backend.services.job_notification_service import get_job_notification_service + from backend.services.email_service import get_email_service + + job_manager = JobManager() + job = job_manager.get_job(job_id) + + if not job: + raise HTTPException(status_code=404, detail=f"Job {job_id} not found") + + # Get youtube, dropbox URLs, and brand_code from state_data (may be None) + state_data = job.state_data or {} + youtube_url = state_data.get('youtube_url') + dropbox_url = state_data.get('dropbox_link') + brand_code = state_data.get('brand_code') + + # Render the completion message + notification_service = get_job_notification_service() + message = notification_service.get_completion_message( + job_id=job.job_id, + user_name=None, # Use default "there" + artist=job.artist, + title=job.title, + youtube_url=youtube_url, + dropbox_url=dropbox_url, + ) + + # Send the email + email_service = get_email_service() + success = email_service.send_job_completion( + to_email=request.to_email, + message_content=message, + artist=job.artist, + title=job.title, + brand_code=brand_code, + cc_admin=request.cc_admin, + ) + + if success: + logger.info(f"Admin sent completion email for job {job_id} to {request.to_email}") + return SendCompletionEmailResponse( + success=True, + job_id=job_id, + to_email=request.to_email, + message=f"Completion email sent to {request.to_email}", + ) + else: + logger.error(f"Failed to send completion email for job {job_id}") + raise HTTPException( + status_code=500, + detail="Failed to send email. Check email service configuration." + ) diff --git a/backend/api/routes/internal.py b/backend/api/routes/internal.py index acda99f5..f36e2247 100644 --- a/backend/api/routes/internal.py +++ b/backend/api/routes/internal.py @@ -316,13 +316,118 @@ async def trigger_render_video_worker( ) +@router.post("/jobs/{job_id}/check-idle-reminder") +async def check_idle_reminder( + job_id: str, + http_request: Request, + auth_data: Tuple[str, UserType, int] = Depends(require_admin) +): + """ + Check if a job needs an idle reminder email. + + This endpoint is called by a Cloud Tasks scheduled task 5 minutes after + a job enters a blocking state (AWAITING_REVIEW or AWAITING_INSTRUMENTAL_SELECTION). + + If the job is still in the blocking state and no reminder has been sent yet, + sends a reminder email to the user. + + Idempotency: Only one reminder per job (tracked via reminder_sent flag). + """ + from backend.models.job import JobStatus + from backend.services.job_notification_service import get_job_notification_service + + # Extract trace context from incoming request + trace_context = extract_trace_context(dict(http_request.headers)) + + logger.info(f"[job:{job_id}] IDLE_REMINDER_CHECK starting") + add_span_attribute("job_id", job_id) + add_span_attribute("operation", "idle_reminder_check") + + job_manager = JobManager() + job = job_manager.get_job(job_id) + + if not job: + logger.warning(f"[job:{job_id}] Job not found for idle reminder check") + add_span_event("job_not_found") + return {"status": "not_found", "job_id": job_id, "message": "Job not found"} + + # Check if job is still in a blocking state + blocking_states = [JobStatus.AWAITING_REVIEW, JobStatus.AWAITING_INSTRUMENTAL_SELECTION] + if job.status not in [s.value for s in blocking_states]: + logger.info(f"[job:{job_id}] Job no longer in blocking state ({job.status}), skipping reminder") + add_span_event("not_blocking", {"current_status": job.status}) + return { + "status": "skipped", + "job_id": job_id, + "message": f"Job not in blocking state (current: {job.status})" + } + + # Normalize state_data to prevent None errors + state_data = job.state_data or {} + + # Check if reminder was already sent (idempotency) + if state_data.get('reminder_sent'): + logger.info(f"[job:{job_id}] Reminder already sent, skipping") + add_span_event("already_sent") + return {"status": "already_sent", "job_id": job_id, "message": "Reminder already sent"} + + # Check if user has an email + if not job.user_email: + logger.warning(f"[job:{job_id}] No user email, cannot send reminder") + add_span_event("no_email") + return {"status": "no_email", "job_id": job_id, "message": "No user email configured"} + + # Determine action type + action_type = state_data.get('blocking_action_type') + if not action_type: + action_type = "lyrics" if job.status == JobStatus.AWAITING_REVIEW.value else "instrumental" + + # Send the reminder email + try: + notification_service = get_job_notification_service() + + success = await notification_service.send_action_reminder_email( + job_id=job.job_id, + user_email=job.user_email, + action_type=action_type, + user_name=None, # Could fetch from user service if needed + artist=job.artist, + title=job.title, + audio_hash=job.audio_hash, + review_token=job.review_token, + instrumental_token=job.instrumental_token, + ) + + if success: + # Mark reminder as sent (prevents duplicate sends) + job_manager.firestore.update_job(job_id, { + 'state_data': {**state_data, 'reminder_sent': True} + }) + logger.info(f"[job:{job_id}] Sent {action_type} reminder email to {job.user_email}") + add_span_event("reminder_sent", {"action_type": action_type}) + return { + "status": "sent", + "job_id": job_id, + "message": f"Sent {action_type} reminder to {job.user_email}" + } + else: + logger.error(f"[job:{job_id}] Failed to send reminder email") + add_span_event("send_failed") + return {"status": "failed", "job_id": job_id, "message": "Failed to send reminder"} + + except Exception as e: + logger.exception(f"[job:{job_id}] Error sending reminder: {e}") + add_span_event("error", {"error": str(e)}) + return {"status": "error", "job_id": job_id, "message": str(e)} + + @router.get("/health") async def internal_health( auth_data: Tuple[str, UserType, int] = Depends(require_admin) ): """ Internal health check endpoint. - + Used to verify the internal API is responsive. Requires admin authentication. """ diff --git a/backend/services/email_service.py b/backend/services/email_service.py index 5d2a3c2d..df138f8e 100644 --- a/backend/services/email_service.py +++ b/backend/services/email_service.py @@ -14,7 +14,7 @@ import html import logging import os from abc import ABC, abstractmethod -from typing import Optional +from typing import Optional, List from backend.config import get_settings @@ -31,7 +31,8 @@ class EmailProvider(ABC): to_email: str, subject: str, html_content: str, - text_content: Optional[str] = None + text_content: Optional[str] = None, + cc_emails: Optional[List[str]] = None, ) -> bool: """Send an email. Returns True if successful.""" pass @@ -49,10 +50,13 @@ class ConsoleEmailProvider(EmailProvider): to_email: str, subject: str, html_content: str, - text_content: Optional[str] = None + text_content: Optional[str] = None, + cc_emails: Optional[List[str]] = None, ) -> bool: logger.info("=" * 60) logger.info(f"EMAIL TO: {to_email}") + if cc_emails: + logger.info(f"CC: {', '.join(cc_emails)}") logger.info(f"SUBJECT: {subject}") logger.info("-" * 60) logger.info(text_content or html_content) @@ -77,12 +81,13 @@ class SendGridEmailProvider(EmailProvider): to_email: str, subject: str, html_content: str, - text_content: Optional[str] = None + text_content: Optional[str] = None, + cc_emails: Optional[List[str]] = None, ) -> bool: try: # Import here to avoid requiring sendgrid in all environments from sendgrid import SendGridAPIClient - from sendgrid.helpers.mail import Mail, Email, To, Content + from sendgrid.helpers.mail import Mail, Email, To, Content, Cc sg = SendGridAPIClient(api_key=self.api_key) @@ -93,13 +98,28 @@ class SendGridEmailProvider(EmailProvider): html_content=Content("text/html", html_content) ) + # Add CC recipients if provided (deduplicated and normalized) + if cc_emails: + # Normalize emails (lowercase, strip whitespace) and deduplicate + seen = set() + unique_cc_emails = [] + for cc_email in cc_emails: + normalized = cc_email.strip().lower() + if normalized and normalized not in seen: + seen.add(normalized) + unique_cc_emails.append(cc_email.strip()) + + for cc_email in unique_cc_emails: + message.add_cc(Cc(cc_email)) + if text_content: message.add_content(Content("text/plain", text_content)) response = sg.send(message) if response.status_code >= 200 and response.status_code < 300: - logger.info(f"Email sent to {to_email} via SendGrid") + cc_info = f" (CC: {', '.join(cc_emails)})" if cc_emails else "" + logger.info(f"Email sent to {to_email}{cc_info} via SendGrid") return True else: logger.error(f"SendGrid returned status {response.status_code}") @@ -816,6 +836,197 @@ Thanks for being part of making Nomad Karaoke better! from datetime import datetime return datetime.now().year + def send_job_completion( + self, + to_email: str, + message_content: str, + artist: Optional[str] = None, + title: Optional[str] = None, + brand_code: Optional[str] = None, + cc_admin: bool = True, + ) -> bool: + """ + Send job completion email with the rendered template content. + + Args: + to_email: User's email address + message_content: Pre-rendered message content (plain text) + artist: Artist name for subject line + title: Song title for subject line + brand_code: Release ID (e.g., "NOMAD-1178") for subject line + cc_admin: Whether to CC gen@nomadkaraoke.com + + Returns: + True if email was sent successfully + """ + # Build subject: "NOMAD-1178: Artist - Title (Your karaoke video is ready!)" + if brand_code and artist and title: + subject = f"{brand_code}: {artist} - {title} (Your karaoke video is ready!)" + elif artist and title: + subject = f"{artist} - {title} (Your karaoke video is ready!)" + else: + subject = "Your karaoke video is ready!" + + # Convert plain text to simple HTML (preserve line breaks) + html_content = f""" + + + + + + +
+ +
+ +
{html.escape(message_content)}
+ + + + +""" + + cc_emails = ["gen@nomadkaraoke.com"] if cc_admin else None + + return self.provider.send_email( + to_email=to_email, + subject=subject, + html_content=html_content, + text_content=message_content, + cc_emails=cc_emails, + ) + + def send_action_reminder( + self, + to_email: str, + message_content: str, + action_type: str, + artist: Optional[str] = None, + title: Optional[str] = None, + ) -> bool: + """ + Send action-needed reminder email. + + Args: + to_email: User's email address + message_content: Pre-rendered message content (plain text) + action_type: Type of action needed ("lyrics" or "instrumental") + artist: Artist name for subject line + title: Song title for subject line + + Returns: + True if email was sent successfully + """ + # Build subject based on action type + song_info = f" for {artist} - {title}" if artist and title else "" + if action_type == "lyrics": + subject = f"Action needed: Review lyrics{song_info}" + elif action_type == "instrumental": + subject = f"Action needed: Select instrumental{song_info}" + else: + subject = f"Action needed{song_info}" + + # Convert plain text to simple HTML + html_content = f""" + + + + + + +
+ +
+ +
+ ⏰ Your karaoke video is waiting for you! +
+ +
{html.escape(message_content)}
+ + + + +""" + + return self.provider.send_email( + to_email=to_email, + subject=subject, + html_content=html_content, + text_content=message_content, + ) + # Global instance _email_service = None diff --git a/backend/services/job_manager.py b/backend/services/job_manager.py index 1be62da5..d08b3589 100644 --- a/backend/services/job_manager.py +++ b/backend/services/job_manager.py @@ -359,9 +359,147 @@ class JobManager: 'instrumental_token': updates['instrumental_token'], 'instrumental_token_expires_at': updates['instrumental_token_expires_at'] }) - + logger.info(f"Job {job_id} transitioned to {new_status}") + + # Trigger notifications asynchronously (fire-and-forget) + self._trigger_state_notifications(job_id, new_status) + return True + + def _trigger_state_notifications(self, job_id: str, new_status: JobStatus) -> None: + """ + Trigger email notifications based on state transitions. + + This is fire-and-forget - notification failures don't affect job processing. + + Args: + job_id: Job ID + new_status: New job status + """ + import asyncio + + try: + # Get the job to access user info + job = self.get_job(job_id) + if not job or not job.user_email: + logger.debug(f"No user email for job {job_id}, skipping notifications") + return + + # Job completion notification + if new_status == JobStatus.COMPLETE: + self._schedule_completion_email(job) + + # Idle reminder scheduling for blocking states + elif new_status in [JobStatus.AWAITING_REVIEW, JobStatus.AWAITING_INSTRUMENTAL_SELECTION]: + self._schedule_idle_reminder(job, new_status) + + except Exception as e: + # Never let notification failures affect job processing + logger.error(f"Error triggering notifications for job {job_id}: {e}") + + def _schedule_completion_email(self, job: Job) -> None: + """ + Schedule sending a job completion email. + + Uses asyncio to fire-and-forget the email sending. + """ + import asyncio + import threading + + try: + from backend.services.job_notification_service import get_job_notification_service + + notification_service = get_job_notification_service() + + # Get youtube, dropbox URLs, and brand_code from state_data (may be None) + state_data = job.state_data or {} + youtube_url = state_data.get('youtube_url') + dropbox_url = state_data.get('dropbox_link') + brand_code = state_data.get('brand_code') + + # Create async task (fire-and-forget) + async def send_email(): + await notification_service.send_job_completion_email( + job_id=job.job_id, + user_email=job.user_email, + user_name=None, # Could fetch from user service if needed + artist=job.artist, + title=job.title, + youtube_url=youtube_url, + dropbox_url=dropbox_url, + brand_code=brand_code, + ) + + # Try to get existing event loop, create new one if none exists + try: + loop = asyncio.get_running_loop() + # If we're in an async context, create a task + loop.create_task(send_email()) + except RuntimeError: + # No event loop - we're likely in a sync context + # Use daemon thread to avoid blocking job completion + def run_in_thread(): + asyncio.run(send_email()) + thread = threading.Thread(target=run_in_thread, daemon=True) + thread.start() + + logger.info(f"Scheduled completion email for job {job.job_id}") + + except Exception as e: + logger.error(f"Failed to schedule completion email for job {job.job_id}: {e}") + + def _schedule_idle_reminder(self, job: Job, new_status: JobStatus) -> None: + """ + Schedule an idle reminder for a blocking state. + + Records the timestamp when the blocking state was entered and + schedules a Cloud Tasks task for 5 minutes later. + """ + import asyncio + import threading + + try: + # Record when we entered blocking state (for idle detection) + blocking_entered_at = datetime.utcnow().isoformat() + + action_type = "lyrics" if new_status == JobStatus.AWAITING_REVIEW else "instrumental" + + # Update state_data with blocking state info (handle None state_data) + existing_state_data = job.state_data or {} + state_data_update = { + 'blocking_state_entered_at': blocking_entered_at, + 'blocking_action_type': action_type, + 'reminder_sent': False, # Will be set to True after reminder is sent + } + + self.firestore.update_job(job.job_id, { + 'state_data': {**existing_state_data, **state_data_update} + }) + + # Schedule the idle reminder check via worker service (5 min delay) + from backend.services.worker_service import get_worker_service + + async def schedule_reminder(): + worker_service = get_worker_service() + await worker_service.schedule_idle_reminder(job.job_id) + + # Try to get existing event loop, create new one if none exists + try: + loop = asyncio.get_running_loop() + loop.create_task(schedule_reminder()) + except RuntimeError: + # No event loop - we're in a sync context + # Use daemon thread to avoid blocking job processing + def run_in_thread(): + asyncio.run(schedule_reminder()) + thread = threading.Thread(target=run_in_thread, daemon=True) + thread.start() + + logger.info(f"Scheduled idle reminder for job {job.job_id} ({action_type})") + + except Exception as e: + logger.error(f"Failed to schedule idle reminder for job {job.job_id}: {e}") def update_state_data(self, job_id: str, key: str, value: Any) -> None: """ diff --git a/backend/services/job_notification_service.py b/backend/services/job_notification_service.py new file mode 100644 index 00000000..0b43eb69 --- /dev/null +++ b/backend/services/job_notification_service.py @@ -0,0 +1,271 @@ +""" +Job notification service for sending emails on job state changes. + +Handles: +- Job completion emails (when job enters COMPLETE status) +- Action reminder emails (when user is idle at blocking states) + +This service orchestrates between the template service and email service, +building the complete notification flow for jobs. +""" +import logging +import os +from typing import Optional, Dict, Any + +from backend.services.email_service import get_email_service +from backend.services.template_service import get_template_service + + +logger = logging.getLogger(__name__) + + +# Environment variable to enable/disable auto emails +ENABLE_AUTO_EMAILS = os.getenv("ENABLE_AUTO_EMAILS", "true").lower() == "true" + +# Feedback form URL (configured per environment, empty by default to avoid placeholder in emails) +FEEDBACK_FORM_URL = os.getenv("FEEDBACK_FORM_URL", "") + + +def _mask_email(email: str) -> str: + """Mask email for logging to protect PII. Shows first char + domain.""" + if not email or "@" not in email: + return "***" + local, domain = email.split("@", 1) + if len(local) <= 1: + return f"*@{domain}" + return f"{local[0]}***@{domain}" + + +class JobNotificationService: + """ + Service for sending job-related email notifications. + + Coordinates between template service (for message rendering) and + email service (for sending). + """ + + def __init__(self): + """Initialize notification service.""" + self.email_service = get_email_service() + self.template_service = get_template_service() + self.frontend_url = os.getenv("FRONTEND_URL", "https://gen.nomadkaraoke.com") + self.backend_url = os.getenv("BACKEND_URL", "https://api.nomadkaraoke.com") + + def _build_review_url(self, job_id: str, audio_hash: Optional[str] = None, review_token: Optional[str] = None) -> str: + """Build the lyrics review URL for a job.""" + import urllib.parse + + review_ui_url = os.getenv("REVIEW_UI_URL", f"{self.frontend_url}/lyrics/") + base_api_url = f"{self.backend_url}/api/review/{job_id}" + encoded_api_url = urllib.parse.quote(base_api_url, safe='') + + url = f"{review_ui_url}?baseApiUrl={encoded_api_url}" + if audio_hash: + url += f"&audioHash={urllib.parse.quote(audio_hash, safe='')}" + if review_token: + url += f"&reviewToken={urllib.parse.quote(review_token, safe='')}" + return url + + def _build_instrumental_url(self, job_id: str, instrumental_token: Optional[str] = None) -> str: + """Build the instrumental selection URL for a job.""" + base_api_url = f"{self.backend_url}/api/jobs/{job_id}" + + import urllib.parse + encoded_api_url = urllib.parse.quote(base_api_url, safe='') + + url = f"{self.frontend_url}/instrumental/?baseApiUrl={encoded_api_url}" + if instrumental_token: + url += f"&instrumentalToken={urllib.parse.quote(instrumental_token, safe='')}" + return url + + async def send_job_completion_email( + self, + job_id: str, + user_email: str, + user_name: Optional[str] = None, + artist: Optional[str] = None, + title: Optional[str] = None, + youtube_url: Optional[str] = None, + dropbox_url: Optional[str] = None, + brand_code: Optional[str] = None, + ) -> bool: + """ + Send job completion email to user. + + Args: + job_id: Job ID + user_email: User's email address + user_name: User's display name (optional) + artist: Artist name + title: Song title + youtube_url: YouTube video URL + dropbox_url: Dropbox folder URL + brand_code: Release ID (e.g., "NOMAD-1178") + + Returns: + True if email was sent successfully + """ + if not ENABLE_AUTO_EMAILS: + logger.info(f"Auto emails disabled, skipping completion email for job {job_id}") + return False + + if not user_email: + logger.warning(f"No user email for job {job_id}, skipping completion email") + return False + + try: + # Render the completion message using template service + message_content = self.template_service.render_job_completion( + name=user_name, + youtube_url=youtube_url, + dropbox_url=dropbox_url, + artist=artist, + title=title, + job_id=job_id, + feedback_url=FEEDBACK_FORM_URL, + ) + + # Send the email with CC to admin + success = self.email_service.send_job_completion( + to_email=user_email, + message_content=message_content, + artist=artist, + title=title, + brand_code=brand_code, + cc_admin=True, + ) + + if success: + logger.info(f"Sent completion email for job {job_id} to {_mask_email(user_email)}") + else: + logger.error(f"Failed to send completion email for job {job_id}") + + return success + + except Exception as e: + logger.exception(f"Error sending completion email for job {job_id}: {e}") + return False + + async def send_action_reminder_email( + self, + job_id: str, + user_email: str, + action_type: str, + user_name: Optional[str] = None, + artist: Optional[str] = None, + title: Optional[str] = None, + audio_hash: Optional[str] = None, + review_token: Optional[str] = None, + instrumental_token: Optional[str] = None, + ) -> bool: + """ + Send action-needed reminder email to user. + + Args: + job_id: Job ID + user_email: User's email address + action_type: Type of action needed ("lyrics" or "instrumental") + user_name: User's display name + artist: Artist name + title: Song title + audio_hash: Audio hash for review URL + review_token: Review token for URL + instrumental_token: Instrumental token for URL + + Returns: + True if email was sent successfully + """ + if not ENABLE_AUTO_EMAILS: + logger.info(f"Auto emails disabled, skipping reminder for job {job_id}") + return False + + if not user_email: + logger.warning(f"No user email for job {job_id}, skipping reminder") + return False + + try: + # Render the appropriate template + if action_type == "lyrics": + review_url = self._build_review_url(job_id, audio_hash, review_token) + message_content = self.template_service.render_action_needed_lyrics( + name=user_name, + artist=artist, + title=title, + review_url=review_url, + ) + elif action_type == "instrumental": + instrumental_url = self._build_instrumental_url(job_id, instrumental_token) + message_content = self.template_service.render_action_needed_instrumental( + name=user_name, + artist=artist, + title=title, + instrumental_url=instrumental_url, + ) + else: + logger.error(f"Unknown action type: {action_type}") + return False + + # Send the reminder email (no CC) + success = self.email_service.send_action_reminder( + to_email=user_email, + message_content=message_content, + action_type=action_type, + artist=artist, + title=title, + ) + + if success: + logger.info(f"Sent {action_type} reminder for job {job_id} to {_mask_email(user_email)}") + else: + logger.error(f"Failed to send {action_type} reminder for job {job_id}") + + return success + + except Exception as e: + logger.exception(f"Error sending {action_type} reminder for job {job_id}: {e}") + return False + + def get_completion_message( + self, + job_id: str, + user_name: Optional[str] = None, + artist: Optional[str] = None, + title: Optional[str] = None, + youtube_url: Optional[str] = None, + dropbox_url: Optional[str] = None, + ) -> str: + """ + Get the rendered completion message for a job (for admin copy functionality). + + Args: + job_id: Job ID + user_name: User's display name + artist: Artist name + title: Song title + youtube_url: YouTube video URL + dropbox_url: Dropbox folder URL + + Returns: + Rendered message content as plain text + """ + return self.template_service.render_job_completion( + name=user_name, + youtube_url=youtube_url, + dropbox_url=dropbox_url, + artist=artist, + title=title, + job_id=job_id, + feedback_url=FEEDBACK_FORM_URL, + ) + + +# Global instance +_job_notification_service: Optional[JobNotificationService] = None + + +def get_job_notification_service() -> JobNotificationService: + """Get the global job notification service instance.""" + global _job_notification_service + if _job_notification_service is None: + _job_notification_service = JobNotificationService() + return _job_notification_service diff --git a/backend/services/template_service.py b/backend/services/template_service.py new file mode 100644 index 00000000..1e5d9f85 --- /dev/null +++ b/backend/services/template_service.py @@ -0,0 +1,330 @@ +""" +Template service for managing email templates stored in GCS. + +Templates are stored in GCS bucket and rendered with job-specific variables. +This allows updating email content without code deployment. + +Template locations: +- gs://{bucket}/templates/job-completion.txt - Job completion email (plain text) +- gs://{bucket}/templates/action-needed-lyrics.txt - Lyrics review reminder +- gs://{bucket}/templates/action-needed-instrumental.txt - Instrumental selection reminder +""" +import logging +import re +from typing import Optional, Dict, Any + +from backend.config import get_settings + + +logger = logging.getLogger(__name__) + + +# Default templates (fallback if GCS fetch fails) +DEFAULT_JOB_COMPLETION_TEMPLATE = """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 +""" + +DEFAULT_ACTION_NEEDED_LYRICS_TEMPLATE = """Hi {name}, + +Your karaoke video for "{artist} - {title}" is ready for lyrics review! + +The AI has transcribed and synchronized the lyrics, but they may need some corrections. Please review and approve them so we can finish generating your video. + +Review your lyrics here: +{review_url} + +This usually takes just a few minutes. + +Thanks! +-Nomad Karaoke +""" + +DEFAULT_ACTION_NEEDED_INSTRUMENTAL_TEMPLATE = """Hi {name}, + +Your karaoke video for "{artist} - {title}" is almost done! + +We've separated the audio into different versions. Please select which instrumental track you'd like to use for the final video. + +Select your instrumental here: +{instrumental_url} + +Thanks! +-Nomad Karaoke +""" + + +class TemplateService: + """ + Service for fetching and rendering email templates from GCS. + + Templates support the following 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 + - {instrumental_url} - Instrumental selection URL + - {feedback_url} - Feedback form URL + """ + + TEMPLATE_PREFIX = "templates/" + + def __init__(self): + """Initialize template service.""" + self.settings = get_settings() + self._storage_client = None + self._bucket = None + + @property + def storage_client(self): + """Lazy-initialize storage client.""" + if self._storage_client is None: + from google.cloud import storage + self._storage_client = storage.Client(project=self.settings.google_cloud_project) + return self._storage_client + + @property + def bucket(self): + """Get the GCS bucket for templates.""" + if self._bucket is None: + self._bucket = self.storage_client.bucket(self.settings.gcs_bucket_name) + return self._bucket + + def _fetch_template_from_gcs(self, template_name: str) -> Optional[str]: + """ + Fetch a template from GCS. + + Args: + template_name: Name of template file (e.g., "job-completion.txt") + + Returns: + Template content as string, or None if not found + """ + blob_path = f"{self.TEMPLATE_PREFIX}{template_name}" + try: + blob = self.bucket.blob(blob_path) + if blob.exists(): + content = blob.download_as_text() + logger.debug(f"Fetched template from GCS: {blob_path}") + return content + else: + logger.warning(f"Template not found in GCS: {blob_path}") + return None + except Exception as e: + logger.error(f"Failed to fetch template {blob_path}: {e}") + return None + + def get_job_completion_template(self) -> str: + """Get the job completion email template.""" + template = self._fetch_template_from_gcs("job-completion.txt") + if template is None: + logger.info("Using default job completion template") + return DEFAULT_JOB_COMPLETION_TEMPLATE + return template + + def get_action_needed_lyrics_template(self) -> str: + """Get the lyrics review reminder template.""" + template = self._fetch_template_from_gcs("action-needed-lyrics.txt") + if template is None: + logger.info("Using default lyrics reminder template") + return DEFAULT_ACTION_NEEDED_LYRICS_TEMPLATE + return template + + def get_action_needed_instrumental_template(self) -> str: + """Get the instrumental selection reminder template.""" + template = self._fetch_template_from_gcs("action-needed-instrumental.txt") + if template is None: + logger.info("Using default instrumental reminder template") + return DEFAULT_ACTION_NEEDED_INSTRUMENTAL_TEMPLATE + return template + + def render_template(self, template: str, variables: Dict[str, Any]) -> str: + """ + Render a template with the given variables. + + Missing variables are replaced with empty strings. + Handles conditional sections like feedback URL. + + Args: + template: Template string with {variable} placeholders + variables: Dictionary of variable values + + Returns: + Rendered template string + """ + result = template + + # Handle feedback URL section - remove if not provided + if not variables.get("feedback_url"): + # Remove feedback section (lines containing feedback_url placeholder and surrounding text) + result = re.sub( + r'\n*If you have a moment.*?\{feedback_url\}\n*', + '\n', + result, + flags=re.DOTALL + ) + variables["feedback_url"] = "" + + # Replace all variables + for key, value in variables.items(): + placeholder = "{" + key + "}" + result = result.replace(placeholder, str(value) if value else "") + + # Clean up any remaining unreplaced placeholders + result = re.sub(r'\{[a-z_]+\}', '', result) + + return result.strip() + + def render_job_completion( + self, + name: Optional[str] = None, + youtube_url: Optional[str] = None, + dropbox_url: Optional[str] = None, + artist: Optional[str] = None, + title: Optional[str] = None, + job_id: Optional[str] = None, + feedback_url: Optional[str] = None, + ) -> str: + """ + Render the job completion email template. + + Args: + name: User's display name (defaults to "there") + youtube_url: YouTube video URL + dropbox_url: Dropbox folder URL + artist: Artist name + title: Song title + job_id: Job ID + feedback_url: Feedback form URL (optional) + + Returns: + Rendered email content + """ + template = self.get_job_completion_template() + variables = { + "name": name or "there", + "youtube_url": youtube_url or "[YouTube URL not available]", + "dropbox_url": dropbox_url or "[Dropbox URL not available]", + "artist": artist or "Unknown Artist", + "title": title or "Unknown Title", + "job_id": job_id or "", + "feedback_url": feedback_url, + } + return self.render_template(template, variables) + + def render_action_needed_lyrics( + self, + name: Optional[str] = None, + artist: Optional[str] = None, + title: Optional[str] = None, + review_url: str = "", + ) -> str: + """ + Render the lyrics review reminder template. + + Args: + name: User's display name + artist: Artist name + title: Song title + review_url: Lyrics review URL + + Returns: + Rendered email content + """ + template = self.get_action_needed_lyrics_template() + variables = { + "name": name or "there", + "artist": artist or "Unknown Artist", + "title": title or "Unknown Title", + "review_url": review_url, + } + return self.render_template(template, variables) + + def render_action_needed_instrumental( + self, + name: Optional[str] = None, + artist: Optional[str] = None, + title: Optional[str] = None, + instrumental_url: str = "", + ) -> str: + """ + Render the instrumental selection reminder template. + + Args: + name: User's display name + artist: Artist name + title: Song title + instrumental_url: Instrumental selection URL + + Returns: + Rendered email content + """ + template = self.get_action_needed_instrumental_template() + variables = { + "name": name or "there", + "artist": artist or "Unknown Artist", + "title": title or "Unknown Title", + "instrumental_url": instrumental_url, + } + return self.render_template(template, variables) + + def upload_template(self, template_name: str, content: str) -> bool: + """ + Upload a template to GCS. + + Args: + template_name: Name of template file (e.g., "job-completion.txt") + content: Template content + + Returns: + True if upload successful + """ + blob_path = f"{self.TEMPLATE_PREFIX}{template_name}" + try: + blob = self.bucket.blob(blob_path) + blob.upload_from_string(content, content_type="text/plain") + logger.info(f"Uploaded template to GCS: {blob_path}") + return True + except Exception as e: + logger.error(f"Failed to upload template {blob_path}: {e}") + return False + + +# Global instance +_template_service: Optional[TemplateService] = None + + +def get_template_service() -> TemplateService: + """Get the global template service instance.""" + global _template_service + if _template_service is None: + _template_service = TemplateService() + return _template_service diff --git a/backend/services/worker_service.py b/backend/services/worker_service.py index 7671f194..08dfe84a 100644 --- a/backend/services/worker_service.py +++ b/backend/services/worker_service.py @@ -37,6 +37,7 @@ WORKER_QUEUES = { "screens": "screens-worker-queue", "render-video": "render-worker-queue", "video": "video-worker-queue", + "idle-reminder": "idle-reminder-queue", # For delayed idle reminder checks } # Dispatch deadlines for each worker type (in seconds) @@ -49,8 +50,12 @@ WORKER_DISPATCH_DEADLINES = { "screens": 600, # 10 min - Screen generation is fast "render-video": 1800, # 30 min - Video encoding can be slow "video": 1800, # 30 min - Video encoding can be slow + "idle-reminder": 60, # 1 min - Quick check and potential email send } +# Default delay for idle reminders (seconds) +IDLE_REMINDER_DELAY_SECONDS = 5 * 60 # 5 minutes + class WorkerService: """ @@ -430,6 +435,99 @@ class WorkerService: """Trigger render video worker (post-review).""" return await self.trigger_worker("render-video", job_id) + async def schedule_idle_reminder( + self, + job_id: str, + delay_seconds: int = IDLE_REMINDER_DELAY_SECONDS + ) -> bool: + """ + Schedule an idle reminder check for a job. + + The reminder task will be delivered after the specified delay. + When the task executes, it checks if the job is still in a blocking + state and sends a reminder email if the user hasn't taken action. + + Args: + job_id: Job ID to check + delay_seconds: Delay before executing the check (default: 5 minutes) + + Returns: + True if task was scheduled successfully, False otherwise + """ + if not self._use_cloud_tasks: + # In development mode, log and skip (no delayed execution support) + logger.info( + f"[job:{job_id}] Idle reminder not scheduled (Cloud Tasks disabled). " + f"Would have fired in {delay_seconds}s." + ) + return True + + try: + from google.cloud import tasks_v2 + from google.protobuf import timestamp_pb2 + import time + + queue_name = WORKER_QUEUES.get("idle-reminder") + if not queue_name: + logger.error("Idle reminder queue not configured") + return False + + project = self.settings.google_cloud_project + if not project: + logger.error("GOOGLE_CLOUD_PROJECT not set") + return False + + location = self.settings.gcp_region + + # Build queue path + parent = self.tasks_client.queue_path(project, location, queue_name) + + # Build headers + headers = { + "Content-Type": "application/json", + } + + if self._admin_token: + headers["X-Admin-Token"] = self._admin_token + + # Inject trace context + headers = inject_trace_context(headers) + + # Calculate schedule time + schedule_time = timestamp_pb2.Timestamp() + schedule_time.FromSeconds(int(time.time()) + delay_seconds) + + dispatch_deadline_seconds = WORKER_DISPATCH_DEADLINES.get("idle-reminder", 60) + + # Build task payload + task = { + "http_request": { + "http_method": tasks_v2.HttpMethod.POST, + "url": f"{self._base_url}/api/internal/jobs/{job_id}/check-idle-reminder", + "headers": headers, + "body": json.dumps({"job_id": job_id}).encode(), + "oidc_token": { + "service_account_email": f"karaoke-backend@{project}.iam.gserviceaccount.com", + }, + }, + "schedule_time": schedule_time, + "dispatch_deadline": duration_pb2.Duration(seconds=dispatch_deadline_seconds), + } + + # Create task + response = self.tasks_client.create_task(parent=parent, task=task) + logger.info( + f"[job:{job_id}] Scheduled idle reminder check in {delay_seconds}s: {response.name}" + ) + return True + + except Exception as e: + logger.error( + f"[job:{job_id}] Failed to schedule idle reminder: {e}", + exc_info=True + ) + return False + # Global worker service instance _worker_service: Optional[WorkerService] = None diff --git a/backend/tests/test_admin_email_endpoints.py b/backend/tests/test_admin_email_endpoints.py new file mode 100644 index 00000000..4e929a35 --- /dev/null +++ b/backend/tests/test_admin_email_endpoints.py @@ -0,0 +1,411 @@ +""" +Unit tests for admin email endpoints. + +Tests the completion message and send email API endpoints. +""" +import pytest +from unittest.mock import Mock, patch, MagicMock, AsyncMock +from fastapi.testclient import TestClient +from fastapi import FastAPI + +from backend.api.routes.admin import router +from backend.api.dependencies import require_admin +from backend.models.job import Job, JobStatus + + +# Create a test app with the admin router +# The router already has prefix="/admin", so we add /api prefix +app = FastAPI() +app.include_router(router, prefix="/api") + + +def get_mock_admin(): + """Override for require_admin dependency.""" + return ("admin@example.com", "admin", 1) + + +# Override the require_admin dependency +app.dependency_overrides[require_admin] = get_mock_admin + + +@pytest.fixture +def client(): + """Create a test client.""" + return TestClient(app) + + +@pytest.fixture +def mock_job(): + """Create a mock job.""" + job = Mock(spec=Job) + job.job_id = "test-job-123" + job.user_email = "user@example.com" + job.artist = "Test Artist" + job.title = "Test Song" + job.status = JobStatus.COMPLETE + job.audio_hash = "hash123" + job.review_token = "review123" + job.instrumental_token = "inst123" + job.state_data = { + "youtube_url": "https://youtube.com/watch?v=test123", + "dropbox_link": "https://dropbox.com/folder/test", + "brand_code": "NOMAD-1234", + } + return job + + +class TestGetCompletionMessage: + """Tests for GET /api/admin/jobs/{job_id}/completion-message endpoint.""" + + def test_returns_completion_message(self, client, mock_job): + """Test successful completion message retrieval.""" + with patch('backend.api.routes.admin.JobManager') as mock_jm_class, \ + patch('backend.services.job_notification_service.get_job_notification_service') as mock_get_ns: + + # Setup mocks + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm_class.return_value = mock_jm + + mock_ns = Mock() + mock_ns.get_completion_message.return_value = "Your video is ready!" + mock_get_ns.return_value = mock_ns + + response = client.get( + "/api/admin/jobs/test-job-123/completion-message", + headers={"Authorization": "Bearer admin-token"} + ) + + assert response.status_code == 200 + data = response.json() + assert data["job_id"] == "test-job-123" + assert data["message"] == "Your video is ready!" + # Subject format: "NOMAD-1234: Test Artist - Test Song (Your karaoke video is ready!)" + assert data["subject"] == "NOMAD-1234: Test Artist - Test Song (Your karaoke video is ready!)" + assert data["youtube_url"] == "https://youtube.com/watch?v=test123" + assert data["dropbox_url"] == "https://dropbox.com/folder/test" + + def test_returns_404_when_job_not_found(self, client): + """Test 404 when job doesn't exist.""" + with patch('backend.api.routes.admin.JobManager') as mock_jm_class: + mock_jm = Mock() + mock_jm.get_job.return_value = None + mock_jm_class.return_value = mock_jm + + response = client.get( + "/api/admin/jobs/nonexistent-job/completion-message", + headers={"Authorization": "Bearer admin-token"} + ) + + assert response.status_code == 404 + + def test_handles_none_state_data(self, client, mock_job): + """Test handling of job with None state_data.""" + mock_job.state_data = None + + with patch('backend.api.routes.admin.JobManager') as mock_jm_class, \ + patch('backend.services.job_notification_service.get_job_notification_service') as mock_get_ns: + + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm_class.return_value = mock_jm + + mock_ns = Mock() + mock_ns.get_completion_message.return_value = "Your video is ready!" + mock_get_ns.return_value = mock_ns + + response = client.get( + "/api/admin/jobs/test-job-123/completion-message", + headers={"Authorization": "Bearer admin-token"} + ) + + assert response.status_code == 200 + data = response.json() + assert data["youtube_url"] is None + assert data["dropbox_url"] is None + + def test_default_subject_without_song_info(self, client, mock_job): + """Test default subject when no artist/title.""" + mock_job.artist = None + mock_job.title = None + + with patch('backend.api.routes.admin.JobManager') as mock_jm_class, \ + patch('backend.services.job_notification_service.get_job_notification_service') as mock_get_ns: + + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm_class.return_value = mock_jm + + mock_ns = Mock() + mock_ns.get_completion_message.return_value = "Message" + mock_get_ns.return_value = mock_ns + + response = client.get( + "/api/admin/jobs/test-job-123/completion-message", + headers={"Authorization": "Bearer admin-token"} + ) + + assert response.status_code == 200 + data = response.json() + assert data["subject"] == "Your karaoke video is ready!" + + +class TestSendCompletionEmail: + """Tests for POST /api/admin/jobs/{job_id}/send-completion-email endpoint.""" + + def test_sends_email_successfully(self, client, mock_job): + """Test successful email sending.""" + with patch('backend.api.routes.admin.JobManager') as mock_jm_class, \ + patch('backend.services.job_notification_service.get_job_notification_service') as mock_get_ns, \ + patch('backend.services.email_service.get_email_service') as mock_get_es: + + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm_class.return_value = mock_jm + + mock_ns = Mock() + mock_ns.get_completion_message.return_value = "Your video is ready!" + mock_get_ns.return_value = mock_ns + + mock_es = Mock() + mock_es.send_job_completion.return_value = True + mock_get_es.return_value = mock_es + + response = client.post( + "/api/admin/jobs/test-job-123/send-completion-email", + json={"to_email": "customer@example.com", "cc_admin": True}, + headers={"Authorization": "Bearer admin-token"} + ) + + assert response.status_code == 200 + data = response.json() + assert data["success"] is True + assert data["job_id"] == "test-job-123" + assert data["to_email"] == "customer@example.com" + + # Verify email was sent with correct params + mock_es.send_job_completion.assert_called_once_with( + to_email="customer@example.com", + message_content="Your video is ready!", + artist="Test Artist", + title="Test Song", + brand_code="NOMAD-1234", + cc_admin=True, + ) + + def test_sends_email_without_cc(self, client, mock_job): + """Test email sending without CC.""" + with patch('backend.api.routes.admin.JobManager') as mock_jm_class, \ + patch('backend.services.job_notification_service.get_job_notification_service') as mock_get_ns, \ + patch('backend.services.email_service.get_email_service') as mock_get_es: + + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm_class.return_value = mock_jm + + mock_ns = Mock() + mock_ns.get_completion_message.return_value = "Message" + mock_get_ns.return_value = mock_ns + + mock_es = Mock() + mock_es.send_job_completion.return_value = True + mock_get_es.return_value = mock_es + + response = client.post( + "/api/admin/jobs/test-job-123/send-completion-email", + json={"to_email": "customer@example.com", "cc_admin": False}, + headers={"Authorization": "Bearer admin-token"} + ) + + assert response.status_code == 200 + + # Verify CC was not included + call_kwargs = mock_es.send_job_completion.call_args.kwargs + assert call_kwargs["cc_admin"] is False + + def test_returns_404_when_job_not_found(self, client): + """Test 404 when job doesn't exist.""" + with patch('backend.api.routes.admin.JobManager') as mock_jm_class: + mock_jm = Mock() + mock_jm.get_job.return_value = None + mock_jm_class.return_value = mock_jm + + response = client.post( + "/api/admin/jobs/nonexistent-job/send-completion-email", + json={"to_email": "customer@example.com"}, + headers={"Authorization": "Bearer admin-token"} + ) + + assert response.status_code == 404 + + def test_returns_500_when_email_fails(self, client, mock_job): + """Test 500 when email sending fails.""" + with patch('backend.api.routes.admin.JobManager') as mock_jm_class, \ + patch('backend.services.job_notification_service.get_job_notification_service') as mock_get_ns, \ + patch('backend.services.email_service.get_email_service') as mock_get_es: + + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm_class.return_value = mock_jm + + mock_ns = Mock() + mock_ns.get_completion_message.return_value = "Message" + mock_get_ns.return_value = mock_ns + + mock_es = Mock() + mock_es.send_job_completion.return_value = False # Email failed + mock_get_es.return_value = mock_es + + response = client.post( + "/api/admin/jobs/test-job-123/send-completion-email", + json={"to_email": "customer@example.com"}, + headers={"Authorization": "Bearer admin-token"} + ) + + assert response.status_code == 500 + assert "Failed to send email" in response.json()["detail"] + + def test_handles_none_state_data(self, client, mock_job): + """Test handling of job with None state_data.""" + mock_job.state_data = None + + with patch('backend.api.routes.admin.JobManager') as mock_jm_class, \ + patch('backend.services.job_notification_service.get_job_notification_service') as mock_get_ns, \ + patch('backend.services.email_service.get_email_service') as mock_get_es: + + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm_class.return_value = mock_jm + + mock_ns = Mock() + mock_ns.get_completion_message.return_value = "Message" + mock_get_ns.return_value = mock_ns + + mock_es = Mock() + mock_es.send_job_completion.return_value = True + mock_get_es.return_value = mock_es + + response = client.post( + "/api/admin/jobs/test-job-123/send-completion-email", + json={"to_email": "customer@example.com"}, + headers={"Authorization": "Bearer admin-token"} + ) + + assert response.status_code == 200 + + def test_accepts_any_email_string(self, client, mock_job): + """Test that any string is currently accepted as email (no validation). + + Documents current behavior: FastAPI/Pydantic doesn't validate email + format by default. If validation is added later, this test should + be updated to expect 422 for invalid emails. + """ + with patch('backend.api.routes.admin.JobManager') as mock_jm_class, \ + patch('backend.services.job_notification_service.get_job_notification_service') as mock_get_ns, \ + patch('backend.services.email_service.get_email_service') as mock_get_es: + + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm_class.return_value = mock_jm + + mock_ns = Mock() + mock_ns.get_completion_message.return_value = "Message" + mock_get_ns.return_value = mock_ns + + mock_es = Mock() + mock_es.send_job_completion.return_value = True + mock_get_es.return_value = mock_es + + response = client.post( + "/api/admin/jobs/test-job-123/send-completion-email", + json={"to_email": "invalid-email"}, # Not a valid email format + headers={"Authorization": "Bearer admin-token"} + ) + + # Currently accepts any string - endpoint succeeds + assert response.status_code == 200 + # Verify the invalid email was passed through + mock_es.send_job_completion.assert_called_once() + call_kwargs = mock_es.send_job_completion.call_args.kwargs + assert call_kwargs["to_email"] == "invalid-email" + + +class TestIdleReminderEndpoint: + """Tests for the internal idle reminder endpoint.""" + + def test_sends_reminder_when_still_idle(self, mock_job): + """Test that reminder is sent when user is still idle.""" + from backend.api.routes.internal import router as internal_router + from backend.api.dependencies import require_admin + + # Create test app for internal router + # The router already has prefix="/internal", so we add /api prefix + test_app = FastAPI() + test_app.include_router(internal_router, prefix="/api") + test_app.dependency_overrides[require_admin] = get_mock_admin + + mock_job.status = JobStatus.AWAITING_REVIEW.value # Use .value for string comparison + mock_job.state_data = { + "blocking_state_entered_at": "2024-01-01T00:00:00", + "blocking_action_type": "lyrics", + "reminder_sent": False, + } + + with patch('backend.api.routes.internal.JobManager') as mock_jm_class, \ + patch('backend.services.job_notification_service.get_job_notification_service') as mock_get_ns: + + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm.firestore = Mock() # Mock firestore for update_job call + mock_jm_class.return_value = mock_jm + + mock_ns = Mock() + mock_ns.send_action_reminder_email = AsyncMock(return_value=True) + mock_get_ns.return_value = mock_ns + + test_client = TestClient(test_app) + response = test_client.post( + "/api/internal/jobs/test-job-123/check-idle-reminder", + headers={"Authorization": "Bearer admin-token"} + ) + + # Should succeed and return "sent" status + assert response.status_code == 200 + data = response.json() + assert data["status"] == "sent" + assert data["job_id"] == "test-job-123" + + def test_skips_reminder_when_already_sent(self, mock_job): + """Test that reminder is skipped if already sent.""" + from backend.api.routes.internal import router as internal_router + from backend.api.dependencies import require_admin + + # Create test app for internal router + # The router already has prefix="/internal", so we add /api prefix + test_app = FastAPI() + test_app.include_router(internal_router, prefix="/api") + test_app.dependency_overrides[require_admin] = get_mock_admin + + mock_job.status = JobStatus.AWAITING_REVIEW.value # Use .value for string comparison + mock_job.state_data = { + "blocking_state_entered_at": "2024-01-01T00:00:00", + "blocking_action_type": "lyrics", + "reminder_sent": True, # Already sent + } + + with patch('backend.api.routes.internal.JobManager') as mock_jm_class: + mock_jm = Mock() + mock_jm.get_job.return_value = mock_job + mock_jm_class.return_value = mock_jm + + test_client = TestClient(test_app) + response = test_client.post( + "/api/internal/jobs/test-job-123/check-idle-reminder", + headers={"Authorization": "Bearer admin-token"} + ) + + # Should succeed with "already_sent" status + assert response.status_code == 200 + data = response.json() + assert data["status"] == "already_sent" + assert data["job_id"] == "test-job-123" diff --git a/backend/tests/test_email_service.py b/backend/tests/test_email_service.py new file mode 100644 index 00000000..ba029a69 --- /dev/null +++ b/backend/tests/test_email_service.py @@ -0,0 +1,492 @@ +""" +Unit tests for email service. + +Tests the new job completion and action reminder email methods, +as well as CC support. +""" +import pytest +from unittest.mock import Mock, patch, MagicMock + +from backend.services.email_service import ( + EmailService, + EmailProvider, + ConsoleEmailProvider, + SendGridEmailProvider, + get_email_service, +) + + +class TestConsoleEmailProvider: + """Tests for console email provider.""" + + def test_send_email_basic(self): + """Test basic email logging.""" + provider = ConsoleEmailProvider() + + result = provider.send_email( + to_email="user@example.com", + subject="Test Subject", + html_content="

Test content

", + ) + + assert result is True + + def test_send_email_with_text_content(self): + """Test email with text content.""" + provider = ConsoleEmailProvider() + + result = provider.send_email( + to_email="user@example.com", + subject="Test Subject", + html_content="

Test

", + text_content="Test plain text", + ) + + assert result is True + + def test_send_email_with_cc(self): + """Test email with CC recipients.""" + provider = ConsoleEmailProvider() + + result = provider.send_email( + to_email="user@example.com", + subject="Test Subject", + html_content="

Test

", + cc_emails=["cc1@example.com", "cc2@example.com"], + ) + + assert result is True + + +class TestSendGridEmailProvider: + """Tests for SendGrid email provider.""" + + def test_send_email_success(self): + """Test successful email sending via SendGrid.""" + provider = SendGridEmailProvider( + api_key="test-api-key", + from_email="from@example.com", + from_name="Test Sender", + ) + + mock_response = Mock() + mock_response.status_code = 202 + + # Patch at the sendgrid module level since it's imported inline + with patch('sendgrid.SendGridAPIClient') as mock_sg: + mock_client = Mock() + mock_client.send.return_value = mock_response + mock_sg.return_value = mock_client + + result = provider.send_email( + to_email="user@example.com", + subject="Test Subject", + html_content="

Test

", + ) + + assert result is True + mock_client.send.assert_called_once() + + def test_send_email_with_cc(self): + """Test email sending with CC via SendGrid.""" + provider = SendGridEmailProvider( + api_key="test-api-key", + from_email="from@example.com", + ) + + mock_response = Mock() + mock_response.status_code = 202 + + with patch('sendgrid.SendGridAPIClient') as mock_sg: + mock_client = Mock() + mock_client.send.return_value = mock_response + mock_sg.return_value = mock_client + + result = provider.send_email( + to_email="user@example.com", + subject="Test Subject", + html_content="

Test

", + cc_emails=["cc@example.com"], + ) + + assert result is True + + def test_send_email_failure_status(self): + """Test email sending failure due to bad status.""" + provider = SendGridEmailProvider( + api_key="test-api-key", + from_email="from@example.com", + ) + + mock_response = Mock() + mock_response.status_code = 400 + + with patch('sendgrid.SendGridAPIClient') as mock_sg: + mock_client = Mock() + mock_client.send.return_value = mock_response + mock_sg.return_value = mock_client + + result = provider.send_email( + to_email="user@example.com", + subject="Test Subject", + html_content="

Test

", + ) + + assert result is False + + def test_send_email_exception(self): + """Test email sending exception handling.""" + provider = SendGridEmailProvider( + api_key="test-api-key", + from_email="from@example.com", + ) + + with patch('sendgrid.SendGridAPIClient') as mock_sg: + mock_sg.return_value.send.side_effect = Exception("API error") + + result = provider.send_email( + to_email="user@example.com", + subject="Test Subject", + html_content="

Test

", + ) + + assert result is False + + +class TestEmailServiceJobCompletion: + """Tests for job completion email method.""" + + def test_send_job_completion_basic(self): + """Test basic job completion email.""" + service = EmailService() + service.provider = Mock() + service.provider.send_email.return_value = True + + result = service.send_job_completion( + to_email="user@example.com", + message_content="Your video is ready!", + ) + + assert result is True + service.provider.send_email.assert_called_once() + + def test_send_job_completion_with_song_info(self): + """Test job completion email includes song in subject.""" + service = EmailService() + service.provider = Mock() + service.provider.send_email.return_value = True + + service.send_job_completion( + to_email="user@example.com", + message_content="Your video is ready!", + artist="Test Artist", + title="Test Song", + ) + + call_args = service.provider.send_email.call_args + subject = call_args.kwargs.get('subject') or call_args[0][1] + assert "Test Artist" in subject + assert "Test Song" in subject + + def test_send_job_completion_with_brand_code(self): + """Test job completion email includes brand code in subject.""" + service = EmailService() + service.provider = Mock() + service.provider.send_email.return_value = True + + service.send_job_completion( + to_email="user@example.com", + message_content="Your video is ready!", + artist="Seether", + title="Tonight", + brand_code="NOMAD-1178", + ) + + call_args = service.provider.send_email.call_args + subject = call_args.kwargs.get('subject') or call_args[0][1] + # Subject format: "NOMAD-1178: Seether - Tonight (Your karaoke video is ready!)" + assert subject == "NOMAD-1178: Seether - Tonight (Your karaoke video is ready!)" + + def test_send_job_completion_default_subject(self): + """Test job completion email default subject without song info.""" + service = EmailService() + service.provider = Mock() + service.provider.send_email.return_value = True + + service.send_job_completion( + to_email="user@example.com", + message_content="Your video is ready!", + ) + + call_args = service.provider.send_email.call_args + subject = call_args.kwargs.get('subject') or call_args[0][1] + assert "karaoke video is ready" in subject.lower() + + def test_send_job_completion_with_cc(self): + """Test job completion email with CC to admin.""" + service = EmailService() + service.provider = Mock() + service.provider.send_email.return_value = True + + service.send_job_completion( + to_email="user@example.com", + message_content="Your video is ready!", + cc_admin=True, + ) + + call_kwargs = service.provider.send_email.call_args.kwargs + assert "gen@nomadkaraoke.com" in call_kwargs.get('cc_emails', []) + + def test_send_job_completion_without_cc(self): + """Test job completion email without CC.""" + service = EmailService() + service.provider = Mock() + service.provider.send_email.return_value = True + + service.send_job_completion( + to_email="user@example.com", + message_content="Your video is ready!", + cc_admin=False, + ) + + call_kwargs = service.provider.send_email.call_args.kwargs + assert call_kwargs.get('cc_emails') is None + + def test_send_job_completion_escapes_html(self): + """Test that message content is HTML-escaped.""" + service = EmailService() + service.provider = Mock() + service.provider.send_email.return_value = True + + service.send_job_completion( + to_email="user@example.com", + message_content="Test ", + ) + + call_kwargs = service.provider.send_email.call_args.kwargs + html_content = call_kwargs.get('html_content') + assert "", + action_type="lyrics", + ) + + call_kwargs = service.provider.send_email.call_args.kwargs + html_content = call_kwargs.get('html_content') + assert "