feat: add async HTTP client support

README.md

@@ -2,3 +2,28 @@
 
 A Python-based payment gateway system for Shade Protocol.
 
+## Async requests
+
+`Gateway` provides async resource methods backed by a shared
+`httpx.AsyncClient`.  Close the gateway when it is no longer needed, either
+explicitly or by using the async HTTP client as a context manager.
+
+```python
+from shade import Gateway
+
+gateway = Gateway(api_key="sk_test_...")
+try:
+    payment = await gateway.process_payment_async(100.0, "USD")
+finally:
+    await gateway.aclose()
+```
+
+For direct transport use, `AsyncHTTPClient.request()` has the same arguments
+and returns the same decoded-dictionary response shape as `SyncHTTPClient`:
+
+```python
+from shade import AsyncHTTPClient
+
+async with AsyncHTTPClient("https://api.example.com", "sk_test_...") as client:
+    payments = await client.request("GET", "/payments")
+```

TODO.md

@@ -0,0 +1,31 @@
+# Async HTTP Client Implementation
+
+## Plan
+
+### 1. http.py — Refactor
+- [x] Extract shared `_build_request(method, path, payload)` helper used by both `SyncHTTPClient` and `AsyncHTTPClient`
+- [x] Rewrite `AsyncHTTPClient` to use `httpx.AsyncClient` instead of `aiohttp`
+  - Same constructor args as `SyncHTTPClient`
+  - `async def request(...)` with `async with httpx.AsyncClient(...)` lifecycle
+  - `aclose()` method for explicit cleanup
+  - `__aenter__` / `__aexit__` context manager support
+- [ ] Remove aiohttp import/fallback
+
+### 2. client.py — Add AsyncShadeClient
+- [ ] Add `AsyncShadeClient` mirroring `ShadeClient` with `async def request(...)`
+- [ ] Uses `httpx.AsyncClient`
+- [ ] `async with` context manager and `aclose()`
+
+### 3. gateway.py — Update Gateway
+- [ ] Instantiate new httpx-based `AsyncHTTPClient`
+
+### 4. __init__.py — Export updates
+- [ ] Export any new public classes
+
+### 5. Tests
+- [ ] Update `test_rate_limit.py` — Replace aiohttp mocks with httpx mocks
+- [ ] Run tests to confirm everything passes
+
+### 6. pyproject.toml
+- [ ] Remove aiohttp dev dependency (no longer needed)
+

pyproject.toml

@@ -14,10 +14,10 @@ pydantic = "^2.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.4.0"
+pytest-asyncio = "^0.23.0"
 flake8 = "^6.1.0"
 black = "^23.7.0"
 isort = "^5.12.0"
-aiohttp = "^3.14.1"
 httpx = "^0.28.1"
 
 

src/shade/gateway.py

@@ -142,6 +142,10 @@ def process_payment(self, amount: float, currency: str) -> Dict[str, Any]:
     # Async API
     # ------------------------------------------------------------------
 
+    async def aclose(self) -> None:
+        """Explicitly close the underlying async HTTP client."""
+        await self._async_http.aclose()
+
     async def process_payment_async(
         self, amount: float, currency: str
     ) -> Dict[str, Any]: