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 "