hostpay 0.2.0__tar.gz → 0.3.0__tar.gz

{hostpay-0.2.0 → hostpay-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hostpay
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for the HostPay payments API
 Project-URL: Homepage, https://hpay.host-sl.com
 Project-URL: Documentation, https://hpay.host-sl.com/docs
@@ -31,14 +31,12 @@ Description-Content-Type: text/markdown
 # HostPay Python SDK
 
 A small, typed client for the [HostPay](https://hpay.host-sl.com) payments API —
-wallets, deposits, transfers, payouts, escrow, transaction queries, user/wallet lifecycle management, and webhook verification.
+wallets, deposits, transfers, payouts, escrow, transaction queries, user/wallet lifecycle management, and webhook verification. Ships both a sync (`HostPay`) and an async (`AsyncHostPay`) client.
 
 ## Install
 
 ```bash
-pip install hostpay          # once published
-# or, from this repo:
-pip install ./sdk/python
+pip install hostpay
 ```
 
 Requires Python 3.8+ and `httpx`.
@@ -74,6 +72,26 @@ hold = client.escrow.hold(wallet_id=wallet.id, amount=10)
 client.escrow.release(hold.id, recipient_wallet_id="...")
 ```
 
+## Async
+
+`AsyncHostPay` exposes the exact same surface — every method awaited, built on
+`httpx.AsyncClient`. Use it from FastAPI, aiohttp, or any asyncio app:
+
+```python
+from hostpay import AsyncHostPay
+
+async with AsyncHostPay(api_key="ak-...", secret_key="sk-...") as client:
+    user = await client.users.create(
+        app_user_id="user_123", name="Alice", phone_number="+23279000000"
+    )
+    wallet = await client.wallets.create(user.id)
+    await client.deposits.mobile_money(wallet_id=wallet.id, amount=100)
+```
+
+Outside a context manager, call `await client.aclose()` when done. Webhook
+verification (`client.webhooks.construct_event`) is pure crypto with no I/O,
+so it stays a plain synchronous call on both clients.
+
 ## Authentication
 
 Pass your `api-key` and `secret-key` once at construction; they're sent on every

{hostpay-0.2.0 → hostpay-0.3.0}/README.md

@@ -1,14 +1,12 @@
 # HostPay Python SDK
 
 A small, typed client for the [HostPay](https://hpay.host-sl.com) payments API —
-wallets, deposits, transfers, payouts, escrow, transaction queries, user/wallet lifecycle management, and webhook verification.
+wallets, deposits, transfers, payouts, escrow, transaction queries, user/wallet lifecycle management, and webhook verification. Ships both a sync (`HostPay`) and an async (`AsyncHostPay`) client.
 
 ## Install
 
 ```bash
-pip install hostpay          # once published
-# or, from this repo:
-pip install ./sdk/python
+pip install hostpay
 ```
 
 Requires Python 3.8+ and `httpx`.
@@ -44,6 +42,26 @@ hold = client.escrow.hold(wallet_id=wallet.id, amount=10)
 client.escrow.release(hold.id, recipient_wallet_id="...")
 ```
 
+## Async
+
+`AsyncHostPay` exposes the exact same surface — every method awaited, built on
+`httpx.AsyncClient`. Use it from FastAPI, aiohttp, or any asyncio app:
+
+```python
+from hostpay import AsyncHostPay
+
+async with AsyncHostPay(api_key="ak-...", secret_key="sk-...") as client:
+    user = await client.users.create(
+        app_user_id="user_123", name="Alice", phone_number="+23279000000"
+    )
+    wallet = await client.wallets.create(user.id)
+    await client.deposits.mobile_money(wallet_id=wallet.id, amount=100)
+```
+
+Outside a context manager, call `await client.aclose()` when done. Webhook
+verification (`client.webhooks.construct_event`) is pure crypto with no I/O,
+so it stays a plain synchronous call on both clients.
+
 ## Authentication
 
 Pass your `api-key` and `secret-key` once at construction; they're sent on every

{hostpay-0.2.0 → hostpay-0.3.0}/hostpay/__init__.py

@@ -1,5 +1,5 @@
 """HostPay Python SDK."""
-from ._client import HostPay
+from ._client import AsyncHostPay, HostPay
 from ._object import HostPayObject
 from .errors import (
     APIConnectionError,
@@ -12,10 +12,11 @@ from .errors import (
 )
 from .models import EscrowResponse, TransactionResponse, UserRead, WalletRead
 
-__version__ = "0.1.0"
+from ._client import _VERSION as __version__
 
 __all__ = [
     "HostPay",
+    "AsyncHostPay",
     "HostPayObject",
     "HostPayError",
     "AuthenticationError",

hostpay-0.3.0/hostpay/_async_resources.py

@@ -0,0 +1,247 @@
+"""Async twins of the resource groups in resources.py.
+
+Kept as an explicit mirror (rather than sharing the sync classes) so that
+`await client.users.create(...)` type-checks: an async def returning UserRead
+is awaitable, a sync method annotated UserRead is not. A parity test asserts
+the two modules expose identical classes, methods, and signatures.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .models import EscrowResponse, TransactionResponse, UserRead, WalletRead
+from .resources import PROVIDER_AFRICELL, PROVIDER_ORANGE  # noqa: F401 (re-export)
+
+
+class _Resource:
+    def __init__(self, transport: Any) -> None:
+        self._t = transport
+
+
+class Users(_Resource):
+    async def create(
+        self,
+        app_user_id: str,
+        name: str,
+        phone_number: str,
+        email: Optional[str] = None,
+        username: Optional[str] = None,
+    ) -> UserRead:
+        return await self._t.request("POST", "/api/v1/users/create/", json={
+            "app_user_id": app_user_id,
+            "name": name,
+            "phone_number": phone_number,
+            "email": email,
+            "username": username,
+        })
+
+    async def get(self, user_id: str) -> UserRead:
+        return await self._t.request("GET", f"/api/v1/users/{user_id}/")
+
+    async def list(self, is_active: Optional[bool] = None) -> list[UserRead]:
+        params = {} if is_active is None else {"is_active": is_active}
+        return await self._t.request("GET", "/api/v1/users/", params=params)
+
+    async def update(
+        self,
+        user_id: str,
+        app_user_id: str,
+        name: str,
+        phone_number: str,
+        email: Optional[str] = None,
+        username: Optional[str] = None,
+    ) -> UserRead:
+        """Full update — the API expects the complete user body; app_user_id
+        must match the existing value (it is immutable)."""
+        return await self._t.request("PUT", f"/api/v1/users/{user_id}/", json={
+            "app_user_id": app_user_id,
+            "name": name,
+            "phone_number": phone_number,
+            "email": email,
+            "username": username,
+        })
+
+    async def delete(self, user_id: str) -> Any:
+        return await self._t.request("DELETE", f"/api/v1/users/{user_id}/")
+
+    async def disable(self, user_id: str) -> Any:
+        return await self._t.request("POST", f"/api/v1/users/{user_id}/disable")
+
+    async def enable(self, user_id: str) -> Any:
+        return await self._t.request("POST", f"/api/v1/users/{user_id}/enable")
+
+
+class Wallets(_Resource):
+    async def create(self, user_id: str) -> WalletRead:
+        return await self._t.request("POST", f"/api/v1/wallets/create/{user_id}/")
+
+    async def get(self, user_id: str) -> WalletRead:
+        return await self._t.request("GET", f"/api/v1/wallets/{user_id}/")
+
+    async def balance(self, wallet_id: str) -> Any:
+        return await self._t.request("GET", f"/api/v1/wallets/{wallet_id}/balance")
+
+    async def list(self, is_active: Optional[bool] = None) -> list[WalletRead]:
+        params = {} if is_active is None else {"is_active": is_active}
+        return await self._t.request("GET", "/api/v1/wallets/", params=params)
+
+    async def disable(self, wallet_id: str) -> Any:
+        return await self._t.request("POST", f"/api/v1/wallets/{wallet_id}/disable")
+
+    async def enable(self, wallet_id: str) -> Any:
+        return await self._t.request("POST", f"/api/v1/wallets/{wallet_id}/enable")
+
+
+class Transactions(_Resource):
+    async def get(self, transaction_id: str) -> TransactionResponse:
+        return await self._t.request("GET", f"/api/v1/transactions/{transaction_id}")
+
+    async def list(
+        self,
+        status: Optional[str] = None,
+        transaction_type: Optional[str] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        search: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[TransactionResponse]:
+        params = {
+            "status": status,
+            "transaction_type": transaction_type,
+            "start_date": start_date,
+            "end_date": end_date,
+            "search": search,
+            "limit": limit,
+            "offset": offset,
+        }
+        return await self._t.request(
+            "GET",
+            "/api/v1/transactions/",
+            params={k: v for k, v in params.items() if v is not None},
+        )
+
+    async def for_wallet(self, wallet_id: str) -> list[TransactionResponse]:
+        """All transactions for a wallet, incoming and outgoing."""
+        return await self._t.request("GET", f"/api/v1/transactions/wallet/{wallet_id}")
+
+
+class Deposits(_Resource):
+    async def mobile_money(
+        self, wallet_id: str, amount: int, idempotency_key: Optional[str] = None
+    ) -> Any:
+        return await self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/mobile-money-deposit",
+            json={"wallet_id": wallet_id, "amount": amount},
+            idempotency_key=idempotency_key,
+        )
+
+    async def card(
+        self,
+        wallet_id: str,
+        amount: float,
+        payment_method_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        return await self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/card-deposit/create",
+            json={
+                "wallet_id": wallet_id,
+                "amount": amount,
+                "payment_method_id": payment_method_id,
+            },
+            idempotency_key=idempotency_key,
+        )
+
+
+class Transfers(_Resource):
+    async def create(
+        self,
+        sender_wallet_id: str,
+        recipient_identifier: str,
+        amount: float,
+        description: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> TransactionResponse:
+        return await self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/transfer/",
+            json={
+                "sender_wallet_id": sender_wallet_id,
+                "recipient_identifier": recipient_identifier,
+                "amount": amount,
+                "description": description,
+            },
+            idempotency_key=idempotency_key,
+        )
+
+
+class Payouts(_Resource):
+    async def mobile_money(
+        self,
+        wallet_id: str,
+        amount: float,
+        phone_number: str,
+        provider: str = PROVIDER_ORANGE,
+        currency: str = "SLE",
+        idempotency_key: Optional[str] = None,
+    ) -> TransactionResponse:
+        return await self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/mobile-money-cashout/",
+            json={
+                "wallet_id": wallet_id,
+                "amount": amount,
+                "phone_number": phone_number,
+                "provider": provider,
+                "currency": currency,
+            },
+            idempotency_key=idempotency_key,
+        )
+
+    async def bank(
+        self,
+        wallet_id: str,
+        amount: float,
+        currency: str = "usd",
+        description: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> TransactionResponse:
+        return await self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/payout/",
+            json={
+                "wallet_id": wallet_id,
+                "amount": amount,
+                "currency": currency,
+                "description": description,
+            },
+            idempotency_key=idempotency_key,
+        )
+
+
+class Escrow(_Resource):
+    async def hold(
+        self, wallet_id: str, amount: float, description: Optional[str] = None
+    ) -> EscrowResponse:
+        return await self._t.request("POST", "/api/v1/escrow/hold", json={
+            "wallet_id": wallet_id,
+            "amount": amount,
+            "description": description,
+        })
+
+    async def release(
+        self, transaction_id: str, recipient_wallet_id: str, amount: Optional[float] = None
+    ) -> EscrowResponse:
+        return await self._t.request(
+            "POST",
+            f"/api/v1/escrow/{transaction_id}/release",
+            json={"recipient_wallet_id": recipient_wallet_id, "amount": amount},
+        )
+
+    async def refund(self, transaction_id: str, amount: Optional[float] = None) -> EscrowResponse:
+        return await self._t.request(
+            "POST", f"/api/v1/escrow/{transaction_id}/refund", json={"amount": amount}
+        )

hostpay-0.3.0/hostpay/_client.py

@@ -0,0 +1,250 @@
+"""HTTP transport + the top-level HostPay clients (sync and async)."""
+from __future__ import annotations
+
+import asyncio
+import time
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+from typing import Any, Dict, Optional
+
+import httpx
+
+from . import _async_resources
+from ._object import HostPayObject, _wrap
+from .errors import APIConnectionError, error_from_status
+from .resources import (
+    Deposits,
+    Escrow,
+    Payouts,
+    Transactions,
+    Transfers,
+    Users,
+    Wallets,
+)
+from .webhooks import Webhooks
+
+DEFAULT_BASE_URL = "https://hpay-api.host-sl.com"
+
+# Single-sourced from pyproject.toml via the installed package metadata, so it
+# can never drift from the released version again.
+try:
+    _VERSION = _pkg_version("hostpay")
+except PackageNotFoundError:  # uninstalled source checkout
+    _VERSION = "0.0.0.dev0"
+
+
+class _Transport:
+    """Builds authenticated requests, retries transient failures, maps errors."""
+
+    def __init__(
+        self,
+        api_key: str,
+        secret_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        http_client: Optional[httpx.Client],
+    ) -> None:
+        self._max_retries = max_retries
+        # Auth is applied per-request so a caller-supplied http_client is still
+        # authenticated.
+        self._auth = {
+            "api-key": api_key,
+            "secret-key": secret_key,
+            "User-Agent": f"hostpay-python/{_VERSION}",
+        }
+        self._client = http_client or httpx.Client(
+            base_url=base_url.rstrip("/"), timeout=timeout
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[dict] = None,
+        params: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        headers: Dict[str, str] = dict(self._auth)
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        # Retry only idempotent-safe conditions: connection errors and 5xx. POSTs
+        # are retried too — the API supports Idempotency-Key for money movements.
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = self._client.request(
+                    method, path, json=json, params=params, headers=headers
+                )
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    time.sleep(0.5 * (2 ** attempt))
+                    continue
+                raise APIConnectionError(f"Could not reach HostPay: {exc}") from exc
+
+            if resp.status_code >= 500 and attempt < self._max_retries:
+                time.sleep(0.5 * (2 ** attempt))
+                continue
+            return _handle_response(resp)
+        raise APIConnectionError(f"Could not reach HostPay: {last_exc}")
+
+    def close(self) -> None:
+        self._client.close()
+
+
+def _handle_response(resp: "httpx.Response") -> Any:
+    if 200 <= resp.status_code < 300:
+        if not resp.content:
+            return None
+        return _wrap(resp.json())
+    try:
+        body = resp.json()
+        detail = body.get("detail", body) if isinstance(body, dict) else body
+    except ValueError:
+        detail = resp.text
+    message = detail if isinstance(detail, str) else f"HTTP {resp.status_code}"
+    raise error_from_status(resp.status_code, message, detail)
+
+
+class HostPay:
+    """HostPay API client.
+
+    >>> client = HostPay(api_key="ak-...", secret_key="sk-...")
+    >>> user = client.users.create(app_user_id="u1", name="Alice", phone_number="+23279000000")
+    >>> wallet = client.wallets.create(user.id)
+    >>> client.deposits.mobile_money(wallet_id=wallet.id, amount=100)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        secret_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key or not secret_key:
+            raise ValueError("api_key and secret_key are required")
+        self._transport = _Transport(
+            api_key, secret_key, base_url, timeout, max_retries, http_client
+        )
+        self.users = Users(self._transport)
+        self.wallets = Wallets(self._transport)
+        self.deposits = Deposits(self._transport)
+        self.transfers = Transfers(self._transport)
+        self.transactions = Transactions(self._transport)
+        self.payouts = Payouts(self._transport)
+        self.escrow = Escrow(self._transport)
+        self.webhooks = Webhooks()
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "HostPay":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class _AsyncTransport:
+    """Async twin of _Transport: same auth, retries, and error mapping."""
+
+    def __init__(
+        self,
+        api_key: str,
+        secret_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        http_client: Optional[httpx.AsyncClient],
+    ) -> None:
+        self._max_retries = max_retries
+        # Auth is applied per-request so a caller-supplied http_client is still
+        # authenticated.
+        self._auth = {
+            "api-key": api_key,
+            "secret-key": secret_key,
+            "User-Agent": f"hostpay-python/{_VERSION}",
+        }
+        self._client = http_client or httpx.AsyncClient(
+            base_url=base_url.rstrip("/"), timeout=timeout
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[dict] = None,
+        params: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        headers: Dict[str, str] = dict(self._auth)
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        # Retry only idempotent-safe conditions: connection errors and 5xx. POSTs
+        # are retried too — the API supports Idempotency-Key for money movements.
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = await self._client.request(
+                    method, path, json=json, params=params, headers=headers
+                )
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    await asyncio.sleep(0.5 * (2 ** attempt))
+                    continue
+                raise APIConnectionError(f"Could not reach HostPay: {exc}") from exc
+
+            if resp.status_code >= 500 and attempt < self._max_retries:
+                await asyncio.sleep(0.5 * (2 ** attempt))
+                continue
+            return _handle_response(resp)
+        raise APIConnectionError(f"Could not reach HostPay: {last_exc}")
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+
+class AsyncHostPay:
+    """Async HostPay API client — the same surface as HostPay, awaited.
+
+    >>> async with AsyncHostPay(api_key="ak-...", secret_key="sk-...") as client:
+    ...     user = await client.users.create(app_user_id="u1", name="Alice", phone_number="+23279000000")
+    ...     wallet = await client.wallets.create(user.id)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        secret_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        if not api_key or not secret_key:
+            raise ValueError("api_key and secret_key are required")
+        self._transport = _AsyncTransport(
+            api_key, secret_key, base_url, timeout, max_retries, http_client
+        )
+        self.users = _async_resources.Users(self._transport)
+        self.wallets = _async_resources.Wallets(self._transport)
+        self.deposits = _async_resources.Deposits(self._transport)
+        self.transfers = _async_resources.Transfers(self._transport)
+        self.transactions = _async_resources.Transactions(self._transport)
+        self.payouts = _async_resources.Payouts(self._transport)
+        self.escrow = _async_resources.Escrow(self._transport)
+        # Webhook verification is pure crypto (no I/O) — shared with the sync client.
+        self.webhooks = Webhooks()
+
+    async def aclose(self) -> None:
+        await self._transport.close()
+
+    async def __aenter__(self) -> "AsyncHostPay":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

{hostpay-0.2.0 → hostpay-0.3.0}/hostpay/resources.py

@@ -81,6 +81,10 @@ class Wallets(_Resource):
     def balance(self, wallet_id: str) -> Any:
         return self._t.request("GET", f"/api/v1/wallets/{wallet_id}/balance")
 
+    def list(self, is_active: Optional[bool] = None) -> list[WalletRead]:
+        params = {} if is_active is None else {"is_active": is_active}
+        return self._t.request("GET", "/api/v1/wallets/", params=params)
+
     def disable(self, wallet_id: str) -> Any:
         return self._t.request("POST", f"/api/v1/wallets/{wallet_id}/disable")
 

{hostpay-0.2.0 → hostpay-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostpay"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for the HostPay payments API"
 readme = "README.md"
 requires-python = ">=3.8"

hostpay-0.3.0/tests/test_async_client.py

@@ -0,0 +1,153 @@
+"""Async client tests — mirrors test_client.py through AsyncHostPay.
+
+Runs each case with asyncio.run() inside a plain sync test, so no
+pytest-asyncio dependency (works unchanged on Python 3.8–3.14).
+"""
+import asyncio
+import inspect
+import json
+
+import httpx
+import pytest
+
+from hostpay import AsyncHostPay, AuthenticationError, InvalidRequestError
+from hostpay import _async_resources, resources
+
+
+def _client(handler):
+    """An AsyncHostPay client whose HTTP layer is a MockTransport running `handler`."""
+    mock = httpx.MockTransport(handler)
+    http = httpx.AsyncClient(base_url="https://api.test", transport=mock)
+    return AsyncHostPay(api_key="ak-x", secret_key="sk-y", http_client=http)
+
+
+def test_auth_headers_and_path_and_body():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"] = request.url.path
+        seen["api-key"] = request.headers.get("api-key")
+        seen["secret-key"] = request.headers.get("secret-key")
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(201, json={"id": "usr_1", "name": "Alice"})
+
+    async def case():
+        async with _client(handler) as client:
+            return await client.users.create(
+                app_user_id="u1", name="Alice", phone_number="+23279000000"
+            )
+
+    user = asyncio.run(case())
+    assert seen["path"] == "/api/v1/users/create/"
+    assert seen["api-key"] == "ak-x" and seen["secret-key"] == "sk-y"
+    assert seen["body"]["app_user_id"] == "u1"
+    assert user.id == "usr_1"  # attribute access on the response
+
+
+def test_idempotency_key_forwarded():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["idem"] = request.headers.get("Idempotency-Key")
+        return httpx.Response(200, json={"transaction_id": "txn_1"})
+
+    async def case():
+        async with _client(handler) as client:
+            await client.deposits.mobile_money(
+                wallet_id="w1", amount=100, idempotency_key="abc-123"
+            )
+
+    asyncio.run(case())
+    assert seen["idem"] == "abc-123"
+
+
+def test_error_mapping():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(403, json={"detail": "Invalid credentials"})
+
+    async def case():
+        async with _client(handler) as client:
+            await client.wallets.balance("w1")
+
+    with pytest.raises(AuthenticationError) as exc:
+        asyncio.run(case())
+    assert exc.value.status_code == 403
+    assert "Invalid credentials" in str(exc.value)
+
+
+def test_validation_error_is_invalid_request():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(422, json={"detail": "bad amount"})
+
+    async def case():
+        async with _client(handler) as client:
+            await client.payouts.mobile_money(
+                wallet_id="w1", amount=-5, phone_number="+232"
+            )
+
+    with pytest.raises(InvalidRequestError):
+        asyncio.run(case())
+
+
+def test_query_params_and_list_response():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"] = request.url.path
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(200, json=[{"id": "usr_1"}])
+
+    async def case():
+        async with _client(handler) as client:
+            return await client.users.list(is_active=True)
+
+    users = asyncio.run(case())
+    assert seen["path"] == "/api/v1/users/"
+    assert seen["query"] == {"is_active": "true"}
+    assert users[0]["id"] == "usr_1"
+
+
+def test_retries_5xx_then_succeeds():
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(1)
+        if len(calls) == 1:
+            return httpx.Response(502, json={"detail": "bad gateway"})
+        return httpx.Response(200, json={"balance": "5.00"})
+
+    async def case():
+        async with _client(handler) as client:
+            return await client.wallets.balance("w1")
+
+    bal = asyncio.run(case())
+    assert len(calls) == 2
+    assert bal["balance"] == "5.00"
+
+
+def test_async_resources_mirror_sync():
+    """The async module must expose the same classes, methods, and signatures
+    as the sync one — this is the guard that keeps the two copies in step."""
+    sync_classes = {
+        n: c
+        for n, c in vars(resources).items()
+        if inspect.isclass(c) and not n.startswith("_") and c.__module__ == resources.__name__
+    }
+    assert sync_classes, "no sync resource classes found"
+    for name, sync_cls in sync_classes.items():
+        async_cls = getattr(_async_resources, name, None)
+        assert async_cls is not None, f"missing async twin for {name}"
+        sync_methods = {
+            n: f for n, f in inspect.getmembers(sync_cls, inspect.isfunction)
+            if not n.startswith("_")
+        }
+        async_methods = {
+            n: f for n, f in inspect.getmembers(async_cls, inspect.isfunction)
+            if not n.startswith("_")
+        }
+        assert sync_methods.keys() == async_methods.keys(), name
+        for meth, sync_fn in sync_methods.items():
+            assert inspect.iscoroutinefunction(async_methods[meth]), f"{name}.{meth} not async"
+            assert inspect.signature(sync_fn) == inspect.signature(async_methods[meth]), (
+                f"{name}.{meth} signature drifted"
+            )

{hostpay-0.2.0 → hostpay-0.3.0}/tests/test_client.py

@@ -123,3 +123,18 @@ def test_lifecycle_and_transactions_paths():
         ("GET", "/api/v1/transactions/wallet/w1", {}),
         ("GET", "/api/v1/transactions/", {"status": "completed", "limit": "10", "offset": "0"}),
     ]
+
+
+def test_wallets_list_passes_query_params():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"] = request.url.path
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(200, json=[{"id": "w1", "balance": "5.00"}])
+
+    client = _client(handler)
+    wallets = client.wallets.list(is_active=True)
+    assert seen["path"] == "/api/v1/wallets/"
+    assert seen["query"] == {"is_active": "true"}
+    assert wallets[0]["id"] == "w1"

hostpay-0.2.0/hostpay/_client.py

@@ -1,138 +0,0 @@
-"""HTTP transport + the top-level HostPay client."""
-from __future__ import annotations
-
-import time
-from typing import Any, Dict, Optional
-
-import httpx
-
-from ._object import HostPayObject, _wrap
-from .errors import APIConnectionError, error_from_status
-from .resources import (
-    Deposits,
-    Escrow,
-    Payouts,
-    Transactions,
-    Transfers,
-    Users,
-    Wallets,
-)
-from .webhooks import Webhooks
-
-DEFAULT_BASE_URL = "https://hpay-api.host-sl.com"
-
-
-class _Transport:
-    """Builds authenticated requests, retries transient failures, maps errors."""
-
-    def __init__(
-        self,
-        api_key: str,
-        secret_key: str,
-        base_url: str,
-        timeout: float,
-        max_retries: int,
-        http_client: Optional[httpx.Client],
-    ) -> None:
-        self._max_retries = max_retries
-        # Auth is applied per-request so a caller-supplied http_client is still
-        # authenticated.
-        self._auth = {
-            "api-key": api_key,
-            "secret-key": secret_key,
-            "User-Agent": "hostpay-python/0.1.0",
-        }
-        self._client = http_client or httpx.Client(
-            base_url=base_url.rstrip("/"), timeout=timeout
-        )
-
-    def request(
-        self,
-        method: str,
-        path: str,
-        json: Optional[dict] = None,
-        params: Optional[dict] = None,
-        idempotency_key: Optional[str] = None,
-    ) -> Any:
-        headers: Dict[str, str] = dict(self._auth)
-        if idempotency_key:
-            headers["Idempotency-Key"] = idempotency_key
-        # Retry only idempotent-safe conditions: connection errors and 5xx. POSTs
-        # are retried too — the API supports Idempotency-Key for money movements.
-        last_exc: Optional[Exception] = None
-        for attempt in range(self._max_retries + 1):
-            try:
-                resp = self._client.request(
-                    method, path, json=json, params=params, headers=headers
-                )
-            except httpx.HTTPError as exc:
-                last_exc = exc
-                if attempt < self._max_retries:
-                    time.sleep(0.5 * (2 ** attempt))
-                    continue
-                raise APIConnectionError(f"Could not reach HostPay: {exc}") from exc
-
-            if resp.status_code >= 500 and attempt < self._max_retries:
-                time.sleep(0.5 * (2 ** attempt))
-                continue
-            return _handle_response(resp)
-        raise APIConnectionError(f"Could not reach HostPay: {last_exc}")
-
-    def close(self) -> None:
-        self._client.close()
-
-
-def _handle_response(resp: "httpx.Response") -> Any:
-    if 200 <= resp.status_code < 300:
-        if not resp.content:
-            return None
-        return _wrap(resp.json())
-    try:
-        body = resp.json()
-        detail = body.get("detail", body) if isinstance(body, dict) else body
-    except ValueError:
-        detail = resp.text
-    message = detail if isinstance(detail, str) else f"HTTP {resp.status_code}"
-    raise error_from_status(resp.status_code, message, detail)
-
-
-class HostPay:
-    """HostPay API client.
-
-    >>> client = HostPay(api_key="ak-...", secret_key="sk-...")
-    >>> user = client.users.create(app_user_id="u1", name="Alice", phone_number="+23279000000")
-    >>> wallet = client.wallets.create(user.id)
-    >>> client.deposits.mobile_money(wallet_id=wallet.id, amount=100)
-    """
-
-    def __init__(
-        self,
-        api_key: str,
-        secret_key: str,
-        base_url: str = DEFAULT_BASE_URL,
-        timeout: float = 30.0,
-        max_retries: int = 2,
-        http_client: Optional[httpx.Client] = None,
-    ) -> None:
-        if not api_key or not secret_key:
-            raise ValueError("api_key and secret_key are required")
-        self._transport = _Transport(
-            api_key, secret_key, base_url, timeout, max_retries, http_client
-        )
-        self.users = Users(self._transport)
-        self.wallets = Wallets(self._transport)
-        self.deposits = Deposits(self._transport)
-        self.transfers = Transfers(self._transport)
-        self.transactions = Transactions(self._transport)
-        self.payouts = Payouts(self._transport)
-        self.escrow = Escrow(self._transport)
-        self.webhooks = Webhooks()
-
-    def close(self) -> None:
-        self._transport.close()
-
-    def __enter__(self) -> "HostPay":
-        return self
-
-    def __exit__(self, *exc: object) -> None:
-        self.close()