Files
karaoke-gen/tests/unit/test_postmark_admin_service.py
Andrew Beveridge ☄️andClaude Opus 4.8 1e99f9e0d5 feat(admin): per-job/user locale badge + "emails sent to user" history (#930)
## Summary

Two admin-only features so support/intervention work can (a) know what
language/country a user is using the product in, and (b) see the exact
emails ever sent to a user, rendered as they appeared in the inbox with
full delivery metadata.

### A — Language / country visibility (admin-only)
- New `get_full_locale_from_request()` captures the real UI language
(any of 33, not the narrowed en/es/de email locale) on **every**
job-creation path (URL, upload, audio-search, bulk, made-for-you via
Stripe metadata). Stored as `Job.locale` (+ added to the dashboard
summary projection) and `User.ui_locale` (kept separate from
`User.locale`).
- `LocaleBadge` (flag + language) shown in the admin jobs table, admin
job detail (+ country via the existing `IpInfo` on the creation IP), the
user-detail header, and the customer `JobCard` **gated to admins only**
— regular users never see it.
- Country is derived from IP (existing `ip_geolocation_service`); no new
capture.

### B — "Emails sent to this user"
- Every send routes through one `EmailService._log_and_send` chokepoint
that persists each email to a new Firestore `email_log` collection
(rendered HTML + Postmark MessageID), best-effort so it can never break
or delay a send. Single-use auth/capability tokens (magic-link, review,
referral) are **redacted** before persistence.
- `PostmarkAdminService` merges the Postmark Messages API (last ~45
days: exact HTML + opens/clicks/bounce/delivery status, paginated) with
the Firestore log (permanent), de-duplicated by message id.
- Endpoints `GET /api/admin/users/{email}/emails` and `GET
/api/admin/emails/{id}`; the user-detail "Emails Sent" card opens a
modal rendering the email in a sandboxed `<iframe srcDoc>` with a
metadata side panel.
- New Firestore composite index (`email_log` recipient + created_at)
added to Pulumi.

## Testing
- **41 new backend tests** (locale capture incl. q=0, email logging +
token redaction, PostmarkAdminService incl. pagination + 45-day
fallback, job-locale persistence, admin endpoints) — all pass.
- **10 new frontend tests** (LocaleBadge, UserEmailsCard list +
sandboxed-iframe modal) — all pass.
- Regression sweep on related existing suites: green. Preview-email flow
smoke-tested through the new chokepoint.

## Notes
- `pulumi up` for the new `email_log` index should be applied before
merge (done locally).
- `Job.locale` populates for new jobs going forward; historical jobs
fall back to the submitting user's locale where shown.

Local CodeRabbit review completed and addressed (token redaction,
pagination, row a11y, locale-overwrite guard, q=0 handling).

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

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-23 01:51:42 -04:00

176 lines
8.1 KiB
Python

"""Tests for PostmarkAdminService — admin email-history queries.
Merges the Postmark Messages API (last ~45 days, rich metadata) with our
persisted Firestore email_log (permanent), de-duplicating by MessageID, and
serves full message detail with a log fallback for expired Postmark content.
"""
from unittest.mock import MagicMock, patch
import backend.services.postmark_admin_service as pm
from backend.services.postmark_admin_service import PostmarkAdminService
def _log_doc(doc_id, data):
d = MagicMock()
d.id = doc_id
d.to_dict.return_value = data
return d
def _make_service(log_docs=None):
svc = PostmarkAdminService(server_token="tok")
fake_db = MagicMock()
# collection().where().order_by().limit().stream() -> log_docs
stream = MagicMock()
stream.stream.return_value = log_docs or []
fake_db.collection.return_value.where.return_value.order_by.return_value.limit.return_value = stream
svc._db = fake_db
return svc, fake_db
class TestHistoryMerge:
def test_merges_and_dedupes_by_message_id(self):
# Postmark returns m1 + m2; the log also has m2 (dupe) + m3 (older, purged).
postmark_json = {
"Messages": [
{"MessageID": "m1", "Subject": "Welcome", "Recipients": ["u@x.com"],
"From": "gen@x.com", "ReceivedAt": "2026-08-20T10:00:00Z", "Status": "Sent"},
{"MessageID": "m2", "Subject": "Receipt", "Recipients": ["u@x.com"],
"From": "gen@x.com", "ReceivedAt": "2026-08-21T10:00:00Z", "Status": "Sent"},
]
}
log_docs = [
_log_doc("m2", {"postmark_message_id": "m2", "recipient": "u@x.com",
"subject": "Receipt", "html_content": "<p>r</p>",
"created_at": "2026-08-21T10:00:00Z", "email_type": "credits_added"}),
_log_doc("auto3", {"postmark_message_id": "m3", "recipient": "u@x.com",
"subject": "Old", "html_content": "<p>old</p>",
"created_at": "2026-07-01T10:00:00Z", "email_type": "welcome"}),
]
svc, _ = _make_service(log_docs)
resp = MagicMock(status_code=200)
resp.json.return_value = postmark_json
with patch.object(pm.requests, "get", return_value=resp):
history = svc.get_user_email_history("u@x.com")
ids = {e["message_id"] for e in history["emails"]}
assert ids == {"m1", "m2", "m3"} # dupe m2 collapsed, m3 from log preserved
assert history["count"] == 3
assert history["postmark_available"] is True
# Newest first
sent = [e["sent_at"] for e in history["emails"]]
assert sent == sorted(sent, reverse=True)
# m2 present in both sources → flagged as having stored HTML
m2 = next(e for e in history["emails"] if e["message_id"] == "m2")
assert m2["source"] == "postmark"
assert m2["has_stored_html"] is True
def test_paginates_postmark_until_exhausted(self):
svc, _ = _make_service([])
# 250 total messages across pages of 100 → 3 requests (100, 100, 50).
def fake_get(url, headers=None, params=None, timeout=None):
offset = params["offset"]
remaining = max(0, 250 - offset)
n = min(params["count"], remaining)
msgs = [{"MessageID": f"m{offset+i}", "Subject": "s", "Recipients": ["u@x.com"],
"ReceivedAt": f"2026-08-20T{(offset+i) % 24:02d}:00:00Z"} for i in range(n)]
r = MagicMock(status_code=200)
r.json.return_value = {"Messages": msgs, "TotalCount": 250}
return r
with patch.object(pm.requests, "get", side_effect=fake_get) as get_mock:
history = svc.get_user_email_history("u@x.com")
assert get_mock.call_count == 3 # paged, not a single batch
assert history["count"] == 250
def test_no_postmark_token_returns_log_only(self):
svc, _ = _make_service([
_log_doc("auto1", {"postmark_message_id": None, "recipient": "u@x.com",
"subject": "Hi", "html_content": "<p>h</p>",
"created_at": "2026-08-01T00:00:00Z"}),
])
svc.server_token = None
history = svc.get_user_email_history("u@x.com")
assert history["postmark_available"] is False
assert history["count"] == 1
assert history["emails"][0]["source"] == "log"
def test_postmark_error_degrades_to_log(self):
svc, _ = _make_service([])
resp = MagicMock(status_code=500, text="server error")
with patch.object(pm.requests, "get", return_value=resp):
history = svc.get_user_email_history("u@x.com")
assert history["count"] == 0 # no crash, empty result
class TestEmailDetail:
def test_postmark_detail_parses_events(self):
svc, _ = _make_service()
details = {
"MessageID": "m1", "Subject": "Welcome", "From": "gen@x.com",
"Recipients": ["u@x.com"], "HtmlBody": "<h1>Hi</h1>", "TextBody": "Hi",
"ReceivedAt": "2026-08-20T10:00:00Z", "MessageStream": "outbound",
"MessageEvents": [
{"Type": "Delivered", "ReceivedAt": "2026-08-20T10:01:00Z", "Details": {}},
{"Type": "Opened", "ReceivedAt": "2026-08-20T11:00:00Z", "Details": {}},
{"Type": "Opened", "ReceivedAt": "2026-08-20T12:00:00Z", "Details": {}},
],
}
resp = MagicMock(status_code=200)
resp.json.return_value = details
with patch.object(pm.requests, "get", return_value=resp):
detail = svc.get_email_detail("m1")
assert detail["html_body"] == "<h1>Hi</h1>"
assert detail["status"] == "Delivered"
assert detail["open_count"] == 2
assert detail["delivered_at"] == "2026-08-20T10:01:00+00:00" or detail["delivered_at"].startswith("2026-08-20T10:01:00")
def test_bounced_status_from_events(self):
svc, _ = _make_service()
details = {
"MessageID": "m9", "Subject": "x", "HtmlBody": "<p>x</p>",
"MessageEvents": [{"Type": "Bounced", "ReceivedAt": "2026-08-20T10:01:00Z",
"Details": {"Type": "HardBounce"}}],
}
resp = MagicMock(status_code=200)
resp.json.return_value = details
with patch.object(pm.requests, "get", return_value=resp):
detail = svc.get_email_detail("m9")
assert detail["status"] == "Bounced"
assert detail["bounce"] == {"Type": "HardBounce"}
def test_postmark_404_falls_back_to_log(self):
svc, fake_db = _make_service()
# Postmark 404 (older than retention) → read stored copy by message id.
snap = MagicMock()
snap.exists = True
snap.to_dict.return_value = {
"postmark_message_id": "old1", "recipient": "u@x.com", "subject": "Old",
"html_content": "<p>stored</p>", "created_at": "2026-06-01T00:00:00Z",
"email_type": "welcome",
}
fake_db.collection.return_value.document.return_value.get.return_value = snap
resp = MagicMock(status_code=404, text="not found")
with patch.object(pm.requests, "get", return_value=resp):
detail = svc.get_email_detail("old1")
assert detail is not None
assert detail["source"] == "log"
assert detail["html_body"] == "<p>stored</p>"
def test_source_log_skips_postmark(self):
svc, fake_db = _make_service()
snap = MagicMock()
snap.exists = True
snap.to_dict.return_value = {"postmark_message_id": "x", "recipient": "u@x.com",
"subject": "S", "html_content": "<p>b</p>",
"created_at": "2026-06-01T00:00:00Z"}
fake_db.collection.return_value.document.return_value.get.return_value = snap
with patch.object(pm.requests, "get") as get_mock:
detail = svc.get_email_detail("x", source="log")
get_mock.assert_not_called() # log source must not hit Postmark
assert detail["source"] == "log"
assert detail["html_body"] == "<p>b</p>"