solvapay-python 0.7.0__py3-none-any.whl → 0.7.2__py3-none-any.whl

solvapay/__init__.py

@@ -21,24 +21,44 @@ from solvapay.events import (
     PurchaseUpdated,
     WebhookEvent,
 )
-from solvapay.exceptions import SolvaPayAPIError, SolvaPayError
+from solvapay.exceptions import (
+    APIConnectionError,
+    APIError,
+    APIServerError,
+    APITimeoutError,
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    SolvaPayAPIError,
+    SolvaPayError,
+)
 from solvapay.models import BalanceResponse, Merchant, Plan, PlatformConfig, Product
 from solvapay.paywall import PaywallRequired
 from solvapay.webhooks import verify_webhook
 
 __all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIServerError",
+    "APITimeoutError",
     "AsyncSolvaPay",
+    "AuthenticationError",
     "BalanceResponse",
     "CheckoutSessionCreated",
     "CustomerCreated",
     "CustomerDeleted",
     "CustomerUpdated",
+    "InvalidRequestError",
     "Merchant",
+    "NotFoundError",
     "PaymentFailed",
     "PaymentRefundFailed",
     "PaymentRefunded",
     "PaymentSucceeded",
     "PaywallRequired",
+    "PermissionError",
     "Plan",
     "PlatformConfig",
     "Product",
@@ -47,6 +67,7 @@ __all__ = [
     "PurchaseExpired",
     "PurchaseSuspended",
     "PurchaseUpdated",
+    "RateLimitError",
     "SolvaPay",
     "SolvaPayAPIError",
     "SolvaPayError",
@@ -54,4 +75,4 @@ __all__ = [
     "paywall",
     "verify_webhook",
 ]
-__version__ = "0.7.0"
+__version__ = "0.7.2"

solvapay/_async_client.py

@@ -6,6 +6,7 @@ Use `async with AsyncSolvaPay() as sv: ...` for proper teardown.
 
 from __future__ import annotations
 
+import logging
 import time
 from typing import Any
 
@@ -56,11 +57,13 @@ class AsyncSolvaPay:
         *,
         base_url: str | None = None,
         timeout: float = 30.0,
+        logger: logging.Logger | None = None,
     ) -> None:
         self._http = AsyncHttpClient(
             api_key=resolve_api_key(api_key),
             base_url=resolve_base_url(base_url),
             timeout=timeout,
+            logger=logger,
         )
 
     async def aclose(self) -> None:
@@ -79,6 +82,7 @@ class AsyncSolvaPay:
         product_ref: str,
         plan_ref: str | None = None,
         return_url: str | None = None,
+        idempotency_key: str | None = None,
     ) -> CheckoutSession:
         req = CheckoutSessionRequest(
             customer_ref=customer_ref,
@@ -91,6 +95,7 @@ class AsyncSolvaPay:
                 "POST",
                 "/v1/sdk/checkout-sessions",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         return CheckoutSession.model_validate(data)
@@ -102,6 +107,7 @@ class AsyncSolvaPay:
         *,
         email: str | None = None,
         name: str | None = None,
+        idempotency_key: str | None = None,
     ) -> str:
         lookup_ref = external_ref or customer_ref
         try:
@@ -122,7 +128,10 @@ class AsyncSolvaPay:
         )
         created = await self._http.send(
             _RequestSpec(
-                "POST", "/v1/sdk/customers", json=req.model_dump(by_alias=True, exclude_none=True)
+                "POST",
+                "/v1/sdk/customers",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         ref = created.get("reference") or created.get("customerRef")
@@ -226,7 +235,11 @@ class AsyncSolvaPay:
         return BalanceResponse.model_validate(data)
 
     async def cancel_purchase(
-        self, purchase_ref: str, *, reason: str | None = None
+        self,
+        purchase_ref: str,
+        *,
+        reason: str | None = None,
+        idempotency_key: str | None = None,
     ) -> dict[str, Any]:
         """Cancel a purchase. Maps to POST /v1/sdk/purchases/{ref}/cancel."""
         req = CancelPurchaseRequest(reason=reason)
@@ -235,13 +248,20 @@ class AsyncSolvaPay:
                 "POST",
                 f"/v1/sdk/purchases/{purchase_ref}/cancel",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
 
-    async def reactivate_purchase(self, purchase_ref: str) -> dict[str, Any]:
+    async def reactivate_purchase(
+        self, purchase_ref: str, *, idempotency_key: str | None = None
+    ) -> dict[str, Any]:
         """Reactivate a cancelled purchase. Maps to POST /v1/sdk/purchases/{ref}/reactivate."""
         return await self._http.send(
-            _RequestSpec("POST", f"/v1/sdk/purchases/{purchase_ref}/reactivate")
+            _RequestSpec(
+                "POST",
+                f"/v1/sdk/purchases/{purchase_ref}/reactivate",
+                idempotency_key=idempotency_key,
+            )
         )
 
     # --- Admin: Products ---
@@ -257,7 +277,9 @@ class AsyncSolvaPay:
         data = await self._http.send(_RequestSpec("GET", f"/v1/sdk/products/{product_ref}"))
         return Product.model_validate(data)
 
-    async def create_product(self, *, name: str, type: str, default_currency: str) -> Product:
+    async def create_product(
+        self, *, name: str, type: str, default_currency: str, idempotency_key: str | None = None
+    ) -> Product:
         """Create a product. Maps to POST /v1/sdk/products."""
         req = CreateProductRequest(name=name, type=type, default_currency=default_currency)
         data = await self._http.send(
@@ -265,6 +287,7 @@ class AsyncSolvaPay:
                 "POST",
                 "/v1/sdk/products",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         return Product.model_validate(data)
@@ -273,7 +296,9 @@ class AsyncSolvaPay:
         """Delete a product. Maps to DELETE /v1/sdk/products/{ref}."""
         return await self._http.send(_RequestSpec("DELETE", f"/v1/sdk/products/{product_ref}"))
 
-    async def clone_product(self, product_ref: str, *, new_name: str) -> Product:
+    async def clone_product(
+        self, product_ref: str, *, new_name: str, idempotency_key: str | None = None
+    ) -> Product:
         """Clone a product with a new name. Maps to POST /v1/sdk/products/{ref}/clone."""
         req = CloneProductRequest(new_name=new_name)
         data = await self._http.send(
@@ -281,6 +306,7 @@ class AsyncSolvaPay:
                 "POST",
                 f"/v1/sdk/products/{product_ref}/clone",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         return Product.model_validate(data)
@@ -302,6 +328,7 @@ class AsyncSolvaPay:
         price: float | None = None,
         currency: str | None = None,
         interval: str | None = None,
+        idempotency_key: str | None = None,
     ) -> Plan:
         """Create a plan for a product. Maps to POST /v1/sdk/products/{ref}/plans."""
         req = CreatePlanRequest(
@@ -312,6 +339,7 @@ class AsyncSolvaPay:
                 "POST",
                 f"/v1/sdk/products/{product_ref}/plans",
                 json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
             )
         )
         return Plan.model_validate(data)

solvapay/_http.py

@@ -2,12 +2,26 @@
 
 from __future__ import annotations
 
+import logging
+import time
 from dataclasses import dataclass
 from typing import Any
 
 import httpx
 
-from solvapay.exceptions import SolvaPayAPIError
+from solvapay.exceptions import (
+    APIConnectionError,
+    APIError,
+    APIServerError,
+    APITimeoutError,
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+)
+
+_logger = logging.getLogger("solvapay.http")
 
 
 @dataclass(frozen=True)
@@ -22,22 +36,109 @@ class _RequestSpec:
         return {"Idempotency-Key": self.idempotency_key} if self.idempotency_key else {}
 
 
+def _parse_error(response: httpx.Response) -> APIError:
+    request_id = response.headers.get("x-request-id") or response.headers.get("x-correlation-id")
+    error_code: str | None = None
+    error_message: str | None = None
+    try:
+        payload = response.json()
+        if isinstance(payload, dict):
+            err = payload.get("error", payload)
+            if isinstance(err, dict):
+                code = err.get("code")
+                msg = err.get("message")
+                if isinstance(code, str):
+                    error_code = code
+                if isinstance(msg, str):
+                    error_message = msg
+    except Exception:
+        pass
+
+    status = response.status_code
+    body = response.text
+
+    if status == 401:
+        return AuthenticationError(
+            status, body, request_id=request_id, error_code=error_code, error_message=error_message
+        )
+    if status == 403:
+        return PermissionError(
+            status, body, request_id=request_id, error_code=error_code, error_message=error_message
+        )
+    if status == 404:
+        return NotFoundError(
+            status, body, request_id=request_id, error_code=error_code, error_message=error_message
+        )
+    if status == 429:
+        return RateLimitError(
+            status,
+            body,
+            request_id=request_id,
+            error_code=error_code,
+            error_message=error_message,
+            retry_after=response.headers.get("Retry-After"),
+        )
+    if 400 <= status < 500:
+        return InvalidRequestError(
+            status, body, request_id=request_id, error_code=error_code, error_message=error_message
+        )
+    return APIServerError(
+        status, body, request_id=request_id, error_code=error_code, error_message=error_message
+    )
+
+
 def _handle(response: httpx.Response) -> dict[str, Any]:
     if not response.is_success:
-        raise SolvaPayAPIError(response.status_code, response.text)
+        raise _parse_error(response)
     if response.status_code == 204 or not response.content:
         return {}
     return response.json()  # type: ignore[no-any-return]
 
 
+def _log_response(
+    logger: logging.Logger,
+    spec: _RequestSpec,
+    response: httpx.Response,
+    duration_ms: int,
+) -> None:
+    request_id = response.headers.get("x-request-id") or response.headers.get("x-correlation-id")
+    extra: dict[str, object] = {"request_id": request_id, "duration_ms": duration_ms}
+    if response.is_success:
+        logger.info(
+            "%s %s → %d (%dms)",
+            spec.method,
+            spec.path,
+            response.status_code,
+            duration_ms,
+            extra=extra,
+        )
+    else:
+        logger.warning(
+            "%s %s → %d (%dms)",
+            spec.method,
+            spec.path,
+            response.status_code,
+            duration_ms,
+            extra={**extra, "body_excerpt": response.text[:200]},
+        )
+
+
 class HttpClient:
-    def __init__(self, *, api_key: str, base_url: str, timeout: float = 30.0) -> None:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float = 30.0,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self._logger = logger or _logger
         self._client = httpx.Client(
             base_url=base_url,
             headers={
                 "Authorization": f"Bearer {api_key}",
                 "Content-Type": "application/json",
-                "User-Agent": "solvapay-python/0.7.0",
+                "User-Agent": "solvapay-python/0.7.1",
             },
             timeout=timeout,
         )
@@ -52,15 +153,17 @@ class HttpClient:
         self.close()
 
     def send(self, spec: _RequestSpec) -> dict[str, Any]:
-        return _handle(
-            self._client.request(
-                spec.method,
-                spec.path,
-                json=spec.json,
-                params=spec.params,
-                headers=spec.headers(),
+        t0 = time.perf_counter()
+        try:
+            response = self._client.request(
+                spec.method, spec.path, json=spec.json, params=spec.params, headers=spec.headers()
             )
-        )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(str(exc)) from exc
+        except (httpx.ConnectError, httpx.ReadError) as exc:
+            raise APIConnectionError(str(exc)) from exc
+        _log_response(self._logger, spec, response, int((time.perf_counter() - t0) * 1000))
+        return _handle(response)
 
     def request(
         self,
@@ -75,13 +178,21 @@ class HttpClient:
 
 
 class AsyncHttpClient:
-    def __init__(self, *, api_key: str, base_url: str, timeout: float = 30.0) -> None:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float = 30.0,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self._logger = logger or _logger
         self._client = httpx.AsyncClient(
             base_url=base_url,
             headers={
                 "Authorization": f"Bearer {api_key}",
                 "Content-Type": "application/json",
-                "User-Agent": "solvapay-python/0.7.0",
+                "User-Agent": "solvapay-python/0.7.1",
             },
             timeout=timeout,
         )
@@ -96,12 +207,14 @@ class AsyncHttpClient:
         await self.aclose()
 
     async def send(self, spec: _RequestSpec) -> dict[str, Any]:
-        return _handle(
-            await self._client.request(
-                spec.method,
-                spec.path,
-                json=spec.json,
-                params=spec.params,
-                headers=spec.headers(),
+        t0 = time.perf_counter()
+        try:
+            response = await self._client.request(
+                spec.method, spec.path, json=spec.json, params=spec.params, headers=spec.headers()
             )
-        )
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError(str(exc)) from exc
+        except (httpx.ConnectError, httpx.ReadError) as exc:
+            raise APIConnectionError(str(exc)) from exc
+        _log_response(self._logger, spec, response, int((time.perf_counter() - t0) * 1000))
+        return _handle(response)

solvapay/client.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import time
 from typing import Any
 
@@ -54,11 +55,13 @@ class SolvaPay:
         *,
         base_url: str | None = None,
         timeout: float = 30.0,
+        logger: logging.Logger | None = None,
     ) -> None:
         self._http = HttpClient(
             api_key=resolve_api_key(api_key),
             base_url=resolve_base_url(base_url),
             timeout=timeout,
+            logger=logger,
         )
 
     def close(self) -> None:
@@ -77,6 +80,7 @@ class SolvaPay:
         product_ref: str,
         plan_ref: str | None = None,
         return_url: str | None = None,
+        idempotency_key: str | None = None,
     ) -> CheckoutSession:
         """Create a hosted checkout session.
 
@@ -101,6 +105,7 @@ class SolvaPay:
             "POST",
             "/v1/sdk/checkout-sessions",
             json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
         )
         return CheckoutSession.model_validate(data)
 
@@ -111,6 +116,7 @@ class SolvaPay:
         *,
         email: str | None = None,
         name: str | None = None,
+        idempotency_key: str | None = None,
     ) -> str:
         """Idempotently create or look up a customer.
 
@@ -140,6 +146,7 @@ class SolvaPay:
             "POST",
             "/v1/sdk/customers",
             json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
         )
         ref = created.get("reference") or created.get("customerRef")
         if not ref:
@@ -238,18 +245,27 @@ class SolvaPay:
         data = self._http.request("GET", f"/v1/sdk/customers/{customer_ref}/balance")
         return BalanceResponse.model_validate(data)
 
-    def cancel_purchase(self, purchase_ref: str, *, reason: str | None = None) -> dict[str, Any]:
+    def cancel_purchase(
+        self, purchase_ref: str, *, reason: str | None = None, idempotency_key: str | None = None
+    ) -> dict[str, Any]:
         """Cancel a purchase. Maps to POST /v1/sdk/purchases/{ref}/cancel."""
         req = CancelPurchaseRequest(reason=reason)
         return self._http.request(
             "POST",
             f"/v1/sdk/purchases/{purchase_ref}/cancel",
             json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
         )
 
-    def reactivate_purchase(self, purchase_ref: str) -> dict[str, Any]:
+    def reactivate_purchase(
+        self, purchase_ref: str, *, idempotency_key: str | None = None
+    ) -> dict[str, Any]:
         """Reactivate a cancelled purchase. Maps to POST /v1/sdk/purchases/{ref}/reactivate."""
-        return self._http.request("POST", f"/v1/sdk/purchases/{purchase_ref}/reactivate")
+        return self._http.request(
+            "POST",
+            f"/v1/sdk/purchases/{purchase_ref}/reactivate",
+            idempotency_key=idempotency_key,
+        )
 
     # --- Admin: Products ---
 
@@ -264,13 +280,16 @@ class SolvaPay:
         data = self._http.request("GET", f"/v1/sdk/products/{product_ref}")
         return Product.model_validate(data)
 
-    def create_product(self, *, name: str, type: str, default_currency: str) -> Product:
+    def create_product(
+        self, *, name: str, type: str, default_currency: str, idempotency_key: str | None = None
+    ) -> Product:
         """Create a product. Maps to POST /v1/sdk/products."""
         req = CreateProductRequest(name=name, type=type, default_currency=default_currency)
         data = self._http.request(
             "POST",
             "/v1/sdk/products",
             json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
         )
         return Product.model_validate(data)
 
@@ -278,13 +297,16 @@ class SolvaPay:
         """Delete a product. Maps to DELETE /v1/sdk/products/{ref}."""
         return self._http.request("DELETE", f"/v1/sdk/products/{product_ref}")
 
-    def clone_product(self, product_ref: str, *, new_name: str) -> Product:
+    def clone_product(
+        self, product_ref: str, *, new_name: str, idempotency_key: str | None = None
+    ) -> Product:
         """Clone a product with a new name. Maps to POST /v1/sdk/products/{ref}/clone."""
         req = CloneProductRequest(new_name=new_name)
         data = self._http.request(
             "POST",
             f"/v1/sdk/products/{product_ref}/clone",
             json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
         )
         return Product.model_validate(data)
 
@@ -305,6 +327,7 @@ class SolvaPay:
         price: float | None = None,
         currency: str | None = None,
         interval: str | None = None,
+        idempotency_key: str | None = None,
     ) -> Plan:
         """Create a plan for a product. Maps to POST /v1/sdk/products/{ref}/plans."""
         req = CreatePlanRequest(
@@ -314,6 +337,7 @@ class SolvaPay:
             "POST",
             f"/v1/sdk/products/{product_ref}/plans",
             json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
         )
         return Plan.model_validate(data)
 

solvapay/exceptions.py

@@ -7,10 +7,80 @@ class SolvaPayError(Exception):
     """Base exception for all SolvaPay SDK errors."""
 
 
-class SolvaPayAPIError(SolvaPayError):
+class APIError(SolvaPayError):
     """Raised when the SolvaPay API returns a non-2xx response."""
 
-    def __init__(self, status_code: int, body: str, message: str | None = None) -> None:
+    def __init__(
+        self,
+        status_code: int,
+        body: str,
+        *,
+        request_id: str | None = None,
+        error_code: str | None = None,
+        error_message: str | None = None,
+        message: str | None = None,
+    ) -> None:
         self.status_code = status_code
         self.body = body
+        self.request_id = request_id
+        self.error_code = error_code
+        self.error_message = error_message
         super().__init__(message or f"SolvaPay API error {status_code}: {body}")
+
+
+class AuthenticationError(APIError):
+    """401 — invalid or missing API key."""
+
+
+class PermissionError(APIError):  # shadows built-in; intentional in SDK module namespace
+    """403 — insufficient permissions for this operation."""
+
+
+class NotFoundError(APIError):
+    """404 — requested resource does not exist."""
+
+
+class RateLimitError(APIError):
+    """429 — rate limit exceeded. Check .retry_after for the suggested delay (seconds)."""
+
+    def __init__(
+        self,
+        status_code: int,
+        body: str,
+        *,
+        request_id: str | None = None,
+        error_code: str | None = None,
+        error_message: str | None = None,
+        message: str | None = None,
+        retry_after: str | None = None,
+    ) -> None:
+        super().__init__(
+            status_code,
+            body,
+            request_id=request_id,
+            error_code=error_code,
+            error_message=error_message,
+            message=message,
+        )
+        self.retry_after = retry_after
+
+
+class InvalidRequestError(APIError):
+    """4xx (non-401/403/404/429) — malformed or invalid request."""
+
+
+class APIServerError(APIError):
+    """5xx — server-side error."""
+
+
+class APIConnectionError(SolvaPayError):
+    """Network-level error — connection refused, reset, or DNS failure."""
+
+
+class APITimeoutError(SolvaPayError):
+    """Request timed out before the server responded."""
+
+
+# Back-compat alias: existing `except SolvaPayAPIError` catches and `.status_code` access
+# continue to work. Will emit DeprecationWarning in v1.0 pre-tag.
+SolvaPayAPIError = APIError

solvapay/idempotency.py

@@ -0,0 +1,16 @@
+"""Idempotency key helpers for SolvaPay SDK."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+
+def from_payload(*parts: str | int | float | None) -> str:
+    """SHA256 of stable-serialized payload parts → 32-hex-char key.
+
+    Deterministic, 24h-safe. Caller is responsible for input stability.
+    Retried POSTs must supply the *same* key as the original call.
+    """
+    data = json.dumps(parts, separators=(",", ":"), default=str)
+    return hashlib.sha256(data.encode()).hexdigest()[:32]

solvapay/paywall.py

@@ -124,24 +124,29 @@ def require_async(
                     f"@paywall.require_async expected str kwarg '{customer_ref_arg}', "
                     f"got {type(customer_ref).__name__}"
                 )
-            sv: AsyncSolvaPay = client if isinstance(client, AsyncSolvaPay) else AsyncSolvaPay()
-            limits = await sv.check_limits(
-                customer_ref=customer_ref,
-                product_ref=product,
-                plan_ref=plan,
-            )
-            if not limits.within_limits:
-                checkout_url = limits.checkout_url
-                if checkout_url is None:
-                    try:
-                        session = await sv.create_checkout_session(
-                            customer_ref=customer_ref, product_ref=product, plan_ref=plan
-                        )
-                        checkout_url = session.checkout_url
-                    except SolvaPayError:
-                        pass
-                raise PaywallRequired(checkout_url=checkout_url)
-            return await fn(*args, **kwargs)
+            _owns_client = not isinstance(client, AsyncSolvaPay)
+            sv: AsyncSolvaPay = AsyncSolvaPay() if _owns_client else client  # type: ignore[assignment]
+            try:
+                limits = await sv.check_limits(
+                    customer_ref=customer_ref,
+                    product_ref=product,
+                    plan_ref=plan,
+                )
+                if not limits.within_limits:
+                    checkout_url = limits.checkout_url
+                    if checkout_url is None:
+                        try:
+                            session = await sv.create_checkout_session(
+                                customer_ref=customer_ref, product_ref=product, plan_ref=plan
+                            )
+                            checkout_url = session.checkout_url
+                        except SolvaPayError:
+                            pass
+                    raise PaywallRequired(checkout_url=checkout_url)
+                return await fn(*args, **kwargs)
+            finally:
+                if _owns_client:
+                    await sv.aclose()
 
         return wrapper
 

{solvapay_python-0.7.0.dist-info → solvapay_python-0.7.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solvapay-python
-Version: 0.7.0
+Version: 0.7.2
 Summary: Community Python SDK for SolvaPay (agent-native payment rails)
 Project-URL: Homepage, https://github.com/dhruv-sanan/solvapay-python
 Project-URL: Issues, https://github.com/dhruv-sanan/solvapay-python/issues
@@ -9,14 +9,17 @@ Author: Dhruv Sanan
 License: MIT
 License-File: LICENSE
 Keywords: agents,fintech,mcp,payments,solvapay
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.5
@@ -32,12 +35,15 @@ Description-Content-Type: text/markdown
 
 Community Python SDK for [SolvaPay](https://solvapay.com) — payment rails for the agentic economy.
 
-> **Status:** v0.6, community-maintained. Available on PyPI. Pending official adoption.
+> **Status:** v0.7.2, community-maintained. Available on PyPI. Pending official adoption.
 > Mirrors the most-used surface of [@solvapay/core](https://github.com/solvapay/solvapay-sdk).
 
 Python is the dominant language for agent frameworks (LangChain, FastMCP, CrewAI, AutoGen). SolvaPay's official SDK is TypeScript-only. This SDK brings first-class Python support so agent developers can gate tools behind paywalls without switching ecosystems.
 
-> **New in v0.6:** Admin endpoints (products, plans, merchant, platform config). Published to PyPI.
+> **New in v0.7.2:** Async resource leak fix in `@paywall.require_async` — `AsyncSolvaPay` now properly closed when owned by the decorator. Example dep fixes.
+> **v0.7.1:** Full error hierarchy (`AuthenticationError`, `NotFoundError`, `RateLimitError`, `APIConnectionError`, `APITimeoutError`), idempotency keys on all mutating ops, `py.typed` PEP 561 marker, structured HTTP logging.
+> **New in v0.7.0:** Real-API alignment (wire-format fixes), `paywall_state.gate()` enrichment helper, marketplace Streamlit demo.
+> **v0.6:** Admin endpoints (products, plans, merchant, platform config). Published to PyPI.
 > **v0.5:** Paywall state classifier (`paywall_state` module) and LangChain `monetize_tool` decorator — gate any LangChain tool behind a SolvaPay paywall with one line.
 > **v0.4:** Async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events.
 
@@ -147,12 +153,69 @@ if not limits.within_limits:
     print(d.checkout_url)   # "https://solvapay.com/c/..."
 ```
 
+For real-API calls use `gate()` instead — it enriches the bare `/v1/sdk/limits` response (which has no `plan` or `checkout_url`) in one call:
+
+```python
+from solvapay.paywall_state import gate
+
+decision = gate(sv, customer_ref="cus_x", product_ref="prd_y")
+# decision.state        — PaywallState.UPGRADE_REQUIRED (etc)
+# decision.checkout_url — minted via create_checkout_session if needed
+# decision.message      — TS-style copy with URL inlined
+```
+
+## Error handling
+
+v0.7.1 ships a structured exception hierarchy under `SolvaPayError`:
+
+```python
+import time
+from solvapay import (
+    SolvaPayError,        # catch-all
+    APIError,             # base for all HTTP errors — has .status_code, .request_id
+    AuthenticationError,  # 401
+    NotFoundError,        # 404
+    RateLimitError,       # 429 — adds .retry_after
+    APIConnectionError,   # network failure
+    APITimeoutError,      # request timeout
+)
+
+try:
+    sv.get_customer("cus_missing")
+except NotFoundError as e:
+    print(e.status_code, e.request_id)
+except RateLimitError as e:
+    time.sleep(float(e.retry_after or 1))
+except SolvaPayError:
+    raise
+```
+
+Use `except SolvaPayError` as the catch-all. Prefer specific subclasses over checking `.status_code`.
+
+## Idempotency keys
+
+All mutating ops accept an optional `idempotency_key` to make retries safe:
+
+```python
+from solvapay.idempotency import from_payload
+
+key = from_payload("checkout", customer_ref, product_ref)
+session = sv.create_checkout_session(
+    customer_ref=customer_ref,
+    product_ref="prd_xyz",
+    idempotency_key=key,
+)
+```
+
+`from_payload(*parts)` hashes its args to a 32-hex-char deterministic key. Pass the same key on retry — SolvaPay deduplicates server-side.
+
 ## Examples
 
 | Path | What it shows |
 |---|---|
 | [`examples/fastmcp-paywall/`](examples/fastmcp-paywall/) | FastMCP server with two paywalled tools. Demo for `@paywall.require` + MCP. |
 | [`examples/langchain-paywall/`](examples/langchain-paywall/) | LangChain agent with `monetize_tool`. Shows paywall response in agent trace. |
+| [`examples/marketplace/`](examples/marketplace/) | Streamlit demo — paywalled AI-agent marketplace. Real sandbox, real Gemini LLM, two demo customers (one subscribed, one free tier). Shows `paywall_state.gate()` in action. |
 
 ## TS ↔ Python parity
 
@@ -196,6 +259,22 @@ session = sv.create_checkout_session(
 | `cancel_purchase` | `POST /v1/sdk/purchases/{ref}/cancel` | Cancel a subscription |
 | `reactivate_purchase` | `POST /v1/sdk/purchases/{ref}/reactivate` | Reactivate cancelled purchase |
 
+**Admin (new in v0.6):**
+
+| Python | Verb + path | Description |
+|---|---|---|
+| `list_products` | `GET /v1/sdk/products` | List all products |
+| `get_product` | `GET /v1/sdk/products/{ref}` | Fetch product |
+| `create_product` | `POST /v1/sdk/products` | Create product |
+| `delete_product` | `DELETE /v1/sdk/products/{ref}` | Delete product |
+| `clone_product` | `POST /v1/sdk/products/{ref}/clone` | Clone product |
+| `list_plans` | `GET /v1/sdk/products/{ref}/plans` | List plans |
+| `create_plan` | `POST /v1/sdk/products/{ref}/plans` | Create plan |
+| `update_plan` | `PUT /v1/sdk/products/{ref}/plans/{ref}` | Update plan |
+| `delete_plan` | `DELETE /v1/sdk/products/{ref}/plans/{ref}` | Delete plan |
+| `get_merchant` | `GET /v1/sdk/merchant` | Merchant info |
+| `get_platform_config` | `GET /v1/sdk/platform-config` | Platform config |
+
 All methods available on both `SolvaPay` (sync) and `AsyncSolvaPay` (async).
 
 ## Webhook handler (FastAPI)
@@ -258,6 +337,9 @@ async def handle_webhook(request: Request) -> dict:
 - v0.4 — async client (`AsyncSolvaPay`), lifecycle ops, typed webhook events ✅
 - v0.5 — paywall state classifier, LangChain `monetize_tool` decorator ✅
 - v0.6 — admin endpoints (products, plans, merchant, platform config), PyPI publish ✅
+- v0.7.0 — real-API wire-format fixes, `paywall_state.gate()`, marketplace demo ✅
+- v0.7.1 — structured error hierarchy, idempotency keys, `py.typed`, structured logging ✅
+- v0.7.2 — async resource leak fix (`require_async`), example dep fixes ✅
 
 ## Contributing
 

solvapay_python-0.7.2.dist-info/RECORD

@@ -0,0 +1,19 @@
+solvapay/__init__.py,sha256=1GgHO6-iQViSW0vZGKghMV1NMHDtWEy-gM-SRr06Ch0,1774
+solvapay/_async_client.py,sha256=4RtP3K5NlkqOSfqDNS26Hzit4aUbh68HSvCDUVrmYoY,13509
+solvapay/_config.py,sha256=yPU_GM77pXwPfIzuncuLRNv4322q5bB9qaawN3izEB8,606
+solvapay/_http.py,sha256=ug396rug0EsKCgs_rgi8iYMkfm0hKOlQQ2sEjyUz22o,6709
+solvapay/client.py,sha256=D-tvloBnTCweh_AwFYSEYgQaqXaSMT3j_eQ1UjlUYnM,13321
+solvapay/events.py,sha256=m2VLrbLLJpiPfuTryNSL2hB6pHfq4YO0a9kjhT4hniY,1844
+solvapay/exceptions.py,sha256=QKWARp-l-7-WnwJC03qbmktgjGI9q0sNmckzE0NPf6U,2384
+solvapay/fastapi.py,sha256=vouWqbc_Yurdg8dIZ7zhO4-J_QxpYnyNgwyLHgDEoHs,2125
+solvapay/idempotency.py,sha256=LzsLw6TeaeLJbMVqZSEQ-038f6oIUomCmQDBqzlKMGE,514
+solvapay/langchain.py,sha256=VOrze5-7COE4--kn8JqbyrmwhWwv3XwN3Ol3YMpffgc,2353
+solvapay/models.py,sha256=SsmkSLH5xp-Hgf2GjhDcrqGt5FoWKtXJkDZUQE7wwWI,6810
+solvapay/paywall.py,sha256=OQCX8XT73IWDaFyRHDz_19ZYOkXY891O_zDbpI73D7U,5771
+solvapay/paywall_state.py,sha256=pfP_-5B6LRcWrvItwgDwh-9f-DSowYaFDKXxGJvYPrg,7048
+solvapay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+solvapay/webhooks.py,sha256=6EuoISjJzrKEUIoNpt__l2FnJvQR4T7XnT7fzOFHl5U,2738
+solvapay_python-0.7.2.dist-info/METADATA,sha256=2Fbd-hzM9PsqJEEBiWXbYuIh6OWrq5CUlZieDfMueCg,12767
+solvapay_python-0.7.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+solvapay_python-0.7.2.dist-info/licenses/LICENSE,sha256=wJURmEXLdSdApQdHG-RCwBoZVka1Oux8zNrLxGC30S8,1068
+solvapay_python-0.7.2.dist-info/RECORD,,

solvapay_python-0.7.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-solvapay/__init__.py,sha256=m9gn3b3cyL4ZExnevrrkSWfIScB_ELHSDXb-G7PA5CQ,1365
-solvapay/_async_client.py,sha256=Y9zGFPMNwqA-vAdr8hnTVjvRRpr05piaX2el5bkQCSc,12644
-solvapay/_config.py,sha256=yPU_GM77pXwPfIzuncuLRNv4322q5bB9qaawN3izEB8,606
-solvapay/_http.py,sha256=LsOdoVycSWFW8GimGq4dZpfKFGz1ZvHgWAPhmDpuVsM,3026
-solvapay/client.py,sha256=3x-SjM3sLRi86A1_tIGX2snmo7IMaJXd93qaU_h86CA,12548
-solvapay/events.py,sha256=m2VLrbLLJpiPfuTryNSL2hB6pHfq4YO0a9kjhT4hniY,1844
-solvapay/exceptions.py,sha256=PLWXtAo8UsBqxScqq2AnWANNRFlzryq2vljt_SnB1jw,511
-solvapay/fastapi.py,sha256=vouWqbc_Yurdg8dIZ7zhO4-J_QxpYnyNgwyLHgDEoHs,2125
-solvapay/langchain.py,sha256=VOrze5-7COE4--kn8JqbyrmwhWwv3XwN3Ol3YMpffgc,2353
-solvapay/models.py,sha256=SsmkSLH5xp-Hgf2GjhDcrqGt5FoWKtXJkDZUQE7wwWI,6810
-solvapay/paywall.py,sha256=jlMZ9LG6GNL010R8fV30cKQmSub3VRPW079Fm1wbsO8,5522
-solvapay/paywall_state.py,sha256=pfP_-5B6LRcWrvItwgDwh-9f-DSowYaFDKXxGJvYPrg,7048
-solvapay/webhooks.py,sha256=6EuoISjJzrKEUIoNpt__l2FnJvQR4T7XnT7fzOFHl5U,2738
-solvapay_python-0.7.0.dist-info/METADATA,sha256=Zwth8LdaDTeW9LMwb8XPhLPAGHwM_o0pC-KK6Fcaeew,9084
-solvapay_python-0.7.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-solvapay_python-0.7.0.dist-info/licenses/LICENSE,sha256=wJURmEXLdSdApQdHG-RCwBoZVka1Oux8zNrLxGC30S8,1068
-solvapay_python-0.7.0.dist-info/RECORD,,