feat(http): implement rate-limit handling with auto-retry (#11)

pyproject.toml

@@ -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]

src/shade/__init__.py

@@ -1,19 +1,26 @@
+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"
 
 __all__ = [
+    "AsyncHTTPClient",
     "AuthenticationError",
     "Gateway",
+    "HTTPError",
     "InvalidRequestError",
     "NetworkError",
     "NotFoundError",
+    "RateLimitError",
     "ShadeError",
-]
+    "SyncHTTPClient",
+]

src/shade/errors.py

@@ -1,3 +1,6 @@
+"""
+Shade SDK exceptions.
+"""
 from __future__ import annotations
 
 from typing import Optional
@@ -23,6 +26,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."""
 
@@ -36,4 +81,4 @@ class NotFoundError(ShadeError):
 
 
 class NetworkError(ShadeError):
-    """Raised when the SDK cannot complete a network request."""
+    """Raised when the SDK cannot complete a network request."""

src/shade/gateway.py

@@ -1,13 +1,89 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .http import AsyncHTTPClient, SyncHTTPClient, DEFAULT_MAX_RETRIES
+
+
 class Gateway:
     """
     Main entry point for the Shade Payment Gateway.
+
+    Parameters
+    ----------
+    api_key : str
+        Your Shade API key.
+    base_url : str
+        Override the default API base URL (useful for testing).
+    max_retries : int
+        Number of automatic retries on HTTP 429.  Defaults to
+        ``DEFAULT_MAX_RETRIES`` (3).  Set to ``0`` to disable.
+    timeout : float
+        Per-request socket timeout in seconds.
     """
-    def __init__(self):
-        pass
 
-    def process_payment(self, amount: float, currency: str):
+    _DEFAULT_BASE_URL = "https://api.shadeprotocol.io/v1"
+
+    def __init__(
+        self,
+        api_key: str = "",
+        base_url: str = "",
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must be a non-empty string")
+        self.api_key = api_key
+        self._base_url = base_url or self._DEFAULT_BASE_URL
+        self._http = SyncHTTPClient(
+            base_url=self._base_url,
+            api_key=api_key,
+            max_retries=max_retries,
+            timeout=timeout,
+        )
+        self._async_http = AsyncHTTPClient(
+            base_url=self._base_url,
+            api_key=api_key,
+            max_retries=max_retries,
+            timeout=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},
+        )