e2a 2.1.0__tar.gz → 2.2.0__tar.gz

{e2a-2.1.0 → e2a-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: e2a
-Version: 2.1.0
+Version: 2.2.0
 Summary: Python SDK for the e2a protocol — email-to-agent authentication
 Project-URL: Homepage, https://e2a.dev
 Project-URL: Repository, https://github.com/Mnexa-AI/e2a
@@ -431,7 +431,7 @@ All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `subject`, `t
 High-level sync client. `api_key` falls back to `E2A_API_KEY` env var.
 
 - `client.parse_webhook(body, secret=None)` → `InboundEmail` — parse + HMAC-verify (recommended for webhook handlers). Reads `E2A_WEBHOOK_SECRET` if no secret is passed; raises `PermissionError` on bad signature.
-- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`. Returns *unverified* — claim fields raise `UnverifiedEmailError` until `email.verify_signature()` succeeds.
+- `client.parse(body)` → `InboundEmail` — *deprecated since 2.2, removed in 3.0.* Accepts bytes, str, dict, or `MessageDetail` and returns an unverified email. Use `parse_webhook` for webhook handlers, or `email.unverified_payload` for inspection without verification. Calling `parse` emits a `DeprecationWarning`.
 - `client.get_message(message_id)` → `InboundEmail` — pre-verified (REST channel auth)
 - `client.get_messages(status="unread", page_size=50)` → `MessageList`
 - `client.reply(message_id, body, ...)` → `SendResult`

{e2a-2.1.0 → e2a-2.2.0}/README.md

@@ -397,7 +397,7 @@ All claim fields (`message_id`, `sender`, `recipient`, `to`, `cc`, `subject`, `t
 High-level sync client. `api_key` falls back to `E2A_API_KEY` env var.
 
 - `client.parse_webhook(body, secret=None)` → `InboundEmail` — parse + HMAC-verify (recommended for webhook handlers). Reads `E2A_WEBHOOK_SECRET` if no secret is passed; raises `PermissionError` on bad signature.
-- `client.parse(body)` → `InboundEmail` — accepts bytes, str, dict, or `MessageDetail`. Returns *unverified* — claim fields raise `UnverifiedEmailError` until `email.verify_signature()` succeeds.
+- `client.parse(body)` → `InboundEmail` — *deprecated since 2.2, removed in 3.0.* Accepts bytes, str, dict, or `MessageDetail` and returns an unverified email. Use `parse_webhook` for webhook handlers, or `email.unverified_payload` for inspection without verification. Calling `parse` emits a `DeprecationWarning`.
 - `client.get_message(message_id)` → `InboundEmail` — pre-verified (REST channel auth)
 - `client.get_messages(status="unread", page_size=50)` → `MessageList`
 - `client.reply(message_id, body, ...)` → `SendResult`

{e2a-2.1.0 → e2a-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "e2a"
-version = "2.1.0"
+version = "2.2.0"
 description = "Python SDK for the e2a protocol — email-to-agent authentication"
 readme = "README.md"
 license = "Apache-2.0"

{e2a-2.1.0 → e2a-2.2.0}/src/e2a/v1/async_client.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import base64
 import json
 import os
+import warnings
 from typing import TYPE_CHECKING, Any, AsyncIterator, Optional
 from urllib.parse import quote
 
@@ -306,13 +307,33 @@ class AsyncE2AClient:
     ) -> AsyncInboundEmail:
         """Parse a webhook payload into an AsyncInboundEmail.
 
+        .. deprecated:: 2.2
+           Use :meth:`parse_webhook` for webhook handlers (parse + verify
+           in one call) or :attr:`AsyncInboundEmail.unverified_payload`
+           for inspection without verification. ``parse`` will be removed
+           in 3.0.
+
         Synchronous (no I/O). The returned email's ``.reply()`` is async.
 
         Returns an *unverified* AsyncInboundEmail — claim fields raise
         :class:`UnverifiedEmailError` until you call
-        :meth:`AsyncInboundEmail.verify_signature`. For webhook handlers,
-        prefer :meth:`parse_webhook` which combines parse + verify.
+        :meth:`AsyncInboundEmail.verify_signature`.
         """
+        warnings.warn(
+            "AsyncE2AClient.parse() is deprecated and will be removed in 3.0. "
+            "For webhook handlers, use client.parse_webhook(body) — it "
+            "parses and HMAC-verifies in one call. For inspection without "
+            "verification, use email.unverified_payload after parse_webhook.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._parse_unverified(body)
+
+    def _parse_unverified(
+        self,
+        body: bytes | str | dict[str, Any] | MessageDetail,
+    ) -> AsyncInboundEmail:
+        """Internal parse without the deprecation warning."""
         if isinstance(body, MessageDetail):
             data = body.model_dump(by_alias=True)
         elif isinstance(body, dict):
@@ -334,7 +355,7 @@ class AsyncE2AClient:
         See :meth:`E2AClient.parse_webhook` — identical contract.
         Synchronous despite living on the async client (no I/O).
         """
-        email = self.parse(body)
+        email = self._parse_unverified(body)
         if not email.verify_signature(secret):
             raise PermissionError("HMAC signature verification failed")
         return email

{e2a-2.1.0 → e2a-2.2.0}/src/e2a/v1/client.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import base64
 import json
 import os
+import warnings
 from typing import Any, Optional
 
 from e2a.v1.api import E2AApi
@@ -92,14 +93,39 @@ class E2AClient:
     ) -> InboundEmail:
         """Parse a webhook payload or MessageDetail into an InboundEmail.
 
+        .. deprecated:: 2.2
+           Use :meth:`parse_webhook` for webhook handlers (parse + verify
+           in one call) or :attr:`InboundEmail.unverified_payload` for
+           inspection without verification. ``parse`` will be removed in
+           3.0.
+
         Accepts bytes, JSON string, dict, or a generated MessageDetail.
 
         The returned InboundEmail starts in the *unverified* state —
-        property accesses (sender, subject, body, …) will raise
-        :class:`UnverifiedEmailError` until you call
-        :meth:`InboundEmail.verify_signature`. For webhook handlers,
-        prefer :meth:`parse_webhook` which combines parse + verify.
+        property accesses (sender, subject, body, …) raise
+        :class:`UnverifiedEmailError` until :meth:`InboundEmail.verify_signature`
+        succeeds. The combination of "looks usable" + "blows up on first
+        field access" is precisely the trap that motivated the deprecation;
+        ``parse_webhook`` raises immediately on bad signatures and returns
+        a ready-to-use object on success.
         """
+        warnings.warn(
+            "E2AClient.parse() is deprecated and will be removed in 3.0. "
+            "For webhook handlers, use client.parse_webhook(body) — it "
+            "parses and HMAC-verifies in one call. For inspection without "
+            "verification, use email.unverified_payload after parse_webhook.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._parse_unverified(body)
+
+    def _parse_unverified(
+        self,
+        body: bytes | str | dict[str, Any] | MessageDetail,
+    ) -> InboundEmail:
+        """Internal parse without the deprecation warning. ``parse_webhook``
+        delegates here so the recommended path doesn't emit the warning
+        meant for direct ``parse`` callers."""
         if isinstance(body, MessageDetail):
             data = body.model_dump(by_alias=True)
         elif isinstance(body, dict):
@@ -126,7 +152,7 @@ class E2AClient:
         ``secret`` defaults to the ``E2A_WEBHOOK_SECRET`` environment
         variable (with ``E2A_HMAC_SECRET`` accepted as a deprecated alias).
         """
-        email = self.parse(body)
+        email = self._parse_unverified(body)
         if not email.verify_signature(secret):
             raise PermissionError("HMAC signature verification failed")
         return email

{e2a-2.1.0 → e2a-2.2.0}/src/e2a/v1/handler.py

@@ -344,11 +344,14 @@ class InboundEmail:
 
         ``secret`` defaults to the ``E2A_WEBHOOK_SECRET`` environment
         variable when omitted (with ``E2A_HMAC_SECRET`` accepted as a
-        deprecated alias), so the standard webhook-handler pattern is::
-
-            email = client.parse(body)
-            if not email.verify_signature():
-                return 401
+        deprecated alias).
+
+        Most webhook handlers should use :meth:`E2AClient.parse_webhook`
+        instead — it calls ``verify_signature`` internally and raises
+        ``PermissionError`` on failure, so the handler reads as one
+        concise call. Use ``verify_signature`` directly only when you
+        need to inspect ``unverified_payload`` first or have some other
+        reason to keep the unverified object around.
 
         Checks (in order):
 

{e2a-2.1.0 → e2a-2.2.0}/tests/test_v1_async_client.py

@@ -121,6 +121,36 @@ async def test_parse_unsupported_type():
             client.parse(12345)
 
 
+@pytest.mark.anyio
+async def test_parse_emits_deprecation_warning():
+    """Mirror of the sync test — async client's `parse` must also emit
+    the deprecation warning so async webhook handlers see the same
+    migration signal."""
+    webhook = _make_message_detail_json()
+    async with AsyncE2AClient(api_key="k", agent_email="bot@agents.e2a.dev") as client:
+        with pytest.warns(DeprecationWarning, match="parse_webhook"):
+            client.parse(webhook)
+
+
+@pytest.mark.anyio
+async def test_parse_webhook_does_not_emit_deprecation_warning(monkeypatch):
+    """Same regression guard as the sync test — `parse_webhook` must not
+    surface the deprecation warning meant for direct `parse` callers."""
+    import warnings
+
+    monkeypatch.setenv("E2A_WEBHOOK_SECRET", "secret-xyz")
+    webhook = _make_message_detail_json()
+    async with AsyncE2AClient(api_key="k", agent_email="bot@agents.e2a.dev") as client:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            try:
+                client.parse_webhook(webhook)
+            except DeprecationWarning:
+                pytest.fail("parse_webhook should not emit DeprecationWarning")
+            except PermissionError:
+                pass
+
+
 # ── get_message() ────────────────────────────────────────────────
 
 

{e2a-2.1.0 → e2a-2.2.0}/tests/test_v1_client.py

@@ -116,6 +116,40 @@ def test_parse_unsupported_type():
             client.parse(12345)
 
 
+def test_parse_emits_deprecation_warning():
+    """Calling the legacy `parse` method on the sync client emits a
+    DeprecationWarning that points users at parse_webhook. Pin the
+    deprecation contract so it isn't silently dropped before 3.0."""
+    webhook = _make_message_detail_json()
+    with E2AClient(api_key="k", agent_email="bot@agents.e2a.dev") as client:
+        with pytest.warns(DeprecationWarning, match="parse_webhook"):
+            client.parse(webhook)
+
+
+def test_parse_webhook_does_not_emit_deprecation_warning(monkeypatch):
+    """The recommended path must not emit the deprecation warning even
+    though it shares the underlying parse logic. Regression: an early
+    refactor had parse_webhook delegate to parse(), which made every
+    correct caller see the deprecation message."""
+    import warnings
+
+    monkeypatch.setenv("E2A_WEBHOOK_SECRET", "secret-xyz")
+    webhook = _make_message_detail_json()
+    with E2AClient(api_key="k", agent_email="bot@agents.e2a.dev") as client:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error")
+            try:
+                client.parse_webhook(webhook)
+            except DeprecationWarning:
+                pytest.fail("parse_webhook should not emit DeprecationWarning")
+            except PermissionError:
+                # Expected — fixture body has no real signature, so
+                # verify_signature returns False and parse_webhook raises.
+                # The point of this test is the absence of DeprecationWarning,
+                # which we'd have hit before the PermissionError if present.
+                pass
+
+
 # ── get_message() ────────────────────────────────────────────────