poststack 0.4.0__py3-none-any.whl

poststack/__init__.py

@@ -0,0 +1,159 @@
+"""PostStack Python SDK.
+
+Public API::
+
+    from poststack import PostStack, AsyncPostStack, PostStackError
+
+    client = PostStack(api_key="sk_live_...")
+    client.emails.send({"from": "a@b.com", "to": ["c@d.com"], "subject": "hi"})
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._client import (
+    DEFAULT_BASE_URL,
+    AsyncPostStackClient,
+    PostStackClient,
+)
+from ._errors import APIError, PostStackError
+from .resources import (
+    ApiKeysResource,
+    AsyncApiKeysResource,
+    AsyncBroadcastsResource,
+    AsyncContactPropertiesResource,
+    AsyncContactsResource,
+    AsyncDomainsResource,
+    AsyncEmailsResource,
+    AsyncEmailValidationsResource,
+    AsyncMailboxesResource,
+    AsyncSegmentsResource,
+    AsyncSignupFormsResource,
+    AsyncSubscriptionTopicsResource,
+    AsyncSuppressionsResource,
+    AsyncTemplatesResource,
+    AsyncWebhooksResource,
+    AsyncWorkflowsResource,
+    BroadcastsResource,
+    ContactPropertiesResource,
+    ContactsResource,
+    DomainsResource,
+    EmailsResource,
+    EmailValidationsResource,
+    MailboxesResource,
+    SegmentsResource,
+    SignupFormsResource,
+    SubscriptionTopicsResource,
+    SuppressionsResource,
+    TemplatesResource,
+    WebhooksResource,
+    WorkflowsResource,
+)
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "PostStack",
+    "AsyncPostStack",
+    "PostStackError",
+    "APIError",
+    "__version__",
+]
+
+
+class PostStack:
+    """Synchronous PostStack client.
+
+    Example::
+
+        client = PostStack(api_key="sk_live_...")
+        client.emails.send({
+            "from": "hello@example.com",
+            "to": ["user@example.com"],
+            "subject": "Hello",
+            "html": "<p>Hi</p>",
+        })
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = PostStackClient(
+            api_key=api_key, base_url=base_url, timeout=timeout
+        )
+        self.emails = EmailsResource(self._client)
+        self.domains = DomainsResource(self._client)
+        self.contacts = ContactsResource(self._client)
+        self.contact_properties = ContactPropertiesResource(self._client)
+        self.segments = SegmentsResource(self._client)
+        self.templates = TemplatesResource(self._client)
+        self.webhooks = WebhooksResource(self._client)
+        self.broadcasts = BroadcastsResource(self._client)
+        self.suppressions = SuppressionsResource(self._client)
+        self.api_keys = ApiKeysResource(self._client)
+        self.mailboxes = MailboxesResource(self._client)
+        self.subscription_topics = SubscriptionTopicsResource(self._client)
+        self.workflows = WorkflowsResource(self._client)
+        self.signup_forms = SignupFormsResource(self._client)
+        self.email_validations = EmailValidationsResource(self._client)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "PostStack":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncPostStack:
+    """Asynchronous PostStack client.
+
+    Example::
+
+        async with AsyncPostStack(api_key="sk_live_...") as client:
+            await client.emails.send({...})
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = AsyncPostStackClient(
+            api_key=api_key, base_url=base_url, timeout=timeout
+        )
+        self.emails = AsyncEmailsResource(self._client)
+        self.domains = AsyncDomainsResource(self._client)
+        self.contacts = AsyncContactsResource(self._client)
+        self.contact_properties = AsyncContactPropertiesResource(self._client)
+        self.segments = AsyncSegmentsResource(self._client)
+        self.templates = AsyncTemplatesResource(self._client)
+        self.webhooks = AsyncWebhooksResource(self._client)
+        self.broadcasts = AsyncBroadcastsResource(self._client)
+        self.suppressions = AsyncSuppressionsResource(self._client)
+        self.api_keys = AsyncApiKeysResource(self._client)
+        self.mailboxes = AsyncMailboxesResource(self._client)
+        self.subscription_topics = AsyncSubscriptionTopicsResource(self._client)
+        self.workflows = AsyncWorkflowsResource(self._client)
+        self.signup_forms = AsyncSignupFormsResource(self._client)
+        self.email_validations = AsyncEmailValidationsResource(self._client)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncPostStack":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+
+# Re-export for advanced callers.
+_: Optional[type] = None  # noqa: E305 - keeps ruff/mypy happy with Optional import

poststack/_client.py

@@ -0,0 +1,333 @@
+"""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)

poststack/_errors.py

@@ -0,0 +1,33 @@
+"""Errors raised by the PostStack SDK."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class PostStackError(Exception):
+    """Raised when the PostStack API returns a non-2xx response."""
+
+    def __init__(
+        self,
+        status_code: int,
+        error: str,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(error)
+        self.status_code = status_code
+        self.error = error
+        self.code = code
+        self.request_id = request_id
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return (
+            f"PostStackError(status_code={self.status_code!r}, "
+            f"error={self.error!r}, code={self.code!r}, "
+            f"request_id={self.request_id!r})"
+        )
+
+
+# Alias retained for callers expecting a generic APIError type.
+APIError = PostStackError

poststack/resources/__init__.py

@@ -0,0 +1,59 @@
+"""Resource classes mirroring the PostStack TypeScript SDK."""
+
+from .api_keys import ApiKeysResource, AsyncApiKeysResource
+from .broadcasts import AsyncBroadcastsResource, BroadcastsResource
+from .contact_properties import (
+    AsyncContactPropertiesResource,
+    ContactPropertiesResource,
+)
+from .contacts import AsyncContactsResource, ContactsResource
+from .domains import AsyncDomainsResource, DomainsResource
+from .email_validations import (
+    AsyncEmailValidationsResource,
+    EmailValidationsResource,
+)
+from .emails import AsyncEmailsResource, EmailsResource
+from .mailboxes import AsyncMailboxesResource, MailboxesResource
+from .segments import AsyncSegmentsResource, SegmentsResource
+from .signup_forms import AsyncSignupFormsResource, SignupFormsResource
+from .subscription_topics import (
+    AsyncSubscriptionTopicsResource,
+    SubscriptionTopicsResource,
+)
+from .suppressions import AsyncSuppressionsResource, SuppressionsResource
+from .templates import AsyncTemplatesResource, TemplatesResource
+from .webhooks import AsyncWebhooksResource, WebhooksResource
+from .workflows import AsyncWorkflowsResource, WorkflowsResource
+
+__all__ = [
+    "ApiKeysResource",
+    "AsyncApiKeysResource",
+    "BroadcastsResource",
+    "AsyncBroadcastsResource",
+    "ContactPropertiesResource",
+    "AsyncContactPropertiesResource",
+    "ContactsResource",
+    "AsyncContactsResource",
+    "DomainsResource",
+    "AsyncDomainsResource",
+    "EmailValidationsResource",
+    "AsyncEmailValidationsResource",
+    "EmailsResource",
+    "AsyncEmailsResource",
+    "MailboxesResource",
+    "AsyncMailboxesResource",
+    "SegmentsResource",
+    "AsyncSegmentsResource",
+    "SignupFormsResource",
+    "AsyncSignupFormsResource",
+    "SubscriptionTopicsResource",
+    "AsyncSubscriptionTopicsResource",
+    "SuppressionsResource",
+    "AsyncSuppressionsResource",
+    "TemplatesResource",
+    "AsyncTemplatesResource",
+    "WebhooksResource",
+    "AsyncWebhooksResource",
+    "WorkflowsResource",
+    "AsyncWorkflowsResource",
+]

poststack/resources/api_keys.py

@@ -0,0 +1,63 @@
+"""API keys resource — mirrors packages/sdk/src/resources/api-keys.ts."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from .._client import AsyncPostStackClient, PostStackClient
+
+
+class ApiKeysResource:
+    def __init__(self, client: PostStackClient) -> None:
+        self._client = client
+
+    def create(
+        self, input: Dict[str, Any], *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return self._client.post("/api-keys", input, timeout=timeout)
+
+    def list(
+        self,
+        params: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        return self._client.get("/api-keys", params, timeout=timeout)
+
+    def get(
+        self, id: int, *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return self._client.get(f"/api-keys/{id}", timeout=timeout)
+
+    def revoke(
+        self, id: int, *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return self._client.delete(f"/api-keys/{id}", timeout=timeout)
+
+
+class AsyncApiKeysResource:
+    def __init__(self, client: AsyncPostStackClient) -> None:
+        self._client = client
+
+    async def create(
+        self, input: Dict[str, Any], *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return await self._client.post("/api-keys", input, timeout=timeout)
+
+    async def list(
+        self,
+        params: Optional[Mapping[str, Any]] = None,
+        *,
+        timeout: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        return await self._client.get("/api-keys", params, timeout=timeout)
+
+    async def get(
+        self, id: int, *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return await self._client.get(f"/api-keys/{id}", timeout=timeout)
+
+    async def revoke(
+        self, id: int, *, timeout: Optional[float] = None
+    ) -> Dict[str, Any]:
+        return await self._client.delete(f"/api-keys/{id}", timeout=timeout)