solvapay-python 0.6.0__py3-none-any.whl

solvapay/__init__.py

@@ -0,0 +1,57 @@
+"""SolvaPay community Python SDK."""
+
+from __future__ import annotations
+
+from solvapay import paywall
+from solvapay._async_client import AsyncSolvaPay
+from solvapay.client import SolvaPay
+from solvapay.events import (
+    CheckoutSessionCreated,
+    CustomerCreated,
+    CustomerDeleted,
+    CustomerUpdated,
+    PaymentFailed,
+    PaymentRefunded,
+    PaymentRefundFailed,
+    PaymentSucceeded,
+    PurchaseCancelled,
+    PurchaseCreated,
+    PurchaseExpired,
+    PurchaseSuspended,
+    PurchaseUpdated,
+    WebhookEvent,
+)
+from solvapay.exceptions import SolvaPayAPIError, SolvaPayError
+from solvapay.models import BalanceResponse, Merchant, Plan, PlatformConfig, Product
+from solvapay.paywall import PaywallRequired
+from solvapay.webhooks import verify_webhook
+
+__all__ = [
+    "AsyncSolvaPay",
+    "BalanceResponse",
+    "CheckoutSessionCreated",
+    "CustomerCreated",
+    "CustomerDeleted",
+    "CustomerUpdated",
+    "Merchant",
+    "PaymentFailed",
+    "PaymentRefundFailed",
+    "PaymentRefunded",
+    "PaymentSucceeded",
+    "PaywallRequired",
+    "Plan",
+    "PlatformConfig",
+    "Product",
+    "PurchaseCancelled",
+    "PurchaseCreated",
+    "PurchaseExpired",
+    "PurchaseSuspended",
+    "PurchaseUpdated",
+    "SolvaPay",
+    "SolvaPayAPIError",
+    "SolvaPayError",
+    "WebhookEvent",
+    "paywall",
+    "verify_webhook",
+]
+__version__ = "0.6.0"

solvapay/_async_client.py

@@ -0,0 +1,355 @@
+"""Async SolvaPay client. Mirrors SolvaPay sync surface 1:1.
+
+Constructor signature identical to `SolvaPay`. All ops are `async def`.
+Use `async with AsyncSolvaPay() as sv: ...` for proper teardown.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from solvapay._config import resolve_api_key, resolve_base_url
+from solvapay._http import AsyncHttpClient, _RequestSpec
+from solvapay.exceptions import SolvaPayAPIError
+from solvapay.models import (
+    BalanceResponse,
+    CancelPurchaseRequest,
+    CheckLimitsRequest,
+    CheckoutSession,
+    CheckoutSessionRequest,
+    CloneProductRequest,
+    CreateCustomerRequest,
+    CreatePlanRequest,
+    CreateProductRequest,
+    Customer,
+    LimitResponse,
+    Merchant,
+    Plan,
+    PlatformConfig,
+    Product,
+    TrackUsageRequest,
+    UpdateCustomerRequest,
+    UpdatePlanRequest,
+)
+
+
+class AsyncSolvaPay:
+    """Async SolvaPay API client.
+
+    Args:
+        api_key: SolvaPay secret key. Falls back to SOLVAPAY_SECRET_KEY env var.
+        base_url: API base URL. Falls back to SOLVAPAY_API_BASE_URL env var,
+                  then to https://api.solvapay.com.
+        timeout: HTTP timeout in seconds. Default 30.
+
+    Example:
+        >>> async with AsyncSolvaPay() as sv:
+        ...     session = await sv.create_checkout_session(
+        ...         customer_ref="cus_123", product_ref="prd_0QKI8NHF"
+        ...     )
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = AsyncHttpClient(
+            api_key=resolve_api_key(api_key),
+            base_url=resolve_base_url(base_url),
+            timeout=timeout,
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSolvaPay:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def create_checkout_session(
+        self,
+        *,
+        customer_ref: str,
+        product_ref: str,
+        plan_ref: str | None = None,
+        return_url: str | None = None,
+    ) -> CheckoutSession:
+        req = CheckoutSessionRequest(
+            customer_ref=customer_ref,
+            product_ref=product_ref,
+            plan_ref=plan_ref,
+            return_url=return_url,
+        )
+        data = await self._http.send(
+            _RequestSpec(
+                "POST",
+                "/v1/sdk/checkout-sessions",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+            )
+        )
+        return CheckoutSession.model_validate(data)
+
+    async def ensure_customer(
+        self,
+        customer_ref: str,
+        external_ref: str | None = None,
+        *,
+        email: str | None = None,
+        name: str | None = None,
+    ) -> str:
+        lookup_ref = external_ref or customer_ref
+        try:
+            existing = await self._http.send(
+                _RequestSpec("GET", "/v1/sdk/customers", params={"externalRef": lookup_ref})
+            )
+            if existing.get("customerRef"):
+                return str(existing["customerRef"])
+        except SolvaPayAPIError as exc:
+            if exc.status_code != 404:
+                raise
+
+        req = CreateCustomerRequest(
+            email=email or f"{customer_ref}-{int(time.time())}@auto-created.local",
+            external_ref=lookup_ref,
+            name=name,
+        )
+        created = await self._http.send(
+            _RequestSpec(
+                "POST", "/v1/sdk/customers", json=req.model_dump(by_alias=True, exclude_none=True)
+            )
+        )
+        return str(created["customerRef"])
+
+    async def get_customer(
+        self,
+        customer_ref: str | None = None,
+        *,
+        external_ref: str | None = None,
+        email: str | None = None,
+    ) -> Customer:
+        if customer_ref:
+            data = await self._http.send(_RequestSpec("GET", f"/v1/sdk/customers/{customer_ref}"))
+        elif external_ref:
+            data = await self._http.send(
+                _RequestSpec("GET", "/v1/sdk/customers", params={"externalRef": external_ref})
+            )
+        elif email:
+            data = await self._http.send(
+                _RequestSpec("GET", "/v1/sdk/customers", params={"email": email})
+            )
+        else:
+            raise ValueError("Must provide customer_ref, external_ref, or email")
+        return Customer.model_validate(data)
+
+    async def check_limits(
+        self,
+        *,
+        customer_ref: str,
+        product_ref: str,
+        plan_ref: str | None = None,
+        meter_name: str | None = None,
+        usage_type: str | None = None,
+    ) -> LimitResponse:
+        req = CheckLimitsRequest(
+            customer_ref=customer_ref,
+            product_ref=product_ref,
+            plan_ref=plan_ref,
+            meter_name=meter_name,
+            usage_type=usage_type,
+        )
+        data = await self._http.send(
+            _RequestSpec(
+                "POST", "/v1/sdk/limits", json=req.model_dump(by_alias=True, exclude_none=True)
+            )
+        )
+        return LimitResponse.model_validate(data)
+
+    async def track_usage(
+        self,
+        *,
+        customer_ref: str,
+        product_ref: str,
+        meter_name: str,
+        units: float,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Record usage against a meter. Maps to POST /v1/sdk/usages."""
+        req = TrackUsageRequest(
+            customer_ref=customer_ref,
+            product_ref=product_ref,
+            meter_name=meter_name,
+            units=units,
+        )
+        return await self._http.send(
+            _RequestSpec(
+                "POST",
+                "/v1/sdk/usages",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    async def update_customer(
+        self,
+        customer_ref: str,
+        *,
+        email: str | None = None,
+        name: str | None = None,
+        external_ref: str | None = None,
+    ) -> Customer:
+        """Update customer fields. Maps to PATCH /v1/sdk/customers/{ref}."""
+        req = UpdateCustomerRequest(email=email, name=name, external_ref=external_ref)
+        data = await self._http.send(
+            _RequestSpec(
+                "PATCH",
+                f"/v1/sdk/customers/{customer_ref}",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+            )
+        )
+        return Customer.model_validate(data)
+
+    async def get_customer_balance(self, customer_ref: str) -> BalanceResponse:
+        """Get credit balance for a customer. Maps to GET /v1/sdk/customers/{ref}/balance."""
+        data = await self._http.send(
+            _RequestSpec("GET", f"/v1/sdk/customers/{customer_ref}/balance")
+        )
+        return BalanceResponse.model_validate(data)
+
+    async def cancel_purchase(
+        self, purchase_ref: str, *, reason: str | None = None
+    ) -> dict[str, Any]:
+        """Cancel a purchase. Maps to POST /v1/sdk/purchases/{ref}/cancel."""
+        req = CancelPurchaseRequest(reason=reason)
+        return await self._http.send(
+            _RequestSpec(
+                "POST",
+                f"/v1/sdk/purchases/{purchase_ref}/cancel",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+            )
+        )
+
+    async def reactivate_purchase(self, purchase_ref: str) -> 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")
+        )
+
+    # --- Admin: Products ---
+
+    async def list_products(self) -> list[Product]:
+        """List all products. Maps to GET /v1/sdk/products."""
+        data = await self._http.send(_RequestSpec("GET", "/v1/sdk/products"))
+        items: list[Any] = data if isinstance(data, list) else data.get("products", [])
+        return [Product.model_validate(p) for p in items]
+
+    async def get_product(self, product_ref: str) -> Product:
+        """Get a product by ref. Maps to GET /v1/sdk/products/{ref}."""
+        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:
+        """Create a product. Maps to POST /v1/sdk/products."""
+        req = CreateProductRequest(name=name, type=type, default_currency=default_currency)
+        data = await self._http.send(
+            _RequestSpec(
+                "POST",
+                "/v1/sdk/products",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+            )
+        )
+        return Product.model_validate(data)
+
+    async def delete_product(self, product_ref: str) -> dict[str, Any]:
+        """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:
+        """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(
+            _RequestSpec(
+                "POST",
+                f"/v1/sdk/products/{product_ref}/clone",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+            )
+        )
+        return Product.model_validate(data)
+
+    # --- Admin: Plans ---
+
+    async def list_plans(self, product_ref: str) -> list[Plan]:
+        """List plans for a product. Maps to GET /v1/sdk/products/{ref}/plans."""
+        data = await self._http.send(_RequestSpec("GET", f"/v1/sdk/products/{product_ref}/plans"))
+        items: list[Any] = data if isinstance(data, list) else data.get("plans", [])
+        return [Plan.model_validate(p) for p in items]
+
+    async def create_plan(
+        self,
+        product_ref: str,
+        *,
+        name: str,
+        type: str,
+        price: float | None = None,
+        currency: str | None = None,
+        interval: str | None = None,
+    ) -> Plan:
+        """Create a plan for a product. Maps to POST /v1/sdk/products/{ref}/plans."""
+        req = CreatePlanRequest(
+            name=name, type=type, price=price, currency=currency, interval=interval
+        )
+        data = await self._http.send(
+            _RequestSpec(
+                "POST",
+                f"/v1/sdk/products/{product_ref}/plans",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+            )
+        )
+        return Plan.model_validate(data)
+
+    async def update_plan(
+        self,
+        product_ref: str,
+        plan_ref: str,
+        *,
+        name: str | None = None,
+        type: str | None = None,
+        price: float | None = None,
+        currency: str | None = None,
+        interval: str | None = None,
+    ) -> Plan:
+        """Update a plan. Maps to PUT /v1/sdk/products/{ref}/plans/{ref}."""
+        req = UpdatePlanRequest(
+            name=name, type=type, price=price, currency=currency, interval=interval
+        )
+        data = await self._http.send(
+            _RequestSpec(
+                "PUT",
+                f"/v1/sdk/products/{product_ref}/plans/{plan_ref}",
+                json=req.model_dump(by_alias=True, exclude_none=True),
+            )
+        )
+        return Plan.model_validate(data)
+
+    async def delete_plan(self, product_ref: str, plan_ref: str) -> dict[str, Any]:
+        """Delete a plan. Maps to DELETE /v1/sdk/products/{ref}/plans/{ref}."""
+        return await self._http.send(
+            _RequestSpec("DELETE", f"/v1/sdk/products/{product_ref}/plans/{plan_ref}")
+        )
+
+    # --- Admin: Merchant + Platform ---
+
+    async def get_merchant(self) -> Merchant:
+        """Get merchant account details. Maps to GET /v1/sdk/merchant."""
+        data = await self._http.send(_RequestSpec("GET", "/v1/sdk/merchant"))
+        return Merchant.model_validate(data)
+
+    async def get_platform_config(self) -> PlatformConfig:
+        """Get platform-level configuration. Maps to GET /v1/sdk/platform-config."""
+        data = await self._http.send(_RequestSpec("GET", "/v1/sdk/platform-config"))
+        return PlatformConfig.model_validate(data)

solvapay/_config.py

@@ -0,0 +1,22 @@
+"""Environment configuration loading."""
+
+from __future__ import annotations
+
+import os
+
+DEFAULT_BASE_URL = "https://api.solvapay.com"
+
+
+def resolve_api_key(explicit: str | None) -> str:
+    key = explicit or os.environ.get("SOLVAPAY_SECRET_KEY")
+    if not key:
+        from solvapay.exceptions import SolvaPayError
+
+        raise SolvaPayError(
+            "SolvaPay API key not provided. Pass api_key=... or set SOLVAPAY_SECRET_KEY env var."
+        )
+    return key
+
+
+def resolve_base_url(explicit: str | None) -> str:
+    return explicit or os.environ.get("SOLVAPAY_API_BASE_URL") or DEFAULT_BASE_URL

solvapay/_http.py

@@ -0,0 +1,107 @@
+"""Internal HTTP transport. Not part of public API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from solvapay.exceptions import SolvaPayAPIError
+
+
+@dataclass(frozen=True)
+class _RequestSpec:
+    method: str
+    path: str
+    json: dict[str, Any] | None = None
+    params: dict[str, Any] | None = None
+    idempotency_key: str | None = None
+
+    def headers(self) -> dict[str, str]:
+        return {"Idempotency-Key": self.idempotency_key} if self.idempotency_key else {}
+
+
+def _handle(response: httpx.Response) -> dict[str, Any]:
+    if not response.is_success:
+        raise SolvaPayAPIError(response.status_code, response.text)
+    if response.status_code == 204 or not response.content:
+        return {}
+    return response.json()  # type: ignore[no-any-return]
+
+
+class HttpClient:
+    def __init__(self, *, api_key: str, base_url: str, timeout: float = 30.0) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "solvapay-python/0.4.0",
+            },
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        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(),
+            )
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        return self.send(_RequestSpec(method, path, json, params, idempotency_key))
+
+
+class AsyncHttpClient:
+    def __init__(self, *, api_key: str, base_url: str, timeout: float = 30.0) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "solvapay-python/0.4.0",
+            },
+            timeout=timeout,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncHttpClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        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(),
+            )
+        )