poststack 0.4.0__tar.gz → 0.5.0__tar.gz

{poststack-0.4.0 → poststack-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: poststack
-Version: 0.4.0
+Version: 0.5.0
 Summary: Official Python SDK for the PostStack Email API
 Project-URL: Homepage, https://poststack.dev
 Project-URL: Documentation, https://poststack.dev/docs
@@ -22,7 +22,7 @@ Classifier: Topic :: Communications :: Email
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.25.0
-Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic>=2.4.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'

{poststack-0.4.0 → poststack-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "poststack"
-version = "0.4.0"
+version = "0.5.0"
 description = "Official Python SDK for the PostStack Email API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,7 +25,8 @@ classifiers = [
 ]
 dependencies = [
     "httpx>=0.25.0",
-    "pydantic>=2.0.0",
+    # 2.4.0 floor closes GHSA-mr82-8j83-vxmv (regex DoS in 2.0–2.3.x).
+    "pydantic>=2.4.0",
 ]
 
 [project.optional-dependencies]
@@ -43,6 +44,9 @@ Issues = "https://github.com/getpoststack/python-sdk/issues"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/poststack"]
+# PEP 561: ship the `py.typed` marker so downstream type checkers (mypy,
+# pyright) honor our annotations.
+include = ["src/poststack/py.typed"]
 
 [tool.hatch.build.targets.sdist]
 include = [

{poststack-0.4.0 → poststack-0.5.0}/src/poststack/__init__.py

@@ -10,8 +10,6 @@ Public API::
 
 from __future__ import annotations
 
-from typing import Optional
-
 from ._client import (
     DEFAULT_BASE_URL,
     AsyncPostStackClient,
@@ -51,7 +49,7 @@ from .resources import (
     WorkflowsResource,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "PostStack",
@@ -155,5 +153,3 @@ class AsyncPostStack:
         await self.aclose()
 
 
-# Re-export for advanced callers.
-_: Optional[type] = None  # noqa: E305 - keeps ruff/mypy happy with Optional import

{poststack-0.4.0 → poststack-0.5.0}/src/poststack/_client.py

@@ -1,333 +1,351 @@
-"""HTTP client used by every resource module.
-
-Implements two parallel clients (sync + async) with identical interfaces so
-resources can pick the transport they need. Auth is a simple Bearer token.
-
-Both clients apply:
-  - a per-attempt timeout (default 30s, override per call)
-  - exponential-backoff retries on transient failures (network errors, 408,
-    429, 5xx) up to ``max_retries`` (default 3)
-  - automatic ``Idempotency-Key`` injection on POSTs so that a retry after a
-    network blip does not create a duplicate resource
-"""
-
-from __future__ import annotations
-
-import asyncio
-import random
-import time
-import uuid
-from typing import Any, Mapping, Optional
-
-import httpx
-
-from ._errors import PostStackError
-
-DEFAULT_BASE_URL = "https://api.poststack.dev"
-DEFAULT_TIMEOUT = 30.0
-DEFAULT_MAX_RETRIES = 3
-BASE_RETRY_DELAY = 0.25
-SDK_VERSION = "0.5.0"
-USER_AGENT = f"PostStack-Python-SDK/{SDK_VERSION}"
-
-RETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504}
-
-
-def _build_headers(api_key: str) -> dict[str, str]:
-    return {
-        "Authorization": f"Bearer {api_key}",
-        "Content-Type": "application/json",
-        "User-Agent": USER_AGENT,
-    }
-
-
-def _clean_params(
-    params: Optional[Mapping[str, Any]],
-) -> Optional[dict[str, str]]:
-    if not params:
-        return None
-    out: dict[str, str] = {}
-    for key, value in params.items():
-        if value is None:
-            continue
-        out[key] = str(value)
-    return out or None
-
-
-def _raise_for_status(response: httpx.Response) -> None:
-    if response.is_success:
-        return
-    request_id = response.headers.get("x-request-id")
-    try:
-        body = response.json()
-    except ValueError:
-        body = {}
-    error_message = (
-        body.get("error") if isinstance(body, dict) else None
-    ) or response.reason_phrase or "Unknown error"
-    code = body.get("code") if isinstance(body, dict) else None
-    raise PostStackError(
-        status_code=response.status_code,
-        error=error_message,
-        code=code,
-        request_id=request_id,
-    )
-
-
-def _parse_body(response: httpx.Response) -> Any:
-    # Some endpoints (e.g. CSV export) return non-JSON. Fall back to text.
-    content_type = response.headers.get("content-type", "")
-    if "application/json" in content_type:
-        return response.json()
-    text = response.text
-    if not text:
-        return None
-    try:
-        return response.json()
-    except ValueError:
-        return text
-
-
-def _retry_delay(attempt: int) -> float:
-    """Full-jitter exponential backoff — pick uniformly in [0, base*2**attempt)."""
-    return random.random() * (BASE_RETRY_DELAY * (2**attempt))
-
-
-def _idempotency_headers() -> dict[str, str]:
-    return {"Idempotency-Key": str(uuid.uuid4())}
-
-
-class PostStackClient:
-    """Synchronous HTTP client."""
-
-    def __init__(
-        self,
-        api_key: str,
-        base_url: str = DEFAULT_BASE_URL,
-        timeout: float = DEFAULT_TIMEOUT,
-        max_retries: int = DEFAULT_MAX_RETRIES,
-        transport: Optional[httpx.BaseTransport] = None,
-    ) -> None:
-        self._base_url = base_url.rstrip("/")
-        self._timeout = timeout
-        self._max_retries = max_retries
-        self._httpx = httpx.Client(
-            base_url=self._base_url,
-            headers=_build_headers(api_key),
-            timeout=timeout,
-            transport=transport,
-        )
-
-    # Lifecycle ------------------------------------------------------------
-
-    def close(self) -> None:
-        self._httpx.close()
-
-    def __enter__(self) -> "PostStackClient":
-        return self
-
-    def __exit__(self, *args: Any) -> None:
-        self.close()
-
-    # HTTP methods ---------------------------------------------------------
-
-    def _request(
-        self,
-        method: str,
-        path: str,
-        *,
-        params: Optional[Mapping[str, Any]] = None,
-        body: Any = None,
-        extra_headers: Optional[Mapping[str, str]] = None,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        request_timeout = timeout if timeout is not None else self._timeout
-
-        last_exc: Optional[BaseException] = None
-        for attempt in range(self._max_retries + 1):
-            try:
-                response = self._httpx.request(
-                    method,
-                    path,
-                    params=_clean_params(params),
-                    json=body if body is not None else None,
-                    headers=dict(extra_headers) if extra_headers else None,
-                    timeout=request_timeout,
-                )
-            except httpx.TransportError as exc:
-                last_exc = exc
-                if attempt < self._max_retries:
-                    time.sleep(_retry_delay(attempt))
-                    continue
-                raise
-
-            if (
-                response.status_code in RETRYABLE_STATUSES
-                and attempt < self._max_retries
-            ):
-                time.sleep(_retry_delay(attempt))
-                continue
-
-            _raise_for_status(response)
-            return _parse_body(response)
-
-        # If we exit the loop via `continue` on the final attempt, last_exc
-        # holds the most recent error.
-        assert last_exc is not None  # noqa: S101
-        raise last_exc
-
-    def get(
-        self,
-        path: str,
-        params: Optional[Mapping[str, Any]] = None,
-        *,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        return self._request("GET", path, params=params, timeout=timeout)
-
-    def post(
-        self,
-        path: str,
-        body: Any = None,
-        *,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        return self._request(
-            "POST",
-            path,
-            body=body,
-            extra_headers=_idempotency_headers(),
-            timeout=timeout,
-        )
-
-    def patch(
-        self,
-        path: str,
-        body: Any,
-        *,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        return self._request("PATCH", path, body=body, timeout=timeout)
-
-    def delete(
-        self,
-        path: str,
-        *,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        return self._request("DELETE", path, timeout=timeout)
-
-
-class AsyncPostStackClient:
-    """Asynchronous HTTP client."""
-
-    def __init__(
-        self,
-        api_key: str,
-        base_url: str = DEFAULT_BASE_URL,
-        timeout: float = DEFAULT_TIMEOUT,
-        max_retries: int = DEFAULT_MAX_RETRIES,
-        transport: Optional[httpx.AsyncBaseTransport] = None,
-    ) -> None:
-        self._base_url = base_url.rstrip("/")
-        self._timeout = timeout
-        self._max_retries = max_retries
-        self._httpx = httpx.AsyncClient(
-            base_url=self._base_url,
-            headers=_build_headers(api_key),
-            timeout=timeout,
-            transport=transport,
-        )
-
-    async def aclose(self) -> None:
-        await self._httpx.aclose()
-
-    async def __aenter__(self) -> "AsyncPostStackClient":
-        return self
-
-    async def __aexit__(self, *args: Any) -> None:
-        await self.aclose()
-
-    async def _request(
-        self,
-        method: str,
-        path: str,
-        *,
-        params: Optional[Mapping[str, Any]] = None,
-        body: Any = None,
-        extra_headers: Optional[Mapping[str, str]] = None,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        request_timeout = timeout if timeout is not None else self._timeout
-
-        last_exc: Optional[BaseException] = None
-        for attempt in range(self._max_retries + 1):
-            try:
-                response = await self._httpx.request(
-                    method,
-                    path,
-                    params=_clean_params(params),
-                    json=body if body is not None else None,
-                    headers=dict(extra_headers) if extra_headers else None,
-                    timeout=request_timeout,
-                )
-            except httpx.TransportError as exc:
-                last_exc = exc
-                if attempt < self._max_retries:
-                    await asyncio.sleep(_retry_delay(attempt))
-                    continue
-                raise
-
-            if (
-                response.status_code in RETRYABLE_STATUSES
-                and attempt < self._max_retries
-            ):
-                await asyncio.sleep(_retry_delay(attempt))
-                continue
-
-            _raise_for_status(response)
-            return _parse_body(response)
-
-        assert last_exc is not None  # noqa: S101
-        raise last_exc
-
-    async def get(
-        self,
-        path: str,
-        params: Optional[Mapping[str, Any]] = None,
-        *,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        return await self._request("GET", path, params=params, timeout=timeout)
-
-    async def post(
-        self,
-        path: str,
-        body: Any = None,
-        *,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        return await self._request(
-            "POST",
-            path,
-            body=body,
-            extra_headers=_idempotency_headers(),
-            timeout=timeout,
-        )
-
-    async def patch(
-        self,
-        path: str,
-        body: Any,
-        *,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        return await self._request("PATCH", path, body=body, timeout=timeout)
-
-    async def delete(
-        self,
-        path: str,
-        *,
-        timeout: Optional[float] = None,
-    ) -> Any:
-        return await self._request("DELETE", path, timeout=timeout)
+"""HTTP client used by every resource module.
+
+Implements two parallel clients (sync + async) with identical interfaces so
+resources can pick the transport they need. Auth is a simple Bearer token.
+
+Both clients apply:
+  - a per-attempt timeout (default 30s, override per call)
+  - exponential-backoff retries on transient failures (network errors, 408,
+    429, 5xx) up to ``max_retries`` (default 3)
+  - automatic ``Idempotency-Key`` injection on POSTs so that a retry after a
+    network blip does not create a duplicate resource
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+import uuid
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from ._errors import PostStackError
+
+DEFAULT_BASE_URL = "https://api.poststack.dev"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+BASE_RETRY_DELAY = 0.25
+
+
+def _sdk_version() -> str:
+    """Read the package version lazily to avoid a circular import.
+
+    ``__init__.py`` imports from this module before assigning
+    ``__version__``, so resolving at import time would observe the wrong
+    value (or fail). Calling at request-build time is cheap and keeps
+    ``__version__`` as the single source of truth (mirrored in
+    pyproject.toml at release).
+    """
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("poststack")
+    except PackageNotFoundError:
+        # Editable install / source tree without an installed dist.
+        from importlib import import_module
+
+        return getattr(import_module("poststack"), "__version__", "0.0.0")
+
+RETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504}
+
+
+def _build_headers(api_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "User-Agent": f"PostStack-Python-SDK/{_sdk_version()}",
+    }
+
+
+def _clean_params(
+    params: Optional[Mapping[str, Any]],
+) -> Optional[dict[str, str]]:
+    if not params:
+        return None
+    out: dict[str, str] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        out[key] = str(value)
+    return out or None
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    request_id = response.headers.get("x-request-id")
+    try:
+        body = response.json()
+    except ValueError:
+        body = {}
+    error_message = (
+        body.get("error") if isinstance(body, dict) else None
+    ) or response.reason_phrase or "Unknown error"
+    code = body.get("code") if isinstance(body, dict) else None
+    raise PostStackError(
+        status_code=response.status_code,
+        error=error_message,
+        code=code,
+        request_id=request_id,
+    )
+
+
+def _parse_body(response: httpx.Response) -> Any:
+    # Some endpoints (e.g. CSV export) return non-JSON. Fall back to text.
+    content_type = response.headers.get("content-type", "")
+    if "application/json" in content_type:
+        return response.json()
+    text = response.text
+    if not text:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return text
+
+
+def _retry_delay(attempt: int) -> float:
+    """Full-jitter exponential backoff — pick uniformly in [0, base*2**attempt)."""
+    return random.random() * (BASE_RETRY_DELAY * (2**attempt))
+
+
+def _idempotency_headers() -> dict[str, str]:
+    return {"Idempotency-Key": str(uuid.uuid4())}
+
+
+class PostStackClient:
+    """Synchronous HTTP client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._httpx = httpx.Client(
+            base_url=self._base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # Lifecycle ------------------------------------------------------------
+
+    def close(self) -> None:
+        self._httpx.close()
+
+    def __enter__(self) -> "PostStackClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # HTTP methods ---------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        request_timeout = timeout if timeout is not None else self._timeout
+
+        last_exc: Optional[BaseException] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._httpx.request(
+                    method,
+                    path,
+                    params=_clean_params(params),
+                    json=body if body is not None else None,
+                    headers=dict(extra_headers) if extra_headers else None,
+                    timeout=request_timeout,
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    time.sleep(_retry_delay(attempt))
+                    continue
+                raise
+
+            if (
+                response.status_code in RETRYABLE_STATUSES
+                and attempt < self._max_retries
+            ):
+                time.sleep(_retry_delay(attempt))
+                continue
+
+            _raise_for_status(response)
+            return _parse_body(response)
+
+        # If we exit the loop via `continue` on the final attempt, last_exc
+        # holds the most recent error.
+        assert last_exc is not None  # noqa: S101
+        raise last_exc
+
+    def get(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        return self._request("GET", path, params=params, timeout=timeout)
+
+    def post(
+        self,
+        path: str,
+        body: Any = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        return self._request(
+            "POST",
+            path,
+            body=body,
+            extra_headers=_idempotency_headers(),
+            timeout=timeout,
+        )
+
+    def patch(
+        self,
+        path: str,
+        body: Any,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        return self._request("PATCH", path, body=body, timeout=timeout)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        return self._request("DELETE", path, timeout=timeout)
+
+
+class AsyncPostStackClient:
+    """Asynchronous HTTP client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._httpx = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+            transport=transport,
+        )
+
+    async def aclose(self) -> None:
+        await self._httpx.aclose()
+
+    async def __aenter__(self) -> "AsyncPostStackClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        request_timeout = timeout if timeout is not None else self._timeout
+
+        last_exc: Optional[BaseException] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._httpx.request(
+                    method,
+                    path,
+                    params=_clean_params(params),
+                    json=body if body is not None else None,
+                    headers=dict(extra_headers) if extra_headers else None,
+                    timeout=request_timeout,
+                )
+            except httpx.TransportError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    await asyncio.sleep(_retry_delay(attempt))
+                    continue
+                raise
+
+            if (
+                response.status_code in RETRYABLE_STATUSES
+                and attempt < self._max_retries
+            ):
+                await asyncio.sleep(_retry_delay(attempt))
+                continue
+
+            _raise_for_status(response)
+            return _parse_body(response)
+
+        assert last_exc is not None  # noqa: S101
+        raise last_exc
+
+    async def get(
+        self,
+        path: str,
+        params: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        return await self._request("GET", path, params=params, timeout=timeout)
+
+    async def post(
+        self,
+        path: str,
+        body: Any = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        return await self._request(
+            "POST",
+            path,
+            body=body,
+            extra_headers=_idempotency_headers(),
+            timeout=timeout,
+        )
+
+    async def patch(
+        self,
+        path: str,
+        body: Any,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        return await self._request("PATCH", path, body=body, timeout=timeout)
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        return await self._request("DELETE", path, timeout=timeout)

{poststack-0.4.0 → poststack-0.5.0}/src/poststack/resources/contacts.py

@@ -32,6 +32,13 @@ class ContactsResource:
             f"/contacts/{quote(id, safe='')}", timeout=timeout
         )
 
+    def get_by_email(
+        self, email: str, *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return self._client.get(
+            f"/contacts/by-email/{quote(email, safe='')}", timeout=timeout
+        )
+
     def update(
         self,
         id: str,
@@ -92,6 +99,13 @@ class AsyncContactsResource:
             f"/contacts/{quote(id, safe='')}", timeout=timeout
         )
 
+    async def get_by_email(
+        self, email: str, *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return await self._client.get(
+            f"/contacts/by-email/{quote(email, safe='')}", timeout=timeout
+        )
+
     async def update(
         self,
         id: str,

{poststack-0.4.0 → poststack-0.5.0}/src/poststack/resources/webhooks.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import hashlib
+import hmac
 from typing import Any, Dict, Mapping, Optional
 
 from .._client import AsyncPostStackClient, PostStackClient
@@ -14,6 +16,14 @@ class WebhooksResource:
     def create(
         self, input: Dict[str, Any], *, timeout: Optional[float] = None
     ) -> Dict[str, Any]:
+        """Create a webhook.
+
+        The server response is ``{"webhook": {...}, "signingSecret": "..."}``.
+        Store ``signingSecret`` immediately — it's only surfaced here (the
+        server keeps an encrypted copy and afterwards only returns a
+        masked prefix). Pass it to :meth:`verify` to validate inbound
+        deliveries.
+        """
         return self._client.post("/webhooks", input, timeout=timeout)
 
     def get(
@@ -71,6 +81,45 @@ class WebhooksResource:
             timeout=timeout,
         )
 
+    @staticmethod
+    def verify(
+        payload: str | bytes, signature_header: str, secret: str
+    ) -> bool:
+        """Verify an incoming webhook against the ``X-PostStack-Signature``
+        header.
+
+        Header format is ``sha256=<hex-hmac>``. The HMAC is SHA-256 of the
+        raw JSON request body keyed by the webhook's plaintext signing
+        secret. Pass ``payload`` exactly as received — re-serializing
+        through ``json.loads/dumps`` will change byte-for-byte content and
+        the signature will not match.
+
+        Returns ``False`` on any shape mismatch (missing/malformed header,
+        wrong length, mismatched HMAC) so callers can ``return 401`` on
+        the bare boolean. Uses :func:`hmac.compare_digest` for the byte
+        comparison.
+        """
+        if (
+            not isinstance(signature_header, str)
+            or not signature_header.startswith("sha256=")
+        ):
+            return False
+
+        provided_hex = signature_header[len("sha256=") :].strip().lower()
+        if not provided_hex or any(
+            c not in "0123456789abcdef" for c in provided_hex
+        ):
+            return False
+        if len(provided_hex) % 2 != 0:
+            return False
+
+        body = payload.encode("utf-8") if isinstance(payload, str) else payload
+        expected_hex = hmac.new(
+            secret.encode("utf-8"), body, hashlib.sha256
+        ).hexdigest()
+
+        return hmac.compare_digest(expected_hex, provided_hex)
+
 
 class AsyncWebhooksResource:
     def __init__(self, client: AsyncPostStackClient) -> None:
@@ -79,6 +128,8 @@ class AsyncWebhooksResource:
     async def create(
         self, input: Dict[str, Any], *, timeout: Optional[float] = None
     ) -> Dict[str, Any]:
+        """Create a webhook. See :meth:`WebhooksResource.create` for the
+        response shape and signing-secret semantics."""
         return await self._client.post("/webhooks", input, timeout=timeout)
 
     async def get(
@@ -137,3 +188,6 @@ class AsyncWebhooksResource:
             f"/webhooks/{id}/deliveries/{delivery_id}/replay",
             timeout=timeout,
         )
+
+    # Verify is sync-only — pure crypto, no IO. Alias for ergonomics.
+    verify = staticmethod(WebhooksResource.verify)

{poststack-0.4.0 → poststack-0.5.0}/src/poststack/types.py

@@ -226,6 +226,29 @@ class ImportContactsResult(_Model):
 # ---------------------------------------------------------------------------
 
 
+SegmentComparator = Literal[
+    "equals", "not_equals", "contains", "starts_with", "ends_with"
+]
+SegmentOperator = Literal["and", "or"]
+
+
+class SegmentCondition(_Model):
+    """One leaf condition in a segment rules tree.
+
+    The field is **comparator**, not operator — `operator` is reserved for
+    the rules-tree boolean connective on `SegmentRules`.
+    """
+
+    field: str
+    comparator: SegmentComparator
+    value: str
+
+
+class SegmentRules(_Model):
+    operator: SegmentOperator
+    conditions: List[SegmentCondition]
+
+
 class Segment(_Model):
     id: str
     name: str
@@ -234,8 +257,9 @@ class Segment(_Model):
 
 
 class SegmentPreviewResult(_Model):
+    """Server returns count only — no `sample` field."""
+
     count: int
-    sample: List[Contact]
 
 
 # ---------------------------------------------------------------------------
@@ -277,6 +301,21 @@ class Webhook(_Model):
     events: List[str]
     active: bool
     created_at: str = Field(alias="createdAt")
+    # Plaintext signing secret — populated only on the response from
+    # `Webhooks.create()` (the server keeps an encrypted copy and only
+    # surfaces a masked prefix on subsequent reads).
+    signing_secret: Optional[str] = Field(
+        default=None, alias="signingSecret"
+    )
+
+
+class CreateWebhookResult(_Model):
+    """Response shape for `Webhooks.create()` — wraps the webhook plus its
+    plaintext `signing_secret` so callers can store the secret immediately.
+    """
+
+    webhook: Webhook
+    signing_secret: str = Field(alias="signingSecret")
 
 
 class WebhookDelivery(_Model):
@@ -352,6 +391,10 @@ class ApiKey(_Model):
     last_used_at: Optional[str] = Field(default=None, alias="lastUsedAt")
     expires_at: Optional[str] = Field(default=None, alias="expiresAt")
     created_at: str = Field(alias="createdAt")
+    # Plaintext secret — only present on `ApiKeys.create()` /
+    # `ApiKeys.rotate()`. List/get responses omit it (server stores only
+    # a peppered hash and cannot re-issue).
+    key: Optional[str] = None
 
 
 # ---------------------------------------------------------------------------
@@ -489,9 +532,14 @@ __all__ = [
     "ContactProperty",
     "ImportContactsResult",
     "Segment",
+    "SegmentComparator",
+    "SegmentCondition",
+    "SegmentOperator",
     "SegmentPreviewResult",
+    "SegmentRules",
     "Template",
     "TemplatePreset",
+    "CreateWebhookResult",
     "Webhook",
     "WebhookDelivery",
     "Broadcast",