mailfixture 0.2.0__tar.gz → 0.4.1__tar.gz

{mailfixture-0.2.0 → mailfixture-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailfixture
-Version: 0.2.0
+Version: 0.4.1
 Summary: Email fixtures for your test suite — programmatic inboxes, long-polling, first-class OTP and link extraction.
 Project-URL: Homepage, https://mailfixture.com
 Project-URL: Documentation, https://mailfixture.com/docs

{mailfixture-0.2.0 → mailfixture-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mailfixture"
-version = "0.2.0"
+version = "0.4.1"
 description = "Email fixtures for your test suite — programmatic inboxes, long-polling, first-class OTP and link extraction."
 readme = "README.md"
 license = "MIT"

{mailfixture-0.2.0 → mailfixture-0.4.1}/src/mailfixture/__init__.py

@@ -42,6 +42,11 @@ __all__ = [
     "Otp",
     "OtpCandidate",
     "Link",
+    "Auth",
+    "SpfAuth",
+    "DkimAuth",
+    "DmarcAuth",
+    "FollowResult",
     "Attachment",
     "Domain",
     "DomainVerification",
@@ -55,7 +60,7 @@ __all__ = [
     "MailFixtureTimeout",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.4.1"
 
 DEFAULT_BASE_URL = "https://api.mailfixture.com"
 #: Server-side ceiling for one long-poll request; the client chains
@@ -138,6 +143,103 @@ class Link:
         return cls(url=data["url"], text=data.get("text"), kind=data.get("class", "other"))
 
 
+@dataclass
+class SpfAuth:
+    """SPF verdict for the delivering session. `result` uses the RFC 8601
+    strings: pass | fail | softfail | neutral | none | temperror |
+    permerror."""
+
+    result: str
+    #: The domain SPF was evaluated for (envelope sender, or HELO for
+    #: bounces).
+    domain: Optional[str]
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "SpfAuth":
+        return cls(result=data.get("result", "none"), domain=data.get("domain"))
+
+
+@dataclass
+class DkimAuth:
+    """One DKIM signature's verdict. A broken signature reports `neutral`
+    (RFC 6376 treats it as unsigned) with the reason in `error`."""
+
+    result: str
+    domain: Optional[str]
+    selector: Optional[str]
+    error: Optional[str]
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "DkimAuth":
+        return cls(
+            result=data.get("result", "none"),
+            domain=data.get("domain"),
+            selector=data.get("selector"),
+            error=data.get("error"),
+        )
+
+
+@dataclass
+class DmarcAuth:
+    """DMARC verdict: pass when either aligned mechanism passed; `none`
+    when the From domain publishes no record (then `policy` is None)."""
+
+    result: str
+    #: The RFC5322.From domain DMARC was evaluated for.
+    domain: Optional[str]
+    #: none | quarantine | reject — only when a record exists.
+    policy: Optional[str]
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "DmarcAuth":
+        return cls(
+            result=data.get("result", "none"),
+            domain=data.get("domain"),
+            policy=data.get("policy"),
+        )
+
+
+@dataclass
+class Auth:
+    """Inbound SPF/DKIM/DMARC verification results for a message.
+    Unsigned mail has an empty `dkim` list."""
+
+    spf: SpfAuth
+    dkim: List[DkimAuth]
+    dmarc: DmarcAuth
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "Auth":
+        return cls(
+            spf=SpfAuth._from_json(data.get("spf") or {}),
+            dkim=[DkimAuth._from_json(d) for d in data.get("dkim") or []],
+            dmarc=DmarcAuth._from_json(data.get("dmarc") or {}),
+        )
+
+
+@dataclass
+class FollowResult:
+    """Outcome of a server-side link follow: the final response after
+    redirects. The target's body is never returned."""
+
+    requested_url: str
+    final_url: str
+    status: int
+    redirects: int
+    #: Convenience: status was 2xx.
+    ok: bool
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "FollowResult":
+        return cls(
+            requested_url=data["requested_url"],
+            final_url=data["final_url"],
+            status=data["status"],
+            redirects=data["redirects"],
+            ok=data["ok"],
+        )
+
+
 @dataclass
 class Attachment:
     filename: str
@@ -199,6 +301,13 @@ class Message:
     def links(self) -> List[Link]:
         return [Link._from_json(l) for l in self.extracted.get("links", [])]
 
+    @property
+    def auth(self) -> Optional[Auth]:
+        """SPF/DKIM/DMARC verdicts. None = not verified (message predates
+        the feature or verification was disabled) — never "failed"."""
+        raw = self.extracted.get("auth")
+        return Auth._from_json(raw) if isinstance(raw, dict) else None
+
     @classmethod
     def _from_json(cls, data: Dict[str, Any]) -> "Message":
         return cls(
@@ -440,6 +549,19 @@ class WebhookDelivery:
         )
 
 
+def _follow_body(
+    url: Optional[str], kind: Optional[str], index: Optional[int]
+) -> Dict[str, Any]:
+    body: Dict[str, Any] = {}
+    if url is not None:
+        body["url"] = url
+    if kind is not None:
+        body["class"] = kind
+    if index is not None:
+        body["index"] = index
+    return body
+
+
 def verify_webhook_signature(
     payload: bytes,
     header: str,
@@ -528,15 +650,21 @@ class PhoneNumber:
     #: active | pending — a pending number becomes active within ~a minute.
     status: str
     created_at: datetime
+    #: Scheduled auto-release: set when a plan downgrade left the account
+    #: over its number cap. Upgrading (or releasing other numbers) before
+    #: this date keeps the number. None = not scheduled.
+    release_after: Optional[datetime] = None
     _client: "MailFixture" = field(repr=False, compare=False, default=None)  # type: ignore[assignment]
 
     @classmethod
     def _from_json(cls, data: Dict[str, Any], client: "MailFixture") -> "PhoneNumber":
+        release_after = data.get("release_after")
         return cls(
             id=data["id"],
             phone_number=data["phone_number"],
             status=data["status"],
             created_at=_parse_dt(data["created_at"]),
+            release_after=_parse_dt(release_after) if release_after else None,
             _client=client,
         )
 
@@ -687,6 +815,29 @@ class MailFixture:
         """Decoded bytes of one attachment (index into `Message.attachments`)."""
         return self._request_raw("GET", f"/v1/messages/{message_id}/attachments/{index}")
 
+    def follow_link(
+        self,
+        message_id: str,
+        url: Optional[str] = None,
+        kind: Optional[str] = None,
+        index: Optional[int] = None,
+    ) -> FollowResult:
+        """Server-side click: the API GETs one of the message's extracted
+        links (redirects followed, body discarded) and reports how the
+        target answered.
+
+        Pass at most one of `url` (exact extracted URL), `kind`
+        (verify | reset | unsubscribe | other; wire name `class`), or
+        `index`. Default: the first verify link.
+        """
+        return FollowResult._from_json(
+            self._request(
+                "POST",
+                f"/v1/messages/{message_id}/links/follow",
+                body=_follow_body(url, kind, index),
+            )
+        )
+
     # -- wait helpers (the point of the SDK) --------------------------------
 
     def wait_for_message(
@@ -827,6 +978,22 @@ class MailFixture:
         data = self._request("GET", f"/v1/sms/{sms_id}/links")
         return [Link._from_json(l) for l in data["links"]]
 
+    def follow_sms_link(
+        self,
+        sms_id: str,
+        url: Optional[str] = None,
+        kind: Optional[str] = None,
+        index: Optional[int] = None,
+    ) -> FollowResult:
+        """`follow_link` for an SMS: same selectors, same result shape."""
+        return FollowResult._from_json(
+            self._request(
+                "POST",
+                f"/v1/sms/{sms_id}/links/follow",
+                body=_follow_body(url, kind, index),
+            )
+        )
+
     def wait_for_sms(
         self,
         phone_number_id: str,

{mailfixture-0.2.0 → mailfixture-0.4.1}/tests/test_client.py

@@ -15,6 +15,7 @@ from mailfixture import (
     MailFixture,
     MailFixtureError,
     MailFixtureTimeout,
+    Message,
     verify_webhook_signature,
 )
 
@@ -50,6 +51,11 @@ MESSAGE_DETAIL = {
         "links": [
             {"url": "https://acme.test/verify?t=abc", "text": "Verify", "class": "verify"}
         ],
+        "auth": {
+            "spf": {"result": "pass", "domain": "acme.test"},
+            "dkim": [{"result": "pass", "domain": "acme.test", "selector": "s1"}],
+            "dmarc": {"result": "pass", "domain": "acme.test", "policy": "reject"},
+        },
     },
     "attachments": [
         {"filename": "report.pdf", "content_type": "application/pdf", "size": 123, "inline": False}
@@ -148,6 +154,22 @@ class Stub(BaseHTTPRequestHandler):
         elif path == f"/v1/webhooks/{WH_ID}/enable":
             self.send_response(204)
             self.end_headers()
+        elif path == f"/v1/messages/{MSG_ID}/links/follow":
+            if body.get("class") == "reset":
+                self._problem(404, "not found",
+                              "no reset link extracted (available classes: verify)")
+            else:
+                self._json(200, {
+                    "requested_url": "https://acme.test/verify?t=abc",
+                    "final_url": "https://acme.test/verified",
+                    "status": 200, "redirects": 1, "ok": True,
+                })
+        elif path == f"/v1/sms/{SMS_ID}/links/follow":
+            self._json(200, {
+                "requested_url": "https://acme.test/verify?t=sms",
+                "final_url": "https://acme.test/verify?t=sms",
+                "status": 200, "redirects": 0, "ok": True,
+            })
         elif path == "/v1/domains":
             self._json(201, {
                 "id": MSG_ID, "fqdn": body["fqdn"], "kind": "custom",
@@ -187,7 +209,8 @@ class Stub(BaseHTTPRequestHandler):
             else:
                 self._json(200, {"messages": [SMS_SUMMARY]})
         elif parsed.path == "/v1/phone-numbers":
-            self._json(200, {"phone_numbers": [PHONE_NUMBER]})
+            scheduled = dict(PHONE_NUMBER, release_after="2026-07-14T00:00:00Z")
+            self._json(200, {"phone_numbers": [scheduled]})
         elif parsed.path == f"/v1/sms/{SMS_ID}":
             self._json(200, SMS_DETAIL)
         elif parsed.path == f"/v1/sms/{SMS_ID}/otp":
@@ -269,6 +292,14 @@ class ClientTest(unittest.TestCase):
         self.assertEqual(message.text_body, "Your code is 482913")
         self.assertEqual(message.attachments[0].filename, "report.pdf")
         self.assertTrue(message.tls)
+        self.assertEqual(message.auth.spf.result, "pass")
+        self.assertEqual(message.auth.dkim[0].selector, "s1")
+        self.assertIsNone(message.auth.dkim[0].error)
+        self.assertEqual(message.auth.dmarc.policy, "reject")
+        # Absent auth key (pre-feature message) reads None, not a failure.
+        no_auth = dict(MESSAGE_DETAIL)
+        no_auth["extracted"] = {"otp": {"best": None, "candidates": []}, "links": []}
+        self.assertIsNone(Message._from_json(no_auth).auth)
         poll_path = next(p for m, p, _ in self.state["requests"] if "/messages?" in p)
         self.assertIn("match=subject%3AAcme", poll_path)
         self.assertIn("wait=5", poll_path)
@@ -301,6 +332,34 @@ class ClientTest(unittest.TestCase):
         data = self.client.download_attachment(MSG_ID, 0)
         self.assertEqual(data, b"%PDF-fake")
 
+    def test_follow_link(self):
+        result = self.client.follow_link(MSG_ID)
+        self.assertTrue(result.ok)
+        self.assertEqual(result.status, 200)
+        self.assertEqual(result.redirects, 1)
+        self.assertEqual(result.final_url, "https://acme.test/verified")
+        method, path, body = self.state["requests"][0]
+        self.assertEqual((method, path), ("POST", f"/v1/messages/{MSG_ID}/links/follow"))
+        self.assertEqual(body, {})
+        # kind= travels as the wire field `class`
+        self.client.follow_link(MSG_ID, kind="verify")
+        self.assertEqual(self.state["requests"][-1][2], {"class": "verify"})
+        self.client.follow_link(MSG_ID, url="https://acme.test/verify?t=abc")
+        self.assertEqual(
+            self.state["requests"][-1][2], {"url": "https://acme.test/verify?t=abc"}
+        )
+
+    def test_follow_link_no_such_class(self):
+        with self.assertRaises(MailFixtureError) as ctx:
+            self.client.follow_link(MSG_ID, kind="reset")
+        self.assertEqual(ctx.exception.status, 404)
+
+    def test_follow_sms_link(self):
+        result = self.client.follow_sms_link(SMS_ID, index=0)
+        self.assertTrue(result.ok)
+        self.assertEqual(result.redirects, 0)
+        self.assertEqual(self.state["requests"][-1][2], {"index": 0})
+
     def test_keys_and_domains(self):
         created = self.client.create_key(label="ci")
         self.assertTrue(created.key.startswith("mfx_"))
@@ -313,6 +372,7 @@ class ClientTest(unittest.TestCase):
         number = self.client.create_phone_number()
         self.assertEqual(number.phone_number, "+15551234567")
         self.assertEqual(number.status, "active")
+        self.assertIsNone(number.release_after)  # absent key = not scheduled
         self.assertEqual(self.state["auth_header"], "Bearer mfx_test")
         method, path, _ = self.state["requests"][0]
         self.assertEqual((method, path), ("POST", "/v1/phone-numbers"))
@@ -321,6 +381,9 @@ class ClientTest(unittest.TestCase):
         numbers = self.client.list_phone_numbers()
         self.assertEqual(len(numbers), 1)
         self.assertEqual(numbers[0].phone_number, "+15551234567")
+        self.assertEqual(
+            numbers[0].release_after.isoformat(), "2026-07-14T00:00:00+00:00"
+        )
         numbers[0].release()
         method, path, _ = self.state["requests"][-1]
         self.assertEqual((method, path), ("DELETE", f"/v1/phone-numbers/{PN_ID}"))