Merge upstream/main into fix/13-add-request-response-debug-logging

Resolve conflicts in __init__.py (combine exports), test_gateway.py
(keep patch import, drop unused pytest), and regenerate poetry.lock.

Author: David-patrick-chuks

poetry.lock

@@ -16,6 +16,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,7 +1,30 @@
 from .client import ShadeClient
 from .config import config
 from .gateway import Gateway
+from .http import AsyncHTTPClient, SyncHTTPClient
+from .errors import (
+    AuthenticationError,
+    InvalidRequestError,
+    NetworkError,
+    NotFoundError,
+    HTTPError,
+    RateLimitError,
+    ShadeError,
+)
 
 __version__ = "0.1.0"
 
-__all__ = ["Gateway", "ShadeClient", "config"]
+__all__ = [
+    "AsyncHTTPClient",
+    "AuthenticationError",
+    "Gateway",
+    "HTTPError",
+    "InvalidRequestError",
+    "NetworkError",
+    "NotFoundError",
+    "RateLimitError",
+    "ShadeClient",
+    "ShadeError",
+    "SyncHTTPClient",
+    "config",
+]

src/shade/__init__.py

@@ -0,0 +1,122 @@
+"""
+Shade SDK exceptions.
+"""
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+
+class ShadeError(Exception):
+    """Base exception for all Shade SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_body: Optional[str] = None,
+    ) -> None:
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        if self.status_code is None:
+            return self.message
+        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."""
+
+
+class InvalidRequestError(ShadeError):
+    """Raised when a request is malformed or rejected by validation."""
+
+
+class NotFoundError(ShadeError):
+    """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):
+    """Raised when the SDK cannot complete a network request."""

src/shade/errors.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},
+        )