epay 0.1.0__py3-none-any.whl

epay/__init__.py

@@ -0,0 +1,146 @@
+"""ePay Business API client for Python.
+
+Accept payments from every major Ethiopian mobile wallet and bank with one
+integration::
+
+    from epay import Epay
+
+    epay = Epay()  # reads EPAY_SECRET_KEY
+
+    session = epay.payments.initialize(
+        amount="250.00",
+        currency_code="ETB",
+        customer_phone="+251911234567",
+        merchant_reference="order_123",
+    )
+
+    redirect(session["checkoutUrl"])
+
+An async client is available as :class:`AsyncEpay`, and framework webhook
+helpers live in :mod:`epay.integrations`.
+"""
+
+from __future__ import annotations
+
+from ._config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    mode_from_api_key,
+)
+from ._types import (
+    CANCELLABLE_STATUSES,
+    TRANSACTION_STATUSES,
+    WEBHOOK_EVENT_TYPES,
+    EpayMode,
+    InitializedPayment,
+    PaymentProvider,
+    PaymentProviderItem,
+    TimelineEvent,
+    Transaction,
+    TransactionCustomer,
+    TransactionListResponse,
+    TransactionStatus,
+    TransactionTimeline,
+    VerifiedPayment,
+    WebhookEvent,
+    WebhookEventType,
+)
+from ._version import __version__
+from .async_client import AsyncEpay
+from .client import Epay
+from .errors import (
+    EpayAPIError,
+    EpayAuthenticationError,
+    EpayBadRequestError,
+    EpayConfigError,
+    EpayConflictError,
+    EpayConnectionError,
+    EpayError,
+    EpayNotFoundError,
+    EpayPermissionDeniedError,
+    EpayRateLimitError,
+    EpayServerError,
+    EpayTimeoutError,
+    EpayUnprocessableEntityError,
+    EpayValidationError,
+    EpayWebhookSignatureError,
+)
+from .helpers import (
+    MAX_AMOUNT,
+    MAX_LIST_RANGE_DAYS,
+    format_amount,
+    normalize_currency,
+    normalize_phone,
+)
+from .pagination import PAGE_SIZE, AsyncTransactionPage, TransactionPage
+from .webhooks import (
+    SIGNATURE_HEADER,
+    Webhooks,
+    construct_webhook_event,
+    is_known_webhook_event,
+    sign_webhook_payload,
+    verify_webhook_signature,
+)
+
+__all__ = [
+    "__version__",
+    # Clients
+    "Epay",
+    "AsyncEpay",
+    # Configuration
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_TIMEOUT",
+    "mode_from_api_key",
+    # Errors
+    "EpayError",
+    "EpayAPIError",
+    "EpayAuthenticationError",
+    "EpayBadRequestError",
+    "EpayConfigError",
+    "EpayConflictError",
+    "EpayConnectionError",
+    "EpayNotFoundError",
+    "EpayPermissionDeniedError",
+    "EpayRateLimitError",
+    "EpayServerError",
+    "EpayTimeoutError",
+    "EpayUnprocessableEntityError",
+    "EpayValidationError",
+    "EpayWebhookSignatureError",
+    # Helpers
+    "MAX_AMOUNT",
+    "MAX_LIST_RANGE_DAYS",
+    "format_amount",
+    "normalize_currency",
+    "normalize_phone",
+    # Pagination
+    "PAGE_SIZE",
+    "TransactionPage",
+    "AsyncTransactionPage",
+    # Webhooks
+    "SIGNATURE_HEADER",
+    "Webhooks",
+    "construct_webhook_event",
+    "is_known_webhook_event",
+    "sign_webhook_payload",
+    "verify_webhook_signature",
+    # Types
+    "CANCELLABLE_STATUSES",
+    "TRANSACTION_STATUSES",
+    "WEBHOOK_EVENT_TYPES",
+    "EpayMode",
+    "InitializedPayment",
+    "PaymentProvider",
+    "PaymentProviderItem",
+    "TimelineEvent",
+    "Transaction",
+    "TransactionCustomer",
+    "TransactionListResponse",
+    "TransactionStatus",
+    "TransactionTimeline",
+    "VerifiedPayment",
+    "WebhookEvent",
+    "WebhookEventType",
+]

epay/_config.py

@@ -0,0 +1,106 @@
+"""Client configuration: option resolution and API-key inspection."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+from ._types import EpayMode
+from .errors import EpayConfigError
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_MAX_RETRIES",
+    "Config",
+    "mode_from_api_key",
+    "resolve_config",
+]
+
+#: Default API root.
+DEFAULT_BASE_URL = "https://api.e-pay.et/v1"
+
+#: Default per-attempt timeout, in seconds.
+DEFAULT_TIMEOUT = 30.0
+
+#: Default number of retries after the initial attempt.
+DEFAULT_MAX_RETRIES = 2
+
+
+@dataclass(frozen=True)
+class Config:
+    """Fully resolved client configuration."""
+
+    api_key: str
+    base_url: str
+    timeout: float
+    max_retries: int
+    webhook_secret: Optional[str] = None
+    default_headers: Dict[str, str] = field(default_factory=dict)
+    mode: Optional[EpayMode] = None
+
+
+def mode_from_api_key(api_key: str) -> Optional[EpayMode]:
+    """Derives the traffic mode from a key prefix.
+
+    Returns ``None`` for an ``sk_``-prefixed key with an unrecognised
+    environment segment, so a future key format does not break the client.
+    """
+    if api_key.startswith("sk_live_"):
+        return "live"
+    if api_key.startswith("sk_test_"):
+        return "sandbox"
+    return None
+
+
+def resolve_config(
+    api_key: Optional[str] = None,
+    *,
+    webhook_secret: Optional[str] = None,
+    base_url: Optional[str] = None,
+    timeout: Optional[float] = None,
+    max_retries: Optional[int] = None,
+    default_headers: Optional[Dict[str, str]] = None,
+) -> Config:
+    """Validates and fills in every option, reading environment fallbacks.
+
+    Raises:
+        EpayConfigError: if no API key is available, the key is clearly not a
+            secret key, or an option is out of range.
+    """
+    key = (api_key or os.environ.get("EPAY_SECRET_KEY") or "").strip()
+
+    if not key:
+        raise EpayConfigError(
+            "Missing ePay API key. Pass api_key=... or set the EPAY_SECRET_KEY "
+            "environment variable."
+        )
+    if not key.startswith("sk_"):
+        raise EpayConfigError(
+            'Invalid ePay API key: expected a secret key beginning with "sk_live_" or '
+            '"sk_test_". Secret keys are found in the dashboard under '
+            "Developers -> API Keys."
+        )
+
+    resolved_timeout = DEFAULT_TIMEOUT if timeout is None else float(timeout)
+    if resolved_timeout <= 0:
+        raise EpayConfigError(f"timeout must be a positive number of seconds, received {timeout!r}")
+
+    resolved_retries = DEFAULT_MAX_RETRIES if max_retries is None else int(max_retries)
+    if resolved_retries < 0:
+        raise EpayConfigError(
+            f"max_retries must be a non-negative integer, received {max_retries!r}"
+        )
+
+    root = (base_url or os.environ.get("EPAY_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+    return Config(
+        api_key=key,
+        base_url=root,
+        timeout=resolved_timeout,
+        max_retries=resolved_retries,
+        webhook_secret=webhook_secret or os.environ.get("EPAY_WEBHOOK_SECRET") or None,
+        default_headers=dict(default_headers or {}),
+        mode=mode_from_api_key(key),
+    )

epay/_specs.py

@@ -0,0 +1,197 @@
+"""Request builders shared by the sync and async clients.
+
+Each function validates its inputs and returns a :class:`RequestSpec`. Keeping
+validation here means the sync and async surfaces enforce identical rules.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import date, datetime
+from typing import Any, Dict, Optional, Union
+
+from ._transport import RequestSpec
+from ._types import TRANSACTION_STATUSES
+from .errors import EpayValidationError
+from .helpers import (
+    AmountInput,
+    format_amount,
+    format_date_param,
+    normalize_currency,
+    normalize_phone,
+    require_reference,
+)
+
+__all__ = [
+    "initialize_spec",
+    "verify_spec",
+    "cancel_spec",
+    "list_transactions_spec",
+    "retrieve_spec",
+    "timeline_spec",
+    "providers_list_spec",
+    "providers_get_all_spec",
+]
+
+_OPTIONAL_INITIALIZE_FIELDS = (
+    "merchantReference",
+    "email",
+    "firstName",
+    "lastName",
+    "returnUrl",
+    "callbackUrl",
+)
+
+
+def initialize_spec(
+    *,
+    amount: AmountInput,
+    currency_code: str,
+    customer_phone: str,
+    merchant_reference: Optional[str] = None,
+    email: Optional[str] = None,
+    first_name: Optional[str] = None,
+    last_name: Optional[str] = None,
+    return_url: Optional[str] = None,
+    callback_url: Optional[str] = None,
+    idempotency_key: Optional[str] = None,
+) -> RequestSpec:
+    """Builds the ``POST /transactions/initialize`` request.
+
+    When ``idempotency_key`` is omitted a fresh one is generated per call, which
+    makes the SDK's internal retries safe but does not deduplicate across
+    separate calls.
+    """
+    key = idempotency_key or f"epay_{uuid.uuid4()}"
+    if len(key) > 255:
+        raise EpayValidationError(
+            f"idempotency_key must be at most 255 characters, received {len(key)}"
+        )
+
+    body: Dict[str, Any] = {
+        "amount": format_amount(amount),
+        "currencyCode": normalize_currency(currency_code),
+        "customerPhone": normalize_phone(customer_phone),
+    }
+
+    # Only forward optional fields the caller actually set, so the API applies
+    # its own defaults rather than receiving explicit nulls.
+    optional = {
+        "merchantReference": merchant_reference,
+        "email": email,
+        "firstName": first_name,
+        "lastName": last_name,
+        "returnUrl": return_url,
+        "callbackUrl": callback_url,
+    }
+    for field_name in _OPTIONAL_INITIALIZE_FIELDS:
+        value = optional[field_name]
+        if value is not None:
+            body[field_name] = value
+
+    return RequestSpec(
+        method="POST",
+        path="/transactions/initialize",
+        json=body,
+        headers={"x-idempotency-key": key},
+        # Safe to retry: every attempt carries the same idempotency key.
+        retryable=True,
+    )
+
+
+def verify_spec(reference: str) -> RequestSpec:
+    """Builds the ``GET /transactions/:reference/verify`` request."""
+    from urllib.parse import quote
+
+    return RequestSpec(
+        method="GET",
+        path="/transactions/{}/verify".format(quote(require_reference(reference), safe="")),
+    )
+
+
+def cancel_spec(reference: str) -> RequestSpec:
+    """Builds the ``POST /transactions/:reference/cancel`` request."""
+    from urllib.parse import quote
+
+    return RequestSpec(
+        method="POST",
+        path="/transactions/{}/cancel".format(quote(require_reference(reference), safe="")),
+        # Cancelling twice is rejected with 400 rather than duplicated, but the
+        # endpoint takes no idempotency key, so a retried attempt could act on a
+        # request the server already processed.
+        retryable=False,
+    )
+
+
+def retrieve_spec(reference: str) -> RequestSpec:
+    """Builds the ``GET /transactions/:reference`` request."""
+    from urllib.parse import quote
+
+    return RequestSpec(
+        method="GET",
+        path="/transactions/{}".format(quote(require_reference(reference), safe="")),
+    )
+
+
+def timeline_spec(reference: str) -> RequestSpec:
+    """Builds the ``GET /transactions/:reference/timeline`` request."""
+    from urllib.parse import quote
+
+    return RequestSpec(
+        method="GET",
+        path="/transactions/{}/timeline".format(quote(require_reference(reference), safe="")),
+    )
+
+
+def list_transactions_spec(
+    *,
+    from_date: Optional[Union[str, date, datetime]] = None,
+    to_date: Optional[Union[str, date, datetime]] = None,
+    currency: Optional[str] = None,
+    status: Optional[str] = None,
+    cursor: Optional[str] = None,
+) -> RequestSpec:
+    """Builds the ``GET /transactions`` request.
+
+    Raises:
+        EpayValidationError: if the range is inverted or the status is unknown.
+    """
+    params: Dict[str, Any] = {}
+
+    if from_date is not None:
+        params["from"] = format_date_param(from_date, "from_date")
+    if to_date is not None:
+        params["to"] = format_date_param(to_date, "to_date")
+    if "from" in params and "to" in params and params["from"] > params["to"]:
+        raise EpayValidationError(
+            "from_date ({}) must not be later than to_date ({})".format(
+                params["from"], params["to"]
+            )
+        )
+
+    if currency is not None:
+        params["currency"] = normalize_currency(currency, "currency")
+
+    if status is not None:
+        if status not in TRANSACTION_STATUSES:
+            raise EpayValidationError(
+                "status must be one of {}, received {!r}".format(
+                    ", ".join(TRANSACTION_STATUSES), status
+                )
+            )
+        params["status"] = status
+
+    if cursor is not None:
+        params["cursor"] = cursor
+
+    return RequestSpec(method="GET", path="/transactions", params=params)
+
+
+def providers_list_spec() -> RequestSpec:
+    """Builds the ``GET /payment-providers/list`` request."""
+    return RequestSpec(method="GET", path="/payment-providers/list")
+
+
+def providers_get_all_spec() -> RequestSpec:
+    """Builds the ``GET /payment-providers`` request."""
+    return RequestSpec(method="GET", path="/payment-providers")

epay/_transport.py

@@ -0,0 +1,228 @@
+"""HTTP transport: request specs, retry policy, and error mapping.
+
+The retry policy and error mapping live here as module-level functions so the
+sync and async clients share one implementation and cannot drift apart.
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+import random
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._config import Config
+from ._version import __version__
+from .errors import (
+    EpayConnectionError,
+    EpayTimeoutError,
+    error_from_response,
+    parse_retry_after,
+)
+
+__all__ = ["RequestSpec", "SyncTransport", "AsyncTransport"]
+
+#: Status codes worth a second attempt, alongside anything 5xx.
+_RETRYABLE_STATUSES = frozenset({408, 409, 429})
+
+#: Base delay for exponential backoff, in seconds.
+_BACKOFF_BASE = 0.5
+
+#: Ceiling for a single backoff delay, in seconds.
+_BACKOFF_MAX = 8.0
+
+
+@dataclass(frozen=True)
+class RequestSpec:
+    """A single API call, independent of sync or async execution."""
+
+    method: str
+    path: str
+    params: Optional[Dict[str, Any]] = None
+    json: Optional[Dict[str, Any]] = None
+    headers: Dict[str, str] = field(default_factory=dict)
+    #: Whether a failed attempt may be retried. Defaults to true for GET.
+    retryable: Optional[bool] = None
+
+    @property
+    def label(self) -> str:
+        """Method and path, for error messages."""
+        return f"{self.method} {self.path}"
+
+    def is_retryable(self) -> bool:
+        if self.retryable is not None:
+            return self.retryable
+        return self.method == "GET"
+
+
+def _build_headers(config: Config, spec: RequestSpec) -> Dict[str, str]:
+    headers = {
+        "Accept": "application/json",
+        "Authorization": f"Bearer {config.api_key}",
+        "User-Agent": f"epay-python/{__version__}",
+    }
+    headers.update(config.default_headers)
+    headers.update(spec.headers)
+    if spec.json is not None:
+        headers["Content-Type"] = "application/json"
+    return headers
+
+
+def _url(config: Config, spec: RequestSpec) -> str:
+    path = spec.path if spec.path.startswith("/") else "/" + spec.path
+    return config.base_url + path
+
+
+def _clean_params(params: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """Drops keys whose value is ``None``, so they are absent from the query."""
+    if not params:
+        return None
+    return {key: value for key, value in params.items() if value is not None}
+
+
+def _should_retry_status(status: int) -> bool:
+    return status >= 500 or status in _RETRYABLE_STATUSES
+
+
+def _backoff_delay(attempt: int, retry_after: Optional[float]) -> float:
+    """Exponential backoff with jitter, honouring ``Retry-After``.
+
+    Jitter keeps concurrent clients from retrying in lockstep.
+    """
+    if retry_after is not None:
+        return float(min(retry_after, _BACKOFF_MAX))
+    ceiling = min(_BACKOFF_BASE * (2.0**attempt), _BACKOFF_MAX)
+    return ceiling * (0.5 + random.random() * 0.5)
+
+
+def _parse_body(response: httpx.Response) -> Any:
+    """Parses a response body as JSON, falling back to raw text.
+
+    ``204 No Content`` (returned by cancel) and empty bodies become ``None``.
+    """
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        return response.json()
+    except (ValueError, jsonlib.JSONDecodeError):
+        return response.text
+
+
+def _handle(response: httpx.Response, spec: RequestSpec) -> Any:
+    """Returns the parsed body, or raises the mapped error."""
+    if response.is_success:
+        return _parse_body(response)
+
+    raise error_from_response(
+        status=response.status_code,
+        body=_parse_body(response),
+        headers={key.lower(): value for key, value in response.headers.items()},
+        request=spec.label,
+    )
+
+
+def _translate_transport_error(error: Exception, url: str, timeout: float) -> Exception:
+    """Maps an httpx transport failure onto the SDK hierarchy."""
+    if isinstance(error, httpx.TimeoutException):
+        return EpayTimeoutError(f"Request to {url} timed out after {timeout}s")
+    return EpayConnectionError(f"Could not reach the ePay API at {url}: {error}")
+
+
+class SyncTransport:
+    """Issues API calls over a synchronous ``httpx.Client``."""
+
+    def __init__(self, config: Config, http_client: Optional[httpx.Client] = None) -> None:
+        self._config = config
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=config.timeout)
+
+    def request(self, spec: RequestSpec) -> Any:
+        """Sends a request, retrying transient failures, and returns the body."""
+        import time
+
+        url = _url(self._config, spec)
+        attempts = self._config.max_retries + 1 if spec.is_retryable() else 1
+        last_error: Optional[Exception] = None
+
+        for attempt in range(attempts):
+            is_last = attempt == attempts - 1
+            try:
+                response = self._client.request(
+                    spec.method,
+                    url,
+                    params=_clean_params(spec.params),
+                    json=spec.json,
+                    headers=_build_headers(self._config, spec),
+                    timeout=self._config.timeout,
+                )
+            except httpx.HTTPError as error:
+                last_error = _translate_transport_error(error, url, self._config.timeout)
+                if is_last:
+                    raise last_error from error
+                time.sleep(_backoff_delay(attempt, None))
+                continue
+
+            if response.is_success or is_last or not _should_retry_status(response.status_code):
+                return _handle(response, spec)
+
+            time.sleep(
+                _backoff_delay(attempt, parse_retry_after(response.headers.get("retry-after")))
+            )
+
+        raise last_error or EpayConnectionError(f"{spec.label} failed after {attempts} attempts")
+
+    def close(self) -> None:
+        """Closes the underlying connection pool, if this transport owns it."""
+        if self._owns_client:
+            self._client.close()
+
+
+class AsyncTransport:
+    """Issues API calls over an asynchronous ``httpx.AsyncClient``."""
+
+    def __init__(self, config: Config, http_client: Optional[httpx.AsyncClient] = None) -> None:
+        self._config = config
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=config.timeout)
+
+    async def request(self, spec: RequestSpec) -> Any:
+        """Sends a request, retrying transient failures, and returns the body."""
+        import asyncio
+
+        url = _url(self._config, spec)
+        attempts = self._config.max_retries + 1 if spec.is_retryable() else 1
+        last_error: Optional[Exception] = None
+
+        for attempt in range(attempts):
+            is_last = attempt == attempts - 1
+            try:
+                response = await self._client.request(
+                    spec.method,
+                    url,
+                    params=_clean_params(spec.params),
+                    json=spec.json,
+                    headers=_build_headers(self._config, spec),
+                    timeout=self._config.timeout,
+                )
+            except httpx.HTTPError as error:
+                last_error = _translate_transport_error(error, url, self._config.timeout)
+                if is_last:
+                    raise last_error from error
+                await asyncio.sleep(_backoff_delay(attempt, None))
+                continue
+
+            if response.is_success or is_last or not _should_retry_status(response.status_code):
+                return _handle(response, spec)
+
+            await asyncio.sleep(
+                _backoff_delay(attempt, parse_retry_after(response.headers.get("retry-after")))
+            )
+
+        raise last_error or EpayConnectionError(f"{spec.label} failed after {attempts} attempts")
+
+    async def aclose(self) -> None:
+        """Closes the underlying connection pool, if this transport owns it."""
+        if self._owns_client:
+            await self._client.aclose()