nomba-python 0.1.0__py3-none-any.whl

nomba_python/exceptions.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class NombaError(Exception):
+    """Base exception for all Nomba SDK errors."""
+
+
+class NombaAPIError(NombaError):
+    """Raised when the Nomba API returns a non-success response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        response_body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.response_body = response_body
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        parts = [super().__str__()]
+        if self.status_code is not None:
+            parts.append(f"(status={self.status_code})")
+        if self.code is not None:
+            parts.append(f"(code={self.code})")
+        return " ".join(parts)
+
+
+class NombaAuthError(NombaAPIError):
+    """Raised when authentication with Nomba fails."""
+
+
+class NombaValidationError(NombaError):
+    """
+    Raised locally (before any network call) when a request body is missing
+    required nested fields per Nomba's own OpenAPI spec. This catches
+    mistakes in nested objects (e.g. a missing field inside `order={...}`)
+    that the generated method's flat signature can't enforce on its own.
+    """
+
+    def __init__(self, message: str, *, missing: list[str] | None = None) -> None:
+        super().__init__(message)
+        self.missing = missing or []

nomba_python/flows/__init__.py

@@ -0,0 +1,3 @@
+from .card_payment import AsyncCardPaymentFlow, CardPaymentFlow, CardPaymentStep
+
+__all__ = ["CardPaymentFlow", "AsyncCardPaymentFlow", "CardPaymentStep"]

nomba_python/flows/card_payment.py

@@ -0,0 +1,204 @@
+"""
+Guided helper for Nomba's card-payment flow.
+
+Nomba's card checkout is a multi-step sequence that otherwise requires
+reading their docs to understand:
+
+    1. Create an order                      -> orderReference
+    2. Submit card details                  -> responseCode tells you what's next:
+         "00" = done, payment completed
+         "T0" = OTP required, call submit_otp()
+         "S0" = 3D Secure required, redirect the user using secureAuthenticationData
+    3. (if "T0") submit_otp(otp)            -> or resend_otp() if it didn't arrive
+    4. confirm()                            -> final transaction status/details
+
+This module wraps that sequence in a small stateful object so callers don't
+need to track orderReference/transactionId by hand or look up what each
+responseCode means.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..resources.charge import AsyncCharge, Charge
+from .. import models as _models
+# Response codes Nomba documents on the card-details submission response.
+RESPONSE_CODE_SUCCESS = "00"
+RESPONSE_CODE_OTP_REQUIRED = "T0"
+RESPONSE_CODE_3DS_REQUIRED = "S0"
+
+
+@dataclass
+class CardPaymentStep:
+    """Outcome of a single step in the card-payment flow."""
+
+    raw: _models.SubmitCustomerCardDetailsResponse | _models.SubmitCustomerPaymentOtpResponse | dict[str, Any]
+    response_code: str | None
+    status: Any
+    message: str | None
+    transaction_id: str | None
+    requires_otp: bool
+    requires_3ds: bool
+    secure_authentication_data: dict[str, Any] | None
+    completed: bool
+
+
+def _interpret(raw: _models.SubmitCustomerCardDetailsResponse | _models.SubmitCustomerPaymentOtpResponse, transaction_id_fallback: str | None = None) -> CardPaymentStep:
+    data = raw.get("data", raw) if isinstance(raw.get("data"), dict) else raw
+    response_code = data.get("responseCode")
+    transaction_id = data.get("transactionId") or transaction_id_fallback
+    return CardPaymentStep(
+        raw=raw,
+        response_code=response_code,
+        status=data.get("status"),
+        message=data.get("message"),
+        transaction_id=transaction_id,
+        requires_otp=response_code == RESPONSE_CODE_OTP_REQUIRED,
+        requires_3ds=response_code == RESPONSE_CODE_3DS_REQUIRED,
+        secure_authentication_data=data.get("secureAuthenticationData"),
+        completed=response_code == RESPONSE_CODE_SUCCESS,
+    )
+
+
+class CardPaymentFlow:
+    """
+    Stateful, guided wrapper around Nomba's card-payment + OTP sequence.
+
+    Example:
+        from nomba import Nomba
+        from nomba.flows import CardPaymentFlow
+
+        nomba = Nomba(...)
+        order = nomba.checkout.create_an_online_checkout_order(
+            order={"orderReference": "order-001", "amount": "1000", ...}
+        )
+        order_ref = order["data"]["orderReference"]
+
+        flow = CardPaymentFlow(nomba.charge, order_reference=order_ref)
+        step = flow.submit_card(card_details="...", key="")
+
+        if step.requires_otp:
+            step = flow.submit_otp(otp="123456")
+        elif step.requires_3ds:
+            # redirect the user using step.secure_authentication_data
+            ...
+
+        if step.completed:
+            result = flow.confirm()
+    """
+
+    def __init__(self, charge: "Charge", *, order_reference: str) -> None:
+        self._charge = charge
+        self.order_reference = order_reference
+        self.transaction_id: str | None = None
+
+    def submit_card(
+        self,
+        *,
+        card_details: str,
+        key: str = "",
+        save_card: bool | None = None,
+        device_information: object | None = None,
+    ) -> CardPaymentStep:
+        raw = self._charge.submit_customer_card_details(
+            card_details=card_details,
+            key=key,
+            order_reference=self.order_reference,
+            save_card=save_card,
+            device_information=device_information,
+        )
+        step = _interpret(raw)
+        self.transaction_id = step.transaction_id
+        return step
+
+    def submit_otp(self, otp: str) -> CardPaymentStep:
+        if not self.transaction_id:
+            raise ValueError(
+                "No transaction_id on this flow yet — call submit_card() first."
+            )
+        raw = self._charge.submit_customer_payment_otp(
+            otp=otp,
+            order_reference=self.order_reference,
+            transaction_id=self.transaction_id,
+        )
+        return _interpret(raw, transaction_id_fallback=self.transaction_id)
+
+    def resend_otp(self) -> _models.ResendCustomerPaymentOtpResponse:
+        return self._charge.resend_customer_payment_otp(
+            order_reference=self.order_reference
+        )
+
+    def confirm(self) -> _models.FetchCheckoutTransactionDetailsResponse:
+        return self._charge.fetch_checkout_transaction_details(
+            order_reference=self.order_reference
+        )
+
+    def cancel(self, *, force: bool = False) -> _models.CancelCheckoutTransactionResponse:
+        if not self.transaction_id:
+            raise ValueError(
+                "No transaction_id on this flow yet — call submit_card() first."
+            )
+        return self._charge.cancel_checkout_transaction(
+            transaction_id=self.transaction_id, force_cancel=force
+        )
+
+
+class AsyncCardPaymentFlow:
+    """Async version of `CardPaymentFlow` — same steps, all coroutines."""
+
+    def __init__(self, charge: "AsyncCharge", *, order_reference: str) -> None:
+        self._charge = charge
+        self.order_reference = order_reference
+        self.transaction_id: str | None = None
+
+    async def submit_card(
+        self,
+        *,
+        card_details: str,
+        key: str = "",
+        save_card: bool | None = None,
+        device_information: object | None = None,
+    ) -> CardPaymentStep:
+        raw = await self._charge.submit_customer_card_details(
+            card_details=card_details,
+            key=key,
+            order_reference=self.order_reference,
+            save_card=save_card,
+            device_information=device_information,
+        )
+        step = _interpret(raw)
+        self.transaction_id = step.transaction_id
+        return step
+
+    async def submit_otp(self, otp: str) -> CardPaymentStep:
+        if not self.transaction_id:
+            raise ValueError(
+                "No transaction_id on this flow yet — call submit_card() first."
+            )
+        raw = await self._charge.submit_customer_payment_otp(
+            otp=otp,
+            order_reference=self.order_reference,
+            transaction_id=self.transaction_id,
+        )
+        return _interpret(raw, transaction_id_fallback=self.transaction_id)
+
+    async def resend_otp(self)-> _models.ResendCustomerPaymentOtpResponse:
+        return await self._charge.resend_customer_payment_otp(
+            order_reference=self.order_reference
+        )
+
+    async def confirm(self)-> _models.FetchCheckoutTransactionDetailsResponse:
+        return await self._charge.fetch_checkout_transaction_details(
+            order_reference=self.order_reference
+        )
+
+    async def cancel(self, *, force: bool = False)-> _models.CancelCheckoutTransactionResponse:
+        if not self.transaction_id:
+            raise ValueError(
+                "No transaction_id on this flow yet — call submit_card() first."
+            )
+        return await self._charge.cancel_checkout_transaction(
+            transaction_id=self.transaction_id, force_cancel=force
+        )

nomba_python/http.py

@@ -0,0 +1,418 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import threading
+import time
+from typing import Any
+
+import httpx
+
+from .exceptions import NombaAPIError, NombaAuthError
+
+LIVE_BASE_URL = "https://api.nomba.com"
+SANDBOX_BASE_URL = "https://sandbox.nomba.com"
+
+# Status codes worth retrying: rate limit + transient server-side errors.
+RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
+
+
+def _compute_backoff(attempt: int, retry_after: str | None, backoff_factor: float) -> float:
+    if retry_after:
+        try:
+            return float(retry_after)
+        except ValueError:
+            pass
+    # exponential backoff with jitter: backoff_factor * 2^attempt, +/- 20%
+    base = backoff_factor * (2 ** attempt)
+    jitter = base * random.uniform(-0.2, 0.2)
+    return max(0.0, base + jitter)
+
+
+class NombaClient:
+    """
+    Low-level HTTP client for the Nomba API.
+
+    Handles OAuth2 client-credentials authentication, token caching/refresh
+    (with a lock so concurrent requests don't race to re-fetch a token),
+    the `accountId` header that most endpoints require, and automatic
+    retry-with-backoff for 429/5xx responses.
+
+    Example:
+        client = NombaClient(
+            client_id="...",
+            client_secret="...",
+            account_id="...",
+        )
+        account = client.get(f"/v1/accounts/virtual/{account_ref}")
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        account_id: str,
+        *,
+        sandbox: bool = False,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff_factor: float = 0.5,
+    ) -> None:
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.account_id = account_id
+        self.base_url = SANDBOX_BASE_URL if sandbox else LIVE_BASE_URL
+        self.max_retries = max_retries
+        self.backoff_factor = backoff_factor
+
+        self._access_token: str | None = None
+        self._token_expires_at: float = 0.0
+        self._token_lock = threading.Lock()
+
+        self._http = httpx.Client(base_url=self.base_url, timeout=timeout)
+
+    # -- auth -----------------------------------------------------------
+
+    def _fetch_token_locked(self) -> None:
+        try:
+            response = self._http.post(
+                "/v1/auth/token/issue",
+                headers={
+                    "Content-Type": "application/json",
+                    "accountId": self.account_id,
+                },
+                json={
+                    "grant_type": "client_credentials",
+                    "client_id": self.client_id,
+                    "client_secret": self.client_secret,
+                },
+            )
+        except httpx.HTTPError as exc:
+            raise NombaAuthError(f"Failed to reach Nomba auth endpoint: {exc}") from exc
+
+        if response.status_code >= 400:
+            raise NombaAuthError(
+                "Failed to obtain access token",
+                status_code=response.status_code,
+                response_body=_safe_json(response),
+            )
+
+        body = _safe_json(response) or {}
+        data = body.get("data", body)
+        token = data.get("access_token")
+        if not token:
+            raise NombaAuthError(
+                "Nomba auth response did not include an access_token",
+                response_body=body,
+            )
+
+        expires_in = data.get("expires_in", 3600)
+        self._access_token = token
+        # refresh a little early to avoid edge-of-expiry failures
+        self._token_expires_at = time.monotonic() + max(int(expires_in) - 60, 0)
+
+    def _ensure_token(self) -> str:
+        # fast path: token already valid, no lock needed
+        if self._access_token is not None and time.monotonic() < self._token_expires_at:
+            return self._access_token
+        # slow path: only one thread should actually fetch; others wait then
+        # re-check (the lock serializes them, avoiding a fetch stampede).
+        with self._token_lock:
+            if self._access_token is None or time.monotonic() >= self._token_expires_at:
+                self._fetch_token_locked()
+        assert self._access_token is not None
+        return self._access_token
+
+    def _invalidate_token(self) -> None:
+        with self._token_lock:
+            self._access_token = None
+
+    # -- request helpers --------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        extra_headers: dict[str, str] | None = None,
+        _attempt: int = 0,
+        _retry_on_auth_failure: bool = True,
+    ) -> dict[str, Any]:
+        token = self._ensure_token()
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "accountId": self.account_id,
+            "Content-Type": "application/json",
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+
+        try:
+            response = self._http.request(
+                method, path, json=json, params=params, headers=headers
+            )
+        except httpx.HTTPError as exc:
+            raise NombaAPIError(f"Request to {path} failed: {exc}") from exc
+
+        if response.status_code == 401 and _retry_on_auth_failure:
+            # token may have been invalidated server-side; force refresh once
+            self._invalidate_token()
+            return self.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                extra_headers=extra_headers,
+                _attempt=_attempt,
+                _retry_on_auth_failure=False,
+            )
+
+        if response.status_code in RETRYABLE_STATUS_CODES and _attempt < self.max_retries:
+            delay = _compute_backoff(
+                _attempt, response.headers.get("Retry-After"), self.backoff_factor
+            )
+            time.sleep(delay)
+            return self.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                extra_headers=extra_headers,
+                _attempt=_attempt + 1,
+                _retry_on_auth_failure=_retry_on_auth_failure,
+            )
+
+        body = _safe_json(response)
+
+        if response.status_code >= 400:
+            message = "Nomba API request failed"
+            code = None
+            if isinstance(body, dict):
+                message = body.get("description", message)
+                code = body.get("code")
+            raise NombaAPIError(
+                message,
+                status_code=response.status_code,
+                code=code,
+                response_body=body,
+            )
+
+        return body if isinstance(body, dict) else {"data": body}
+
+    def get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return self.request("PUT", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return self.request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "NombaClient":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+
+def _safe_json(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+class AsyncNombaClient:
+    """
+    Async low-level HTTP client for the Nomba API (httpx.AsyncClient based).
+
+    Mirrors NombaClient's behavior: OAuth2 client-credentials auth, token
+    caching/refresh guarded by an asyncio.Lock, the `accountId` header, and
+    automatic retry-with-backoff for 429/5xx responses.
+
+    Example:
+        client = AsyncNombaClient(
+            client_id="...",
+            client_secret="...",
+            account_id="...",
+        )
+        account = await client.get(f"/v1/accounts/virtual/{account_ref}")
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        account_id: str,
+        *,
+        sandbox: bool = False,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        backoff_factor: float = 0.5,
+    ) -> None:
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.account_id = account_id
+        self.base_url = SANDBOX_BASE_URL if sandbox else LIVE_BASE_URL
+        self.max_retries = max_retries
+        self.backoff_factor = backoff_factor
+
+        self._access_token: str | None = None
+        self._token_expires_at: float = 0.0
+        self._token_lock = asyncio.Lock()
+
+        self._http = httpx.AsyncClient(base_url=self.base_url, timeout=timeout)
+
+    # -- auth -----------------------------------------------------------
+
+    async def _fetch_token_locked(self) -> None:
+        try:
+            response = await self._http.post(
+                "/v1/auth/token/issue",
+                headers={
+                    "Content-Type": "application/json",
+                    "accountId": self.account_id,
+                },
+                json={
+                    "grant_type": "client_credentials",
+                    "client_id": self.client_id,
+                    "client_secret": self.client_secret,
+                },
+            )
+        except httpx.HTTPError as exc:
+            raise NombaAuthError(f"Failed to reach Nomba auth endpoint: {exc}") from exc
+
+        if response.status_code >= 400:
+            raise NombaAuthError(
+                "Failed to obtain access token",
+                status_code=response.status_code,
+                response_body=_safe_json(response),
+            )
+
+        body = _safe_json(response) or {}
+        data = body.get("data", body)
+        token = data.get("access_token")
+        if not token:
+            raise NombaAuthError(
+                "Nomba auth response did not include an access_token",
+                response_body=body,
+            )
+
+        expires_in = data.get("expires_in", 3600)
+        self._access_token = token
+        self._token_expires_at = time.monotonic() + max(int(expires_in) - 60, 0)
+
+    async def _ensure_token(self) -> str:
+        if self._access_token is not None and time.monotonic() < self._token_expires_at:
+            return self._access_token
+        async with self._token_lock:
+            if self._access_token is None or time.monotonic() >= self._token_expires_at:
+                await self._fetch_token_locked()
+        assert self._access_token is not None
+        return self._access_token
+
+    async def _invalidate_token(self) -> None:
+        async with self._token_lock:
+            self._access_token = None
+
+    # -- request helpers --------------------------------------------------
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        extra_headers: dict[str, str] | None = None,
+        _attempt: int = 0,
+        _retry_on_auth_failure: bool = True,
+    ) -> dict[str, Any]:
+        token = await self._ensure_token()
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "accountId": self.account_id,
+            "Content-Type": "application/json",
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+
+        try:
+            response = await self._http.request(
+                method, path, json=json, params=params, headers=headers
+            )
+        except httpx.HTTPError as exc:
+            raise NombaAPIError(f"Request to {path} failed: {exc}") from exc
+
+        if response.status_code == 401 and _retry_on_auth_failure:
+            await self._invalidate_token()
+            return await self.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                extra_headers=extra_headers,
+                _attempt=_attempt,
+                _retry_on_auth_failure=False,
+            )
+
+        if response.status_code in RETRYABLE_STATUS_CODES and _attempt < self.max_retries:
+            delay = _compute_backoff(
+                _attempt, response.headers.get("Retry-After"), self.backoff_factor
+            )
+            await asyncio.sleep(delay)
+            return await self.request(
+                method,
+                path,
+                json=json,
+                params=params,
+                extra_headers=extra_headers,
+                _attempt=_attempt + 1,
+                _retry_on_auth_failure=_retry_on_auth_failure,
+            )
+
+        body = _safe_json(response)
+
+        if response.status_code >= 400:
+            message = "Nomba API request failed"
+            code = None
+            if isinstance(body, dict):
+                message = body.get("description", message)
+                code = body.get("code")
+            raise NombaAPIError(
+                message,
+                status_code=response.status_code,
+                code=code,
+                response_body=body,
+            )
+
+        return body if isinstance(body, dict) else {"data": body}
+
+    async def get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.request("POST", path, **kwargs)
+
+    async def put(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.request("PUT", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return await self.request("DELETE", path, **kwargs)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncNombaClient":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.close()