Merge branch 'main' into fix/17-implement-invalid-request-error

Author: codebestia

poetry.lock

@@ -15,6 +15,7 @@ pytest = "^7.4.0"
 flake8 = "^6.1.0"
 black = "^23.7.0"
 isort = "^5.12.0"
+aiohttp = "^3.14.1"
 
 
 [build-system]

pyproject.toml

@@ -1,19 +1,76 @@
+import sys
+from types import ModuleType
+from typing import Optional
+
+from .config import Environment
+from .gateway import Gateway
+from .http import AsyncHTTPClient, SyncHTTPClient
 from .errors import (
     AuthenticationError,
     InvalidRequestError,
     NetworkError,
     NotFoundError,
+    HTTPError,
+    RateLimitError,
     ShadeError,
 )
-from .gateway import Gateway
 
 __version__ = "0.1.0"
 
+# ShadeClient is an alias for Gateway.
+ShadeClient = Gateway
+
 __all__ = [
+    "AsyncHTTPClient",
     "AuthenticationError",
+    "Environment",
     "Gateway",
+    "HTTPError",
     "InvalidRequestError",
     "NetworkError",
     "NotFoundError",
+    "RateLimitError",
+    "ShadeClient",
     "ShadeError",
+    "SyncHTTPClient",
+    "api_base",
+    "max_retries",
+    "timeout",
 ]
+
+
+class _ShadeModule(ModuleType):
+    """Module subclass that exposes config-backed attributes on the shade package."""
+
+    @property
+    def api_base(self) -> Optional[str]:
+        from . import config as _config
+        return _config.api_base
+
+    @api_base.setter
+    def api_base(self, value: Optional[str]) -> None:
+        from . import config as _config
+        _config.api_base = value
+
+    @property
+    def timeout(self) -> float:
+        from . import config as _config
+        return _config.timeout
+
+    @timeout.setter
+    def timeout(self, value: float) -> None:
+        from . import config as _config
+        _config.timeout = value
+
+    @property
+    def max_retries(self) -> int:
+        from . import config as _config
+        return _config.max_retries
+
+    @max_retries.setter
+    def max_retries(self, value: int) -> None:
+        from . import config as _config
+        _config.max_retries = value
+
+
+sys.modules[__name__].__class__ = _ShadeModule

src/shade/__init__.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from stellar_sdk import Network
+
+# Module-level API base URL override. Intended for development and testing only.
+# Set this before creating any client to route all requests to a custom host.
+api_base: Optional[str] = None
+
+# Default HTTP client settings. Override via ``shade.timeout`` / ``shade.max_retries``
+# or per-client constructor arguments on ``ShadeClient`` / ``Gateway``.
+DEFAULT_TIMEOUT: float = 30.0
+DEFAULT_MAX_RETRIES: int = 3
+MAX_RETRIES_LIMIT: int = 10
+
+timeout: float = DEFAULT_TIMEOUT
+max_retries: int = DEFAULT_MAX_RETRIES
+
+
+def validate_client_settings(timeout: float, max_retries: int) -> None:
+    """Raise ValueError for out-of-range timeout or retry settings."""
+    if timeout <= 0:
+        raise ValueError(f"timeout must be greater than 0, got {timeout!r}")
+    if max_retries < 0 or max_retries > MAX_RETRIES_LIMIT:
+        raise ValueError(
+            f"max_retries must be between 0 and {MAX_RETRIES_LIMIT}, got {max_retries!r}"
+        )
+
+
+class Environment(str, Enum):
+    MAINNET = "mainnet"
+    TESTNET = "testnet"
+
+    @property
+    def base_url(self) -> str:
+        _urls: dict[str, str] = {
+            "mainnet": "https://api.shadeprotocol.io/v1",
+            "testnet": "https://testnet.api.shadeprotocol.io/v1",
+        }
+        return _urls[self.value]
+
+    @property
+    def network_passphrase(self) -> str:
+        _passphrases: dict[str, str] = {
+            "mainnet": Network.PUBLIC_NETWORK_PASSPHRASE,
+            "testnet": Network.TESTNET_NETWORK_PASSPHRASE,
+        }
+        return _passphrases[self.value]

src/shade/config.py

@@ -1,3 +1,6 @@
+"""
+Shade SDK exceptions.
+"""
 from __future__ import annotations
 
 import json
@@ -26,6 +29,48 @@ def __str__(self) -> str:
         return f"{self.message} (status code: {self.status_code})"
 
 
+class HTTPError(ShadeError):
+    """Raised for non-2xx responses that are not handled by a more specific error."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        response_body: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body)
+
+
+class RateLimitError(HTTPError):
+    """
+    Raised when the API returns HTTP 429 Too Many Requests and either:
+    - auto-retry is disabled, or
+    - ``max_retries`` has been exhausted.
+
+    Attributes
+    ----------
+    retry_after : int | None
+        Seconds to wait before the next attempt, parsed from the
+        ``Retry-After`` response header.  ``None`` if the header was absent.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[int] = None,
+        status_code: int = 429,
+        response_body: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response_body=response_body)
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:  # pragma: no cover
+        base = super().__str__()
+        if self.retry_after is not None:
+            return f"{base} (retry after {self.retry_after}s)"
+        return base
+
+
 class AuthenticationError(ShadeError):
     """Raised when authentication fails or credentials are invalid."""
 
@@ -75,7 +120,44 @@ def from_response(
 
 
 class NotFoundError(ShadeError):
-    """Raised when an API resource cannot be found."""
+    """Raised on HTTP 404 responses.
+
+    Attributes:
+        resource_type: Kind of resource that was not found (e.g. "payment", "invoice").
+        resource_id:   ID of the missing resource.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_body: Optional[str] = None,
+        resource_type: Optional[str] = None,
+        resource_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status_code, response_body)
+        parsed = _parse_body(response_body)
+        self.resource_type: Optional[str] = resource_type or parsed.get("resource_type")
+        self.resource_id: Optional[str] = resource_id or parsed.get("resource_id")
+
+    @classmethod
+    def from_response(
+        cls,
+        message: str,
+        response_body: Optional[str] = None,
+    ) -> "NotFoundError":
+        """Construct from a raw 404 response body."""
+        return cls(message, status_code=404, response_body=response_body)
+
+
+def _parse_body(response_body: Optional[str]) -> dict:
+    if not response_body:
+        return {}
+    try:
+        data = json.loads(response_body)
+        return data if isinstance(data, dict) else {}
+    except (json.JSONDecodeError, ValueError):
+        return {}
 
 
 class NetworkError(ShadeError):

src/shade/errors.py

@@ -1,13 +1,113 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from . import config as _config
+from .config import Environment, validate_client_settings
+from .http import AsyncHTTPClient, SyncHTTPClient
+
+
 class Gateway:
     """
     Main entry point for the Shade Payment Gateway.
+
+    Parameters
+    ----------
+    api_key : str
+        Your Shade API key.
+    environment : Environment
+        Controls the Stellar network passphrase and the default API URL.
+        Defaults to ``Environment.MAINNET``.
+    api_base : str, optional
+        Override the API host for this client (useful for local dev or staging).
+        Takes precedence over the module-level ``shade.api_base`` and the
+        URL derived from ``environment``. Trailing slashes are trimmed.
+        Intended for development and testing only.
+    base_url : str
+        Deprecated. Prefer ``api_base``.
+    max_retries : int, optional
+        Number of automatic retries on HTTP 429 and transient failures.
+        Defaults to the module-level ``shade.max_retries`` (3).  Set to ``0``
+        to disable auto-retry.
+    timeout : float, optional
+        Per-request socket timeout in seconds.  Defaults to the module-level
+        ``shade.timeout`` (30.0).
     """
-    def __init__(self):
-        pass
 
-    def process_payment(self, amount: float, currency: str):
+    def __init__(
+        self,
+        api_key: str = "",
+        environment: Environment = Environment.MAINNET,
+        api_base: Optional[str] = None,
+        base_url: str = "",
+        max_retries: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must be a non-empty string")
+        self.api_key = api_key
+        self.environment = environment
+
+        resolved_max_retries = (
+            _config.max_retries if max_retries is None else max_retries
+        )
+        resolved_timeout = _config.timeout if timeout is None else timeout
+        validate_client_settings(resolved_timeout, resolved_max_retries)
+
+        # Resolution order: explicit api_base > module-level shade.api_base
+        # > legacy base_url > environment URL
+        resolved = api_base or _config.api_base or base_url or environment.base_url
+        self._base_url = resolved.rstrip("/")
+
+        self._http = SyncHTTPClient(
+            base_url=self._base_url,
+            api_key=api_key,
+            max_retries=resolved_max_retries,
+            timeout=resolved_timeout,
+        )
+        self._async_http = AsyncHTTPClient(
+            base_url=self._base_url,
+            api_key=api_key,
+            max_retries=resolved_max_retries,
+            timeout=resolved_timeout,
+        )
+
+    # ------------------------------------------------------------------
+    # Sync API
+    # ------------------------------------------------------------------
+
+    def process_payment(self, amount: float, currency: str) -> Dict[str, Any]:
         """
-        Process a payment (placeholder).
+        Process a payment (sync).
+
+        Parameters
+        ----------
+        amount : float
+            Payment amount.
+        currency : str
+            ISO 4217 currency code (e.g. ``"USD"``).
+
+        Returns
+        -------
+        dict
+            API response body.
         """
-        print(f"Processing payment of {amount} {currency}...")
-        return True
+        return self._http.request(
+            "POST",
+            "/payments",
+            {"amount": amount, "currency": currency},
+        )
+
+    # ------------------------------------------------------------------
+    # Async API
+    # ------------------------------------------------------------------
+
+    async def process_payment_async(
+        self, amount: float, currency: str
+    ) -> Dict[str, Any]:
+        """Async variant of :meth:`process_payment`."""
+        return await self._async_http.request(
+            "POST",
+            "/payments",
+            {"amount": amount, "currency": currency},
+        )