e2a 2.3.0__tar.gz → 2.5.0__tar.gz

{e2a-2.3.0 → e2a-2.5.0}/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 2.5.0
+
+### Added
+- Generated types for the per-user resource-limits primitive that
+  shipped with #158: `LimitsInfo`, `LimitsCaps`, `LimitsUsage`. These
+  describe the response shape of `GET /api/v1/users/me/limits`, which
+  the hosted dashboard uses to render the upgrade affordance and the
+  "you've used X of Y" surface. The high-level `E2AClient` doesn't
+  yet expose a typed helper for this endpoint — it's surfaced as a
+  dashboard-only concern today, and SDK consumers querying their own
+  usage should call `/agents` / `/messages` directly. The types are
+  emitted so anyone consuming the raw OpenAPI generation has the
+  shapes available.
+
+### Notes
+- No runtime client behavior changed in this release. If you're not
+  using the limits primitive (self-host deployments without a paid
+  tier), 2.5.0 is functionally identical to 2.4.0.
+
+## 2.4.0
+
+### Added
+- `idempotency_key` parameter on `E2AClient.approve_message()` and its
+  async counterpart (and on the lower-level `E2AApi.approve_message()`).
+  Approve fires a real SES send, so without a stable key a retry after
+  a transient failure could double-send. When supplied it's threaded
+  through as the `Idempotency-Key` header; when omitted the SDK mints
+  a fresh UUIDv4 per call — that gives network-layer retry safety only.
+  Supply a stable key derived from the review event (typically the
+  pending `message_id`) to dedupe across an explicit retry loop.
+- `sort`, `from_`, `subject_contains`, `conversation_id`, `since`,
+  `until` kwargs on `E2AApi.list_messages()` and the high-level
+  `E2AClient.get_messages()` (sync + async). `sort` defaults
+  server-side to newest-first; pass `"asc"` for FIFO polling. The
+  substring filters are case-insensitive and capped at 200 chars
+  server-side. `since` / `until` accept RFC3339 timestamps and
+  bracket `created_at`. Filter values are encoded into `next_token`,
+  so continuation requests must keep the same filter values.
+
+### Changed
+- **Default sort flipped to newest-first** on `GET /messages`. Prior
+  releases silently returned oldest-first for `direction=inbound` (the
+  SDK default) and newest-first for `direction=all`. A polling agent
+  that relied on FIFO drain order should now pass `sort="asc"` to
+  preserve the old behavior.
+- `agent_mode` is now a required field on `RegisterAgentRequest`. The
+  server previously silently defaulted to `"cloud"` and then 400'd
+  with a cryptic "webhook_url is required" message; it now explicitly
+  rejects requests missing `agent_mode` with a clear error. Pydantic
+  v2 will raise a validation error if you instantiate the request
+  without it. Set `agent_mode="local"` or `"cloud"` explicitly.
+
 ## 2.3.0
 
 ### Added

{e2a-2.3.0 → e2a-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: e2a
-Version: 2.3.0
+Version: 2.5.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

{e2a-2.3.0 → e2a-2.5.0}/pyproject.toml

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

{e2a-2.3.0 → e2a-2.5.0}/src/e2a/v1/api.py

@@ -191,8 +191,44 @@ class E2AApi:
         status: str = "unread",
         page_size: int = 50,
         token: Optional[str] = None,
+        sort: Optional[str] = None,
+        from_: Optional[str] = None,
+        subject_contains: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
     ) -> ListMessagesResponse:
+        """List messages for an agent.
+
+        ``sort`` defaults server-side to ``"desc"`` (newest first).
+        Pass ``"asc"`` for FIFO polling — drain the inbox in arrival
+        order. The choice is encoded in ``next_token`` so subsequent
+        pages keep the same order; switching mid-pagination returns
+        400.
+
+        ``from_``, ``subject_contains``: case-insensitive substring
+        match (Postgres ILIKE). Capped server-side at 200 chars.
+
+        ``conversation_id``: exact match — narrow to one thread.
+
+        ``since`` / ``until``: RFC3339 timestamps (``datetime.isoformat()``
+        produces a valid value as long as it ends in ``Z`` or has a
+        timezone offset). Bracket on ``created_at`` (``>= since`` and
+        ``< until``).
+        """
         params: dict[str, str] = {"status": status, "page_size": str(page_size)}
+        if sort:
+            params["sort"] = sort
+        if from_:
+            params["from"] = from_
+        if subject_contains:
+            params["subject_contains"] = subject_contains
+        if conversation_id:
+            params["conversation_id"] = conversation_id
+        if since:
+            params["since"] = since
+        if until:
+            params["until"] = until
         if token:
             params["token"] = token
         resp = self._client.get(
@@ -264,17 +300,27 @@ class E2AApi:
         self,
         message_id: str,
         overrides: Optional[ApprovePendingMessageRequest] = None,
+        idempotency_key: Optional[str] = None,
     ) -> ApprovePendingMessageResponse:
         """Approve a held outbound message.
 
         Pass ``overrides`` to approve with edits (any subset of
         subject / body_text / body_html / to / cc / bcc / attachments).
         Pass ``None`` (the default) to approve the draft as-is.
+
+        ``idempotency_key`` is sent as the ``Idempotency-Key`` header.
+        Approve fires a real SES send, so supplying a stable key
+        derived from the review event makes retries safe (the server
+        replays the original response instead of double-sending).
+        When omitted the SDK mints a fresh UUIDv4 per call — that
+        gives network-layer retry safety only; the per-call default
+        does not survive an explicit retry loop.
         """
         payload = overrides.model_dump(by_alias=True, exclude_none=True) if overrides else {}
         resp = self._client.post(
             f"/api/v1/messages/{quote(message_id, safe='')}/approve",
             json=payload,
+            headers=_idempotency_header(idempotency_key),
         )
         _check_response(resp)
         return ApprovePendingMessageResponse.model_validate(resp.json())

{e2a-2.3.0 → e2a-2.5.0}/src/e2a/v1/async_client.py

@@ -164,8 +164,28 @@ class AsyncE2AApi:
         status: str = "unread",
         page_size: int = 50,
         token: Optional[str] = None,
+        sort: Optional[str] = None,
+        from_: Optional[str] = None,
+        subject_contains: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
     ) -> ListMessagesResponse:
+        """Async variant of :meth:`E2AApi.list_messages`. See that
+        method for the full filter / sort docs."""
         params: dict[str, str] = {"status": status, "page_size": str(page_size)}
+        if sort:
+            params["sort"] = sort
+        if from_:
+            params["from"] = from_
+        if subject_contains:
+            params["subject_contains"] = subject_contains
+        if conversation_id:
+            params["conversation_id"] = conversation_id
+        if since:
+            params["since"] = since
+        if until:
+            params["until"] = until
         if token:
             params["token"] = token
         resp = await self._client.get(
@@ -231,11 +251,15 @@ class AsyncE2AApi:
         self,
         message_id: str,
         overrides: Optional[ApprovePendingMessageRequest] = None,
+        idempotency_key: Optional[str] = None,
     ) -> ApprovePendingMessageResponse:
+        """Async variant of :meth:`E2AApi.approve_message`. ``idempotency_key``
+        closes the SES double-send window — see that method for details."""
         payload = overrides.model_dump(by_alias=True, exclude_none=True) if overrides else {}
         resp = await self._client.post(
             f"/api/v1/messages/{quote(message_id, safe='')}/approve",
             json=payload,
+            headers=_idempotency_header(idempotency_key),
         )
         _check_response(resp)
         return ApprovePendingMessageResponse.model_validate(resp.json())
@@ -389,10 +413,35 @@ class AsyncE2AClient:
         page_size: int = 50,
         token: Optional[str] = None,
         agent_email: Optional[str] = None,
+        sort: Optional[str] = None,
+        from_: Optional[str] = None,
+        subject_contains: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
     ) -> MessageList:
-        """Fetch message summaries with ergonomic field names."""
+        """Fetch message summaries with ergonomic field names.
+
+        ``sort`` defaults server-side to ``"desc"`` (newest first). Pass
+        ``"asc"`` to drain the inbox in arrival order — FIFO polling.
+
+        Search filters (``from_``, ``subject_contains``, ``conversation_id``,
+        ``since``, ``until``) match the sync client — see
+        :meth:`E2AApi.list_messages` for the full reference.
+        """
         email = self._require_agent_email(agent_email)
-        resp = await self.api.list_messages(email, status=status, page_size=page_size, token=token)
+        resp = await self.api.list_messages(
+            email,
+            status=status,
+            page_size=page_size,
+            token=token,
+            sort=sort,
+            from_=from_,
+            subject_contains=subject_contains,
+            conversation_id=conversation_id,
+            since=since,
+            until=until,
+        )
         messages = [
             MessageSummary(
                 message_id=m.message_id or "",
@@ -564,6 +613,7 @@ class AsyncE2AClient:
         to: Optional[list[str]] = None,
         cc: Optional[list[str]] = None,
         bcc: Optional[list[str]] = None,
+        idempotency_key: Optional[str] = None,
     ):
         any_override = any(
             v is not None for v in (subject, body_text, body_html, to, cc, bcc)
@@ -580,7 +630,7 @@ class AsyncE2AClient:
             if any_override
             else None
         )
-        return await self.api.approve_message(message_id, overrides)
+        return await self.api.approve_message(message_id, overrides, idempotency_key=idempotency_key)
 
     async def reject_message(self, message_id: str, reason: str = ""):
         return await self.api.reject_message(message_id, reason)

{e2a-2.3.0 → e2a-2.5.0}/src/e2a/v1/client.py

@@ -185,10 +185,36 @@ class E2AClient:
         page_size: int = 50,
         token: Optional[str] = None,
         agent_email: Optional[str] = None,
+        sort: Optional[str] = None,
+        from_: Optional[str] = None,
+        subject_contains: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        since: Optional[str] = None,
+        until: Optional[str] = None,
     ) -> MessageList:
-        """Fetch message summaries with ergonomic field names."""
+        """Fetch message summaries with ergonomic field names.
+
+        ``sort`` defaults server-side to ``"desc"`` (newest first). Pass
+        ``"asc"`` to drain the inbox in arrival order — FIFO polling.
+
+        ``from_`` / ``subject_contains`` are case-insensitive substring
+        filters (capped at 200 chars server-side). ``conversation_id``
+        exact-matches a thread. ``since`` / ``until`` are RFC3339
+        timestamps bounding ``created_at``.
+        """
         email = self._require_agent_email(agent_email)
-        resp = self.api.list_messages(email, status=status, page_size=page_size, token=token)
+        resp = self.api.list_messages(
+            email,
+            status=status,
+            page_size=page_size,
+            token=token,
+            sort=sort,
+            from_=from_,
+            subject_contains=subject_contains,
+            conversation_id=conversation_id,
+            since=since,
+            until=until,
+        )
         messages = [
             MessageSummary(
                 message_id=m.message_id or "",
@@ -369,11 +395,19 @@ class E2AClient:
         to: Optional[list[str]] = None,
         cc: Optional[list[str]] = None,
         bcc: Optional[list[str]] = None,
+        idempotency_key: Optional[str] = None,
     ):
         """Approve a held outbound message.
 
         Pass any subset of overrides to approve with edits; pass none
         to approve as-is.
+
+        ``idempotency_key`` makes retries safe across the SES double-
+        send window. Supply a stable key derived from the review event
+        (e.g. the dashboard click id or the pending ``message_id``) to
+        make retries dedupe. When omitted the SDK mints a fresh UUIDv4
+        per call — that gives network-layer retry safety only; the
+        per-call default does not survive an explicit retry loop.
         """
         any_override = any(
             v is not None for v in (subject, body_text, body_html, to, cc, bcc)
@@ -390,7 +424,7 @@ class E2AClient:
             if any_override
             else None
         )
-        return self.api.approve_message(message_id, overrides)
+        return self.api.approve_message(message_id, overrides, idempotency_key=idempotency_key)
 
     def reject_message(self, message_id: str, reason: str = ""):
         """Reject a held outbound message. The optional reason is

{e2a-2.3.0 → e2a-2.5.0}/src/e2a/v1/generated/__init__.py

@@ -143,6 +143,26 @@ class Domain(BaseModel):
     verified_at: str | None = None
 
 
+class LimitsCaps(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    max_agents: int | None = None
+    max_domains: int | None = None
+    max_messages_month: int | None = None
+    max_storage_bytes: int | None = None
+
+
+class LimitsUsage(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    agents: int | None = None
+    domains: int | None = None
+    messages_month: int | None = None
+    storage_bytes: int | None = None
+
+
 class ListAgentsResponse(BaseModel):
     model_config = ConfigDict(
         populate_by_name=True,
@@ -267,11 +287,15 @@ class RegisterAgentRequest(BaseModel):
     model_config = ConfigDict(
         populate_by_name=True,
     )
-    agent_mode: str | None = None
-    email: str | None = None
-    name: str | None = None
-    slug: str | None = None
-    webhook_url: str | None = None
+    agent_mode: Literal['local', 'cloud'] = Field(
+        ...,
+        description='AgentMode selects how inbound mail is delivered. Required; must be "local" or "cloud". See the type-level docs for the difference.',
+        examples=['local'],
+    )
+    email: str | None = Field(None, examples=['my-bot@yourdomain.com'])
+    name: str | None = Field(None, examples=['My Bot'])
+    slug: str | None = Field(None, examples=['my-bot'])
+    webhook_url: str | None = Field(None, examples=['https://example.com/e2a/webhook'])
 
 
 class RegisterAgentResponse(BaseModel):
@@ -405,6 +429,16 @@ class ApprovePendingMessageRequest(BaseModel):
     to: list[str] | None = None
 
 
+class LimitsInfo(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    limits: LimitsCaps | None = None
+    plan_code: str | None = None
+    upgrade_url: str | None = None
+    usage: LimitsUsage | None = None
+
+
 class ListMessagesResponse(BaseModel):
     model_config = ConfigDict(
         populate_by_name=True,

{e2a-2.3.0 → e2a-2.5.0}/tests/test_idempotency.py

@@ -128,3 +128,56 @@ def test_high_level_client_reply_threads_idempotency_key(httpx_mock):
 
     req = httpx_mock.get_request()
     assert req.headers["Idempotency-Key"] == "client-reply-key"
+
+
+# approve_message is also side-effectful — fires a real SES send when
+# the reviewer approves a held draft. Without an Idempotency-Key a
+# transient retry after a successful approve could double-send. Cover
+# the same contract: auto-generated key by default, caller-supplied
+# key passes through verbatim, high-level client threads it through.
+
+
+def test_approve_message_auto_generates_idempotency_key(httpx_mock):
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/messages/msg_p/approve",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_p", "method": "smtp", "edited": False},
+    )
+
+    with E2AApi(api_key="e2a_test") as api:
+        api.approve_message("msg_p")
+
+    req = httpx_mock.get_request()
+    key = req.headers["Idempotency-Key"]
+    assert key, "Idempotency-Key header not set"
+    assert UUIDV4_RE.match(key), f"key {key!r} is not a UUIDv4 hex/canonical shape"
+
+
+def test_approve_message_honors_caller_supplied_key(httpx_mock):
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/messages/msg_p/approve",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_p", "method": "smtp", "edited": False},
+    )
+
+    with E2AApi(api_key="e2a_test") as api:
+        api.approve_message("msg_p", idempotency_key="approve-key-1")
+
+    req = httpx_mock.get_request()
+    assert req.headers["Idempotency-Key"] == "approve-key-1"
+
+
+def test_high_level_client_approve_threads_idempotency_key(httpx_mock):
+    httpx_mock.add_response(
+        url=f"{BASE}/api/v1/messages/msg_p/approve",
+        method="POST",
+        json={"status": "sent", "message_id": "msg_p", "method": "smtp", "edited": False},
+    )
+
+    with E2AClient(
+        api_key="e2a_test", agent_email="bot@test.dev"
+    ) as client:
+        client.approve_message("msg_p", idempotency_key="high-level-approve-key")
+
+    req = httpx_mock.get_request()
+    assert req.headers["Idempotency-Key"] == "high-level-approve-key"

{e2a-2.3.0 → e2a-2.5.0}/tests/test_v1_api.py

@@ -158,13 +158,13 @@ def test_register_agent(httpx_mock):
     )
 
     with E2AApi(api_key="k") as api:
-        result = api.register_agent(RegisterAgentRequest(slug="new"))
+        result = api.register_agent(RegisterAgentRequest(slug="new", agent_mode="local"))
 
     assert isinstance(result, RegisterAgentResponse)
     assert result.email == "new@agents.e2a.dev"
 
     body = json.loads(httpx_mock.get_request().content)
-    assert body == {"slug": "new"}
+    assert body == {"slug": "new", "agent_mode": "local"}
 
 
 def test_get_agent(httpx_mock):

{e2a-2.3.0 → e2a-2.5.0}/tests/test_v1_async_client.py

@@ -294,10 +294,10 @@ async def test_register_agent_slug(httpx_mock):
     )
 
     async with AsyncE2AClient(api_key="k") as client:
-        await client.register_agent("new")
+        await client.register_agent("new", agent_mode="local")
 
     body = json.loads(httpx_mock.get_request().content)
-    assert body == {"slug": "new"}
+    assert body == {"slug": "new", "agent_mode": "local"}
 
 
 @pytest.mark.anyio

{e2a-2.3.0 → e2a-2.5.0}/tests/test_v1_client.py

@@ -442,10 +442,10 @@ def test_register_agent_slug_only(httpx_mock):
     )
 
     with E2AClient(api_key="k") as client:
-        result = client.register_agent("new")
+        result = client.register_agent("new", agent_mode="local")
 
     body = json.loads(httpx_mock.get_request().content)
-    assert body == {"slug": "new"}
+    assert body == {"slug": "new", "agent_mode": "local"}
 
 
 def test_register_agent_custom_domain(httpx_mock):