onepay 0.1.0__py3-none-any.whl

onepay/__init__.py

@@ -0,0 +1,88 @@
+"""OnePay Python SDK — Official SDK for the OnePay payment gateway.
+
+Quick start::
+
+    from onepay import OnePay
+
+    client = OnePay(
+        app_id="YOUR_APP_ID",
+        hash_salt="YOUR_HASH_SALT",
+        app_token="YOUR_APP_TOKEN",
+    )
+
+    result = client.checkout.create(
+        amount=1000.00,
+        currency="LKR",
+        reference="ORDER-123",
+        customer_first_name="Amila",
+        customer_last_name="Perera",
+        customer_phone_number="+94771234567",
+        customer_email="amila@store.lk",
+        transaction_redirect_url="https://store.lk/thank-you",
+    )
+    print(result.redirect_url)
+
+For async usage::
+
+    from onepay import AsyncOnePay
+
+    client = AsyncOnePay(...)
+    result = await client.checkout.create(...)
+"""
+
+from __future__ import annotations
+
+from onepay._auth import generate_hash
+from onepay._version import __version__
+from onepay.client import AsyncOnePay, OnePay
+
+# Exceptions
+from onepay.exceptions import (
+    APIError,
+    AuthenticationError,
+    InvalidAmountError,
+    InvalidAppIdError,
+    InvalidCurrencyError,
+    InvalidRequestError,
+    NetworkError,
+    OnePayError,
+    RateLimitError,
+    RefundNotAllowedError,
+)
+
+# Enums
+from onepay.models.enums import (
+    Currency,
+    PaymentStatus,
+    RefundReason,
+    SubscriptionInterval,
+)
+from onepay.webhook import Webhook, WebhookEvent
+
+__all__ = [
+    # Version
+    "__version__",
+    # Clients
+    "OnePay",
+    "AsyncOnePay",
+    # Utilities
+    "generate_hash",
+    "Webhook",
+    "WebhookEvent",
+    # Exceptions
+    "OnePayError",
+    "APIError",
+    "AuthenticationError",
+    "InvalidRequestError",
+    "InvalidAppIdError",
+    "InvalidAmountError",
+    "InvalidCurrencyError",
+    "RefundNotAllowedError",
+    "RateLimitError",
+    "NetworkError",
+    # Enums
+    "Currency",
+    "PaymentStatus",
+    "RefundReason",
+    "SubscriptionInterval",
+]

onepay/_auth.py

@@ -0,0 +1,59 @@
+"""Authentication utilities for the OnePay SDK.
+
+Provides SHA-256 hash generation for payment requests and auth header
+construction for different API endpoint groups.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Dict
+
+
+def generate_hash(app_id: str, currency: str, amount: str, hash_salt: str) -> str:
+    """Generate SHA-256 hash for OnePay payment requests.
+
+    The hash is computed as ``SHA256(app_id + currency + amount + hash_salt)``
+    with all values concatenated as plain strings with no separators.
+
+    Args:
+        app_id: Your OnePay application identifier.
+        currency: Three-letter ISO currency code (e.g., ``"LKR"``).
+        amount: The transaction amount as a string (e.g., ``"100.00"``).
+        hash_salt: Your OnePay hash salt (secret key).
+
+    Returns:
+        Lowercase hexadecimal SHA-256 hash string.
+
+    Example:
+        >>> generate_hash("APP123", "LKR", "100.00", "SALT456")
+        'a1b2c3...'
+    """
+    payload = f"{app_id}{currency}{amount}{hash_salt}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def build_auth_header(token: str) -> Dict[str, str]:
+    """Build the Authorization header dictionary.
+
+    Args:
+        token: The bearer/API token value.
+
+    Returns:
+        Dictionary with ``Authorization`` and ``Content-Type`` headers.
+    """
+    return {
+        "Authorization": token,
+        "Content-Type": "application/json",
+    }
+
+
+def build_json_header() -> Dict[str, str]:
+    """Build a basic JSON Content-Type header (no auth).
+
+    Returns:
+        Dictionary with ``Content-Type`` header only.
+    """
+    return {
+        "Content-Type": "application/json",
+    }

onepay/_config.py

@@ -0,0 +1,123 @@
+"""Configuration management for the OnePay SDK.
+
+Loads credentials from constructor arguments or environment variables.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+_DEFAULT_BASE_URL = "https://api.onepay.lk"
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_MAX_RETRIES = 3
+
+
+@dataclass
+class OnePayConfig:
+    """Holds all configuration for an OnePay client instance.
+
+    Values can be provided explicitly or fall back to environment variables:
+        - ``ONEPAY_APP_ID``
+        - ``ONEPAY_HASH_SALT``
+        - ``ONEPAY_APP_TOKEN``
+        - ``ONEPAY_API_KEY``
+        - ``ONEPAY_ACCESS_TOKEN``
+        - ``ONEPAY_BASE_URL``
+    """
+
+    app_id: str = ""
+    hash_salt: str = ""
+    app_token: str = ""
+    api_key: str = ""
+    access_token: str = ""
+    base_url: str = _DEFAULT_BASE_URL
+    timeout: float = _DEFAULT_TIMEOUT
+    max_retries: int = _DEFAULT_MAX_RETRIES
+    debug: bool = False
+
+    # Internal — resolved after __post_init__
+    _resolved: bool = field(default=False, repr=False, init=False)
+
+    def __post_init__(self) -> None:
+        """Resolve unset fields from environment variables."""
+        if not self._resolved:
+            self.app_id = self.app_id or os.environ.get("ONEPAY_APP_ID", "")
+            self.hash_salt = self.hash_salt or os.environ.get("ONEPAY_HASH_SALT", "")
+            self.app_token = self.app_token or os.environ.get("ONEPAY_APP_TOKEN", "")
+            self.api_key = self.api_key or os.environ.get("ONEPAY_API_KEY", "")
+            self.access_token = self.access_token or os.environ.get("ONEPAY_ACCESS_TOKEN", "")
+            self.base_url = self.base_url or os.environ.get(
+                "ONEPAY_BASE_URL", _DEFAULT_BASE_URL
+            )
+            # Strip trailing slashes from base URL
+            self.base_url = self.base_url.rstrip("/")
+            self._resolved = True
+
+    def get_app_token_or_raise(self) -> str:
+        """Return the app token, raising if not configured."""
+        if not self.app_token:
+            raise ValueError(
+                "app_token is required for this operation. "
+                "Pass it to the OnePay constructor or set the ONEPAY_APP_TOKEN environment variable."
+            )
+        return self.app_token
+
+    def get_api_key_or_raise(self) -> str:
+        """Return the API key, raising if not configured."""
+        if not self.api_key:
+            raise ValueError(
+                "api_key is required for this operation. "
+                "Pass it to the OnePay constructor or set the ONEPAY_API_KEY environment variable."
+            )
+        return self.api_key
+
+    def get_access_token_or_raise(self) -> str:
+        """Return the access token, raising if not configured."""
+        if not self.access_token:
+            raise ValueError(
+                "access_token is required for this operation. "
+                "Pass it to the OnePay constructor or set the ONEPAY_ACCESS_TOKEN environment variable."
+            )
+        return self.access_token
+
+    def get_hash_salt_or_raise(self) -> str:
+        """Return the hash salt, raising if not configured."""
+        if not self.hash_salt:
+            raise ValueError(
+                "hash_salt is required for this operation. "
+                "Pass it to the OnePay constructor or set the ONEPAY_HASH_SALT environment variable."
+            )
+        return self.hash_salt
+
+    def get_app_id_or_raise(self) -> str:
+        """Return the app ID, raising if not configured."""
+        if not self.app_id:
+            raise ValueError(
+                "app_id is required for this operation. "
+                "Pass it to the OnePay constructor or set the ONEPAY_APP_ID environment variable."
+            )
+        return self.app_id
+
+    def redacted_repr(self) -> str:
+        """Return a string representation with secrets redacted."""
+        def _redact(val: str) -> str:
+            if not val:
+                return "(not set)"
+            if len(val) <= 8:
+                return "***"
+            return val[:4] + "***" + val[-4:]
+
+        return (
+            f"OnePayConfig("
+            f"app_id={_redact(self.app_id)!r}, "
+            f"hash_salt={_redact(self.hash_salt)!r}, "
+            f"app_token={_redact(self.app_token)!r}, "
+            f"api_key={_redact(self.api_key)!r}, "
+            f"access_token={_redact(self.access_token)!r}, "
+            f"base_url={self.base_url!r}, "
+            f"timeout={self.timeout}, "
+            f"max_retries={self.max_retries}, "
+            f"debug={self.debug}"
+            f")"
+        )

onepay/_http.py

@@ -0,0 +1,326 @@
+"""HTTP client layer for the OnePay SDK.
+
+Provides both synchronous and asynchronous HTTP clients with automatic
+retry logic, error parsing, and structured logging.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import time
+from typing import Any, Dict, Optional, TypeVar
+
+import httpx
+
+from onepay._config import OnePayConfig
+from onepay._version import __version__
+from onepay.exceptions import (
+    APIError,
+    AuthenticationError,
+    InvalidRequestError,
+    NetworkError,
+    OnePayError,
+    RateLimitError,
+)
+
+logger = logging.getLogger("onepay")
+
+T = TypeVar("T")
+
+_USER_AGENT = f"onepay-python/{__version__}"
+
+
+def _parse_error_response(
+    status_code: int,
+    response_data: Dict[str, Any],
+) -> APIError:
+    """Parse an HTTP error response into the appropriate exception type."""
+    message = response_data.get("message", "") or response_data.get("error", "")
+    if not message:
+        message = str(response_data)
+
+    # Detect specific 400 error types from the message
+    msg_lower = message.lower() if isinstance(message, str) else ""
+
+    if status_code == 401:
+        return AuthenticationError(message=message, raw_response=response_data)
+
+    if status_code == 429:
+        return RateLimitError(message=message, raw_response=response_data)
+
+    if status_code == 400:
+        if "invalid app" in msg_lower:
+            from onepay.exceptions import InvalidAppIdError
+
+            return InvalidAppIdError(message=message, raw_response=response_data)
+        if "invalid amount" in msg_lower:
+            from onepay.exceptions import InvalidAmountError
+
+            return InvalidAmountError(message=message, raw_response=response_data)
+        if "currency" in msg_lower and ("not available" in msg_lower or "invalid" in msg_lower):
+            from onepay.exceptions import InvalidCurrencyError
+
+            return InvalidCurrencyError(message=message, raw_response=response_data)
+        if "refund" in msg_lower:
+            from onepay.exceptions import RefundNotAllowedError
+
+            return RefundNotAllowedError(message=message, raw_response=response_data)
+        return InvalidRequestError(message=message, raw_response=response_data)
+
+    return APIError(message=message, status_code=status_code, raw_response=response_data)
+
+
+def _should_retry(status_code: int) -> bool:
+    """Determine if a request should be retried based on status code."""
+    return status_code == 429 or status_code >= 500
+
+
+def _backoff_delay(attempt: int, base: float = 0.5, max_delay: float = 30.0) -> float:
+    """Calculate exponential backoff delay with jitter."""
+    delay = min(base * (2 ** attempt), max_delay)
+    jitter = random.uniform(0, delay * 0.5)  # noqa: S311
+    return float(delay + jitter)
+
+
+class SyncHttpClient:
+    """Synchronous HTTP client backed by ``httpx.Client``."""
+
+    def __init__(self, config: OnePayConfig) -> None:
+        self._config = config
+        self._client = httpx.Client(
+            base_url=config.base_url,
+            timeout=httpx.Timeout(config.timeout),
+            headers={"User-Agent": _USER_AGENT},
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """Execute an HTTP request with retry logic.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE).
+            path: API endpoint path (e.g., ``/v3/checkout/link/``).
+            json: JSON body for the request.
+            params: Query parameters.
+            headers: Additional headers.
+
+        Returns:
+            Parsed JSON response as a dictionary.
+
+        Raises:
+            APIError: On API error responses.
+            NetworkError: On connection or timeout failures.
+        """
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                if self._config.debug:
+                    logger.debug(
+                        "OnePay API request: %s %s (attempt %d/%d)",
+                        method,
+                        path,
+                        attempt + 1,
+                        self._config.max_retries + 1,
+                    )
+
+                response = self._client.request(
+                    method=method,
+                    url=path,
+                    json=json,
+                    params=params,
+                    headers=headers,
+                )
+
+                if self._config.debug:
+                    logger.debug(
+                        "OnePay API response: %d %s",
+                        response.status_code,
+                        path,
+                    )
+
+                # Parse response
+                try:
+                    response_data = response.json()
+                except Exception:
+                    response_data = {"message": response.text}
+
+                # Success
+                if response.is_success:
+                    return response_data  # type: ignore[no-any-return]
+
+                # Check if we should retry
+                if _should_retry(response.status_code) and attempt < self._config.max_retries:
+                    delay = _backoff_delay(attempt)
+                    if self._config.debug:
+                        logger.debug(
+                            "Retrying in %.2fs after HTTP %d",
+                            delay,
+                            response.status_code,
+                        )
+                    time.sleep(delay)
+                    last_error = _parse_error_response(response.status_code, response_data)
+                    continue
+
+                # Non-retryable error
+                raise _parse_error_response(response.status_code, response_data)
+
+            except OnePayError:
+                raise
+            except httpx.TimeoutException as exc:
+                last_error = NetworkError(
+                    message=f"Request timed out: {method} {path}",
+                    original_error=exc,
+                )
+                if attempt < self._config.max_retries:
+                    delay = _backoff_delay(attempt)
+                    time.sleep(delay)
+                    continue
+                raise last_error from exc
+            except httpx.HTTPError as exc:
+                last_error = NetworkError(
+                    message=f"Network error: {exc}",
+                    original_error=exc,
+                )
+                if attempt < self._config.max_retries:
+                    delay = _backoff_delay(attempt)
+                    time.sleep(delay)
+                    continue
+                raise last_error from exc
+
+        # Should not reach here, but just in case
+        if last_error:
+            raise last_error
+        raise NetworkError(message="Request failed after all retries.")
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client backed by ``httpx.AsyncClient``."""
+
+    def __init__(self, config: OnePayConfig) -> None:
+        self._config = config
+        self._client = httpx.AsyncClient(
+            base_url=config.base_url,
+            timeout=httpx.Timeout(config.timeout),
+            headers={"User-Agent": _USER_AGENT},
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """Execute an async HTTP request with retry logic.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE).
+            path: API endpoint path (e.g., ``/v3/checkout/link/``).
+            json: JSON body for the request.
+            params: Query parameters.
+            headers: Additional headers.
+
+        Returns:
+            Parsed JSON response as a dictionary.
+
+        Raises:
+            APIError: On API error responses.
+            NetworkError: On connection or timeout failures.
+        """
+        import asyncio
+
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                if self._config.debug:
+                    logger.debug(
+                        "OnePay API request: %s %s (attempt %d/%d)",
+                        method,
+                        path,
+                        attempt + 1,
+                        self._config.max_retries + 1,
+                    )
+
+                response = await self._client.request(
+                    method=method,
+                    url=path,
+                    json=json,
+                    params=params,
+                    headers=headers,
+                )
+
+                if self._config.debug:
+                    logger.debug(
+                        "OnePay API response: %d %s",
+                        response.status_code,
+                        path,
+                    )
+
+                try:
+                    response_data = response.json()
+                except Exception:
+                    response_data = {"message": response.text}
+
+                if response.is_success:
+                    return response_data  # type: ignore[no-any-return]
+
+                if _should_retry(response.status_code) and attempt < self._config.max_retries:
+                    delay = _backoff_delay(attempt)
+                    if self._config.debug:
+                        logger.debug(
+                            "Retrying in %.2fs after HTTP %d",
+                            delay,
+                            response.status_code,
+                        )
+                    await asyncio.sleep(delay)
+                    last_error = _parse_error_response(response.status_code, response_data)
+                    continue
+
+                raise _parse_error_response(response.status_code, response_data)
+
+            except OnePayError:
+                raise
+            except httpx.TimeoutException as exc:
+                last_error = NetworkError(
+                    message=f"Request timed out: {method} {path}",
+                    original_error=exc,
+                )
+                if attempt < self._config.max_retries:
+                    delay = _backoff_delay(attempt)
+                    await asyncio.sleep(delay)
+                    continue
+                raise last_error from exc
+            except httpx.HTTPError as exc:
+                last_error = NetworkError(
+                    message=f"Network error: {exc}",
+                    original_error=exc,
+                )
+                if attempt < self._config.max_retries:
+                    delay = _backoff_delay(attempt)
+                    await asyncio.sleep(delay)
+                    continue
+                raise last_error from exc
+
+        if last_error:
+            raise last_error
+        raise NetworkError(message="Request failed after all retries.")
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client."""
+        await self._client.aclose()

onepay/_version.py

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