solvapay-python 0.6.0__py3-none-any.whl

solvapay/client.py

@@ -0,0 +1,352 @@
+"""Public SolvaPay client. Synchronous; mirrors @solvapay/core surface."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from solvapay._config import resolve_api_key, resolve_base_url
+from solvapay._http import HttpClient
+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 SolvaPay:
+    """Synchronous 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:
+        >>> from solvapay import SolvaPay
+        >>> sv = SolvaPay()  # reads SOLVAPAY_SECRET_KEY
+        >>> session = sv.create_checkout_session(
+        ...     customer_ref="cus_123", product_ref="prd_0QKI8NHF"
+        ... )
+        >>> print(session.checkout_url)
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = HttpClient(
+            api_key=resolve_api_key(api_key),
+            base_url=resolve_base_url(base_url),
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> SolvaPay:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def create_checkout_session(
+        self,
+        *,
+        customer_ref: str,
+        product_ref: str,
+        plan_ref: str | None = None,
+        return_url: str | None = None,
+    ) -> CheckoutSession:
+        """Create a hosted checkout session.
+
+        Maps to POST /v1/sdk/checkout-sessions.
+
+        Args:
+            customer_ref: Backend customer reference.
+            product_ref: SolvaPay product reference (e.g., "prd_0QKI8NHF").
+            plan_ref: Optional plan reference. Omit to show plan selector.
+            return_url: Optional URL to redirect after checkout.
+
+        Returns:
+            CheckoutSession with .session_id and .checkout_url.
+        """
+        req = CheckoutSessionRequest(
+            customer_ref=customer_ref,
+            product_ref=product_ref,
+            plan_ref=plan_ref,
+            return_url=return_url,
+        )
+        data = self._http.request(
+            "POST",
+            "/v1/sdk/checkout-sessions",
+            json=req.model_dump(by_alias=True, exclude_none=True),
+        )
+        return CheckoutSession.model_validate(data)
+
+    def ensure_customer(
+        self,
+        customer_ref: str,
+        external_ref: str | None = None,
+        *,
+        email: str | None = None,
+        name: str | None = None,
+    ) -> str:
+        """Idempotently create or look up a customer.
+
+        Tries GET /v1/sdk/customers?externalRef=... first. On 404, creates via
+        POST /v1/sdk/customers. Auto-generates a placeholder email if not provided.
+
+        Returns the SolvaPay backend customer reference string.
+        """
+        lookup_ref = external_ref or customer_ref
+        try:
+            existing = self._http.request(
+                "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 = self._http.request(
+            "POST",
+            "/v1/sdk/customers",
+            json=req.model_dump(by_alias=True, exclude_none=True),
+        )
+        return str(created["customerRef"])
+
+    def get_customer(
+        self,
+        customer_ref: str | None = None,
+        *,
+        external_ref: str | None = None,
+        email: str | None = None,
+    ) -> Customer:
+        """Retrieve a customer by ref, external_ref, or email."""
+        if customer_ref:
+            data = self._http.request("GET", f"/v1/sdk/customers/{customer_ref}")
+        elif external_ref:
+            data = self._http.request(
+                "GET", "/v1/sdk/customers", params={"externalRef": external_ref}
+            )
+        elif email:
+            data = self._http.request("GET", "/v1/sdk/customers", params={"email": email})
+        else:
+            raise ValueError("Must provide customer_ref, external_ref, or email")
+        return Customer.model_validate(data)
+
+    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:
+        """Check whether a customer is within their purchase/usage limits.
+
+        Maps to POST /v1/sdk/limits.
+        """
+        req = CheckLimitsRequest(
+            customer_ref=customer_ref,
+            product_ref=product_ref,
+            plan_ref=plan_ref,
+            meter_name=meter_name,
+            usage_type=usage_type,
+        )
+        data = self._http.request(
+            "POST",
+            "/v1/sdk/limits",
+            json=req.model_dump(by_alias=True, exclude_none=True),
+        )
+        return LimitResponse.model_validate(data)
+
+    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 self._http.request(
+            "POST",
+            "/v1/sdk/usages",
+            json=req.model_dump(by_alias=True, exclude_none=True),
+            idempotency_key=idempotency_key,
+        )
+
+    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 = self._http.request(
+            "PATCH",
+            f"/v1/sdk/customers/{customer_ref}",
+            json=req.model_dump(by_alias=True, exclude_none=True),
+        )
+        return Customer.model_validate(data)
+
+    def get_customer_balance(self, customer_ref: str) -> BalanceResponse:
+        """Get credit balance for a customer. Maps to GET /v1/sdk/customers/{ref}/balance."""
+        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]:
+        """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),
+        )
+
+    def reactivate_purchase(self, purchase_ref: str) -> 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")
+
+    # --- Admin: Products ---
+
+    def list_products(self) -> list[Product]:
+        """List all products. Maps to GET /v1/sdk/products."""
+        data = self._http.request("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]
+
+    def get_product(self, product_ref: str) -> Product:
+        """Get a product by ref. Maps to GET /v1/sdk/products/{ref}."""
+        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:
+        """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),
+        )
+        return Product.model_validate(data)
+
+    def delete_product(self, product_ref: str) -> dict[str, Any]:
+        """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:
+        """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),
+        )
+        return Product.model_validate(data)
+
+    # --- Admin: Plans ---
+
+    def list_plans(self, product_ref: str) -> list[Plan]:
+        """List plans for a product. Maps to GET /v1/sdk/products/{ref}/plans."""
+        data = self._http.request("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]
+
+    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 = self._http.request(
+            "POST",
+            f"/v1/sdk/products/{product_ref}/plans",
+            json=req.model_dump(by_alias=True, exclude_none=True),
+        )
+        return Plan.model_validate(data)
+
+    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 = self._http.request(
+            "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)
+
+    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 self._http.request("DELETE", f"/v1/sdk/products/{product_ref}/plans/{plan_ref}")
+
+    # --- Admin: Merchant + Platform ---
+
+    def get_merchant(self) -> Merchant:
+        """Get merchant account details. Maps to GET /v1/sdk/merchant."""
+        data = self._http.request("GET", "/v1/sdk/merchant")
+        return Merchant.model_validate(data)
+
+    def get_platform_config(self) -> PlatformConfig:
+        """Get platform-level configuration. Maps to GET /v1/sdk/platform-config."""
+        data = self._http.request("GET", "/v1/sdk/platform-config")
+        return PlatformConfig.model_validate(data)

solvapay/events.py

@@ -0,0 +1,90 @@
+"""Typed pydantic models for SolvaPay webhook events.
+
+Mirrors the 13 event types in @solvapay/server src/types/webhook.ts.
+Use as a discriminated union with `verify_webhook(..., parse_as=WebhookEvent)`.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _Event(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+    id: str
+    created: int
+    api_version: str
+    livemode: bool
+    data: dict[str, Any]
+
+
+class PaymentSucceeded(_Event):
+    type: Literal["payment.succeeded"]
+
+
+class PaymentFailed(_Event):
+    type: Literal["payment.failed"]
+
+
+class PaymentRefunded(_Event):
+    type: Literal["payment.refunded"]
+
+
+class PaymentRefundFailed(_Event):
+    type: Literal["payment.refund_failed"]
+
+
+class PurchaseCreated(_Event):
+    type: Literal["purchase.created"]
+
+
+class PurchaseUpdated(_Event):
+    type: Literal["purchase.updated"]
+
+
+class PurchaseCancelled(_Event):
+    type: Literal["purchase.cancelled"]
+
+
+class PurchaseExpired(_Event):
+    type: Literal["purchase.expired"]
+
+
+class PurchaseSuspended(_Event):
+    type: Literal["purchase.suspended"]
+
+
+class CustomerCreated(_Event):
+    type: Literal["customer.created"]
+
+
+class CustomerUpdated(_Event):
+    type: Literal["customer.updated"]
+
+
+class CustomerDeleted(_Event):
+    type: Literal["customer.deleted"]
+
+
+class CheckoutSessionCreated(_Event):
+    type: Literal["checkout_session.created"]
+
+
+WebhookEvent = Annotated[
+    PaymentSucceeded
+    | PaymentFailed
+    | PaymentRefunded
+    | PaymentRefundFailed
+    | PurchaseCreated
+    | PurchaseUpdated
+    | PurchaseCancelled
+    | PurchaseExpired
+    | PurchaseSuspended
+    | CustomerCreated
+    | CustomerUpdated
+    | CustomerDeleted
+    | CheckoutSessionCreated,
+    Field(discriminator="type"),
+]

solvapay/exceptions.py

@@ -0,0 +1,16 @@
+"""Exception hierarchy for SolvaPay SDK."""
+
+from __future__ import annotations
+
+
+class SolvaPayError(Exception):
+    """Base exception for all SolvaPay SDK errors."""
+
+
+class SolvaPayAPIError(SolvaPayError):
+    """Raised when the SolvaPay API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, body: str, message: str | None = None) -> None:
+        self.status_code = status_code
+        self.body = body
+        super().__init__(message or f"SolvaPay API error {status_code}: {body}")

solvapay/fastapi.py

@@ -0,0 +1,65 @@
+"""Optional FastAPI integration. Requires `pip install solvapay[fastapi]`."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+try:
+    from fastapi import APIRouter, HTTPException, Request
+except ImportError as exc:
+    raise ImportError("FastAPI is not installed. Run: pip install solvapay[fastapi]") from exc
+
+from solvapay.exceptions import SolvaPayError
+from solvapay.webhooks import verify_webhook
+
+
+def webhook_router(
+    *,
+    secret: str,
+    on_event: Callable[[dict[str, Any]], Awaitable[None]],
+    path: str = "/webhooks/solvapay",
+) -> APIRouter:
+    """Build an APIRouter that verifies and dispatches SolvaPay webhooks.
+
+    Handles signature verification automatically. Mount it on your FastAPI app
+    and implement your event logic in `on_event`.
+
+    Args:
+        secret: Webhook signing secret (starts with `whsec_`). Get from
+                SOLVAPAY_WEBHOOK_SECRET env or your SolvaPay dashboard.
+        on_event: Async callback that receives the verified event dict.
+        path: URL path for the webhook endpoint. Default "/webhooks/solvapay".
+
+    Returns:
+        An APIRouter ready for `app.include_router(...)`.
+
+    Example:
+        import os
+        from solvapay.fastapi import webhook_router
+
+        async def handle_event(event: dict) -> None:
+            if event["type"] == "purchase.created":
+                ...  # grant access
+
+        app.include_router(
+            webhook_router(
+                secret=os.environ["SOLVAPAY_WEBHOOK_SECRET"],
+                on_event=handle_event,
+            )
+        )
+    """
+    router = APIRouter()
+
+    @router.post(path)
+    async def _solvapay_webhook(request: Request) -> dict[str, bool]:
+        body = (await request.body()).decode()
+        sig = request.headers.get("sv-signature", "")
+        try:
+            event = verify_webhook(body=body, signature=sig, secret=secret)
+        except SolvaPayError as exc:
+            raise HTTPException(status_code=401, detail=str(exc)) from exc
+        await on_event(event)
+        return {"received": True}
+
+    return router

solvapay/langchain.py

@@ -0,0 +1,67 @@
+"""Optional LangChain integration. Requires `pip install solvapay[langchain]`."""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import Any
+
+try:
+    from langchain_core.tools import BaseTool
+except ImportError as exc:
+    raise ImportError("LangChain is not installed. Run: pip install solvapay[langchain]") from exc
+
+from solvapay.client import SolvaPay
+from solvapay.paywall_state import decide
+
+
+def monetize_tool(
+    tool: BaseTool,
+    *,
+    product: str,
+    customer_ref_arg: str = "customer_ref",
+    client: SolvaPay | None = None,
+) -> BaseTool:
+    """Wrap a LangChain tool with SolvaPay paywall gating.
+
+    Checks check_limits before each invocation. On gate hit, returns a
+    structured dict with the checkout URL — does NOT raise — so LangChain
+    agents can surface the recovery action to the user.
+
+    Args:
+        tool: Any LangChain BaseTool (Tool, StructuredTool, etc.).
+        product: SolvaPay product reference (e.g., "prd_0QKI8NHF").
+        customer_ref_arg: Name of the kwarg carrying the customer ref.
+        client: Pre-configured SolvaPay instance. Constructs one per call if omitted.
+
+    Returns:
+        The same tool with its `.func` replaced by a gated wrapper.
+
+    Example:
+        from langchain_core.tools import Tool
+        from solvapay.langchain import monetize_tool
+
+        raw = Tool.from_function(name="search", func=do_search, description="Search the web.")
+        paid = monetize_tool(raw, product="prd_search")
+    """
+    sv = client or SolvaPay()
+    original_func = tool.func  # type: ignore[attr-defined]
+
+    @wraps(original_func)
+    def gated(**kwargs: Any) -> Any:
+        customer_ref = kwargs.get(customer_ref_arg)
+        if not isinstance(customer_ref, str):
+            return {"error": f"Missing required argument: {customer_ref_arg}"}
+        limits = sv.check_limits(customer_ref=customer_ref, product_ref=product)
+        if not limits.within_limits:
+            d = decide(limits)
+            return {
+                "paywall_required": True,
+                "state": d.state.value,
+                "message": d.message,
+                "checkout_url": d.checkout_url,
+                "recovery_tool": d.recovery_tool,
+            }
+        return original_func(**kwargs)
+
+    tool.func = gated  # type: ignore[attr-defined]
+    return tool