Files
karaoke-gen/backend/tests/test_conversion_emails.py
Andrew Beveridge ☄️andClaude Opus 5.5 4ad946c3aa feat: free-to-paid conversion emails + last-chance review nudge, OFF until copy approved (v0.271.0) (#1156)
## Summary
This is BACKLOG Frog #2 ("plug the gen revenue leaks"), conversion-email
track. 44% of signups finish a free video, but only 6% ever pay, and
buyers decide fast (median about 5h). 45 users opened lyrics review and
let the job expire.

**Ships dark.** Nothing sends until Andrew approves the copy and
`CONVERSION_EMAILS_ENABLED` / `REVIEW_LAST_CHANCE_ENABLED` are added to
the ci.yml deploy env.

| Email | When | Stream |
|---|---|---|
| E1 "Your karaoke video is done. What's next?" + 25% off any pack for
48h | 2h after a never-paid user's **first** video completes | broadcast
|
| E2 "Your 25% off ends in 8 hours" | last 8h of the offer, if unpaid |
broadcast |
| R2 "6 hours left to finish your karaoke video" | 42h into review (the
existing reminder is at 24h; expiry is 48h) | transactional |

- `services/conversion_emails.py`:
- A `JobManager` hook marks the user on their first unpaid completion.
Tenant, Made For You and test accounts are excluded.
- The hourly `process-stale-reviews` cron sends the emails. It's
idempotent per user, and due times more than 24h stale are skipped, so
turning it on never emails a backlog. No infra change is needed.
- **Promo:** E1 grants `promo_discount_percent` /
`promo_discount_expires_at`. Checkout applies coupon
`conversion-offer-{pct}pct` when it beats a referral discount.
- The buy dialog shows a banner, and its prices use the effective
discount (CodeRabbit finding).
  - The email button links to `/app?buy=1`, which opens the dialog.
- **Compliance:** E1 and E2 go on Postmark's `broadcast` stream, where
Postmark manages unsubscribes (verified: it appends the link). They
include a postal-address footer (`COMMERCIAL_EMAIL_POSTAL_ADDRESS`).
`EmailProvider` gains `message_stream`, and email_log records the
stream.
- Copy is in `backend/translations` (33 locales). Docs:
`docs/CONVERSION-EMAILS.md`, covering how it works, measurement and how
to turn it on.

## Testing
- `make test`: backend 6017, emulator 150, frontend Jest 1688, package
2044. All green. Re-ran the targeted suites after rebasing onto the tip
PR.
- New tests:
- `test_conversion_emails.py` (26): eligibility, E1/E2 windows,
staleness, promo vs referral, broadcast stream, rendering.
- Stale-review R2 tests (3), `BuyCreditsDialog.test.tsx` (3), and an
AuthStatus `?buy=1` test.
- Rendered E1 and R2 HTML and checked them visually.
- Local CodeRabbit: 1 finding fixed.

@coderabbitai ignore

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

https://claude.ai/code/session_019KuzHAU4rxkv8JfD8NmHTN

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 23:50:59 -04:00

251 lines
11 KiB
Python

"""Tests for the free-to-paid conversion emails (E1 offer, E2 reminder, promo discount)."""
from datetime import datetime, timedelta, timezone
from types import SimpleNamespace
from unittest.mock import MagicMock, patch
import pytest
from backend.services import conversion_emails as ce
NOW = datetime(2026, 10, 15, 12, 0, tzinfo=timezone.utc)
@pytest.fixture(autouse=True)
def fixed_now(monkeypatch):
monkeypatch.setattr(ce, "_now", lambda: NOW)
@pytest.fixture
def settings(monkeypatch):
s = SimpleNamespace(
conversion_emails_enabled=True,
conversion_offer_percent=25,
conversion_offer_hours=48,
conversion_e1_delay_hours=2,
conversion_e2_hours_before_expiry=8,
)
monkeypatch.setattr(ce, "get_settings", lambda: s)
return s
class FakeDoc:
def __init__(self, data):
self._data = data
self.id = data["email"]
def to_dict(self):
return dict(self._data)
class FakeDB:
"""Minimal Firestore stand-in: where(field, op, value).stream() over dict rows."""
def __init__(self, rows):
self.rows = rows
def collection(self, name):
assert name == "gen_users"
return self
def where(self, field, op, value):
ops = {"<=": lambda a, b: a <= b, ">": lambda a, b: a > b}
matched = [r for r in self.rows if r.get(field) is not None and ops[op](r[field], value)]
return SimpleNamespace(stream=lambda: [FakeDoc(r) for r in matched])
def _user(**kw):
base = dict(
email="fan@example.com", total_spent=0, total_jobs_completed=1, tenant_id=None,
conversion_e1_due_at=None, conversion_e1_sent_at=None,
promo_discount_percent=None, promo_discount_expires_at=None,
)
base.update(kw)
return SimpleNamespace(**base)
class TestOnJobCompleted:
def _job(self, **kw):
return SimpleNamespace(**{"user_email": "fan@example.com", "made_for_you": False, "tenant_id": None,
"artist": "Queen", "title": "Bohemian Rhapsody", **kw})
def test_first_unpaid_video_is_scheduled(self, settings):
us = MagicMock()
us.get_user.return_value = _user()
assert ce.on_job_completed(self._job(), us) is True
kwargs = us.update_user.call_args.kwargs
assert kwargs["conversion_e1_due_at"] == NOW + timedelta(hours=2)
assert kwargs["first_video_artist"] == "Queen"
@pytest.mark.parametrize("user_kw", [
{"total_spent": 1000},
{"total_jobs_completed": 2},
{"conversion_e1_due_at": NOW},
{"tenant_id": "vocalstar"},
])
def test_ineligible_users_are_skipped(self, settings, user_kw):
us = MagicMock()
us.get_user.return_value = _user(**user_kw)
assert ce.on_job_completed(self._job(), us) is False
us.update_user.assert_not_called()
@pytest.mark.parametrize("job_kw", [
{"made_for_you": True},
{"tenant_id": "vocalstar"},
{"user_email": "x@inbox.testmail.app"},
{"user_email": None},
])
def test_ineligible_jobs_are_skipped(self, settings, job_kw):
us = MagicMock()
us.get_user.return_value = _user()
assert ce.on_job_completed(self._job(**job_kw), us) is False
class TestActivePromo:
def test_active_and_expired(self):
assert ce.active_promo(_user(promo_discount_percent=25, promo_discount_expires_at=NOW + timedelta(hours=1))) == (
25, NOW + timedelta(hours=1))
assert ce.active_promo(_user(promo_discount_percent=25, promo_discount_expires_at=NOW - timedelta(seconds=1))) is None
assert ce.active_promo(_user()) is None
def test_naive_and_string_datetimes(self):
naive = (NOW + timedelta(hours=3)).replace(tzinfo=None)
assert ce.active_promo(_user(promo_discount_percent=20, promo_discount_expires_at=naive))[0] == 20
iso = (NOW + timedelta(hours=3)).isoformat()
assert ce.active_promo(_user(promo_discount_percent=20, promo_discount_expires_at=iso))[0] == 20
class TestPromoCoupon:
def _patch(self, user):
us = MagicMock()
us.get_user.return_value = user
ss = MagicMock()
ss.get_or_create_promo_coupon.side_effect = lambda pct: f"conversion-offer-{pct}pct"
return (patch("backend.services.user_service.get_user_service", return_value=us),
patch("backend.services.stripe_service.get_stripe_service", return_value=ss))
def test_promo_beats_smaller_referral(self):
p1, p2 = self._patch(_user(promo_discount_percent=25, promo_discount_expires_at=NOW + timedelta(hours=5)))
with p1, p2:
assert ce.promo_coupon_for_checkout("fan@example.com", better_than_percent=20) == "conversion-offer-25pct"
assert ce.promo_coupon_for_checkout("fan@example.com", better_than_percent=50) is None
def test_no_promo(self):
p1, p2 = self._patch(_user())
with p1, p2:
assert ce.promo_coupon_for_checkout("fan@example.com") is None
class TestProcess:
def _run(self, rows, settings):
db = FakeDB(rows)
es = MagicMock(frontend_url="https://gen.nomadkaraoke.com")
us = MagicMock()
return ce.process_conversion_emails(db=db, email_service=es, user_service=us), es, us
def test_disabled_is_noop(self, settings):
settings.conversion_emails_enabled = False
result, es, us = self._run([{"email": "a@example.com", "conversion_e1_due_at": NOW}], settings)
assert result["status"] == "disabled"
es.send_conversion_offer.assert_not_called()
def test_e1_sends_and_grants_promo(self, settings):
row = {"email": "a@example.com", "conversion_e1_due_at": NOW - timedelta(minutes=5), "total_spent": 0,
"locale": "es", "first_video_artist": "Queen", "first_video_title": "Bohemian Rhapsody"}
result, es, us = self._run([row], settings)
assert result["e1_sent"] == 1
kwargs = es.send_conversion_offer.call_args.kwargs
assert kwargs["percent"] == 25 and kwargs["locale"] == "es" and kwargs["artist"] == "Queen"
assert kwargs["buy_url"].startswith("https://gen.nomadkaraoke.com/es/app?buy=1&utm_source=email")
assert "utm_campaign=conv_e1" in kwargs["buy_url"]
update = us.update_user.call_args.kwargs
assert update["promo_discount_percent"] == 25
assert update["promo_discount_expires_at"] == NOW + timedelta(hours=48)
assert update["conversion_e1_sent_at"] == NOW
def test_e1_not_due_yet_or_already_sent(self, settings):
rows = [
{"email": "future@example.com", "conversion_e1_due_at": NOW + timedelta(hours=1)},
{"email": "done@example.com", "conversion_e1_due_at": NOW - timedelta(hours=1), "conversion_e1_sent_at": NOW},
]
result, es, _ = self._run(rows, settings)
assert result["e1_sent"] == 0
es.send_conversion_offer.assert_not_called()
@pytest.mark.parametrize("row", [
{"email": "paid@example.com", "conversion_e1_due_at": NOW - timedelta(hours=1), "total_spent": 1000},
{"email": "stale@example.com", "conversion_e1_due_at": NOW - timedelta(hours=30), "total_spent": 0},
])
def test_e1_skips_paid_or_stale_and_marks_done(self, settings, row):
result, es, us = self._run([row], settings)
assert result["e1_sent"] == 0
es.send_conversion_offer.assert_not_called()
assert us.update_user.call_args.kwargs["conversion_e1_skipped"] is True
def test_e2_inside_window(self, settings):
row = {"email": "a@example.com", "conversion_e1_sent_at": NOW - timedelta(hours=41),
"promo_discount_percent": 25, "promo_discount_expires_at": NOW + timedelta(hours=7), "total_spent": 0}
result, es, us = self._run([row], settings)
assert result["e2_sent"] == 1
kwargs = es.send_conversion_offer_reminder.call_args.kwargs
assert kwargs["hours_left"] == 7 and kwargs["percent"] == 25
assert "utm_campaign=conv_e2" in kwargs["buy_url"]
@pytest.mark.parametrize("extra", [
{"promo_discount_expires_at": NOW + timedelta(hours=20)}, # too early
{"conversion_e2_sent_at": NOW - timedelta(hours=1)}, # already sent
{"total_spent": 2400}, # bought
])
def test_e2_skips(self, settings, extra):
row = {"email": "a@example.com", "conversion_e1_sent_at": NOW - timedelta(hours=41),
"promo_discount_percent": 25, "promo_discount_expires_at": NOW + timedelta(hours=7), "total_spent": 0}
row.update(extra)
result, es, _ = self._run([row], settings)
assert result["e2_sent"] == 0
class TestEmailRendering:
@pytest.fixture
def email_service(self):
from backend.services.email_service import EmailService
svc = EmailService.__new__(EmailService)
svc.settings = SimpleNamespace(commercial_email_postal_address="Nomad Karaoke, 1 Test St")
svc.frontend_url = "https://gen.nomadkaraoke.com"
svc._log_and_send = MagicMock(return_value=True)
return svc
def test_offer_goes_on_broadcast_stream_with_postal_address(self, email_service):
email_service.send_conversion_offer(
"a@example.com", "Queen", "Bohemian Rhapsody", 25, 48,
"https://gen.nomadkaraoke.com/en/app?buy=1", "https://gen.nomadkaraoke.com/en/order",
)
kwargs = email_service._log_and_send.call_args.kwargs
assert kwargs["message_stream"] == "broadcast"
assert "25% off any credit pack for the next 48 hours" in kwargs["html_content"]
assert "Queen - Bohemian Rhapsody" in kwargs["html_content"]
assert "1 Test St" in kwargs["html_content"] and "1 Test St" in kwargs["text_content"]
def test_reminder_is_broadcast(self, email_service):
email_service.send_conversion_offer_reminder("a@example.com", 25, 7, "https://x")
kwargs = email_service._log_and_send.call_args.kwargs
assert kwargs["message_stream"] == "broadcast"
assert kwargs["subject"] == "Your 25% off ends in 7 hours"
def test_last_chance_is_transactional(self, email_service):
email_service.send_review_last_chance("a@example.com", "Queen", "Song", "https://x/review", 6)
kwargs = email_service._log_and_send.call_args.kwargs
assert "message_stream" not in kwargs
assert kwargs["subject"] == "6 hours left to finish your karaoke video: Queen - Song"
class TestPostmarkStream:
def test_broadcast_stream_in_payload(self):
from backend.services.email_service import PostmarkEmailProvider
p = PostmarkEmailProvider("tok", "gen@nomadkaraoke.com")
resp = MagicMock(status_code=200)
resp.json.return_value = {"MessageID": "m1"}
with patch.object(p, "_post_with_retry", return_value=resp) as post:
assert p.send_email("a@example.com", "s", "<p>x</p>", message_stream="broadcast")
assert post.call_args.args[0]["MessageStream"] == "broadcast"
assert p.send_email("a@example.com", "s", "<p>x</p>")
assert post.call_args.args[0]["MessageStream"] == "outbound"