feat(server): Gumroad webhook receiver + Postmark email (PR 2)

Wires the second source-adapter (Gumroad) plus the email delivery
that lets the server fulfill a sale end-to-end without operator
intervention.

Auth model: Gumroad doesn't HMAC the body, so we use their
recommended URL-secret pattern (?secret=...). Wrong/missing secret
returns 404 — no signal to a prober that the endpoint exists.

Webhook flow (server/app/routes/webhooks.py):
  1. audit-log the raw payload (gumroad_events row) BEFORE anything
     else, so a later failure leaves us replayable
  2. parse via GumroadAdapter (server/app/adapters/gumroad.py)
  3. mint_from_sale — UNIQUE(source, source_order_id) dedups
     duplicate webhook retries
  4. send the license email
  5. mark gumroad_events.processed = true

Always returns 200 once auth passes. Non-2xx would trigger Gumroad's
3-day retry storm; we'd rather record the failure on the audit row
and replay manually after fixing whatever surfaced.

Product → tier mapping is per-source YAML at
server/config/products.yaml (lru_cached). Adding a SKU = edit yaml,
restart api. Unmapped product_id is an error on the audit row, not
a crash.

EmailService (server/app/email.py): provider-agnostic interface with
Postmark as the first implementation. When POSTMARK_TOKEN is unset
the factory returns LoggingEmailService instead, so the webhook
exercises end-to-end before Postmark is provisioned.

48 unit tests (was 21) including:
- Gumroad secret verify with constant-time compare
- Sale parsing: amount-in-cents, name fallback from email,
  test=true tagging, missing-required fields, offer codes
- Product mapping lookups
- Email rendering text + HTML, HTML-escapes user input
- Postmark client via httpx.MockTransport (success and 4xx)
- Webhook end-to-end: secret check, audit log, idempotency on
  retry, unmapped product, email failure keeps license

Smoke test (server/scripts/smoke.sh) extended to POST a synthetic
Ping payload, verify the row + audit log, prove wrong-secret is
rejected, prove duplicate sale_id stays one row.

SQLite-test compatibility:
- BigInteger primary key uses with_variant(Integer, "sqlite") since
  SQLite only autoincrements INTEGER PRIMARY KEY.
- python-multipart pulled in for FastAPI Form parsing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

server/tests/test_email.py

@@ -0,0 +1,103 @@
+"""EmailService — Postmark client + dev-mode logging fallback."""
+
+from __future__ import annotations
+
+import logging
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+from app.email import (
+    EmailDeliveryError,
+    LicenseEmail,
+    LoggingEmailService,
+    PostmarkEmailService,
+    _render_html,
+    _render_text,
+    get_email_service,
+)
+
+
+def _msg() -> LicenseEmail:
+    return LicenseEmail(
+        to_name="Jane Doe",
+        to_email="jane@example.com",
+        tier="core",
+        license_key="DT1-CORE-aaaa-bbbb",
+        expires_at_iso="2027-05-14T01:00:00Z",
+        blob="DTLIC2:placeholder",
+    )
+
+
+def test_render_text_contains_essentials():
+    body = _render_text(_msg())
+    assert "Jane Doe" in body
+    assert "DTLIC2:placeholder" in body
+    assert "DT1-CORE-aaaa-bbbb" in body
+    assert "core" in body
+    assert "2027-05-14" in body
+
+
+def test_render_html_escapes_user_input():
+    msg = LicenseEmail(
+        to_name="<script>alert(1)</script>",
+        to_email="x@y.com",
+        tier="core",
+        license_key="K",
+        expires_at_iso="2030-01-01T00:00:00Z",
+        blob="DTLIC2:x",
+    )
+    html = _render_html(msg)
+    assert "<script>" not in html
+    assert "&lt;script&gt;" in html
+
+
+def test_logging_service_writes_to_log(caplog):
+    caplog.set_level(logging.INFO)
+    svc = LoggingEmailService()
+    result = svc.send_license(_msg())
+    assert result == "logged"
+    log_text = "\n".join(r.message for r in caplog.records)
+    assert "would send" in log_text
+    assert "jane@example.com" in log_text
+    assert "DTLIC2:placeholder" in log_text
+
+
+def test_factory_returns_logging_when_no_token(monkeypatch):
+    monkeypatch.delenv("POSTMARK_TOKEN", raising=False)
+    monkeypatch.delenv("POSTMARK_TOKEN_FILE", raising=False)
+    from app.config import get_settings
+    get_settings.cache_clear()
+    svc = get_email_service()
+    assert isinstance(svc, LoggingEmailService)
+
+
+def test_postmark_send_success():
+    svc = PostmarkEmailService("test-token", sender="from@example.com")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = request.read().decode()
+        assert "from@example.com" in body
+        assert "jane@example.com" in body
+        assert "DTLIC2:placeholder" in body
+        return httpx.Response(200, json={"MessageID": "pm-12345"})
+
+    transport = httpx.MockTransport(handler)
+    _real_client = httpx.Client
+    with patch("app.email.httpx.Client", lambda **kw: _real_client(transport=transport, **kw)):
+        msg_id = svc.send_license(_msg())
+    assert msg_id == "pm-12345"
+
+
+def test_postmark_send_raises_on_failure():
+    svc = PostmarkEmailService("test-token", sender="from@example.com")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(422, json={"Message": "Invalid sender"})
+
+    transport = httpx.MockTransport(handler)
+    _real_client = httpx.Client
+    with patch("app.email.httpx.Client", lambda **kw: _real_client(transport=transport, **kw)):
+        with pytest.raises(EmailDeliveryError, match="422"):
+            svc.send_license(_msg())

server/tests/test_gumroad_adapter.py

@@ -0,0 +1,97 @@
+"""Gumroad adapter: secret check, Ping parsing, refunds stub."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+import pytest
+
+from app.adapters.gumroad import GumroadAdapter, UnmappedProductError
+
+
+def _sale_payload(**overrides) -> dict:
+    base = {
+        "sale_id": "GUM-1001",
+        "email": "jane@example.com",
+        "full_name": "Jane Doe",
+        "product_id": "datatools-core",
+        "price": "9900",          # cents
+        "currency": "usd",
+        "offer_code": "",
+        "test": "false",
+    }
+    base.update(overrides)
+    return base
+
+
+def test_verify_secret_correct():
+    a = GumroadAdapter(secret="abc123")
+    assert a.verify_secret("abc123") is True
+
+
+def test_verify_secret_wrong():
+    a = GumroadAdapter(secret="abc123")
+    assert a.verify_secret("nope") is False
+
+
+def test_verify_secret_unset_rejects_all():
+    a = GumroadAdapter(secret=None)
+    assert a.verify_secret("anything") is False
+    assert a.verify_secret(None) is False
+
+
+def test_verify_secret_missing_presented_value():
+    a = GumroadAdapter(secret="abc123")
+    assert a.verify_secret(None) is False
+    assert a.verify_secret("") is False
+
+
+def test_parse_sale_happy_path():
+    a = GumroadAdapter(secret="x")
+    sale = a.parse_sale(_sale_payload())
+    assert sale is not None
+    assert sale.source == "gumroad"
+    assert sale.source_order_id == "GUM-1001"
+    assert sale.buyer_email == "jane@example.com"
+    assert sale.buyer_name == "Jane Doe"
+    assert sale.tier == "core"
+    assert sale.years == 1
+    assert sale.amount_paid == Decimal("99.00")
+    assert sale.currency == "USD"
+    assert sale.promotion is None
+
+
+def test_parse_sale_with_offer_code():
+    a = GumroadAdapter(secret="x")
+    sale = a.parse_sale(_sale_payload(offer_code="LAUNCH50"))
+    assert sale.promotion == "LAUNCH50"
+
+
+def test_parse_sale_test_ping_tagged():
+    a = GumroadAdapter(secret="x")
+    sale = a.parse_sale(_sale_payload(test="true"))
+    assert sale.notes == "gumroad test ping"
+
+
+def test_parse_sale_name_fallback_from_email():
+    a = GumroadAdapter(secret="x")
+    sale = a.parse_sale(_sale_payload(full_name="", email="john.doe@example.com"))
+    assert sale.buyer_name == "John Doe"
+
+
+def test_parse_sale_missing_required_returns_none():
+    a = GumroadAdapter(secret="x")
+    assert a.parse_sale(_sale_payload(sale_id="")) is None
+    assert a.parse_sale(_sale_payload(email="")) is None
+    assert a.parse_sale(_sale_payload(product_id="")) is None
+
+
+def test_parse_sale_unmapped_product_raises():
+    a = GumroadAdapter(secret="x")
+    with pytest.raises(UnmappedProductError):
+        a.parse_sale(_sale_payload(product_id="no-such-sku"))
+
+
+def test_parse_refund_stub_returns_none():
+    a = GumroadAdapter(secret="x")
+    assert a.parse_refund({"any": "payload"}) is None

server/tests/test_products.py

@@ -0,0 +1,32 @@
+"""Product → tier mapping lookup."""
+
+from __future__ import annotations
+
+from app.products import lookup, reload_for_tests
+
+
+def setup_function(_):
+    # The yaml file is read once at import; reload to be safe if
+    # other tests mutate state in the future.
+    reload_for_tests()
+
+
+def test_lookup_known_gumroad_product():
+    m = lookup("gumroad", "datatools-core")
+    assert m is not None
+    assert m.tier == "core"
+    assert m.years == 1
+
+
+def test_lookup_unknown_product_returns_none():
+    assert lookup("gumroad", "no-such-product") is None
+
+
+def test_lookup_unknown_source_returns_none():
+    assert lookup("paddle", "datatools-core") is None
+
+
+def test_all_three_tiers_mapped():
+    assert lookup("gumroad", "datatools-lite").tier == "lite"
+    assert lookup("gumroad", "datatools-core").tier == "core"
+    assert lookup("gumroad", "datatools-pro").tier == "pro"

server/tests/test_webhook.py

@@ -0,0 +1,143 @@
+"""End-to-end webhook tests — secret check, audit log, mint, email,
+idempotency."""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import patch
+
+import pytest
+
+from app.email import LicenseEmail
+from app.models import GumroadEvent, License
+
+
+@pytest.fixture
+def with_gumroad_secret(monkeypatch):
+    monkeypatch.setenv("GUMROAD_WEBHOOK_SECRET", "test-gumroad-secret")
+    from app.config import get_settings
+    get_settings.cache_clear()
+    yield
+    get_settings.cache_clear()
+
+
+def _form(**overrides) -> dict:
+    base = {
+        "sale_id": "GUM-2001",
+        "email": "jane@example.com",
+        "full_name": "Jane Doe",
+        "product_id": "datatools-core",
+        "price": "9900",
+        "currency": "usd",
+        "offer_code": "",
+        "test": "false",
+    }
+    base.update(overrides)
+    return base
+
+
+def test_webhook_rejects_missing_secret(client, with_gumroad_secret):
+    r = client.post("/webhooks/gumroad", data=_form())
+    assert r.status_code == 404
+
+
+def test_webhook_rejects_wrong_secret(client, with_gumroad_secret):
+    r = client.post("/webhooks/gumroad?secret=wrong", data=_form())
+    assert r.status_code == 404
+
+
+def test_webhook_mints_and_sends_email(client, with_gumroad_secret, db_session):
+    captured: list[LicenseEmail] = []
+
+    class CapturingEmail:
+        def send_license(self, msg):
+            captured.append(msg)
+            return "captured"
+
+    with patch("app.routes.webhooks.get_email_service", lambda: CapturingEmail()):
+        r = client.post(
+            "/webhooks/gumroad?secret=test-gumroad-secret",
+            data=_form(),
+        )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["status"] == "ok"
+    assert body["license_key"].startswith("DT1-CORE-")
+
+    # DB row landed.
+    row = db_session.query(License).filter_by(source_order_id="GUM-2001").one()
+    assert row.source == "gumroad"
+    assert row.email == "jane@example.com"
+    assert row.tier == "core"
+    assert row.blob.startswith("DTLIC2:")
+
+    # Audit row processed.
+    event = db_session.query(GumroadEvent).filter_by(order_id="GUM-2001").one()
+    assert event.processed is True
+    assert event.error is None
+
+    # Email captured.
+    assert len(captured) == 1
+    assert captured[0].to_email == "jane@example.com"
+    assert captured[0].blob == row.blob
+
+
+def test_webhook_idempotent_on_duplicate_sale_id(client, with_gumroad_secret, db_session):
+    """Gumroad retries on transient failures. Same sale_id must
+    produce one license, not two."""
+    with patch("app.routes.webhooks.get_email_service", lambda: _NullEmail()):
+        client.post("/webhooks/gumroad?secret=test-gumroad-secret", data=_form())
+        client.post("/webhooks/gumroad?secret=test-gumroad-secret", data=_form())
+
+    rows = db_session.query(License).filter_by(source_order_id="GUM-2001").all()
+    assert len(rows) == 1
+    # But both webhook deliveries should be in the audit log.
+    events = db_session.query(GumroadEvent).filter_by(order_id="GUM-2001").all()
+    assert len(events) == 2
+
+
+def test_webhook_unmapped_product_audits_and_returns_200(client, with_gumroad_secret, db_session):
+    """An unknown product_id must NOT crash and must NOT trigger a
+    retry storm. Audit row gets the error reason."""
+    with patch("app.routes.webhooks.get_email_service", lambda: _NullEmail()):
+        r = client.post(
+            "/webhooks/gumroad?secret=test-gumroad-secret",
+            data=_form(product_id="not-a-real-sku", sale_id="GUM-666"),
+        )
+    assert r.status_code == 200
+    assert r.json()["status"] == "logged-no-mint"
+
+    # No license, but audit row with error.
+    assert db_session.query(License).filter_by(source_order_id="GUM-666").count() == 0
+    event = db_session.query(GumroadEvent).filter_by(order_id="GUM-666").one()
+    assert event.processed is False
+    assert "no entry in config/products.yaml" in (event.error or "")
+
+
+def test_webhook_email_failure_keeps_license(client, with_gumroad_secret, db_session):
+    """If Postmark hiccups, the buyer's license is still minted and
+    persists in the DB. They can be served from the renewal portal
+    (PR 3) or a manual resend."""
+    from app.email import EmailDeliveryError
+
+    class FailingEmail:
+        def send_license(self, msg):
+            raise EmailDeliveryError("Postmark 503")
+
+    with patch("app.routes.webhooks.get_email_service", lambda: FailingEmail()):
+        r = client.post(
+            "/webhooks/gumroad?secret=test-gumroad-secret",
+            data=_form(sale_id="GUM-3001"),
+        )
+    assert r.status_code == 200
+    assert r.json()["status"] == "minted-email-failed"
+
+    assert db_session.query(License).filter_by(source_order_id="GUM-3001").count() == 1
+    event = db_session.query(GumroadEvent).filter_by(order_id="GUM-3001").one()
+    assert event.processed is True   # we count it processed so Gumroad doesn't retry
+    assert "email error" in (event.error or "")
+
+
+class _NullEmail:
+    def send_license(self, msg):
+        return "null"