solvapay-python 0.6.0__py3-none-any.whl

solvapay/models.py

@@ -0,0 +1,182 @@
+"""Pydantic models for SolvaPay API request/response payloads.
+
+Python fields are snake_case. API wire format is camelCase.
+Field(alias="camelCase") handles the mapping; populate_by_name=True
+lets callers use either form during construction.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _Base(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+
+class CheckoutSession(_Base):
+    """Response from POST /v1/sdk/checkout-sessions."""
+
+    session_id: str = Field(alias="sessionId")
+    checkout_url: str = Field(alias="checkoutUrl")
+
+
+class Purchase(_Base):
+    reference: str
+    product_name: str | None = Field(default=None, alias="productName")
+    product_ref: str | None = Field(default=None, alias="productRef")
+    plan_ref: str | None = Field(default=None, alias="planRef")
+    status: str
+    start_date: str = Field(alias="startDate")
+    end_date: str | None = Field(default=None, alias="endDate")
+    amount: int | None = None
+    currency: str | None = None
+    cancelled_at: str | None = Field(default=None, alias="cancelledAt")
+
+
+class Customer(_Base):
+    customer_ref: str = Field(alias="customerRef")
+    email: str | None = None
+    name: str | None = None
+    external_ref: str | None = Field(default=None, alias="externalRef")
+    purchases: list[Purchase] | None = None
+
+
+class LimitResponse(_Base):
+    within_limits: bool = Field(alias="withinLimits")
+    remaining: float = 0
+    plan: str | None = None
+    checkout_url: str | None = Field(default=None, alias="checkoutUrl")
+    meter_name: str | None = Field(default=None, alias="meterName")
+    credit_balance: float | None = Field(default=None, alias="creditBalance")
+    credits_per_unit: float | None = Field(default=None, alias="creditsPerUnit")
+    currency: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Request models — snake_case Python fields, camelCase wire via alias
+# ---------------------------------------------------------------------------
+
+
+class CheckoutSessionRequest(_Base):
+    customer_ref: str = Field(serialization_alias="customerRef")
+    product_ref: str = Field(serialization_alias="productRef")
+    plan_ref: str | None = Field(default=None, serialization_alias="planRef")
+    return_url: str | None = Field(default=None, serialization_alias="returnUrl")
+
+
+class CreateCustomerRequest(_Base):
+    email: str
+    external_ref: str = Field(serialization_alias="externalRef")
+    name: str | None = None
+
+
+class CheckLimitsRequest(_Base):
+    customer_ref: str = Field(serialization_alias="customerRef")
+    product_ref: str = Field(serialization_alias="productRef")
+    plan_ref: str | None = Field(default=None, serialization_alias="planRef")
+    meter_name: str | None = Field(default=None, serialization_alias="meterName")
+    usage_type: str | None = Field(default=None, serialization_alias="usageType")
+
+
+class TrackUsageRequest(_Base):
+    customer_ref: str = Field(serialization_alias="customerRef")
+    product_ref: str = Field(serialization_alias="productRef")
+    meter_name: str = Field(serialization_alias="meterName")
+    units: float
+
+
+class UpdateCustomerRequest(_Base):
+    email: str | None = None
+    name: str | None = None
+    external_ref: str | None = Field(default=None, serialization_alias="externalRef")
+
+
+class BalanceResponse(_Base):
+    customer_ref: str = Field(alias="customerRef")
+    balance: float
+    currency: str
+    plan: str | None = None
+
+
+class CancelPurchaseRequest(_Base):
+    reason: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Admin response models
+# ---------------------------------------------------------------------------
+
+
+class Product(_Base):
+    """A SolvaPay product."""
+
+    reference: str
+    name: str
+    type: str
+    status: str | None = None
+    default_currency: str | None = Field(default=None, alias="defaultCurrency")
+    created_at: str | None = Field(default=None, alias="createdAt")
+
+
+class Plan(_Base):
+    """A SolvaPay plan attached to a product."""
+
+    reference: str
+    name: str
+    type: str
+    price: float | None = None
+    currency: str | None = None
+    interval: str | None = None
+    status: str | None = None
+    product_ref: str | None = Field(default=None, alias="productRef")
+
+
+class Merchant(_Base):
+    """Merchant account details."""
+
+    merchant_ref: str | None = Field(default=None, alias="merchantRef")
+    name: str | None = None
+    email: str | None = None
+
+
+class PlatformConfig(_Base):
+    """Platform-level configuration."""
+
+    currency: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Admin request models
+# ---------------------------------------------------------------------------
+
+
+class CreateProductRequest(_Base):
+    name: str
+    type: str
+    default_currency: str = Field(serialization_alias="defaultCurrency")
+
+
+class CreatePlanRequest(_Base):
+    name: str
+    type: str
+    price: float | None = None
+    currency: str | None = None
+    interval: str | None = None
+
+
+class UpdatePlanRequest(_Base):
+    name: str | None = None
+    type: str | None = None
+    price: float | None = None
+    currency: str | None = None
+    interval: str | None = None
+
+
+class CloneProductRequest(_Base):
+    new_name: str = Field(serialization_alias="newName")

solvapay/paywall.py

@@ -0,0 +1,130 @@
+"""Paywall decorator — wrap any function to auto-check limits before running.
+
+Mirrors the @solvapay/server `payable` philosophy in a single decorator.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+from solvapay.exceptions import SolvaPayError
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class PaywallRequired(SolvaPayError):
+    """Raised by @paywall.require when a customer has exceeded their limits."""
+
+    def __init__(self, checkout_url: str | None, message: str = "Paywall: limit exceeded") -> None:
+        self.checkout_url = checkout_url
+        super().__init__(message)
+
+
+def require(
+    *,
+    product: str,
+    plan: str | None = None,
+    customer_ref_arg: str = "customer_ref",
+    client: object | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Decorate a function with a SolvaPay paywall check.
+
+    Before each call, checks `check_limits` for the customer. If
+    `within_limits` is False, raises `PaywallRequired` with the checkout URL
+    so the caller can redirect the user to upgrade.
+
+    The decorated function must accept a `customer_ref` keyword argument
+    (rename via `customer_ref_arg` if needed).
+
+    Args:
+        product: SolvaPay product reference (e.g., "prd_0QKI8NHF").
+        plan: Optional plan reference to check against.
+        customer_ref_arg: Name of the kwarg that carries the customer ref.
+                          Defaults to "customer_ref".
+        client: Pre-configured SolvaPay instance. If omitted, a new client
+                is created per call (reads SOLVAPAY_SECRET_KEY from env).
+
+    Example:
+        sv = SolvaPay()
+
+        @paywall.require(product="prd_0QKI8NHF", client=sv)
+        def run_expensive_query(*, customer_ref: str, query: str) -> dict:
+            ...
+    """
+    from solvapay.client import SolvaPay
+
+    def decorator(fn: Callable[P, R]) -> Callable[P, R]:
+        @wraps(fn)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            customer_ref = kwargs.get(customer_ref_arg)
+            if not isinstance(customer_ref, str):
+                raise SolvaPayError(
+                    f"@paywall.require expected str kwarg '{customer_ref_arg}', "
+                    f"got {type(customer_ref).__name__}"
+                )
+            sv: SolvaPay = client if isinstance(client, SolvaPay) else SolvaPay()
+            limits = sv.check_limits(
+                customer_ref=customer_ref,
+                product_ref=product,
+                plan_ref=plan,
+            )
+            if not limits.within_limits:
+                raise PaywallRequired(checkout_url=limits.checkout_url)
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def require_async(
+    *,
+    product: str,
+    plan: str | None = None,
+    customer_ref_arg: str = "customer_ref",
+    client: object | None = None,
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+    """Async equivalent of @paywall.require. Decorated function must be async.
+
+    Args:
+        product: SolvaPay product reference (e.g., "prd_0QKI8NHF").
+        plan: Optional plan reference to check against.
+        customer_ref_arg: Name of the kwarg that carries the customer ref.
+        client: Pre-configured AsyncSolvaPay instance. If omitted, a new
+                client is created per call (reads SOLVAPAY_SECRET_KEY from env).
+
+    Example:
+        sv = AsyncSolvaPay()
+
+        @paywall.require_async(product="prd_0QKI8NHF", client=sv)
+        async def run_expensive_query(*, customer_ref: str, query: str) -> dict:
+            ...
+    """
+
+    def decorator(fn: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+        @wraps(fn)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            from solvapay._async_client import AsyncSolvaPay
+
+            customer_ref = kwargs.get(customer_ref_arg)
+            if not isinstance(customer_ref, str):
+                raise SolvaPayError(
+                    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:
+                raise PaywallRequired(checkout_url=limits.checkout_url)
+            return await fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

solvapay/paywall_state.py

@@ -0,0 +1,121 @@
+"""Pure-function paywall state machine. Mirrors TS classifyPaywallState.
+
+Input: a LimitResponse (output of check_limits).
+Output: a structured state + display copy + recovery action.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import NamedTuple
+
+from solvapay.models import LimitResponse
+
+
+class PaywallState(str, Enum):
+    OK = "ok"
+    ACTIVATION_REQUIRED = "activation_required"
+    TOPUP_REQUIRED = "topup_required"
+    UPGRADE_REQUIRED = "upgrade_required"
+    REACTIVATION_REQUIRED = "reactivation_required"  # reserved; not yet returned by classify_state
+
+
+class GateDecision(NamedTuple):
+    state: PaywallState
+    message: str
+    recovery_tool: str | None  # "upgrade" | "topup" | "activate_plan" | "manage_account" | None
+    checkout_url: str | None
+
+
+_RECOVERY_TOOL: dict[PaywallState, str | None] = {
+    PaywallState.OK: None,
+    PaywallState.ACTIVATION_REQUIRED: "activate_plan",
+    PaywallState.TOPUP_REQUIRED: "topup",
+    PaywallState.UPGRADE_REQUIRED: "upgrade",
+    PaywallState.REACTIVATION_REQUIRED: "manage_account",
+}
+
+
+def classify_state(limits: LimitResponse) -> PaywallState:
+    """Return the recovery state implied by a check_limits response.
+
+    Precedence mirrors TS classifyPaywallState (paywall-state.ts):
+    1. within_limits → OK
+    2. plan is None → activation_required (no active plan; proxy for activationRequired flag)
+    3. credit_balance present and exhausted → topup_required (usage-based, out of credits)
+    4. everything else → upgrade_required (recurring cap or unresolvable state)
+    """
+    if limits.within_limits:
+        return PaywallState.OK
+    if limits.plan is None:
+        return PaywallState.ACTIVATION_REQUIRED
+    # Usage-based: credit_balance field signals usage-based billing in our LimitResponse.
+    # Mirrors TS: creditBalance === 0 on a usage-based plan → topup path.
+    if limits.credit_balance is not None and limits.credit_balance <= 0:
+        return PaywallState.TOPUP_REQUIRED
+    return PaywallState.UPGRADE_REQUIRED
+
+
+def build_gate_message(state: PaywallState, limits: LimitResponse) -> str:
+    """Terminal-friendly gate copy. Mirrors TS buildGateMessage.
+
+    Inlines checkoutUrl when present so terminal-only MCP/CLI hosts can
+    open a browser directly, matching TS behaviour exactly.
+    """
+    if state == PaywallState.OK:
+        return ""
+    url = limits.checkout_url or None
+    open_clause = f", or open {url} in a browser" if url else ""
+    if state == PaywallState.ACTIVATION_REQUIRED:
+        return (
+            f"Your plan needs activation before you can use this tool. "
+            f"Call the `activate_plan` tool to activate it{open_clause}."
+        )
+    if state == PaywallState.TOPUP_REQUIRED:
+        return f"You're out of credits. Call the `topup` tool to add more{open_clause}."
+    if state == PaywallState.UPGRADE_REQUIRED:
+        return (
+            f"You don't have an active plan for this tool. "
+            f"Call the `upgrade` tool to pick a plan{open_clause}."
+        )
+    # reactivation_required — two alternatives; URL not appended (mirrors TS)
+    return (
+        "Your previous plan is no longer active. "
+        "Call the `manage_account` tool to reactivate it, "
+        "or the `upgrade` tool to pick a new plan."
+    )
+
+
+def build_nudge_message(state: PaywallState, limits: LimitResponse) -> str:
+    """Low-balance / approaching-cap nudge copy. Mirrors TS buildNudgeMessage.
+
+    Only topup_required and upgrade_required produce actionable nudges on
+    successful calls; other states return an empty string.
+    """
+    if state == PaywallState.OK:
+        return ""
+    url = limits.checkout_url or None
+    visit_clause = f", or visit {url}" if url else ""
+    if state == PaywallState.TOPUP_REQUIRED:
+        return (
+            f"Heads up — running low on credits. Call the `topup` tool to add more{visit_clause}."
+        )
+    if state == PaywallState.UPGRADE_REQUIRED:
+        return (
+            f"Heads up — approaching your plan's limit this period. "
+            f"Call the `upgrade` tool for more headroom{visit_clause}."
+        )
+    if state == PaywallState.ACTIVATION_REQUIRED:
+        return f"Heads up — this plan still needs activation. Call the `activate_plan` tool{visit_clause}."
+    return f"Heads up — your plan is no longer active. Call the `manage_account` tool to reactivate it{visit_clause}."
+
+
+def decide(limits: LimitResponse) -> GateDecision:
+    """Full decision: state + gate message + recovery tool + checkout URL."""
+    state = classify_state(limits)
+    return GateDecision(
+        state=state,
+        message=build_gate_message(state, limits),
+        recovery_tool=_RECOVERY_TOOL[state],
+        checkout_url=limits.checkout_url,
+    )

solvapay/webhooks.py

@@ -0,0 +1,86 @@
+"""Webhook signature verification.
+
+Mirrors @solvapay/server verifyWebhook. HMAC-SHA256 over "{timestamp}.{body}"
+with header format "t={ts},v1={hmac}". 5-minute tolerance. Constant-time compare.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, TypeVar
+
+from solvapay.exceptions import SolvaPayError
+
+T = TypeVar("T")
+
+
+def _parse_signature_header(signature: str) -> tuple[int, str]:
+    parts: dict[str, str] = {}
+    for chunk in signature.split(","):
+        if "=" in chunk:
+            k, _, v = chunk.partition("=")
+            parts[k.strip()] = v.strip()
+    if "t" not in parts or "v1" not in parts:
+        raise SolvaPayError("Webhook signature header malformed (missing t= or v1=)")
+    try:
+        ts = int(parts["t"])
+    except ValueError as exc:
+        raise SolvaPayError("Webhook signature timestamp not an integer") from exc
+    return ts, parts["v1"]
+
+
+def verify_webhook(
+    *,
+    body: str,
+    signature: str,
+    secret: str,
+    tolerance: int = 300,
+    parse_as: type[T] | None = None,
+) -> dict[str, Any] | T:
+    """Verify a SolvaPay webhook signature and return the parsed event.
+
+    Args:
+        body: Raw request body string. Must be the exact bytes signed by
+              SolvaPay — do not reformat JSON or strip whitespace.
+        signature: Value of the sv-signature request header.
+        secret: Webhook signing secret (starts with whsec_).
+        tolerance: Max seconds since signature timestamp. Default 300 (5 min).
+        parse_as: Optional pydantic type to validate the event into. Pass
+                  `WebhookEvent` for a typed discriminated union. Omit for
+                  backwards-compatible dict return.
+
+    Returns:
+        Parsed webhook event as dict (default) or instance of `parse_as`.
+
+    Raises:
+        SolvaPayError: Header malformed, timestamp too old, signature mismatch,
+                       or body not valid JSON.
+    """
+    timestamp, received = _parse_signature_header(signature)
+
+    age = abs(int(time.time()) - timestamp)
+    if age > tolerance:
+        raise SolvaPayError(f"Webhook signature timestamp too old (age={age}s)")
+
+    expected = hmac.new(
+        secret.encode(),
+        f"{timestamp}.{body}".encode(),
+        hashlib.sha256,
+    ).hexdigest()
+
+    if not hmac.compare_digest(expected, received):
+        raise SolvaPayError("Webhook signature mismatch")
+
+    try:
+        event: dict[str, Any] = json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise SolvaPayError("Webhook body is not valid JSON") from exc
+
+    if parse_as is None:
+        return event
+    from pydantic import TypeAdapter
+
+    return TypeAdapter(parse_as).validate_python(event)