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

Author: bukkybyte

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,5 +1,14 @@
+from .errors import HTTPError, RateLimitError, ShadeError
 from .gateway import Gateway
+from .http import AsyncHTTPClient, SyncHTTPClient
 
 __version__ = "0.1.0"
 
-__all__ = ["Gateway"]
+__all__ = [
+    "Gateway",
+    "SyncHTTPClient",
+    "AsyncHTTPClient",
+    "ShadeError",
+    "HTTPError",
+    "RateLimitError",
+]

src/shade/__init__.py

@@ -0,0 +1,42 @@
+"""
+Shade SDK exceptions.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class ShadeError(Exception):
+    """Base exception for all Shade SDK errors."""
+
+
+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) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+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) -> None:
+        super().__init__(message, status_code=429)
+        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

src/shade/errors.py

@@ -1,13 +1,87 @@
+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:
+        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},
+        )