mailfixture 0.5.0__tar.gz → 0.6.2__tar.gz

{mailfixture-0.5.0 → mailfixture-0.6.2}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 MailFixture, Inc.
+Copyright (c) 2026 Foundry86 LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

mailfixture-0.5.0/README.md → mailfixture-0.6.2/PKG-INFO

@@ -1,3 +1,21 @@
+Metadata-Version: 2.5
+Name: mailfixture
+Version: 0.6.2
+Summary: Email, SMS, and webhook fixtures for test suites — programmatic inboxes, capture hooks, long-polling, and OTP extraction.
+Project-URL: Homepage, https://mailfixture.com
+Project-URL: Documentation, https://mailfixture.com/docs
+Author-email: MailFixture <support@mailfixture.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: e2e,email,fixtures,otp,playwright,pytest,sms,testing,webhook,webhook-capture,webhook-testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
 # mailfixture
 
 Email fixtures for your test suite. Create a programmatic inbox in one call,
@@ -39,6 +57,17 @@ link = inbox.wait_for_link(kind="verify", timeout=30)
 page.goto(link.url)
 ```
 
+Capturing a webhook your app sends:
+
+```python
+hook = mfx.create_hook(label="checkout", ttl_seconds=900)
+configure_app_webhook(hook.ingest_url)  # your test setup
+trigger_checkout()
+request = hook.wait_for_request(match="body:order.created")
+assert request.method == "POST"
+hook.delete()
+```
+
 Everything on the wait helpers is server-side long-polling: the request is
 held open until a matching message arrives (or the timeout passes, raising
 `mailfixture.MailFixtureTimeout`).
@@ -54,12 +83,19 @@ held open until a matching message arrives (or the timeout passes, raising
 | `inbox.messages(since=, match=, wait=)` / `clear()` / `delete()` | raw listing & lifecycle |
 | `get_message(id)`, `get_otp(id)`, `get_links(id)` | direct message access |
 | `download_attachment(message_id, index)` | decoded attachment bytes |
+| `create_hook(label=, ttl_seconds=)`, `list_hooks()` | webhook capture URL and lifecycle handles |
+| `hook.wait_for_request(match=, since=, timeout=)` | first matching captured request, including full headers and body |
+| `hook.requests(...)`, `clear()`, `delete()` / `get_hook_request(id)` | capture listing, teardown, and direct detail access |
 | `create_domain(fqdn)`, `verify_domain(id)`, `list_domains()`, `delete_domain(id)` | custom domains |
 | `create_key(label=)`, `list_keys()`, `revoke_key(id)` | API keys |
 
 `match` filters with `subject:`, `from:`, or `to:` prefixes; a bare term
 matches the subject.
 
+Capture-hook matching accepts `method:`, `path:`, and `body:`; a bare term
+matches the first 32 KiB of request body bytes. Returned detail bodies are
+complete.
+
 Errors are raised as `mailfixture.MailFixtureError` carrying the API's
 RFC 7807 `status` / `title` / `detail` fields.
 

mailfixture-0.5.0/PKG-INFO → mailfixture-0.6.2/README.md

@@ -1,21 +1,3 @@
-Metadata-Version: 2.4
-Name: mailfixture
-Version: 0.5.0
-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
-Author-email: MailFixture <support@mailfixture.com>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: e2e,email,fixtures,otp,playwright,pytest,testing
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development :: Testing
-Classifier: Typing :: Typed
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
 # mailfixture
 
 Email fixtures for your test suite. Create a programmatic inbox in one call,
@@ -57,6 +39,17 @@ link = inbox.wait_for_link(kind="verify", timeout=30)
 page.goto(link.url)
 ```
 
+Capturing a webhook your app sends:
+
+```python
+hook = mfx.create_hook(label="checkout", ttl_seconds=900)
+configure_app_webhook(hook.ingest_url)  # your test setup
+trigger_checkout()
+request = hook.wait_for_request(match="body:order.created")
+assert request.method == "POST"
+hook.delete()
+```
+
 Everything on the wait helpers is server-side long-polling: the request is
 held open until a matching message arrives (or the timeout passes, raising
 `mailfixture.MailFixtureTimeout`).
@@ -72,12 +65,19 @@ held open until a matching message arrives (or the timeout passes, raising
 | `inbox.messages(since=, match=, wait=)` / `clear()` / `delete()` | raw listing & lifecycle |
 | `get_message(id)`, `get_otp(id)`, `get_links(id)` | direct message access |
 | `download_attachment(message_id, index)` | decoded attachment bytes |
+| `create_hook(label=, ttl_seconds=)`, `list_hooks()` | webhook capture URL and lifecycle handles |
+| `hook.wait_for_request(match=, since=, timeout=)` | first matching captured request, including full headers and body |
+| `hook.requests(...)`, `clear()`, `delete()` / `get_hook_request(id)` | capture listing, teardown, and direct detail access |
 | `create_domain(fqdn)`, `verify_domain(id)`, `list_domains()`, `delete_domain(id)` | custom domains |
 | `create_key(label=)`, `list_keys()`, `revoke_key(id)` | API keys |
 
 `match` filters with `subject:`, `from:`, or `to:` prefixes; a bare term
 matches the subject.
 
+Capture-hook matching accepts `method:`, `path:`, and `body:`; a bare term
+matches the first 32 KiB of request body bytes. Returned detail bodies are
+complete.
+
 Errors are raised as `mailfixture.MailFixtureError` carrying the API's
 RFC 7807 `status` / `title` / `detail` fields.
 

{mailfixture-0.5.0 → mailfixture-0.6.2}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mailfixture"
-version = "0.5.0"
-description = "Email fixtures for your test suite — programmatic inboxes, long-polling, first-class OTP and link extraction."
+version = "0.6.2"
+description = "Email, SMS, and webhook fixtures for test suites — programmatic inboxes, capture hooks, long-polling, and OTP extraction."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.9"
 authors = [{ name = "MailFixture", email = "support@mailfixture.com" }]
-keywords = ["email", "testing", "otp", "fixtures", "e2e", "playwright", "pytest"]
+keywords = ["email", "webhook", "webhook-testing", "webhook-capture", "sms", "testing", "otp", "fixtures", "e2e", "playwright", "pytest"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",

{mailfixture-0.5.0 → mailfixture-0.6.2}/src/mailfixture/__init__.py

@@ -17,6 +17,7 @@ to tune and no flaky retry loop.
 
 from __future__ import annotations
 
+import base64
 import hashlib
 import hmac
 import json
@@ -39,6 +40,10 @@ __all__ = [
     "PhoneNumber",
     "Sms",
     "SmsSummary",
+    "Hook",
+    "HookHeader",
+    "HookRequest",
+    "HookRequestSummary",
     "Otp",
     "OtpCandidate",
     "Link",
@@ -62,7 +67,7 @@ __all__ = [
     "MailFixtureTimeout",
 ]
 
-__version__ = "0.5.0"
+__version__ = "0.6.2"
 
 DEFAULT_BASE_URL = "https://api.mailfixture.com"
 #: Server-side ceiling for one long-poll request; the client chains
@@ -325,7 +330,10 @@ class Message:
     subject: Optional[str]
     text_body: Optional[str]
     html_body: Optional[str]
-    headers: Dict[str, Any]
+    #: Every header in wire order as ``{"name": ..., "value": ...}`` dicts
+    #: (original casing, folded lines unfolded; names can repeat, e.g.
+    #: ``Received``) — look them up case-insensitively.
+    headers: List[Dict[str, str]]
     extracted: Dict[str, Any]
     attachments: List[Attachment]
     raw_size: int
@@ -368,7 +376,7 @@ class Message:
             subject=data.get("subject"),
             text_body=data.get("text_body"),
             html_body=data.get("html_body"),
-            headers=data.get("headers") or {},
+            headers=list(data.get("headers") or []),
             extracted=data.get("extracted") or {},
             attachments=[
                 Attachment(
@@ -444,6 +452,92 @@ class Sms:
         )
 
 
+@dataclass
+class HookRequestSummary:
+    """One request captured by a hook — metadata only; the body rides on
+    `HookRequest` (fetch it with `get_hook_request`)."""
+
+    id: str
+    hook_id: str
+    received_at: datetime
+    #: Uppercased HTTP verb as received.
+    method: str
+    #: Path + query after the token; "/" when the bare ingest URL was hit.
+    path: str
+    content_type: Optional[str]
+    body_size: int
+    #: Wire-format timestamp, used verbatim as the next `since` cursor.
+    received_at_raw: str = field(repr=False, default="")
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "HookRequestSummary":
+        return cls(
+            id=data["id"],
+            hook_id=data["hook_id"],
+            received_at=_parse_dt(data["received_at"]),
+            method=data["method"],
+            path=data["path"],
+            content_type=data.get("content_type"),
+            body_size=data["body_size"],
+            received_at_raw=data["received_at"],
+        )
+
+
+@dataclass
+class HookHeader:
+    name: str
+    value: str
+
+
+@dataclass
+class HookRequest:
+    """A captured request in full: headers and body. Header names are
+    lowercased; duplicate values of one name keep their order, but the
+    relative order of different names is not preserved — don't assert
+    on it. `body` is the text rendering; when `body_is_utf8` is False
+    use `body_bytes` (decoded from `body_base64`) for the exact
+    bytes — signature checks need them."""
+
+    id: str
+    hook_id: str
+    received_at: datetime
+    method: str
+    path: str
+    headers: List[HookHeader]
+    content_type: Optional[str]
+    body: str
+    body_base64: Optional[str]
+    body_is_utf8: bool
+    body_size: int
+    remote_ip: Optional[str]
+    expires_at: datetime
+
+    @property
+    def body_bytes(self) -> bytes:
+        """Exact body bytes (decodes `body_base64` when present)."""
+        if self.body_base64 is not None:
+            return base64.b64decode(self.body_base64)
+        return self.body.encode("utf-8")
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> "HookRequest":
+        return cls(
+            id=data["id"],
+            hook_id=data["hook_id"],
+            received_at=_parse_dt(data["received_at"]),
+            method=data["method"],
+            path=data["path"],
+            headers=[HookHeader(h["name"], h["value"]) for h in data.get("headers", [])],
+            content_type=data.get("content_type"),
+            body=data["body"],
+            body_base64=data.get("body_base64"),
+            body_is_utf8=data["body_is_utf8"],
+            body_size=data["body_size"],
+            remote_ip=data.get("remote_ip"),
+            expires_at=_parse_dt(data["expires_at"]),
+        )
+
+
 @dataclass
 class InboxSummary:
     id: str
@@ -747,6 +841,63 @@ class PhoneNumber:
         self._client.release_phone_number(self.id)
 
 
+@dataclass
+class Hook:
+    """A capture hook (webhook capture) plus the wait helper bound to it.
+
+    Point the app-under-test's webhook config at `ingest_url`, then
+    `wait_for_request()` to assert the webhook fired. Not to be confused
+    with the outbound `Webhook` resource (signed event delivery).
+    """
+
+    id: str
+    #: The public URL to configure in the app under test.
+    ingest_url: str
+    #: Write capability embedded in the URL — treat like a secret.
+    token: str
+    label: Optional[str]
+    ttl_expires_at: Optional[datetime]
+    created_at: datetime
+    _client: "MailFixture" = field(repr=False, compare=False, default=None)  # type: ignore[assignment]
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any], client: "MailFixture") -> "Hook":
+        ttl = data.get("ttl_expires_at")
+        return cls(
+            id=data["id"],
+            ingest_url=data["ingest_url"],
+            token=data["token"],
+            label=data.get("label"),
+            ttl_expires_at=_parse_dt(ttl) if ttl else None,
+            created_at=_parse_dt(data["created_at"]),
+            _client=client,
+        )
+
+    def requests(
+        self,
+        since: Optional[str] = None,
+        match: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> List[HookRequestSummary]:
+        return self._client.list_hook_requests(self.id, since=since, match=match, wait=wait)
+
+    def wait_for_request(
+        self,
+        match: Optional[str] = None,
+        since: Optional[str] = None,
+        timeout: float = 45.0,
+    ) -> HookRequest:
+        return self._client.wait_for_hook_request(
+            self.id, match=match, since=since, timeout=timeout
+        )
+
+    def clear(self) -> None:
+        self._client.clear_hook(self.id)
+
+    def delete(self) -> None:
+        self._client.delete_hook(self.id)
+
+
 class MailFixture:
     """Synchronous MailFixture API client.
 
@@ -952,23 +1103,30 @@ class MailFixture:
             if not summaries and deadline - time.monotonic() <= 0:
                 return
 
-    def _poll(
-        self,
-        inbox_id: str,
-        since: Optional[str],
-        match: Optional[str],
-        remaining: float,
-    ) -> List[MessageSummary]:
-        """One long-poll chunk, rate-limit aware."""
+    def _poll_chunk(self, list_page, since, match, remaining):
+        """One long-poll chunk, rate-limit aware — the single body behind
+        every wait surface (messages, SMS, hook requests), so the server-
+        wait clamp and 429/Retry-After absorption cannot drift."""
         wait = max(0, min(math.ceil(remaining), MAX_SERVER_WAIT))
         try:
-            return self.list_messages(inbox_id, since=since, match=match, wait=wait)
+            return list_page(since=since, match=match, wait=wait)
         except MailFixtureError as err:
             if err.status == 429 and err.retry_after and err.retry_after < remaining:
                 time.sleep(err.retry_after)
                 return []
             raise
 
+    def _poll(
+        self,
+        inbox_id: str,
+        since: Optional[str],
+        match: Optional[str],
+        remaining: float,
+    ) -> List[MessageSummary]:
+        return self._poll_chunk(
+            lambda **kw: self.list_messages(inbox_id, **kw), since, match, remaining
+        )
+
     # -- phone numbers (paid plans) ------------------------------------------
 
     def create_phone_number(self) -> PhoneNumber:
@@ -1106,15 +1264,108 @@ class MailFixture:
         match: Optional[str],
         remaining: float,
     ) -> List[SmsSummary]:
-        """One long-poll chunk, rate-limit aware."""
-        wait = max(0, min(math.ceil(remaining), MAX_SERVER_WAIT))
-        try:
-            return self.list_sms(phone_number_id, since=since, match=match, wait=wait)
-        except MailFixtureError as err:
-            if err.status == 429 and err.retry_after and err.retry_after < remaining:
-                time.sleep(err.retry_after)
-                return []
-            raise
+        """One long-poll chunk over SMS — see `_poll_chunk`."""
+        return self._poll_chunk(
+            lambda **kw: self.list_sms(phone_number_id, **kw), since, match, remaining
+        )
+
+    # -- capture hooks -------------------------------------------------------
+
+    def create_hook(
+        self,
+        label: Optional[str] = None,
+        ttl_seconds: Optional[int] = None,
+    ) -> Hook:
+        """Create a capture hook (webhook capture): a public URL that
+        records every HTTP request sent to it and always answers
+        `200 {"ok":true}`. Point the app under test's webhook config at
+        `hook.ingest_url`."""
+        body: Dict[str, Any] = {}
+        if label is not None:
+            body["label"] = label
+        if ttl_seconds is not None:
+            body["ttl_seconds"] = ttl_seconds
+        data = self._request("POST", "/v1/hooks", body=body)
+        return Hook._from_json(data, self)
+
+    def list_hooks(self) -> List[Hook]:
+        data = self._request("GET", "/v1/hooks")
+        return [Hook._from_json(h, self) for h in data["hooks"]]
+
+    def delete_hook(self, hook_id: str) -> None:
+        """Delete the hook and its captured requests; the URL 404s after."""
+        self._request("DELETE", f"/v1/hooks/{hook_id}")
+
+    def clear_hook(self, hook_id: str) -> None:
+        """Drop captured requests but keep the hook — rerun hygiene."""
+        self._request("POST", f"/v1/hooks/{hook_id}/clear")
+
+    def list_hook_requests(
+        self,
+        hook_id: str,
+        since: Optional[str] = None,
+        match: Optional[str] = None,
+        wait: Optional[int] = None,
+    ) -> List[HookRequestSummary]:
+        """List a hook's captured requests, oldest first.
+
+        `match` filters with `method:` (exact verb, case-insensitive),
+        `path:` or `body:` prefixes (substring; a bare term matches the
+        body). Body matching scans the first 32 KiB; detail bodies remain
+        complete. `wait` long-polls up to that many seconds (server ceiling
+        60) until a matching request arrives."""
+        params: Dict[str, str] = {}
+        if since is not None:
+            params["since"] = since
+        if match is not None:
+            params["match"] = match
+        if wait is not None:
+            params["wait"] = str(wait)
+        data = self._request(
+            "GET",
+            f"/v1/hooks/{hook_id}/requests",
+            params=params,
+            read_timeout=(wait or 0) + 15,
+        )
+        return [HookRequestSummary._from_json(r) for r in data["requests"]]
+
+    def get_hook_request(self, request_id: str) -> HookRequest:
+        return HookRequest._from_json(
+            self._request("GET", f"/v1/hook-requests/{request_id}")
+        )
+
+    def wait_for_hook_request(
+        self,
+        hook_id: str,
+        match: Optional[str] = None,
+        since: Optional[str] = None,
+        timeout: float = 45.0,
+    ) -> HookRequest:
+        """Long-poll until a matching request is captured; returns the
+        full detail. Raises `MailFixtureTimeout` after `timeout` seconds."""
+        deadline = time.monotonic() + timeout
+        cursor = since
+        while True:
+            remaining = deadline - time.monotonic()
+            summaries = self._poll_hook_requests(hook_id, cursor, match, remaining)
+            if summaries:
+                return self.get_hook_request(summaries[0].id)
+            if deadline - time.monotonic() <= 0:
+                raise MailFixtureTimeout(
+                    f"no captured request matching {match!r} within {timeout}s"
+                )
+
+    def _poll_hook_requests(
+        self,
+        hook_id: str,
+        since: Optional[str],
+        match: Optional[str],
+        remaining: float,
+    ) -> List[HookRequestSummary]:
+        """One long-poll chunk over captured requests — see `_poll_chunk`."""
+        return self._poll_chunk(
+            lambda **kw: self.list_hook_requests(hook_id, **kw), since, match, remaining
+        )
 
     # -- domains -----------------------------------------------------------
 

{mailfixture-0.5.0 → mailfixture-0.6.2}/tests/test_client.py

@@ -45,7 +45,11 @@ MESSAGE_DETAIL = {
     "inbox_id": INBOX_ID,
     "text_body": "Your code is 482913",
     "html_body": None,
-    "headers": {"message-id": "<1@acme.test>"},
+    "headers": [
+        {"name": "Received", "value": "from mx1.acme.test"},
+        {"name": "Received", "value": "from mx2.acme.test"},
+        {"name": "Message-ID", "value": "<1@acme.test>"},
+    ],
     "extracted": {
         "otp": {"best": "482913", "candidates": [{"value": "482913", "score": 9.5}]},
         "links": [
@@ -107,6 +111,56 @@ SMS_DETAIL = {
     "expires_at": "2026-07-08T12:00:09Z",
 }
 
+HOOK_ID = "7c9e1f3a-5b6d-4e2f-8a0b-1c3d5e7f9a0c"
+HOOK_REQ_ID = "2d4f6a8b-0c1d-4e3f-9a5b-6c8d0e2f4a6d"
+HOOK = {
+    "id": HOOK_ID,
+    "token": "tokentokentokentokentokentoken12",
+    "ingest_url": "https://hook.mxsink.sh/tokentokentokentokentokentoken12",
+    "label": "checkout",
+    "ttl_expires_at": None,
+    "created_at": T0,
+}
+HOOK_REQ_SUMMARY = {
+    "id": HOOK_REQ_ID,
+    "hook_id": HOOK_ID,
+    "received_at": SMS_T2,
+    "method": "POST",
+    "path": "/?src=stripe",
+    "content_type": "application/json",
+    "body_size": 8,  # b"bin\x00data" is 8 bytes — the stub stays wire-honest
+}
+# A plain-text capture: body_is_utf8 True and NO body_base64 key on the
+# wire (the server omits it for valid UTF-8 bodies).
+HOOK_REQ_TEXT_ID = "3e5a7c9d-1f2a-4b6c-8d0e-2f4a6c8e0b1d"
+HOOK_REQ_TEXT_DETAIL = {
+    "id": HOOK_REQ_TEXT_ID,
+    "hook_id": HOOK_ID,
+    "received_at": SMS_T2,
+    "method": "POST",
+    "path": "/",
+    "content_type": "application/json",
+    "body_size": 16,
+    "headers": [],
+    "body": '{"event":"paid"}',
+    "body_is_utf8": True,
+    "remote_ip": None,
+    "expires_at": "2026-07-08T12:00:09Z",
+}
+HOOK_REQ_DETAIL = {
+    **HOOK_REQ_SUMMARY,
+    "headers": [
+        {"name": "content-type", "value": "application/json"},
+        {"name": "x-sig", "value": "one"},
+        {"name": "x-sig", "value": "two"},
+    ],
+    "body": "bin�data",
+    "body_base64": "YmluAGRhdGE=",
+    "body_is_utf8": False,
+    "remote_ip": "203.0.113.9",
+    "expires_at": "2026-07-08T12:00:09Z",
+}
+
 
 class Stub(BaseHTTPRequestHandler):
     # Per-server-instance state, reset by each test via make_server().
@@ -158,6 +212,12 @@ class Stub(BaseHTTPRequestHandler):
                 self._problem(403, "forbidden", "phone numbers require a paid plan")
             else:
                 self._json(201, PHONE_NUMBER)
+        elif path == "/v1/hooks":
+            self.state["hook_create_body"] = body
+            self._json(201, HOOK)
+        elif path == f"/v1/hooks/{HOOK_ID}/clear":
+            self.send_response(204)
+            self.end_headers()
         elif path == f"/v1/webhooks/{WH_ID}/test":
             self._json(202, {"delivery_id": WH_DELIVERY_ID})
         elif path == f"/v1/webhooks/{WH_ID}/enable":
@@ -247,6 +307,21 @@ class Stub(BaseHTTPRequestHandler):
                 "last_status_code": 200, "last_error": None,
                 "created_at": T0, "delivered_at": T1,
             }]})
+        elif parsed.path == "/v1/hooks":
+            self._json(200, {"hooks": [HOOK]})
+        elif parsed.path == f"/v1/hooks/{HOOK_ID}/requests":
+            polls = self.state.setdefault("hook_polls", 0)
+            self.state["hook_polls"] += 1
+            if self.state.get("hook_rate_limit_first") and polls == 0:
+                self._problem(429, "too many requests", "slow down", {"Retry-After": "1"})
+            elif polls < self.state.get("deliver_hook_on_poll", 0):
+                self._json(200, {"requests": []})
+            else:
+                self._json(200, {"requests": [HOOK_REQ_SUMMARY]})
+        elif parsed.path == f"/v1/hook-requests/{HOOK_REQ_ID}":
+            self._json(200, HOOK_REQ_DETAIL)
+        elif parsed.path == f"/v1/hook-requests/{HOOK_REQ_TEXT_ID}":
+            self._json(200, HOOK_REQ_TEXT_DETAIL)
         elif parsed.path == f"/v1/messages/{MSG_ID}/attachments/0":
             self.send_response(200)
             self.send_header("Content-Type", "application/octet-stream")
@@ -261,6 +336,23 @@ class Stub(BaseHTTPRequestHandler):
         self.end_headers()
 
 
+class VersionLockstepTest(unittest.TestCase):
+    def test_dunder_version_matches_pyproject(self):
+        # pyproject.toml once shipped stuck at 0.2.0 while __version__ said
+        # 0.3.0 (and the JS SDK repeated the class of bug at 0.4.1/0.5.0);
+        # this pins the two so `just sdk-test` fails when a bump misses one.
+        # Regex over tomllib: the SDK supports 3.9+, tomllib is 3.11+.
+        import pathlib
+        import re
+
+        import mailfixture
+
+        pyproject = pathlib.Path(__file__).resolve().parent.parent / "pyproject.toml"
+        match = re.search(r'^version = "([^"]+)"$', pyproject.read_text(), re.M)
+        assert match, "no version line found in pyproject.toml"
+        self.assertEqual(mailfixture.__version__, match.group(1))
+
+
 class ClientTest(unittest.TestCase):
     def setUp(self):
         state = {"requests": [], "polls": 0, "sms_polls": 0}
@@ -299,6 +391,12 @@ class ClientTest(unittest.TestCase):
         message = self.client.wait_for_message(INBOX_ID, match="subject:Acme", timeout=5)
         self.assertEqual(message.otp, "482913")
         self.assertEqual(message.text_body, "Your code is 482913")
+        # headers: the wire's ordered [{name, value}] list, dupes kept
+        self.assertIsInstance(message.headers, list)
+        self.assertEqual(message.headers[2], {"name": "Message-ID", "value": "<1@acme.test>"})
+        self.assertEqual(
+            len([h for h in message.headers if h["name"].lower() == "received"]), 2
+        )
         self.assertEqual(message.attachments[0].filename, "report.pdf")
         self.assertTrue(message.tls)
         self.assertEqual(message.auth.spf.result, "pass")
@@ -466,6 +564,78 @@ class ClientTest(unittest.TestCase):
         self.client.delete_webhook(created.id)
         self.assertEqual(self.state["requests"][-1][0], "DELETE")
 
+    def test_create_hook_sends_snake_case_body(self):
+        hook = self.client.create_hook(label="checkout", ttl_seconds=900)
+        self.assertEqual(hook.id, HOOK_ID)
+        self.assertEqual(hook.ingest_url, HOOK["ingest_url"])
+        self.assertEqual(
+            self.state["hook_create_body"], {"label": "checkout", "ttl_seconds": 900}
+        )
+
+    def test_wait_for_hook_request_survives_empty_polls(self):
+        self.state["deliver_hook_on_poll"] = 2
+        hook = self.client.create_hook()
+        req = hook.wait_for_request(match="method:POST", timeout=10)
+        self.assertEqual(req.id, HOOK_REQ_ID)
+        self.assertEqual(req.method, "POST")
+        self.assertEqual(req.path, "/?src=stripe")
+        # binary body: lossy text + exact bytes via body_base64
+        self.assertFalse(req.body_is_utf8)
+        self.assertEqual(req.body_bytes, b"bin\x00data")
+        # duplicates preserved in header order
+        self.assertEqual(
+            [h.value for h in req.headers if h.name == "x-sig"], ["one", "two"]
+        )
+
+    def test_hook_list_requests_clear_delete(self):
+        hooks = self.client.list_hooks()
+        self.assertEqual(hooks[0].id, HOOK_ID)
+        requests = hooks[0].requests()
+        self.assertEqual(requests[0].hook_id, HOOK_ID)
+        self.assertEqual(requests[0].body_size, 8)
+        hooks[0].clear()
+        hooks[0].delete()
+        calls = [(m, urlparse(p).path) for m, p, _ in self.state["requests"]]
+        self.assertIn(("POST", f"/v1/hooks/{HOOK_ID}/clear"), calls)
+        self.assertIn(("DELETE", f"/v1/hooks/{HOOK_ID}"), calls)
+
+    def test_hook_wait_absorbs_429_mid_wait(self):
+        # The hook poll path is its own lambda into _poll_chunk; the
+        # email-path 429 test proves nothing about it.
+        self.state["hook_rate_limit_first"] = True
+        req = self.client.wait_for_hook_request(HOOK_ID, timeout=10)
+        self.assertEqual(req.id, HOOK_REQ_ID)
+        self.assertGreaterEqual(self.state["hook_polls"], 2)
+
+    def test_hook_wait_sends_wire_params(self):
+        self.client.wait_for_hook_request(
+            HOOK_ID, match="method:POST", since=SMS_T1, timeout=10
+        )
+        polls = [
+            parse_qs(urlparse(p).query)
+            for m, p, _ in self.state["requests"]
+            if urlparse(p).path == f"/v1/hooks/{HOOK_ID}/requests"
+        ]
+        self.assertGreaterEqual(len(polls), 1)
+        for params in polls:
+            self.assertEqual(params["match"], ["method:POST"])
+            self.assertEqual(params["since"], [SMS_T1])
+            self.assertTrue(0 < int(params["wait"][0]) <= 60)
+
+    def test_hook_wait_times_out(self):
+        self.state["deliver_hook_on_poll"] = 10**9
+        with self.assertRaises(MailFixtureTimeout):
+            self.client.wait_for_hook_request(HOOK_ID, timeout=0.3)
+
+    def test_hook_body_bytes_utf8_branch(self):
+        # The binary branch is pinned by the wait test; this is the encode
+        # path: a valid-UTF-8 body has no body_base64 and body_bytes must
+        # be the exact UTF-8 encoding.
+        req = self.client.get_hook_request(HOOK_REQ_TEXT_ID)
+        self.assertTrue(req.body_is_utf8)
+        self.assertIsNone(req.body_base64)
+        self.assertEqual(req.body_bytes, b'{"event":"paid"}')
+
     def test_verify_webhook_signature(self):
         import hashlib
         import hmac as hmac_mod