prava-sdk 0.1.0__py3-none-any.whl

prava_sdk/__init__.py

@@ -0,0 +1,94 @@
+"""Official Python server-side SDK for Prava Payments."""
+
+from ._version import __version__
+from .client import AsyncPravaClient, PravaClient
+from .errors import (
+    PravaAPIError,
+    PravaAuthenticationError,
+    PravaError,
+    PravaInvalidStateError,
+    PravaNotFoundError,
+    PravaPollingTimeoutError,
+    PravaRateLimitError,
+    PravaRequestTimeoutError,
+    PravaTransportError,
+    PravaValidationError,
+)
+from .models import (
+    Card,
+    CardMetadata,
+    CardSelection,
+    CardStatus,
+    CardStatusFilter,
+    CreatedSession,
+    CreateSessionRequest,
+    DeleteCardRequest,
+    DeleteCardResponse,
+    DeleteReason,
+    Environment,
+    IntegrationType,
+    ListCardsRequest,
+    ListCardsResponse,
+    MerchantDetails,
+    PaymentLineItem,
+    PaymentProduct,
+    PaymentResult,
+    PaymentTransaction,
+    ProductDetails,
+    ProductStatus,
+    ProductStatusReport,
+    PurchaseContext,
+    ReportStatusRequest,
+    ReportStatusResponse,
+    RevokeSessionResponse,
+    SessionStatus,
+    TransactionError,
+    TransactionStatus,
+    VisaConfirmation,
+)
+
+__all__ = [
+    "AsyncPravaClient",
+    "Card",
+    "CardMetadata",
+    "CardSelection",
+    "CardStatus",
+    "CardStatusFilter",
+    "CreateSessionRequest",
+    "CreatedSession",
+    "DeleteCardRequest",
+    "DeleteCardResponse",
+    "DeleteReason",
+    "Environment",
+    "IntegrationType",
+    "ListCardsRequest",
+    "ListCardsResponse",
+    "MerchantDetails",
+    "PaymentLineItem",
+    "PaymentProduct",
+    "PaymentResult",
+    "PaymentTransaction",
+    "PravaAPIError",
+    "PravaAuthenticationError",
+    "PravaClient",
+    "PravaError",
+    "PravaInvalidStateError",
+    "PravaNotFoundError",
+    "PravaPollingTimeoutError",
+    "PravaRateLimitError",
+    "PravaRequestTimeoutError",
+    "PravaTransportError",
+    "PravaValidationError",
+    "ProductDetails",
+    "ProductStatus",
+    "ProductStatusReport",
+    "PurchaseContext",
+    "ReportStatusRequest",
+    "ReportStatusResponse",
+    "RevokeSessionResponse",
+    "SessionStatus",
+    "TransactionError",
+    "TransactionStatus",
+    "VisaConfirmation",
+    "__version__",
+]

prava_sdk/_config.py

@@ -0,0 +1,91 @@
+"""Client configuration resolution and environment validation."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from urllib.parse import urlparse
+
+from .errors import PravaValidationError
+from .models import Environment
+
+SANDBOX_BASE_URL = "https://sandbox.api.prava.space"
+PRODUCTION_BASE_URL = "https://api.prava.space"
+
+
+@dataclass(frozen=True, slots=True)
+class ClientConfig:
+    secret_key: str = field(repr=False)
+    environment: Environment
+    base_url: str
+
+
+def _configuration_error(message: str) -> PravaValidationError:
+    return PravaValidationError(message, code="INVALID_CONFIG")
+
+
+def resolve_configuration(
+    secret_key: str | None,
+    environment: Environment | str | None,
+    base_url: str | None,
+) -> ClientConfig:
+    resolved_key = secret_key if secret_key is not None else os.getenv("PRAVA_SECRET_KEY")
+    if not isinstance(resolved_key, str) or not resolved_key:
+        raise _configuration_error(
+            "secret_key is required; pass it explicitly or set PRAVA_SECRET_KEY"
+        )
+
+    if resolved_key.startswith("sk_test_"):
+        inferred_environment = Environment.SANDBOX
+    elif resolved_key.startswith("sk_live_"):
+        inferred_environment = Environment.PRODUCTION
+    else:
+        raise _configuration_error("secret_key must start with sk_test_ or sk_live_")
+
+    if environment is None:
+        resolved_environment = inferred_environment
+    else:
+        try:
+            resolved_environment = Environment(environment)
+        except (TypeError, ValueError) as exc:
+            raise _configuration_error("environment must be sandbox or production") from exc
+        if resolved_environment is not inferred_environment:
+            key_type = "sk_test_*" if inferred_environment is Environment.SANDBOX else "sk_live_*"
+            raise _configuration_error(
+                f"{key_type} keys cannot be used in {resolved_environment.value}"
+            )
+
+    resolved_base_url = (
+        base_url
+        if base_url is not None
+        else (
+            SANDBOX_BASE_URL if resolved_environment is Environment.SANDBOX else PRODUCTION_BASE_URL
+        )
+    )
+    try:
+        parsed_url = urlparse(resolved_base_url)
+        invalid_base_url = (
+            resolved_base_url != resolved_base_url.strip()
+            or parsed_url.scheme not in {"http", "https"}
+            or not parsed_url.netloc
+            or parsed_url.hostname is None
+            or parsed_url.username is not None
+            or parsed_url.password is not None
+            or parsed_url.path not in {"", "/"}
+            or bool(parsed_url.params)
+            or bool(parsed_url.query)
+            or bool(parsed_url.fragment)
+        )
+    except (AttributeError, TypeError, ValueError):
+        invalid_base_url = True
+
+    if invalid_base_url:
+        raise _configuration_error(
+            "base_url must be an HTTP(S) origin without credentials or a path"
+        )
+
+    return ClientConfig(
+        secret_key=resolved_key,
+        environment=resolved_environment,
+        base_url=resolved_base_url.rstrip("/"),
+    )

prava_sdk/_transport.py

@@ -0,0 +1,176 @@
+"""Internal synchronous and asynchronous HTTP transports."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import ValidationError as PydanticValidationError
+
+from ._config import ClientConfig
+from ._version import __version__
+from .errors import (
+    PravaAPIError,
+    PravaRequestTimeoutError,
+    PravaTransportError,
+    error_from_response,
+)
+from .models._base import ResponseModel
+
+ResponseT = TypeVar("ResponseT", bound=ResponseModel)
+
+
+def _response_id(response: httpx.Response) -> str | None:
+    value = response.headers.get("X-Response-ID")
+    return str(value) if value is not None else None
+
+
+def _parse_success(response: httpx.Response, response_model: type[ResponseT]) -> ResponseT:
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise PravaAPIError(
+            "Prava returned a non-JSON success response",
+            code="INVALID_RESPONSE",
+            status_code=response.status_code,
+            response_id=_response_id(response),
+        ) from exc
+
+    try:
+        return response_model.model_validate(payload)
+    except PydanticValidationError as exc:
+        raise PravaAPIError(
+            "Prava returned a response that does not match the documented schema",
+            code="INVALID_RESPONSE",
+            status_code=response.status_code,
+            details={
+                "validation_errors": exc.errors(include_input=False, include_url=False),
+            },
+            response_id=_response_id(response),
+        ) from exc
+
+
+def _headers(secret_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {secret_key}",
+        "Accept": "application/json",
+        "User-Agent": f"prava-sdk-python/{__version__}",
+    }
+
+
+def _closed_client_error() -> PravaTransportError:
+    return PravaTransportError(
+        "The Prava client is closed",
+        code="CLIENT_CLOSED",
+    )
+
+
+class SyncTransport:
+    """Own the synchronous HTTP connection pool and response decoding."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        *,
+        timeout: float | httpx.Timeout,
+        transport: httpx.BaseTransport | None,
+    ) -> None:
+        self.http = httpx.Client(
+            base_url=config.base_url,
+            headers=_headers(config.secret_key),
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=False,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        response_model: type[ResponseT],
+        expected_status: int = 200,
+        json: dict[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> ResponseT:
+        if self.is_closed:
+            raise _closed_client_error()
+        try:
+            response = self.http.request(method, path, json=json, params=params)
+        except httpx.TimeoutException as exc:
+            raise PravaRequestTimeoutError(
+                "Prava API request timed out",
+                code="REQUEST_TIMEOUT",
+            ) from exc
+        except httpx.RequestError as exc:
+            raise PravaTransportError(
+                "Could not reach the Prava API",
+                code="TRANSPORT_ERROR",
+            ) from exc
+
+        if response.status_code != expected_status:
+            raise error_from_response(response)
+        return _parse_success(response, response_model)
+
+    @property
+    def is_closed(self) -> bool:
+        return self.http.is_closed
+
+    def close(self) -> None:
+        self.http.close()
+
+
+class AsyncTransport:
+    """Own the asynchronous HTTP connection pool and response decoding."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        *,
+        timeout: float | httpx.Timeout,
+        transport: httpx.AsyncBaseTransport | None,
+    ) -> None:
+        self.http = httpx.AsyncClient(
+            base_url=config.base_url,
+            headers=_headers(config.secret_key),
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=False,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        response_model: type[ResponseT],
+        expected_status: int = 200,
+        json: dict[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> ResponseT:
+        if self.is_closed:
+            raise _closed_client_error()
+        try:
+            response = await self.http.request(method, path, json=json, params=params)
+        except httpx.TimeoutException as exc:
+            raise PravaRequestTimeoutError(
+                "Prava API request timed out",
+                code="REQUEST_TIMEOUT",
+            ) from exc
+        except httpx.RequestError as exc:
+            raise PravaTransportError(
+                "Could not reach the Prava API",
+                code="TRANSPORT_ERROR",
+            ) from exc
+
+        if response.status_code != expected_status:
+            raise error_from_response(response)
+        return _parse_success(response, response_model)
+
+    @property
+    def is_closed(self) -> bool:
+        return self.http.is_closed
+
+    async def close(self) -> None:
+        await self.http.aclose()

prava_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

prava_sdk/client.py

@@ -0,0 +1,116 @@
+"""Public synchronous and asynchronous Prava clients."""
+
+from __future__ import annotations
+
+import httpx
+
+from ._config import resolve_configuration
+from ._transport import AsyncTransport, SyncTransport
+from .models import Environment
+from .resources import (
+    AsyncCardsResource,
+    AsyncSessionsResource,
+    CardsResource,
+    SessionsResource,
+)
+
+
+class PravaClient:
+    """Synchronous server-side Prava Payments client."""
+
+    def __init__(
+        self,
+        secret_key: str | None = None,
+        *,
+        environment: Environment | str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = 10.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        config = resolve_configuration(secret_key, environment, base_url)
+        self._environment = config.environment
+        self._base_url = config.base_url
+        self._transport = SyncTransport(config, timeout=timeout, transport=transport)
+        self.sessions = SessionsResource(self._transport)
+        self.cards = CardsResource(self._transport)
+
+    @property
+    def environment(self) -> Environment:
+        """Resolved API environment selected from the secret-key prefix."""
+
+        return self._environment
+
+    @property
+    def base_url(self) -> str:
+        """Normalized API origin used by this client."""
+
+        return self._base_url
+
+    @property
+    def is_closed(self) -> bool:
+        """Whether the client's underlying connection pool has been closed."""
+
+        return self._transport.is_closed
+
+    def close(self) -> None:
+        """Close the client's connection pool."""
+
+        self._transport.close()
+
+    def __enter__(self) -> PravaClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncPravaClient:
+    """Asynchronous server-side Prava Payments client."""
+
+    def __init__(
+        self,
+        secret_key: str | None = None,
+        *,
+        environment: Environment | str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = 10.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        config = resolve_configuration(secret_key, environment, base_url)
+        self._environment = config.environment
+        self._base_url = config.base_url
+        self._transport = AsyncTransport(config, timeout=timeout, transport=transport)
+        self.sessions = AsyncSessionsResource(self._transport)
+        self.cards = AsyncCardsResource(self._transport)
+
+    @property
+    def environment(self) -> Environment:
+        """Resolved API environment selected from the secret-key prefix."""
+
+        return self._environment
+
+    @property
+    def base_url(self) -> str:
+        """Normalized API origin used by this client."""
+
+        return self._base_url
+
+    @property
+    def is_closed(self) -> bool:
+        """Whether the client's underlying connection pool has been closed."""
+
+        return self._transport.is_closed
+
+    async def aclose(self) -> None:
+        """Close the client's connection pool."""
+
+        await self._transport.close()
+
+    async def __aenter__(self) -> AsyncPravaClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+
+__all__ = ["AsyncPravaClient", "PravaClient"]

prava_sdk/errors.py

@@ -0,0 +1,134 @@
+"""Exception types and HTTP error parsing for the Prava SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class PravaError(Exception):
+    """Base exception for all SDK and API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        status_code: int | None = None,
+        details: dict[str, Any] | None = None,
+        response_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.details = details
+        self.response_id = response_id
+
+    def __str__(self) -> str:
+        rendered = f"[{self.code}] {self.message}"
+        if self.response_id:
+            rendered += f" (response_id={self.response_id})"
+        return rendered
+
+
+class PravaAuthenticationError(PravaError):
+    """The API rejected the supplied credentials."""
+
+
+class PravaValidationError(PravaError):
+    """The API rejected request fields or local configuration."""
+
+
+class PravaNotFoundError(PravaError):
+    """The requested Prava resource does not exist."""
+
+
+class PravaInvalidStateError(PravaError):
+    """The operation is invalid for the resource's current state."""
+
+
+class PravaRateLimitError(PravaError):
+    """The account or endpoint allowance has been exhausted."""
+
+
+class PravaAPIError(PravaError):
+    """The API returned an unexpected or server-side failure."""
+
+
+class PravaTransportError(PravaError):
+    """The API could not be reached."""
+
+
+class PravaRequestTimeoutError(PravaTransportError):
+    """An individual HTTP request timed out."""
+
+
+class PravaPollingTimeoutError(PravaError):
+    """Payment-result polling did not finish within the requested timeout."""
+
+
+_VALIDATION_CODES = {"VAL_2001", "INVALID_REQUEST"}
+_INVALID_STATE_CODES = {"INVALID_STATE", "MANDATE_EXPIRED", "CARD_INACTIVE"}
+
+
+def error_from_response(response: httpx.Response) -> PravaError:
+    """Convert Prava's common error envelope into a typed exception."""
+
+    code = f"HTTP_{response.status_code}"
+    message = response.reason_phrase or "Prava API request failed"
+    details: dict[str, Any] | None = None
+    response_id = response.headers.get("X-Response-ID")
+
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+
+    if isinstance(payload, dict):
+        nested_error = payload.get("error")
+        error_payload = nested_error if isinstance(nested_error, dict) else payload
+        if isinstance(error_payload.get("code"), str):
+            code = error_payload["code"]
+        if isinstance(error_payload.get("message"), str):
+            message = error_payload["message"]
+        raw_details = error_payload.get("details")
+        if isinstance(raw_details, dict):
+            details = raw_details
+
+    error_type: type[PravaError]
+    if response.status_code in {401, 403} or code.startswith("AUTH_"):
+        error_type = PravaAuthenticationError
+    elif response.status_code == 404:
+        error_type = PravaNotFoundError
+    elif response.status_code == 409 or code in _INVALID_STATE_CODES:
+        error_type = PravaInvalidStateError
+    elif response.status_code in {400, 422} or code in _VALIDATION_CODES:
+        error_type = PravaValidationError
+    elif response.status_code == 429:
+        error_type = PravaRateLimitError
+    else:
+        error_type = PravaAPIError
+
+    return error_type(
+        message,
+        code=code,
+        status_code=response.status_code,
+        details=details,
+        response_id=response_id,
+    )
+
+
+__all__ = [
+    "PravaAPIError",
+    "PravaAuthenticationError",
+    "PravaError",
+    "PravaInvalidStateError",
+    "PravaNotFoundError",
+    "PravaPollingTimeoutError",
+    "PravaRateLimitError",
+    "PravaRequestTimeoutError",
+    "PravaTransportError",
+    "PravaValidationError",
+]

prava_sdk/models/__init__.py

@@ -0,0 +1,71 @@
+"""Public models for the Prava Payments API."""
+
+from .cards import (
+    Card,
+    CardMetadata,
+    DeleteCardRequest,
+    DeleteCardResponse,
+    ListCardsRequest,
+    ListCardsResponse,
+)
+from .enums import (
+    CardStatus,
+    CardStatusFilter,
+    DeleteReason,
+    Environment,
+    IntegrationType,
+    ProductStatus,
+    SessionStatus,
+    TransactionStatus,
+    VisaConfirmation,
+)
+from .sessions import (
+    CardSelection,
+    CreatedSession,
+    CreateSessionRequest,
+    MerchantDetails,
+    PaymentLineItem,
+    PaymentProduct,
+    PaymentResult,
+    PaymentTransaction,
+    ProductDetails,
+    ProductStatusReport,
+    PurchaseContext,
+    ReportStatusRequest,
+    ReportStatusResponse,
+    RevokeSessionResponse,
+    TransactionError,
+)
+
+__all__ = [
+    "Card",
+    "CardMetadata",
+    "CardSelection",
+    "CardStatus",
+    "CardStatusFilter",
+    "CreateSessionRequest",
+    "CreatedSession",
+    "DeleteCardRequest",
+    "DeleteCardResponse",
+    "DeleteReason",
+    "Environment",
+    "IntegrationType",
+    "ListCardsRequest",
+    "ListCardsResponse",
+    "MerchantDetails",
+    "PaymentLineItem",
+    "PaymentProduct",
+    "PaymentResult",
+    "PaymentTransaction",
+    "ProductDetails",
+    "ProductStatus",
+    "ProductStatusReport",
+    "PurchaseContext",
+    "ReportStatusRequest",
+    "ReportStatusResponse",
+    "RevokeSessionResponse",
+    "SessionStatus",
+    "TransactionError",
+    "TransactionStatus",
+    "VisaConfirmation",
+]