"""Provider-neutral, email-client-safe transactional email presentation. Capabilities supply semantic content; this module owns the shared HTML/text shell. Delivery selection and provider credentials intentionally live outside this module. """ from __future__ import annotations import re from dataclasses import dataclass, field from html import escape from urllib.parse import urlparse NEUTRAL_ACCENT = "#1f2937" MANAGED_ATTRIBUTION = "Sent securely via P2HS" _SUPPORT_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$") # Light-theme colors are inline (work everywhere, including clients that strip # """ def _clean(value: str | None, fallback: str = "") -> str: return " ".join((value or "").strip().split()) or fallback def _safe_color(value: str | None) -> str: """Accept only a hex color with readable white CTA text.""" raw = (value or "").strip() if len(raw) not in (4, 7) or not raw.startswith("#"): return NEUTRAL_ACCENT digits = raw[1:] if len(digits) == 3: digits = "".join(ch * 2 for ch in digits) try: r, g, b = (int(digits[i : i + 2], 16) for i in (0, 2, 4)) except ValueError: return NEUTRAL_ACCENT # WCAG-ish luminance gate for white button text. luminance = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255 return f"#{digits.lower()}" if luminance < 0.48 else NEUTRAL_ACCENT def _safe_url(value: str) -> str: parsed = urlparse(value.strip()) if value.strip().startswith("/") and parsed.scheme == "": return value.strip() if parsed.scheme not in {"http", "https", "p2hs"} or not parsed.netloc and parsed.scheme != "p2hs": raise ValueError("transactional email action URL must use http(s) or p2hs") return value.strip() @dataclass(frozen=True) class ApplicationBranding: name: str logo_url: str | None = None accent_color: str | None = None support_identity: str | None = None environment_label: str | None = None @property def display_name(self) -> str: return _clean(self.name, "Your application") @property def accent(self) -> str: return _safe_color(self.accent_color) @property def safe_logo_url(self) -> str | None: if not self.logo_url: return None try: parsed = urlparse(self.logo_url.strip()) if parsed.scheme in {"http", "https"} and parsed.netloc: return self.logo_url.strip() except ValueError: pass return None @dataclass(frozen=True) class EmailPresentation: template_key: str template_version: str title: str intro: str action_label: str | None = None action_url: str | None = None note: str | None = None fallback_url: str | None = None preheader: str | None = None details: tuple[tuple[str, str], ...] = () security_notice: str | None = None @dataclass(frozen=True) class EmailMessage: recipient: str branding: ApplicationBranding presentation: EmailPresentation subject: str footer: str = MANAGED_ATTRIBUTION metadata: dict[str, str] = field(default_factory=dict) def render_transactional_email(message: EmailMessage) -> tuple[str, str]: """Return deterministic ``(html, plain_text)`` for a semantic message.""" p = message.presentation b = message.branding action_url = _safe_url(p.action_url) if p.action_url else None fallback_url = _safe_url(p.fallback_url or p.action_url) if (p.fallback_url or p.action_url) else None name = escape(b.display_name) title = escape(_clean(p.title)) intro = escape(_clean(p.intro)) accent = b.accent logo = "" if b.safe_logo_url: logo = ( f' {name}

' ) env_marker = f' ({escape(_clean(b.environment_label))})' if b.environment_label else "" cta = "" if action_url and p.action_label: cta = ( f'{escape(p.action_label)}' ) details = "".join( f'{escape(k)}' f'{escape(v)}' for k, v in p.details ) details_block = f'{details}

' if details else "" note = f'

{escape(p.note)}

' if p.note else "" security = f'

{escape(p.security_notice)}

' if p.security_notice else "" fallback = "" if fallback_url: fallback = ( '

' 'Having trouble with the button? Copy and paste this link into your browser:
' f'' f'{escape(fallback_url)}

' ) support = "" support_identity = _clean(b.support_identity) if support_identity: support_contact = ( f'{escape(support_identity)}' if _SUPPORT_EMAIL_RE.match(support_identity) else escape(support_identity) ) support = f'

Need help? Contact {support_contact}

' html = f'''{title} {_DARK_MODE_STYLE}

{logo}

{name}{env_marker}

{title}

{intro}

{details_block}

{cta}

{note}{security}{fallback}

{escape(message.footer)}{support}

''' lines = [b.display_name, "", _clean(p.title), "", _clean(p.intro)] lines.extend(f"{k}: {v}" for k, v in p.details) if p.action_label and action_url: lines.extend(["", f"{p.action_label}: {action_url}"]) if p.note: lines.extend(["", _clean(p.note)]) if p.security_notice: lines.extend(["", _clean(p.security_notice)]) if fallback_url: lines.extend(["", "Having trouble with the button?", fallback_url]) lines.extend(["", message.footer]) if support_identity: lines.extend(["", f"Need help? Contact {support_identity}"]) return html, "\n".join(lines) def magic_link_message(*, recipient: str, app_name: str, link_url: str, ttl_minutes: int, logo_url: str | None = None, accent_color: str | None = None, environment_label: str | None = None) -> EmailMessage: duration = f"{ttl_minutes} minutes" if ttl_minutes < 60 else f"{ttl_minutes // 60} hour{'s' if ttl_minutes // 60 != 1 else ''}" branding = ApplicationBranding(app_name, logo_url, accent_color, environment_label=environment_label) presentation = EmailPresentation( template_key="auth.magic_link", template_version="auth.magic_link.v1", title=f"Sign in to {branding.display_name}", intro="Use the secure link below to sign in to your account.", action_label="Sign in", action_url=link_url, fallback_url=link_url, preheader=f"Sign in to {branding.display_name}", security_notice=f"This link expires in {duration}. If you didn't request this email, you can safely ignore it.", ) return EmailMessage(recipient, branding, presentation, f"Sign in to {branding.display_name}")