onefirstflock-donations-embed 1.0.0__py3-none-any.whl

donations_embed/__init__.py

@@ -0,0 +1,157 @@
+"""Server-side Python SDK for the 1st Flock Donations Embed API.
+
+This package provides:
+
+- :class:`Client` — async client for the Customer SDK endpoints
+  (donations, recurring, webhook test).
+- :func:`verify_webhook` / :func:`verify_webhook_async` — constant-time
+  HMAC-SHA256 signature verification for inbound webhook deliveries,
+  returning a parsed :data:`WebhookEvent`.
+- :func:`idempotency_key` — convenience generator for ``Idempotency-Key``
+  header values.
+- A full set of typed Pydantic models for every documented request,
+  response, and webhook payload.
+
+Quickstart::
+
+    >>> from donations_embed import Client, verify_webhook
+    >>> async with Client(api_key="sk_test_…") as client:
+    ...     donation = await client.get_donation("8a1b9c4d-1234-4321-9abc-def012345678")
+    ...     refund = await client.refund_donation(donation.id, amount_cents=1000)
+
+    >>> # In an inbound webhook handler
+    >>> event = verify_webhook(
+    ...     body=raw_body_bytes,
+    ...     signature=request.headers["Flock-Signature"],
+    ...     secret=os.environ["FLOCK_WEBHOOK_SECRET"],
+    ... )
+
+See the README for FastAPI / Starlette / script examples and detailed
+error-handling guidance.
+"""
+
+from __future__ import annotations
+
+from donations_embed._idempotency import idempotency_key
+from donations_embed._version import __version__
+from donations_embed.client import Client
+from donations_embed.errors import (
+    ApiError,
+    AuthError,
+    BadGatewayError,
+    ConflictError,
+    DonationsEmbedError,
+    ForbiddenError,
+    GoneError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+    ValidationError,
+    WebhookError,
+    WebhookFormatError,
+    WebhookSignatureError,
+    WebhookTimestampError,
+)
+from donations_embed.models import (
+    Donation,
+    DonationCompletedEvent,
+    DonationCreatedEvent,
+    DonationCreatedEventObject,
+    DonationEventDonor,
+    DonationEventFundAllocation,
+    DonationEventObject,
+    DonationFailedEvent,
+    DonationListResponse,
+    DonationRefundedEvent,
+    DonationRefundedEventObject,
+    DonationStatus,
+    EventPaymentMethod,
+    FundAllocation,
+    KeyFrozenEvent,
+    KeyFrozenEventObject,
+    KeyFrozenReason,
+    PaymentMethodType,
+    Recurring,
+    RecurringActivatedEvent,
+    RecurringCancelledEvent,
+    RecurringCancelledEventObject,
+    RecurringCancelResponse,
+    RecurringEventObject,
+    RecurringInterval,
+    RecurringListResponse,
+    RecurringPaymentFailedEvent,
+    RecurringPaymentSucceededEvent,
+    RecurringStatus,
+    RefundRequest,
+    RefundResponse,
+    WebhookEnvelope,
+    WebhookEvent,
+    WebhookEventType,
+    WebhookTestRequest,
+    WebhookTestResponse,
+)
+from donations_embed.webhooks import (
+    DEFAULT_TOLERANCE_SECONDS,
+    verify_webhook,
+    verify_webhook_async,
+)
+
+__all__ = [
+    "DEFAULT_TOLERANCE_SECONDS",
+    "ApiError",
+    "AuthError",
+    "BadGatewayError",
+    "Client",
+    "ConflictError",
+    "Donation",
+    "DonationCompletedEvent",
+    "DonationCreatedEvent",
+    "DonationCreatedEventObject",
+    "DonationEventDonor",
+    "DonationEventFundAllocation",
+    "DonationEventObject",
+    "DonationFailedEvent",
+    "DonationListResponse",
+    "DonationRefundedEvent",
+    "DonationRefundedEventObject",
+    "DonationStatus",
+    "DonationsEmbedError",
+    "EventPaymentMethod",
+    "ForbiddenError",
+    "FundAllocation",
+    "GoneError",
+    "KeyFrozenEvent",
+    "KeyFrozenEventObject",
+    "KeyFrozenReason",
+    "NotFoundError",
+    "PaymentMethodType",
+    "RateLimitError",
+    "Recurring",
+    "RecurringActivatedEvent",
+    "RecurringCancelResponse",
+    "RecurringCancelledEvent",
+    "RecurringCancelledEventObject",
+    "RecurringEventObject",
+    "RecurringInterval",
+    "RecurringListResponse",
+    "RecurringPaymentFailedEvent",
+    "RecurringPaymentSucceededEvent",
+    "RecurringStatus",
+    "RefundRequest",
+    "RefundResponse",
+    "ServiceUnavailableError",
+    "ValidationError",
+    "WebhookEnvelope",
+    "WebhookError",
+    "WebhookEvent",
+    "WebhookEventType",
+    "WebhookFormatError",
+    "WebhookSignatureError",
+    "WebhookTestRequest",
+    "WebhookTestResponse",
+    "WebhookTimestampError",
+    "__version__",
+    "idempotency_key",
+    "verify_webhook",
+    "verify_webhook_async",
+]

donations_embed/_http.py

@@ -0,0 +1,318 @@
+"""Internal HTTP transport — typed errors, retry, and idempotency forwarding.
+
+The :class:`HttpTransport` wraps an ``httpx.AsyncClient`` and applies the
+SDK's cross-cutting policies on every request:
+
+- Adds the ``Authorization: Bearer <api_key>`` header.
+- Adds a ``User-Agent`` header identifying the SDK + Python version so the
+  platform can attribute traffic and warn customers running EOL versions.
+- Forwards an optional ``Idempotency-Key`` header.
+- Maps non-2xx responses to typed exceptions
+  (:class:`ApiError` and subclasses).
+- Retries 5xx and 429 responses with exponential backoff + jitter via
+  :mod:`tenacity`.
+
+The transport is internal — public callers always interact through
+:class:`donations_embed.client.Client`.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import platform
+import sys
+from typing import Any
+
+import httpx
+from tenacity import (
+    AsyncRetrying,
+    RetryError,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_random_exponential,
+)
+
+from donations_embed._version import __version__
+from donations_embed.errors import (
+    ApiError,
+    AuthError,
+    BadGatewayError,
+    ConflictError,
+    ForbiddenError,
+    GoneError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+
+DEFAULT_BASE_URL = "https://api.1stflock.com"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+_RETRYABLE_STATUS_CODES = frozenset({500, 502, 503, 504})
+_RETRYABLE_HTTPX_EXCEPTIONS = (
+    httpx.ConnectError,
+    httpx.ConnectTimeout,
+    httpx.ReadTimeout,
+    httpx.WriteTimeout,
+    httpx.RemoteProtocolError,
+)
+
+
+def _build_user_agent() -> str:
+    """Build the ``User-Agent`` string for outbound requests."""
+    py = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    impl = platform.python_implementation().lower()
+    return f"onefirstflock-donations-embed/{__version__} python/{py} ({impl})"
+
+
+class _RetryableStatusError(Exception):
+    """Internal sentinel — wraps a 5xx response so :mod:`tenacity` can retry it.
+
+    We deliberately do NOT make :class:`ApiError` itself retryable, because
+    we want callers to see a typed final error after exhaustion rather than
+    a tenacity-internal type.
+    """
+
+    def __init__(self, response: httpx.Response) -> None:
+        self.response = response
+        super().__init__(f"retryable {response.status_code} from {response.request.url}")
+
+
+class HttpTransport:
+    """Async HTTP transport used by :class:`donations_embed.client.Client`.
+
+    Args:
+        api_key: The Bearer token (an ``sk_live_*`` or ``sk_test_*``
+            secret key).
+        base_url: API base URL; trailing slashes are tolerated.
+        http_client: Optional pre-configured ``httpx.AsyncClient``. Pass
+            one in to share a connection pool with other code, customize
+            proxies, or inject a transport for testing. The transport will
+            **not** close a caller-supplied client.
+        max_retries: Maximum retry attempts for retryable failures
+            (5xx + transient network errors). The original attempt counts
+            as one — ``max_retries=3`` performs at most 4 requests.
+        timeout: Per-request timeout in seconds, applied to connect, read,
+            write, and pool acquisition.
+        logger: Optional :class:`logging.Logger` for low-cardinality
+            request/retry events. Set to ``None`` (default) to suppress
+            logging entirely.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        http_client: httpx.AsyncClient | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=timeout)
+        self._logger = logger or logging.getLogger("donations_embed")
+        self._user_agent = _build_user_agent()
+
+    # ------------------------------------------------------------------ public
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        """Send a request and return the parsed JSON response body.
+
+        Returns ``None`` for 204 responses; raises a typed
+        :class:`ApiError` subclass on every non-2xx status code that
+        survives the retry policy.
+        """
+        url = f"{self._base_url}{path}"
+        headers = self._build_headers(idempotency_key)
+
+        retrying = AsyncRetrying(
+            stop=stop_after_attempt(self._max_retries + 1),
+            wait=wait_random_exponential(multiplier=0.25, max=20),
+            retry=retry_if_exception_type(_RETRYABLE_STATUS_CODES_TYPE),
+            reraise=True,
+        )
+
+        response: httpx.Response | None = None
+        try:
+            async for attempt in retrying:
+                with attempt:
+                    response = await self._send_once(
+                        method, url, headers=headers, params=params, json_body=json_body
+                    )
+                    if response.status_code in _RETRYABLE_STATUS_CODES:
+                        # Retryable status — wrap in our sentinel and let
+                        # tenacity decide. Don't drain the body until we're
+                        # ready to surface the error, so the next attempt
+                        # gets a clean response object.
+                        raise _RetryableStatusError(response)
+        except RetryError as exc:
+            # Should not happen with reraise=True, but keep the branch for
+            # static analyzers that don't see through tenacity's internals.
+            last_result = exc.last_attempt.result()
+            assert isinstance(last_result, httpx.Response)
+            raise self._build_error_from_response(last_result) from exc
+        except _RetryableStatusError as exc:
+            raise self._build_error_from_response(exc.response) from exc
+
+        # ``response`` is guaranteed to be set: tenacity raised on each
+        # failed attempt; on success we fell through with the assignment.
+        assert response is not None
+
+        if response.status_code >= 400:
+            raise self._build_error_from_response(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        try:
+            return response.json()
+        except json.JSONDecodeError as exc:  # pragma: no cover — server contract violation
+            raise ApiError(
+                response.status_code,
+                f"response body did not parse as JSON: {exc}",
+                request_id=response.headers.get("x-request-id"),
+            ) from exc
+
+    async def aclose(self) -> None:
+        """Close the underlying ``httpx.AsyncClient`` if we own it."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    # ----------------------------------------------------------------- private
+
+    def _build_headers(self, idempotency_key: str | None) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": self._user_agent,
+            "Accept": "application/json",
+        }
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+        return headers
+
+    async def _send_once(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str],
+        params: dict[str, Any] | None,
+        json_body: Any | None,
+    ) -> httpx.Response:
+        try:
+            return await self._client.request(
+                method,
+                url,
+                params=_drop_none_params(params),
+                json=json_body,
+                headers=headers,
+                timeout=self._timeout,
+            )
+        except _RETRYABLE_HTTPX_EXCEPTIONS as exc:
+            # tenacity sees the raised exception type and will retry — we
+            # log at DEBUG so production deployments don't drown in transient
+            # network noise.
+            self._logger.debug(
+                "donations-embed: transport error on %s %s: %s",
+                method,
+                url,
+                exc,
+            )
+            raise
+
+    def _build_error_from_response(self, response: httpx.Response) -> ApiError:
+        """Map a 4xx / 5xx response onto the right :class:`ApiError` subclass."""
+        status = response.status_code
+        request_id = response.headers.get("x-request-id")
+        retry_after = _parse_retry_after(response.headers.get("retry-after"))
+
+        code: str | None = None
+        message: str = response.reason_phrase or f"HTTP {status}"
+        details: dict[str, Any] | None = None
+        try:
+            payload = response.json()
+            if isinstance(payload, dict):
+                raw_code = payload.get("code")
+                raw_message = payload.get("message")
+                raw_details = payload.get("details")
+                if isinstance(raw_code, str):
+                    code = raw_code
+                if isinstance(raw_message, str):
+                    message = raw_message
+                if isinstance(raw_details, dict):
+                    details = raw_details
+        except (json.JSONDecodeError, ValueError):  # pragma: no cover — non-JSON error body
+            pass
+
+        common: dict[str, Any] = {
+            "code": code,
+            "details": details,
+            "request_id": request_id,
+        }
+
+        if status == 401:
+            return AuthError(status, message, **common)
+        if status == 403:
+            return ForbiddenError(status, message, **common)
+        if status == 404:
+            return NotFoundError(status, message, **common)
+        if status in (400, 422):
+            return ValidationError(status, message, **common)
+        if status == 409:
+            return ConflictError(status, message, **common)
+        if status == 410:
+            return GoneError(status, message, **common)
+        if status == 429:
+            return RateLimitError(status, message, retry_after=retry_after, **common)
+        if status == 502:
+            return BadGatewayError(status, message, **common)
+        if status == 503:
+            return ServiceUnavailableError(status, message, **common)
+        return ApiError(status, message, **common)
+
+
+def _drop_none_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Strip ``None`` values from query params so they aren't serialized as the literal string ``"None"``."""
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    """Parse a numeric ``Retry-After`` value into seconds.
+
+    The HTTP spec also allows an HTTP-date format. We accept seconds (as
+    integer or float) and silently return ``None`` for date-based values
+    rather than synthesizing a synthetic delay — callers can pivot on
+    ``RateLimitError.retry_after is None`` to fall back to a default.
+    """
+    if value is None:
+        return None
+    try:
+        return float(value.strip())
+    except ValueError:
+        return None
+
+
+# Tuple form for tenacity's ``retry_if_exception_type`` predicate. We have
+# to define this at module scope because tenacity inspects it at decorator-
+# build time, and we want network errors AND our retryable-status sentinel
+# both to trigger a retry.
+_RETRYABLE_STATUS_CODES_TYPE: tuple[type[BaseException], ...] = (
+    _RetryableStatusError,
+    *_RETRYABLE_HTTPX_EXCEPTIONS,
+)

donations_embed/_idempotency.py

@@ -0,0 +1,53 @@
+"""Idempotency-key helper.
+
+The platform's idempotency contract: replaying a request with the same
+``Idempotency-Key`` returns the original response without performing the
+side effect a second time. Keys are scoped per (``api_key``, ``endpoint``)
+and persisted for 24 hours.
+
+This module exposes :func:`idempotency_key`, a tiny convenience wrapper
+that prefixes a fresh UUID4 with a use-case tag so observability tooling
+can group related retries (e.g. all ``refund:*`` keys belong to the refund
+flow). Callers MAY also supply their own keys directly.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+
+# Match the OpenAPI ``Idempotency-Key`` schema constraint (max 255 chars).
+_MAX_KEY_LENGTH = 255
+
+# Conservative validation for the use-case tag — keep it printable ASCII
+# so the resulting key fits cleanly in HTTP headers and log lines.
+_USE_CASE_RE = re.compile(r"^[a-z0-9][a-z0-9_\-.]*$")
+
+
+def idempotency_key(use_case: str) -> str:
+    """Generate a fresh idempotency key tagged with a use-case prefix.
+
+    The returned key has the form ``"<use_case>:<uuid4>"``, e.g.
+    ``"refund:1f2dab36-2a55-4f11-bdc8-2a2a4a95b001"``.
+
+    Args:
+        use_case: A short tag describing the operation
+            (``"refund"``, ``"cancel-recurring"``, ``"replay-confirm"``).
+            Must be lowercase ASCII letters, digits, ``_``, ``-``, or ``.``;
+            an empty or oddly-shaped tag raises :class:`ValueError`.
+
+    Returns:
+        A string suitable for the ``Idempotency-Key`` HTTP header.
+    """
+    if not use_case or not _USE_CASE_RE.match(use_case):
+        raise ValueError(
+            "idempotency use_case must be a non-empty lowercase ASCII tag "
+            "matching ^[a-z0-9][a-z0-9_\\-.]*$"
+        )
+    key = f"{use_case}:{uuid.uuid4()}"
+    if len(key) > _MAX_KEY_LENGTH:
+        # Practically impossible (use_case + UUID4 is well under 255), but
+        # we enforce the contract explicitly so a future caller can't blow
+        # past the limit by passing a 250-char tag.
+        raise ValueError(f"generated idempotency key exceeds {_MAX_KEY_LENGTH} chars")
+    return key

donations_embed/_version.py

@@ -0,0 +1,9 @@
+"""Single source of truth for the SDK version.
+
+Kept in its own module so internal modules (e.g. :mod:`donations_embed._http`)
+can import it without dragging in the public API.
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"