cyrus-payments 0.1.0__tar.gz

cyrus_payments-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+.idea/
+dist/
+build/

cyrus_payments-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: cyrus-payments
+Version: 0.1.0
+Summary: Python SDK for the Cyrus Payments API
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: respx<1,>=0.22; extra == 'dev'

cyrus_payments-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "cyrus-payments"
+version = "0.1.0"
+description = "Python SDK for the Cyrus Payments API"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27,<1",
+    "pydantic>=2.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8,<9",
+    "pytest-asyncio>=0.24,<1",
+    "respx>=0.22,<1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cyrus"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cyrus_payments-0.1.0/src/cyrus/__init__.py

@@ -0,0 +1,43 @@
+"""Python SDK for the Cyrus Payments API."""
+
+from cyrus.client import CyrusClient
+from cyrus._enums import (
+    CustomerStatus,
+    KycTier,
+    MatchStatus,
+    PaymentEventStatus,
+    PaymentEventType,
+    ReconciliationFailureReason,
+    TransactionStatus,
+    TransactionType,
+)
+from cyrus._exceptions import (
+    ConflictError,
+    CyrusAPIError,
+    NotFoundError,
+    ProviderError,
+    ServerError,
+    UnauthorizedError,
+    ValidationError,
+)
+
+__all__ = [
+    "CyrusClient",
+    "ConflictError",
+    "CustomerStatus",
+    "CyrusAPIError",
+    "KycTier",
+    "MatchStatus",
+    "NotFoundError",
+    "PaymentEventStatus",
+    "PaymentEventType",
+    "ProviderError",
+    "ReconciliationFailureReason",
+    "ServerError",
+    "TransactionStatus",
+    "TransactionType",
+    "UnauthorizedError",
+    "ValidationError",
+]
+
+__version__ = "0.1.0"

cyrus_payments-0.1.0/src/cyrus/_enums.py

@@ -0,0 +1,64 @@
+from enum import Enum
+
+
+class TransactionType(str, Enum):
+    CUSTOMER_PAYMENT = "CUSTOMER_PAYMENT"
+    PAYOUT = "PAYOUT"
+    REVERSAL = "REVERSAL"
+    ADJUSTMENT = "ADJUSTMENT"
+
+
+class TransactionStatus(str, Enum):
+    PENDING = "PENDING"
+    SUCCESSFUL = "SUCCESSFUL"
+    FAILED = "FAILED"
+    REVERSED = "REVERSED"
+
+
+class MatchStatus(str, Enum):
+    MATCHED = "MATCHED"
+    UNMATCHED = "UNMATCHED"
+    DISCREPANCY = "DISCREPANCY"
+    ORPHANED = "ORPHANED"
+    MANUAL_REVIEW = "MANUAL_REVIEW"
+
+
+class CustomerStatus(str, Enum):
+    ACTIVE = "ACTIVE"
+    SUSPENDED = "SUSPENDED"
+    CLOSED = "CLOSED"
+
+
+class KycTier(str, Enum):
+    TIER_1 = "TIER_1"
+    TIER_2 = "TIER_2"
+    TIER_3 = "TIER_3"
+
+
+class PaymentEventType(str, Enum):
+    PAYMENT_SUCCESS = "PAYMENT_SUCCESS"
+    PAYMENT_FAILED = "PAYMENT_FAILED"
+    PAYMENT_REVERSED = "PAYMENT_REVERSED"
+    PAYOUT_SUCCESS = "PAYOUT_SUCCESS"
+    PAYOUT_FAILED = "PAYOUT_FAILED"
+    PAYOUT_REFUND = "PAYOUT_REFUND"
+    UNKNOWN = "UNKNOWN"
+
+
+class PaymentEventStatus(str, Enum):
+    RECEIVED = "RECEIVED"
+    PROCESSED = "PROCESSED"
+    IGNORED = "IGNORED"
+    PROCESSED_DUPLICATE = "PROCESSED_DUPLICATE"
+    FAILED = "FAILED"
+    REATTRIBUTED = "REATTRIBUTED"
+
+
+class ReconciliationFailureReason(str, Enum):
+    UNKNOWN_VIRTUAL_ACCOUNT = "UNKNOWN_VIRTUAL_ACCOUNT"
+    INACTIVE_CUSTOMER = "INACTIVE_CUSTOMER"
+    NON_CREDIT_EVENT = "NON_CREDIT_EVENT"
+    DUPLICATE = "DUPLICATE"
+    SIGNATURE_MISMATCH = "SIGNATURE_MISMATCH"
+    AMOUNT_MISMATCH = "AMOUNT_MISMATCH"
+    PROVIDER_UNCONFIRMED = "PROVIDER_UNCONFIRMED"

cyrus_payments-0.1.0/src/cyrus/_exceptions.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+
+class CyrusAPIError(Exception):
+    """Base exception for all Cyrus API errors."""
+
+    def __init__(self, code: str, message: str, status_code: int | None = None) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class NotFoundError(CyrusAPIError):
+    """Resource not found (code 82)."""
+
+
+class UnauthorizedError(CyrusAPIError):
+    """Invalid or missing API key (code 40)."""
+
+
+class ValidationError(CyrusAPIError):
+    """Request validation failed (code 70/71). Includes field-level errors."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        field_errors: list[dict[str, str]] | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        self.field_errors = field_errors or []
+        super().__init__(code=code, message=message, status_code=status_code)
+
+
+class ConflictError(CyrusAPIError):
+    """Resource state conflict (code 81, 409, etc.)."""
+
+
+class ProviderError(CyrusAPIError):
+    """Upstream provider (Nomba) error (code 90)."""
+
+
+class ServerError(CyrusAPIError):
+    """Internal server error (code 99, 5xx)."""

cyrus_payments-0.1.0/src/cyrus/_http.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from cyrus._exceptions import (
+    ConflictError,
+    CyrusAPIError,
+    NotFoundError,
+    ProviderError,
+    ServerError,
+    UnauthorizedError,
+    ValidationError,
+)
+
+_DEFAULT_BASE_URL = "https://api.trycyrus.app"
+_MAX_RETRIES = 3
+_RETRY_BACKOFF = 0.5  # seconds, doubled each attempt
+
+
+class HttpClient:
+    """Thin wrapper around httpx that handles auth, envelope parsing, and retries."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = _MAX_RETRIES,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+        self._max_retries = max_retries
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> Any:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, *, json: dict[str, Any] | None = None) -> Any:
+        return self._request("POST", path, json=json)
+
+    def patch(self, path: str, *, json: dict[str, Any] | None = None) -> Any:
+        return self._request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self._request("DELETE", path)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries):
+            try:
+                resp = self._client.request(method, path, **kwargs)
+                return self._handle_response(resp)
+            except (httpx.TimeoutException, httpx.ConnectError, httpx.RemoteProtocolError) as exc:
+                last_exc = exc
+                if attempt < self._max_retries - 1:
+                    time.sleep(_RETRY_BACKOFF * (2 ** attempt))
+        raise CyrusAPIError(
+            code="99",
+            message=f"Connection failed after {self._max_retries} attempts: {last_exc}",
+            status_code=None,
+        )
+
+    @staticmethod
+    def _handle_response(resp: httpx.Response) -> Any:
+        try:
+            body: dict[str, Any] = resp.json()
+        except ValueError:
+            # The api-key chain rejects missing/invalid keys before the request ever reaches a
+            # controller, so there's no CyrusApiResponse envelope to parse — just a bare status.
+            if resp.status_code in (401, 403):
+                raise UnauthorizedError(
+                    code="40",
+                    message="Invalid or missing API key",
+                    status_code=resp.status_code,
+                ) from None
+            raise CyrusAPIError(
+                code="99",
+                message=f"Unexpected non-JSON response (HTTP {resp.status_code})",
+                status_code=resp.status_code,
+            ) from None
+
+        if resp.status_code >= 500:
+            msg = body.get("message", "Server error")
+            code = body.get("code", "99")
+            raise ServerError(code=code, message=msg, status_code=resp.status_code)
+
+        if body.get("status") is False or body.get("status") == "false":
+            code = body.get("code", "99")
+            msg = body.get("message", "Unknown error")
+            data = body.get("data") or {}
+
+            # Checked first: ResponseCode.INVALID_REQUEST ("71") is a generic business-rule-violation
+            # bucket the backend reuses across many exception types, several of which are genuine
+            # state conflicts returned with HTTP 409 (e.g. closing an already-closed customer,
+            # insufficient wallet funds). A 409 always means ConflictError regardless of which
+            # internal code produced it — checked before the code-based branches below so those
+            # conflicts aren't misclassified as ValidationError. Code "70" (INVALID_INPUT) is never
+            # emitted with 409 — it's exclusively bean-validation failures at 400 — so this reordering
+            # doesn't affect real field-validation errors.
+            if resp.status_code == 409 or code == "81":
+                raise ConflictError(code=code, message=msg, status_code=resp.status_code)
+            if code in ("70", "71"):
+                raise ValidationError(
+                    code=code,
+                    message=msg,
+                    field_errors=data.get("fieldErrors") or [],
+                    status_code=resp.status_code,
+                )
+            if code == "82":
+                raise NotFoundError(code=code, message=msg, status_code=resp.status_code)
+            if code == "40":
+                raise UnauthorizedError(code=code, message=msg, status_code=resp.status_code)
+            if code == "90":
+                raise ProviderError(code=code, message=msg, status_code=resp.status_code)
+            raise CyrusAPIError(code=code, message=msg, status_code=resp.status_code)
+
+        return body.get("data")
+
+    def close(self) -> None:
+        self._client.close()

cyrus_payments-0.1.0/src/cyrus/_pagination.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Any, Iterator, TypeVar
+
+from pydantic import TypeAdapter
+
+from cyrus._http import HttpClient
+from cyrus.models.responses import PageResponse
+
+T = TypeVar("T")
+
+
+class Page:
+    """A single page of results from a paginated endpoint."""
+
+    def __init__(self, data: dict[str, Any], item_type: type[T]) -> None:
+        self._page = PageResponse.model_validate(data)
+        self._adapter = TypeAdapter(list[item_type])  # type: ignore[type-arg]
+        self.items: list[T] = self._adapter.validate_python(self._page.content)
+
+    @property
+    def meta(self) -> PageResponse:
+        return self._page
+
+    @property
+    def total_elements(self) -> int:
+        return self._page.total_elements
+
+    @property
+    def total_pages(self) -> int:
+        return self._page.total_pages
+
+    @property
+    def page_number(self) -> int:
+        return self._page.number
+
+    @property
+    def is_first(self) -> bool:
+        return self._page.first
+
+    @property
+    def is_last(self) -> bool:
+        return self._page.last
+
+    @property
+    def is_empty(self) -> bool:
+        return self._page.empty
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.items)
+
+    def __getitem__(self, index: int) -> T:
+        return self.items[index]
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+
+class PageIterator:
+    """Auto-paginating iterator that yields items across all pages."""
+
+    def __init__(
+        self,
+        client: HttpClient,
+        path: str,
+        item_type: type[T],
+        *,
+        params: dict[str, Any] | None = None,
+        page_size: int = 20,
+    ) -> None:
+        self._client = client
+        self._path = path
+        self._item_type = item_type
+        self._params = params or {}
+        self._page_size = page_size
+        self._current_page = 0
+
+    def __iter__(self) -> Iterator[T]:
+        while True:
+            params = {**self._params, "page": self._current_page, "size": self._page_size}
+            data = self._client.get(self._path, params=params)
+            page = Page(data, self._item_type)
+            yield from page.items
+            if page.is_last or page.is_empty:
+                break
+            self._current_page += 1

cyrus_payments-0.1.0/src/cyrus/_utils.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def query_value(value: Any) -> Any:
+    """Unwrap an Enum member to its wire value for use as a query param.
+
+    httpx's query-param encoder calls ``str()`` on non-primitive values, which for a
+    ``(str, Enum)`` member yields ``"ClassName.MEMBER"`` rather than the member's value
+    (this only differs from JSON body encoding, which uses the member's str content directly).
+    Passing a plain string through unchanged keeps this backward-compatible with callers who
+    don't use the enum types.
+    """
+    return getattr(value, "value", value)

cyrus_payments-0.1.0/src/cyrus/client.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from cyrus._http import HttpClient
+from cyrus.resources.customers import Customers
+from cyrus.resources.payment_events import PaymentEvents
+from cyrus.resources.transactions import Transactions
+
+
+class CyrusClient:
+    """Client for the Cyrus Payments API.
+
+    Usage::
+
+        from cyrus import CyrusClient
+
+        client = CyrusClient(api_key="cyrus_live_xxx")
+        customer = client.customers.create(reference="cust_123", first_name="Ada")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.trycyrus.app",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._http = HttpClient(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self.customers = Customers(self._http)
+        self.transactions = Transactions(self._http)
+        self.payment_events = PaymentEvents(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> CyrusClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

cyrus_payments-0.1.0/src/cyrus/models/__init__.py

@@ -0,0 +1,39 @@
+from cyrus.models.requests import (
+    CreateCustomer,
+    ReattributePaymentEvent,
+    UpdateCustomer,
+    UpdateCustomerStatus,
+    UpdateKycTier,
+)
+from cyrus.models.responses import (
+    Customer,
+    CustomerListItem,
+    CustomerStatement,
+    PageResponse,
+    PaymentEventDetail,
+    PaymentEventListItem,
+    ReattributionResult,
+    StatementRow,
+    StatementSummary,
+    Transaction,
+    VirtualAccountSummary,
+)
+
+__all__ = [
+    "CreateCustomer",
+    "Customer",
+    "CustomerListItem",
+    "CustomerStatement",
+    "PageResponse",
+    "PaymentEventDetail",
+    "PaymentEventListItem",
+    "ReattributionResult",
+    "ReattributePaymentEvent",
+    "StatementRow",
+    "StatementSummary",
+    "Transaction",
+    "UpdateCustomer",
+    "UpdateCustomerStatus",
+    "UpdateKycTier",
+    "VirtualAccountSummary",
+]

cyrus_payments-0.1.0/src/cyrus/models/requests.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cyrus._enums import CustomerStatus, KycTier
+
+
+class CreateCustomer(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    reference: str
+    first_name: str = Field(alias="firstName")
+    last_name: str | None = Field(default=None, alias="lastName")
+    email: str | None = None
+    phone_number: str | None = Field(default=None, alias="phoneNumber")
+    bvn: str | None = None
+
+
+class UpdateCustomer(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    first_name: str | None = Field(default=None, alias="firstName")
+    last_name: str | None = Field(default=None, alias="lastName")
+    email: str | None = None
+    phone_number: str | None = Field(default=None, alias="phoneNumber")
+
+
+class UpdateCustomerStatus(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    status: CustomerStatus
+
+
+class UpdateKycTier(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    tier: KycTier
+
+
+class ReattributePaymentEvent(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    customer_reference: str = Field(alias="customerReference")