posthook-python 1.0.0__py3-none-any.whl

posthook/__init__.py

@@ -0,0 +1,73 @@
+"""Posthook Python SDK — schedule, manage, and verify webhooks."""
+
+from ._client import AsyncPosthook, Posthook
+from ._errors import (
+    AuthenticationError,
+    BadRequestError,
+    ForbiddenError,
+    InternalServerError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PosthookConnectionError,
+    PosthookError,
+    RateLimitError,
+    SignatureVerificationError,
+)
+from ._models import (
+    SORT_BY_CREATED_AT,
+    SORT_BY_POST_AT,
+    SORT_ORDER_ASC,
+    SORT_ORDER_DESC,
+    STATUS_COMPLETED,
+    STATUS_FAILED,
+    STATUS_PENDING,
+    STATUS_RETRY,
+    STRATEGY_EXPONENTIAL,
+    STRATEGY_FIXED,
+    BulkActionResult,
+    Delivery,
+    Hook,
+    HookRetryOverride,
+    QuotaInfo,
+)
+from ._resources._signatures import SignaturesService, create_signatures
+from ._version import VERSION as __version__
+
+__all__ = [
+    # Clients
+    "Posthook",
+    "AsyncPosthook",
+    # Models
+    "Hook",
+    "HookRetryOverride",
+    "QuotaInfo",
+    "BulkActionResult",
+    "Delivery",
+    # Resources
+    "SignaturesService",
+    "create_signatures",
+    # Constants
+    "STATUS_PENDING",
+    "STATUS_RETRY",
+    "STATUS_COMPLETED",
+    "STATUS_FAILED",
+    "SORT_BY_POST_AT",
+    "SORT_BY_CREATED_AT",
+    "SORT_ORDER_ASC",
+    "SORT_ORDER_DESC",
+    "STRATEGY_FIXED",
+    "STRATEGY_EXPONENTIAL",
+    # Errors
+    "PosthookError",
+    "BadRequestError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "PayloadTooLargeError",
+    "RateLimitError",
+    "InternalServerError",
+    "PosthookConnectionError",
+    "SignatureVerificationError",
+    # Version
+    "__version__",
+]

posthook/_client.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from ._errors import AuthenticationError
+from ._http import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    AsyncHttpClient,
+    SyncHttpClient,
+)
+from ._resources._hooks import AsyncHooksService, HooksService
+from ._resources._signatures import SignaturesService
+
+
+class Posthook:
+    """Synchronous Posthook API client.
+
+    Args:
+        api_key: Your Posthook API key. Falls back to the ``POSTHOOK_API_KEY``
+            environment variable if not provided.
+        base_url: Override the API base URL.
+        timeout: Request timeout in seconds.
+        signing_key: Key for webhook signature verification. Falls back to
+            ``POSTHOOK_SIGNING_KEY`` env var.
+        http_client: A custom ``httpx.Client`` instance.
+    """
+
+    hooks: HooksService
+    signatures: SignaturesService
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        signing_key: str | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("POSTHOOK_API_KEY", "")
+        if not resolved_key:
+            raise AuthenticationError(
+                "No API key provided. Pass api_key to the Posthook constructor "
+                "or set the POSTHOOK_API_KEY environment variable."
+            )
+
+        resolved_signing_key = signing_key or os.environ.get("POSTHOOK_SIGNING_KEY")
+
+        self._http = SyncHttpClient(
+            resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.hooks = HooksService(self._http)
+        self.signatures = SignaturesService(resolved_signing_key)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> Posthook:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncPosthook:
+    """Asynchronous Posthook API client.
+
+    Args:
+        api_key: Your Posthook API key. Falls back to the ``POSTHOOK_API_KEY``
+            environment variable if not provided.
+        base_url: Override the API base URL.
+        timeout: Request timeout in seconds.
+        signing_key: Key for webhook signature verification. Falls back to
+            ``POSTHOOK_SIGNING_KEY`` env var.
+        http_client: A custom ``httpx.AsyncClient`` instance.
+    """
+
+    hooks: AsyncHooksService
+    signatures: SignaturesService
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        signing_key: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("POSTHOOK_API_KEY", "")
+        if not resolved_key:
+            raise AuthenticationError(
+                "No API key provided. Pass api_key to the AsyncPosthook constructor "
+                "or set the POSTHOOK_API_KEY environment variable."
+            )
+
+        resolved_signing_key = signing_key or os.environ.get("POSTHOOK_SIGNING_KEY")
+
+        self._http = AsyncHttpClient(
+            resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.hooks = AsyncHooksService(self._http)
+        self.signatures = SignaturesService(resolved_signing_key)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncPosthook:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

posthook/_errors.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+
+class PosthookError(Exception):
+    """Base error class for all Posthook SDK errors."""
+
+    status_code: int | None
+    code: str
+    message: str
+    headers: dict[str, str] | None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str = "",
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.headers = headers
+
+    def __repr__(self) -> str:
+        cls = self.__class__.__name__
+        return f"{cls}(message={self.message!r}, status_code={self.status_code})"
+
+
+class BadRequestError(PosthookError):
+    """Raised for HTTP 400 responses."""
+
+    def __init__(self, message: str, headers: dict[str, str] | None = None) -> None:
+        super().__init__(message, status_code=400, code="bad_request", headers=headers)
+
+
+class AuthenticationError(PosthookError):
+    """Raised for HTTP 401 responses."""
+
+    def __init__(self, message: str, headers: dict[str, str] | None = None) -> None:
+        super().__init__(message, status_code=401, code="authentication_error", headers=headers)
+
+
+class ForbiddenError(PosthookError):
+    """Raised for HTTP 403 responses."""
+
+    def __init__(self, message: str, headers: dict[str, str] | None = None) -> None:
+        super().__init__(message, status_code=403, code="forbidden", headers=headers)
+
+
+class NotFoundError(PosthookError):
+    """Raised for HTTP 404 responses."""
+
+    def __init__(self, message: str, headers: dict[str, str] | None = None) -> None:
+        super().__init__(message, status_code=404, code="not_found", headers=headers)
+
+
+class PayloadTooLargeError(PosthookError):
+    """Raised for HTTP 413 responses."""
+
+    def __init__(self, message: str, headers: dict[str, str] | None = None) -> None:
+        super().__init__(message, status_code=413, code="payload_too_large", headers=headers)
+
+
+class RateLimitError(PosthookError):
+    """Raised for HTTP 429 responses."""
+
+    def __init__(self, message: str, headers: dict[str, str] | None = None) -> None:
+        super().__init__(message, status_code=429, code="rate_limit_exceeded", headers=headers)
+
+
+class InternalServerError(PosthookError):
+    """Raised for HTTP 5xx responses."""
+
+    def __init__(
+        self, message: str, status_code: int = 500, headers: dict[str, str] | None = None
+    ) -> None:
+        super().__init__(message, status_code=status_code, code="internal_error", headers=headers)
+
+
+class PosthookConnectionError(PosthookError):
+    """Raised for network or timeout errors.
+
+    Named ``PosthookConnectionError`` to avoid shadowing the builtin
+    ``ConnectionError``.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="connection_error")
+
+
+class SignatureVerificationError(PosthookError):
+    """Raised when webhook signature verification fails."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="signature_verification_error")
+
+
+def _create_error(
+    status_code: int,
+    message: str,
+    headers: dict[str, str] | None = None,
+) -> PosthookError:
+    """Create the appropriate error subclass for the given HTTP status code."""
+    if status_code == 400:
+        return BadRequestError(message, headers)
+    if status_code == 401:
+        return AuthenticationError(message, headers)
+    if status_code == 403:
+        return ForbiddenError(message, headers)
+    if status_code == 404:
+        return NotFoundError(message, headers)
+    if status_code == 413:
+        return PayloadTooLargeError(message, headers)
+    if status_code == 429:
+        return RateLimitError(message, headers)
+    if status_code >= 500:
+        return InternalServerError(message, status_code, headers)
+    return PosthookError(message, status_code=status_code, code="unknown_error", headers=headers)

posthook/_http.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import logging
+import platform
+import time
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from ._errors import PosthookConnectionError, PosthookError, _create_error
+from ._models import QuotaInfo
+from ._version import VERSION
+
+logger = logging.getLogger("posthook")
+
+DEFAULT_BASE_URL = "https://api.posthook.io"
+DEFAULT_TIMEOUT = 30.0
+
+
+def _parse_quota(headers: httpx.Headers) -> QuotaInfo | None:
+    limit = headers.get("posthook-hookquota-limit")
+    if not limit:
+        return None
+
+    resets_at: datetime | None = None
+    raw_resets = headers.get("posthook-hookquota-resets-at", "")
+    if raw_resets:
+        try:
+            resets_at = datetime.fromisoformat(raw_resets.replace("Z", "+00:00"))
+        except ValueError:
+            pass
+
+    return QuotaInfo(
+        limit=int(limit),
+        usage=int(headers.get("posthook-hookquota-usage", "0")),
+        remaining=int(headers.get("posthook-hookquota-remaining", "0")),
+        resets_at=resets_at,
+    )
+
+
+_USER_AGENT = (
+    f"posthook-python/{VERSION}"
+    f" (Python {platform.python_version()}; {platform.system()})"
+)
+
+
+def _headers(api_key: str) -> dict[str, str]:
+    return {
+        "X-API-Key": api_key,
+        "User-Agent": _USER_AGENT,
+        "Content-Type": "application/json",
+    }
+
+
+def _unwrap_data(body: dict[str, Any]) -> Any:
+    """Extract 'data' from the API response envelope."""
+    return body.get("data")
+
+
+def _extract_error_message(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+        return body.get("error", f"HTTP {response.status_code}")
+    except Exception:
+        return f"HTTP {response.status_code}"
+
+
+class SyncHttpClient:
+    """Synchronous HTTP client wrapping httpx.Client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(
+            timeout=timeout,
+            headers=_headers(api_key),
+        )
+        if http_client is not None:
+            self._client.headers.update(_headers(api_key))
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> tuple[Any, httpx.Headers]:
+        url = f"{self._base_url}{path}"
+
+        # Filter out None values from params
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        start = time.monotonic()
+        try:
+            kwargs: dict[str, Any] = {"json": json, "params": params}
+            if timeout is not None:
+                kwargs["timeout"] = timeout
+            response = self._client.request(
+                method, url, **kwargs
+            )
+            elapsed = time.monotonic() - start
+            logger.debug("%s %s -> %d (%.3fs)", method, path, response.status_code, elapsed)
+
+            if response.status_code >= 400:
+                msg = _extract_error_message(response)
+                hdrs = dict(response.headers)
+                raise _create_error(response.status_code, msg, hdrs)
+
+            body = response.json()
+            return body, response.headers
+
+        except PosthookError:
+            raise
+        except httpx.TimeoutException as exc:
+            raise PosthookConnectionError(f"Request timed out: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise PosthookConnectionError(f"Network error: {exc}") from exc
+
+    def request_data(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> tuple[Any, httpx.Headers]:
+        """Make a request and return (unwrapped_data, headers)."""
+        body, headers = self.request(method, path, json=json, params=params, timeout=timeout)
+        return _unwrap_data(body), headers
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client wrapping httpx.AsyncClient."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            timeout=timeout,
+            headers=_headers(api_key),
+        )
+        if http_client is not None:
+            self._client.headers.update(_headers(api_key))
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> tuple[Any, httpx.Headers]:
+        url = f"{self._base_url}{path}"
+
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        start = time.monotonic()
+        try:
+            kwargs: dict[str, Any] = {"json": json, "params": params}
+            if timeout is not None:
+                kwargs["timeout"] = timeout
+            response = await self._client.request(
+                method, url, **kwargs
+            )
+            elapsed = time.monotonic() - start
+            logger.debug("%s %s -> %d (%.3fs)", method, path, response.status_code, elapsed)
+
+            if response.status_code >= 400:
+                msg = _extract_error_message(response)
+                hdrs = dict(response.headers)
+                raise _create_error(response.status_code, msg, hdrs)
+
+            body = response.json()
+            return body, response.headers
+
+        except PosthookError:
+            raise
+        except httpx.TimeoutException as exc:
+            raise PosthookConnectionError(f"Request timed out: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise PosthookConnectionError(f"Network error: {exc}") from exc
+
+    async def request_data(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> tuple[Any, httpx.Headers]:
+        body, headers = await self.request(method, path, json=json, params=params, timeout=timeout)
+        return _unwrap_data(body), headers
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()

posthook/_models.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+# Hook status constants.
+STATUS_PENDING = "pending"
+STATUS_RETRY = "retry"
+STATUS_COMPLETED = "completed"
+STATUS_FAILED = "failed"
+
+# Sort field constants.
+SORT_BY_POST_AT = "postAt"
+SORT_BY_CREATED_AT = "createdAt"
+
+# Sort order constants.
+SORT_ORDER_ASC = "ASC"
+SORT_ORDER_DESC = "DESC"
+
+# Retry strategy constants.
+STRATEGY_FIXED = "fixed"
+STRATEGY_EXPONENTIAL = "exponential"
+
+
+def _parse_dt(value: str) -> datetime:
+    """Parse an RFC 3339 timestamp string into a datetime."""
+    if not value:
+        return datetime.min.replace(tzinfo=timezone.utc)
+    # Handle "Z" suffix which Python's fromisoformat doesn't support before 3.11
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    return datetime.fromisoformat(value)
+
+
+@dataclass(frozen=True)
+class QuotaInfo:
+    """Hook quota information parsed from response headers."""
+
+    limit: int
+    usage: int
+    remaining: int
+    resets_at: datetime | None
+
+
+@dataclass(frozen=True)
+class HookRetryOverride:
+    """Per-hook retry configuration that overrides project defaults."""
+
+    min_retries: int
+    delay_secs: int
+    strategy: str
+    backoff_factor: float | None = None
+    max_delay_secs: int | None = None
+    jitter: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> HookRetryOverride:
+        return cls(
+            min_retries=data["minRetries"],
+            delay_secs=data["delaySecs"],
+            strategy=data["strategy"],
+            backoff_factor=data.get("backoffFactor"),
+            max_delay_secs=data.get("maxDelaySecs"),
+            jitter=data.get("jitter", False),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "minRetries": self.min_retries,
+            "delaySecs": self.delay_secs,
+            "strategy": self.strategy,
+            "jitter": self.jitter,
+        }
+        if self.backoff_factor is not None:
+            d["backoffFactor"] = self.backoff_factor
+        if self.max_delay_secs is not None:
+            d["maxDelaySecs"] = self.max_delay_secs
+        return d
+
+
+@dataclass(frozen=True)
+class HookSequenceData:
+    """Sequence context for a hook that is part of a sequence."""
+
+    sequence_id: str
+    step_name: str
+    sequence_last_run_at: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> HookSequenceData:
+        return cls(
+            sequence_id=data["sequenceID"],
+            step_name=data["stepName"],
+            sequence_last_run_at=data["sequenceLastRunAt"],
+        )
+
+
+@dataclass
+class Hook:
+    """A scheduled webhook as returned by the Posthook API."""
+
+    id: str
+    path: str
+    data: Any
+    post_at: datetime
+    status: str
+    post_duration_seconds: float
+    created_at: datetime
+    updated_at: datetime
+    domain: str | None = None
+    attempts: int = 0
+    failure_error: str = ""
+    sequence_data: HookSequenceData | None = None
+    retry_override: HookRetryOverride | None = None
+    quota: QuotaInfo | None = field(default=None)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Hook:
+        seq = data.get("sequenceData")
+        retry = data.get("retryOverride")
+        return cls(
+            id=data["id"],
+            path=data["path"],
+            data=data.get("data"),
+            post_at=_parse_dt(data["postAt"]),
+            status=data["status"],
+            post_duration_seconds=data.get("postDurationSeconds", 0.0),
+            created_at=_parse_dt(data.get("createdAt", "")),
+            updated_at=_parse_dt(data.get("updatedAt", "")),
+            domain=data.get("domain"),
+            attempts=data.get("attempts", 0),
+            failure_error=data.get("failureError", ""),
+            sequence_data=HookSequenceData.from_dict(seq) if seq else None,
+            retry_override=HookRetryOverride.from_dict(retry) if retry else None,
+        )
+
+
+@dataclass(frozen=True)
+class BulkActionResult:
+    """Result of a bulk action on hooks."""
+
+    affected: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BulkActionResult:
+        return cls(affected=data.get("affected", 0))
+
+
+@dataclass(frozen=True)
+class Delivery:
+    """A parsed and verified webhook delivery."""
+
+    hook_id: str
+    timestamp: int
+    path: str
+    data: Any
+    body: bytes
+    post_at: datetime
+    posted_at: datetime
+    created_at: datetime
+    updated_at: datetime