devhelm 1.9.0__tar.gz → 1.10.0__tar.gz

{devhelm-1.9.0 → devhelm-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devhelm
-Version: 1.9.0
+Version: 1.10.0
 Summary: DevHelm SDK for Python — typed client for monitors, incidents, alerting, and more
 Project-URL: Homepage, https://github.com/devhelmhq/sdk-python
 Project-URL: Repository, https://github.com/devhelmhq/sdk-python.git

{devhelm-1.9.0 → devhelm-1.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devhelm"
-version = "1.9.0"
+version = "1.10.0"
 description = "DevHelm SDK for Python — typed client for monitors, incidents, alerting, and more"
 authors = [{ name = "DevHelm", email = "hello@devhelm.io" }]
 license = "MIT"

{devhelm-1.9.0 → devhelm-1.10.0}/src/devhelm/resources/email.py

@@ -9,11 +9,14 @@ from __future__ import annotations
 
 import builtins
 import secrets
+from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
+from uuid import UUID
 
 import httpx
 
+from devhelm._errors import DevhelmValidationError
 from devhelm._generated import (
     CreateEmailDomainRequest,
     EmailDnsRecordDto,
@@ -51,6 +54,92 @@ from devhelm.resources.signed_download import (
 DOMAINS = "/api/v1/email/domains"
 
 
+@dataclass(frozen=True, slots=True)
+class DomainActivityBucket:
+    hour: str
+    message_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class DomainActivity:
+    domain_id: UUID
+    buckets: list[DomainActivityBucket]
+
+
+@dataclass(frozen=True, slots=True)
+class MessageSource:
+    source: str
+    truncated: bool
+
+
+def _query(**values: str | None) -> dict[str, str] | None:
+    params: dict[str, str] = {}
+    for key, value in values.items():
+        if value is not None:
+            params[key] = value
+    return params or None
+
+
+def _invalid(context: str) -> DevhelmValidationError:
+    return DevhelmValidationError(f"Invalid response from {context}")
+
+
+def _count(value: object, context: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise _invalid(context)
+    return value
+
+
+def _activity_row(item: object, context: str) -> DomainActivity:
+    if not isinstance(item, dict):
+        raise _invalid(context)
+    domain_id = item.get("domainId")
+    buckets = item.get("buckets")
+    if not isinstance(domain_id, str) or not isinstance(buckets, list):
+        raise _invalid(context)
+    try:
+        parsed_id = UUID(domain_id)
+    except ValueError as exc:
+        raise DevhelmValidationError(
+            f"Invalid response from {context}", cause=exc
+        ) from exc
+    parsed: list[DomainActivityBucket] = []
+    for bucket in buckets:
+        if not isinstance(bucket, dict):
+            raise _invalid(context)
+        hour = bucket.get("hour")
+        if not isinstance(hour, str):
+            raise _invalid(context)
+        parsed.append(
+            DomainActivityBucket(
+                hour=hour, message_count=_count(bucket.get("messageCount"), context)
+            )
+        )
+    return DomainActivity(domain_id=parsed_id, buckets=parsed)
+
+
+def _read_activity(raw: object, context: str) -> list[DomainActivity]:
+    if not isinstance(raw, dict):
+        raise _invalid(context)
+    data = raw.get("data")
+    if not isinstance(data, list):
+        raise _invalid(context)
+    return [_activity_row(item, context) for item in data]
+
+
+def _read_source(raw: object, context: str) -> MessageSource:
+    if not isinstance(raw, dict):
+        raise _invalid(context)
+    data = raw.get("data")
+    if not isinstance(data, dict):
+        raise _invalid(context)
+    source = data.get("source")
+    truncated = data.get("truncated")
+    if not isinstance(source, str) or not isinstance(truncated, bool):
+        raise _invalid(context)
+    return MessageSource(source=source, truncated=truncated)
+
+
 def _domain_segment(name: str) -> str:
     return path_param(name).replace("%2E", ".").replace("%2e", ".")
 
@@ -131,6 +220,11 @@ class Message:
             self._email._client, f"{self._message_path()}/links", InboundEmailLink
         )
 
+    def source(self) -> MessageSource:
+        """Clipped RFC822 text. ``truncated`` means the raw object is longer."""
+        path = f"{self._message_path()}/source"
+        return _read_source(api_get(self._email._client, path), f"GET {path}")
+
     def _message_path(self) -> str:
         return (
             f"{DOMAINS}/{_domain_segment(self._domain)}/messages/"
@@ -148,7 +242,11 @@ class AddressMessages:
         self._local_part = local_part
 
     def list(
-        self, *, cursor: str | None = None, limit: int | None = None
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int | None = None,
+        q: str | None = None,
     ) -> CursorPage[Message]:
         path = f"{DOMAINS}/{_domain_segment(self._domain)}/messages"
         page = fetch_cursor_page(
@@ -157,7 +255,7 @@ class AddressMessages:
             EmailMessageDto,
             cursor,
             limit,
-            extra_params={"inbox": self._local_part},
+            extra_params=_query(inbox=self._local_part, q=q),
         )
         return CursorPage(
             data=[Message(self._email, self._domain, row) for row in page.data],
@@ -266,12 +364,26 @@ class EmailDomains:
     def __init__(self, email: Email) -> None:
         self._email = email
 
-    def list(self) -> list[Domain]:
-        rows = fetch_all_pages(self._email._client, DOMAINS, EmailDomainDto)
+    def list(self, *, search: str | None = None) -> list[Domain]:
+        rows = fetch_all_pages(
+            self._email._client,
+            DOMAINS,
+            EmailDomainDto,
+            extra_params=_query(search=search),
+        )
         return [Domain(self, row) for row in rows]
 
-    def list_page(self, page: int, size: int) -> Page[Domain]:
-        result = fetch_page(self._email._client, DOMAINS, EmailDomainDto, page, size)
+    def list_page(
+        self, page: int, size: int, *, search: str | None = None
+    ) -> Page[Domain]:
+        result = fetch_page(
+            self._email._client,
+            DOMAINS,
+            EmailDomainDto,
+            page,
+            size,
+            extra_params=_query(search=search),
+        )
         return Page(
             data=[Domain(self, row) for row in result.data],
             has_next=result.has_next,
@@ -281,6 +393,18 @@ class EmailDomains:
             next_cursor=result.next_cursor,
         )
 
+    def activity(self, domain_ids: builtins.list[str]) -> builtins.list[DomainActivity]:
+        """Last-24h message counts. An empty id list does not call the API."""
+        if not domain_ids:
+            return []
+        path = f"{DOMAINS}/activity"
+        return _read_activity(
+            api_get(
+                self._email._client, path, params={"domainIds": ",".join(domain_ids)}
+            ),
+            f"GET {path}",
+        )
+
     def get(self, name: str) -> Domain:
         path = f"{DOMAINS}/{_domain_segment(name)}"
         row = parse_single(

{devhelm-1.9.0 → devhelm-1.10.0}/src/devhelm/resources/inboxes.py

@@ -6,7 +6,9 @@ capture URL a sender hits, plus ``wait`` for the captured request.
 
 from __future__ import annotations
 
+import builtins
 import json
+from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 from uuid import UUID
@@ -47,6 +49,73 @@ from devhelm.resources.signed_download import (
 BASE = "/api/v1/webhook/inboxes"
 
 
+@dataclass(frozen=True, slots=True)
+class InboxActivityBucket:
+    hour: str
+    event_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class InboxActivity:
+    inbox_id: UUID
+    buckets: list[InboxActivityBucket]
+
+
+def _query(**values: str | None) -> dict[str, str] | None:
+    params: dict[str, str] = {}
+    for key, value in values.items():
+        if value is not None:
+            params[key] = value
+    return params or None
+
+
+def _invalid(context: str) -> DevhelmValidationError:
+    return DevhelmValidationError(f"Invalid activity response from {context}")
+
+
+def _count(value: object, context: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise _invalid(context)
+    return value
+
+
+def _activity_row(item: object, context: str) -> InboxActivity:
+    if not isinstance(item, dict):
+        raise _invalid(context)
+    inbox_id = item.get("inboxId")
+    buckets = item.get("buckets")
+    if not isinstance(inbox_id, str) or not isinstance(buckets, list):
+        raise _invalid(context)
+    try:
+        parsed_id = UUID(inbox_id)
+    except ValueError as exc:
+        raise DevhelmValidationError(
+            f"Invalid activity response from {context}", cause=exc
+        ) from exc
+    parsed: list[InboxActivityBucket] = []
+    for bucket in buckets:
+        if not isinstance(bucket, dict):
+            raise _invalid(context)
+        hour = bucket.get("hour")
+        if not isinstance(hour, str):
+            raise _invalid(context)
+        parsed.append(
+            InboxActivityBucket(
+                hour=hour, event_count=_count(bucket.get("eventCount"), context)
+            )
+        )
+    return InboxActivity(inbox_id=parsed_id, buckets=parsed)
+
+
+def _read_activity(raw: object, context: str) -> list[InboxActivity]:
+    if not isinstance(raw, dict):
+        raise _invalid(context)
+    data = raw.get("data")
+    if not isinstance(data, list):
+        raise _invalid(context)
+    return [_activity_row(item, context) for item in data]
+
+
 class InboxEvents:
     """Events stored on one inbox."""
 
@@ -55,7 +124,12 @@ class InboxEvents:
         self._inbox_id = inbox_id
 
     def list(
-        self, *, cursor: str | None = None, limit: int | None = None
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int | None = None,
+        method: str | None = None,
+        path: str | None = None,
     ) -> CursorPage[ListedEvent]:
         page = fetch_cursor_page(
             self._inboxes._client,
@@ -63,6 +137,7 @@ class InboxEvents:
             WebhookEventDto,
             cursor,
             limit,
+            extra_params=_query(method=method, path=path),
         )
         return CursorPage(
             data=[self._inboxes._bind_listed(self._inbox_id, row) for row in page.data],
@@ -195,12 +270,23 @@ class Inboxes:
     def __init__(self, client: httpx.Client) -> None:
         self._client = client
 
-    def list(self) -> list[Inbox]:
-        rows = fetch_all_pages(self._client, BASE, WebhookInboxDto)
+    def list(self, *, search: str | None = None) -> list[Inbox]:
+        rows = fetch_all_pages(
+            self._client, BASE, WebhookInboxDto, extra_params=_query(search=search)
+        )
         return [self._bind(row) for row in rows]
 
-    def list_page(self, page: int, size: int) -> Page[Inbox]:
-        result = fetch_page(self._client, BASE, WebhookInboxDto, page, size)
+    def list_page(
+        self, page: int, size: int, *, search: str | None = None
+    ) -> Page[Inbox]:
+        result = fetch_page(
+            self._client,
+            BASE,
+            WebhookInboxDto,
+            page,
+            size,
+            extra_params=_query(search=search),
+        )
         return Page(
             data=[self._bind(row) for row in result.data],
             has_next=result.has_next,
@@ -210,6 +296,16 @@ class Inboxes:
             next_cursor=result.next_cursor,
         )
 
+    def activity(self, inbox_ids: builtins.list[str]) -> builtins.list[InboxActivity]:
+        """Last-24h request counts. An empty id list does not call the API."""
+        if not inbox_ids:
+            return []
+        path = f"{BASE}/activity"
+        return _read_activity(
+            api_get(self._client, path, params={"inboxIds": ",".join(inbox_ids)}),
+            f"GET {path}",
+        )
+
     def get(self, id: str) -> Inbox:
         path = f"{BASE}/{path_param(id)}"
         return self._bind(

devhelm-1.10.0/tests/test_inbound.py

@@ -0,0 +1,234 @@
+"""Inbound inbox and email helpers."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+
+from devhelm import DevhelmApiError
+from devhelm.resources.email import Email
+from devhelm.resources.inboxes import Inboxes
+
+INBOX_ID = "550e8400-e29b-41d4-a716-446655440000"
+EVENT_ID = "550e8400-e29b-41d4-a716-446655440001"
+WHEN = "2026-09-24T12:00:00Z"
+
+EVENT = {
+    "id": EVENT_ID,
+    "inboxId": INBOX_ID,
+    "receivedAt": WHEN,
+    "sizeBytes": 2,
+    "headers": {},
+    "method": "POST",
+    "path": "/",
+    "sha256": "abc",
+    "body": '{"ok":true}',
+}
+
+SIGNED = {
+    "data": {
+        "url": "https://files.example/event",
+        "expiresAt": WHEN,
+        "filename": "event.bin",
+        "contentType": "application/json",
+        "sizeBytes": 2,
+    }
+}
+
+
+def _json(payload: object, status: int = 200) -> httpx.Response:
+    return httpx.Response(status, json=payload)
+
+
+def test_inbox_wait_unwraps_event_and_downloads_signed_url(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    captured: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured.append(request)
+        if request.url.path.endswith("/wait"):
+            return _json({"event": EVENT})
+        if request.url.path.endswith("/raw"):
+            return _json(SIGNED)
+        return _json({"message": str(request.url)}, status=404)
+
+    downloaded: list[str] = []
+
+    def fake_get(url: str, **_kwargs: Any) -> httpx.Response:
+        downloaded.append(url)
+        return httpx.Response(200, content=b"\x09\x09")
+
+    monkeypatch.setattr(httpx, "get", fake_get)
+    client = httpx.Client(
+        transport=httpx.MockTransport(handler), base_url="http://api.test"
+    )
+    event = Inboxes(client).wait(INBOX_ID, timeout_ms=30_000, http={"method": "POST"})
+    assert event.method == "POST"
+    assert event.text() == '{"ok":true}'
+    assert event.json() == {"ok": True}
+    assert event.raw() == b"\x09\x09"
+    assert downloaded == ["https://files.example/event"]
+
+    body = json.loads(captured[0].content)
+    assert body["timeoutMs"] == 30_000
+    assert "receivedAfter" in body
+    assert body["http"] == {"method": "POST"}
+    assert all("files.example" not in str(request.url) for request in captured)
+
+
+INBOX = {
+    "id": INBOX_ID,
+    "workspaceId": 2,
+    "name": "stripe",
+    "status": "active",
+    "publicToken": "tok",
+    "httpUrl": "https://api.test/api/v1/ingest/tok",
+    "httpResponse": {
+        "status": 200,
+        "headers": {},
+        "body": "",
+        "contentType": "text/plain",
+        "delayMs": 0,
+    },
+    "cors": True,
+    "retentionDays": 3,
+    "maxEvents": 10000,
+    "createdAt": WHEN,
+    "updatedAt": WHEN,
+}
+
+PAGE = {"hasNext": False, "hasPrev": False, "totalElements": 1, "totalPages": 1}
+
+
+def test_inbox_search_event_filter_and_activity() -> None:
+    seen: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        if request.url.path.endswith("/activity"):
+            return _json(
+                {
+                    "data": [
+                        {
+                            "inboxId": INBOX_ID,
+                            "buckets": [{"hour": WHEN, "eventCount": 3}],
+                        }
+                    ]
+                }
+            )
+        if request.url.path.endswith("/events"):
+            return _json({"data": [EVENT], "nextCursor": None, "hasMore": False})
+        return _json({"data": [INBOX], **PAGE})
+
+    client = httpx.Client(
+        transport=httpx.MockTransport(handler), base_url="http://api.test"
+    )
+    inboxes = Inboxes(client)
+    assert inboxes.activity([]) == []
+    assert seen == []
+
+    rows = inboxes.list(search="stripe")
+    assert rows[0].name == "stripe"
+    assert seen[0].url.params["search"] == "stripe"
+
+    rows[0].events.list(method="POST", path="/hooks")
+    events = next(request for request in seen if request.url.path.endswith("/events"))
+    assert events.url.params["method"] == "POST"
+    assert events.url.params["path"] == "/hooks"
+
+    activity = inboxes.activity([INBOX_ID])
+    assert activity[0].buckets[0].event_count == 3
+    act = next(request for request in seen if request.url.path.endswith("/activity"))
+    assert act.url.params["inboxIds"] == INBOX_ID
+
+
+def test_email_query_source_and_domain_activity() -> None:
+    domain_id = "550e8400-e29b-41d4-a716-446655440002"
+    message_id = "550e8400-e29b-41d4-a716-446655440003"
+    seen: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        if request.url.path.endswith("/source"):
+            return _json({"data": {"source": "Subject: code", "truncated": False}})
+        if request.url.path.endswith("/activity"):
+            return _json(
+                {
+                    "data": [
+                        {
+                            "domainId": domain_id,
+                            "buckets": [{"hour": WHEN, "messageCount": 4}],
+                        }
+                    ]
+                }
+            )
+        if "/messages" in request.url.path:
+            return _json(
+                {
+                    "data": [
+                        {
+                            "id": message_id,
+                            "domainId": domain_id,
+                            "receivedAt": WHEN,
+                            "sizeBytes": 4,
+                            "headers": {},
+                            "sha256": "abc",
+                        }
+                    ],
+                    "nextCursor": None,
+                    "hasMore": False,
+                }
+            )
+        return _json(
+            {
+                "data": [
+                    {
+                        "id": domain_id,
+                        "name": "ws.devhelmmail.com",
+                        "workspaceId": 2,
+                        "kind": "assigned",
+                        "status": "active",
+                        "mxVerified": True,
+                        "dnsRecords": [],
+                        "createdAt": WHEN,
+                        "updatedAt": WHEN,
+                    }
+                ],
+                **PAGE,
+            }
+        )
+
+    client = httpx.Client(
+        transport=httpx.MockTransport(handler), base_url="http://api.test"
+    )
+    email = Email(client)
+    address = email.address(domain="ws.devhelmmail.com", label="signup")
+    page = address.messages.list(q="code")
+    listed = next(request for request in seen if "/messages" in request.url.path)
+    assert listed.url.params["q"] == "code"
+    assert listed.url.params["inbox"] == address.local_part
+    text = page.data[0].source()
+    assert text.source == "Subject: code"
+    assert text.truncated is False
+
+    domains = email.domains.list(search="ws")
+    assert domains[0].name == "ws.devhelmmail.com"
+    activity = email.domains.activity([domain_id])
+    assert activity[0].buckets[0].message_count == 4
+
+
+def test_email_wait_timeout_raises() -> None:
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return _json({"code": "WAIT_TIMEOUT", "message": "timed out"}, status=408)
+
+    client = httpx.Client(
+        transport=httpx.MockTransport(handler), base_url="http://api.test"
+    )
+    with pytest.raises(DevhelmApiError) as caught:
+        Email(client).wait(to="a@b.devhelmmail.com", timeout_ms=1000)
+    assert caught.value.status == 408
+    assert caught.value.code == "WAIT_TIMEOUT"

{devhelm-1.9.0 → devhelm-1.10.0}/uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.11"
 resolution-markers = [
     "python_full_version >= '3.14'",
@@ -315,8 +315,9 @@ wheels = [
 
 [[package]]
 name = "devhelm"
-version = "1.9.0"
+version = "1.10.0"
 source = { editable = "." }
+default-groups = "all"
 dependencies = [
     { name = "httpx" },
     { name = "pydantic", extra = ["email"] },

devhelm-1.9.0/tests/test_inbound.py

@@ -1,93 +0,0 @@
-"""Inbound inbox and email helpers."""
-
-from __future__ import annotations
-
-import json
-from typing import Any
-
-import httpx
-import pytest
-
-from devhelm import DevhelmApiError
-from devhelm.resources.email import Email
-from devhelm.resources.inboxes import Inboxes
-
-INBOX_ID = "550e8400-e29b-41d4-a716-446655440000"
-EVENT_ID = "550e8400-e29b-41d4-a716-446655440001"
-WHEN = "2026-09-24T12:00:00Z"
-
-EVENT = {
-    "id": EVENT_ID,
-    "inboxId": INBOX_ID,
-    "receivedAt": WHEN,
-    "sizeBytes": 2,
-    "headers": {},
-    "method": "POST",
-    "path": "/",
-    "sha256": "abc",
-    "body": '{"ok":true}',
-}
-
-SIGNED = {
-    "data": {
-        "url": "https://files.example/event",
-        "expiresAt": WHEN,
-        "filename": "event.bin",
-        "contentType": "application/json",
-        "sizeBytes": 2,
-    }
-}
-
-
-def _json(payload: object, status: int = 200) -> httpx.Response:
-    return httpx.Response(status, json=payload)
-
-
-def test_inbox_wait_unwraps_event_and_downloads_signed_url(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    captured: list[httpx.Request] = []
-
-    def handler(request: httpx.Request) -> httpx.Response:
-        captured.append(request)
-        if request.url.path.endswith("/wait"):
-            return _json({"event": EVENT})
-        if request.url.path.endswith("/raw"):
-            return _json(SIGNED)
-        return _json({"message": str(request.url)}, status=404)
-
-    downloaded: list[str] = []
-
-    def fake_get(url: str, **_kwargs: Any) -> httpx.Response:
-        downloaded.append(url)
-        return httpx.Response(200, content=b"\x09\x09")
-
-    monkeypatch.setattr(httpx, "get", fake_get)
-    client = httpx.Client(
-        transport=httpx.MockTransport(handler), base_url="http://api.test"
-    )
-    event = Inboxes(client).wait(INBOX_ID, timeout_ms=30_000, http={"method": "POST"})
-    assert event.method == "POST"
-    assert event.text() == '{"ok":true}'
-    assert event.json() == {"ok": True}
-    assert event.raw() == b"\x09\x09"
-    assert downloaded == ["https://files.example/event"]
-
-    body = json.loads(captured[0].content)
-    assert body["timeoutMs"] == 30_000
-    assert "receivedAfter" in body
-    assert body["http"] == {"method": "POST"}
-    assert all("files.example" not in str(request.url) for request in captured)
-
-
-def test_email_wait_timeout_raises() -> None:
-    def handler(_request: httpx.Request) -> httpx.Response:
-        return _json({"code": "WAIT_TIMEOUT", "message": "timed out"}, status=408)
-
-    client = httpx.Client(
-        transport=httpx.MockTransport(handler), base_url="http://api.test"
-    )
-    with pytest.raises(DevhelmApiError) as caught:
-        Email(client).wait(to="a@b.devhelmmail.com", timeout_ms=1000)
-    assert caught.value.status == 408
-    assert caught.value.code == "WAIT_TIMEOUT"