solvapay 0.1.0.dev4__py3-none-any.whl

solvapay/solvapay.py

@@ -0,0 +1,173 @@
+"""``create_solvapay()``: the SDK's entry point.
+
+```python
+from solvapay import create_solvapay
+
+solvapay = create_solvapay()  # reads SOLVAPAY_SECRET_KEY
+
+@solvapay.payable(product="prd_…")
+async def summarise(text: str, *, customer_ref: str) -> str:
+    ...
+```
+
+Configuration comes from arguments, else the environment, the same
+variables the TypeScript SDK reads:
+
+- ``SOLVAPAY_SECRET_KEY`` (required): the merchant's secret key.
+- ``SOLVAPAY_API_BASE_URL``: defaults to ``https://api.solvapay.com``.
+- ``SOLVAPAY_PRODUCT_REF``: the product a paid call is for, when not given.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import os
+from collections.abc import Awaitable, Callable
+from typing import Any, ParamSpec, TypeVar
+
+from ._http import DEFAULT_API_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_SECONDS
+from .client import AsyncApiClient
+from .errors import SolvaPayError
+from .paywall.decide import (
+    DEFAULT_LIMITS_CACHE_TTL_SECONDS,
+    FreeLimit,
+    Paywall,
+    PaywallDecision,
+    PaywallError,
+)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class SolvaPay:
+    """The API client and the paywall for one merchant key."""
+
+    def __init__(self, *, api: AsyncApiClient, product_ref: str | None = None, **paywall: Any):
+        self.api = api
+        self.product_ref = product_ref
+        self.paywall = Paywall(api, **paywall)
+
+    def require_product(self, product: str | None) -> str:
+        """The product for a paid call: the one given, else ``SOLVAPAY_PRODUCT_REF``."""
+        resolved = product or self.product_ref
+        if not resolved:
+            raise SolvaPayError(
+                "No product: pass product=… or set SOLVAPAY_PRODUCT_REF.",
+                code="missing_product",
+            )
+        return resolved
+
+    async def gate(
+        self,
+        *,
+        customer_ref: str,
+        product: str | None = None,
+        meter: str | None = None,
+        free_limit: FreeLimit | None = None,
+        tool_name: str | None = None,
+    ) -> PaywallDecision:
+        """``allow`` or ``gate`` for one paid call, for a handler you run yourself.
+
+        After an ``allow``, record the outcome with ``paywall.run_allow`` (or
+        call ``paywall.track_usage`` yourself).
+        """
+        return await self.paywall.decide(
+            customer_ref=customer_ref,
+            product=self.require_product(product),
+            meter=meter,
+            free_limit=free_limit,
+            tool_name=tool_name,
+        )
+
+    def payable(
+        self,
+        *,
+        product: str | None = None,
+        meter: str | None = None,
+        free_limit: FreeLimit | None = None,
+        customer_ref_arg: str = "customer_ref",
+    ) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+        """Makes an async function paid. Raises ``PaywallError`` (with ``.gate``) when gated.
+
+        The customer is read from the keyword argument named ``customer_ref_arg``.
+        """
+        resolved_product = self.require_product(product)
+
+        def wrap(handler: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+            if not inspect.iscoroutinefunction(handler):
+                raise SolvaPayError("payable() wraps async functions", code="invalid_argument")
+
+            @functools.wraps(handler)
+            async def paid(*args: P.args, **kwargs: P.kwargs) -> R:
+                customer_ref = kwargs.get(customer_ref_arg)
+                if not isinstance(customer_ref, str) or not customer_ref:
+                    raise SolvaPayError(
+                        f"{handler.__name__}() was called without {customer_ref_arg}=…",
+                        code="identity_required",
+                        status=401,
+                    )
+                decision = await self.paywall.decide(
+                    customer_ref=customer_ref,
+                    product=resolved_product,
+                    meter=meter,
+                    free_limit=free_limit,
+                    tool_name=handler.__name__,
+                )
+                if decision.gate is not None:
+                    raise PaywallError(decision.gate)
+                return await self.paywall.run_allow(
+                    decision,
+                    lambda: handler(*args, **kwargs),
+                    product=resolved_product,
+                    meter=meter,
+                    free_limit=free_limit,
+                    tool_name=handler.__name__,
+                )
+
+            return paid
+
+        return wrap
+
+    async def aclose(self) -> None:
+        await self.api.aclose()
+
+    async def __aenter__(self) -> SolvaPay:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+
+def create_solvapay(
+    *,
+    api_key: str | None = None,
+    api_base_url: str | None = None,
+    product_ref: str | None = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    limits_cache_ttl: float = DEFAULT_LIMITS_CACHE_TTL_SECONDS,
+    api: AsyncApiClient | None = None,
+) -> SolvaPay:
+    """A ``SolvaPay`` from arguments, else the environment. Fails without a secret key."""
+    if api is None:
+        key = api_key or os.environ.get("SOLVAPAY_SECRET_KEY")
+        if not key:
+            raise SolvaPayError(
+                "A SolvaPay secret key is required: pass api_key=… or set SOLVAPAY_SECRET_KEY.",
+                code="missing_secret",
+            )
+        api = AsyncApiClient(
+            api_key=key,
+            api_base_url=api_base_url
+            or os.environ.get("SOLVAPAY_API_BASE_URL")
+            or DEFAULT_API_BASE_URL,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+    return SolvaPay(
+        api=api,
+        product_ref=product_ref or os.environ.get("SOLVAPAY_PRODUCT_REF") or None,
+        limits_cache_ttl=limits_cache_ttl,
+    )

solvapay/webhooks.py

@@ -0,0 +1,93 @@
+"""Webhook signature verification, matching ``@solvapay/server``'s ``verifyWebhook``.
+
+SolvaPay signs a delivery as HMAC-SHA256 over ``"{t}.{raw body}"``, keyed by
+the whole signing secret (``whsec_…``, UTF-8), and sends it in the
+``SV-Signature`` header as ``t={unix seconds},v1={lowercase hex}``.
+
+```python
+from solvapay import verify_webhook
+
+event = verify_webhook(
+    body=request.body,                       # the raw bytes or text, as received
+    signature=request.headers["sv-signature"],
+    secret=os.environ["SOLVAPAY_WEBHOOK_SECRET"],
+)
+```
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from datetime import datetime
+from typing import Any, Final
+
+from .errors import SolvaPayError
+
+WEBHOOK_TOLERANCE_SECONDS: Final = 300
+
+WEBHOOK_ERROR_CODES: Final = {
+    "missing": "webhook_signature_missing",
+    "malformed": "webhook_signature_malformed",
+    "timestamp": "webhook_timestamp_out_of_tolerance",
+    "invalid": "webhook_signature_invalid",
+    "payload": "webhook_payload_invalid",
+}
+
+
+def _reject_constant(name: str) -> Any:
+    # JSON has no NaN or Infinity; json.loads accepts them, JSON.parse does not.
+    raise ValueError(f"{name} is not valid JSON")
+
+
+def verify_webhook(
+    *,
+    body: str | bytes,
+    signature: str | None,
+    secret: str,
+    now: datetime | None = None,
+) -> Any:
+    """Verifies a delivery and returns the parsed event.
+
+    Raises ``SolvaPayError`` whose ``code`` is one of ``WEBHOOK_ERROR_CODES``.
+    ``now`` is the time to check the signature's timestamp against
+    (default: the current time); a timestamp more than 300 seconds away,
+    either way, is rejected.
+    """
+    raw = body if isinstance(body, bytes) else body.encode("utf-8")
+    if not signature:
+        raise SolvaPayError("Missing webhook signature", code=WEBHOOK_ERROR_CODES["missing"])
+
+    parts = [part.strip() for part in signature.split(",")]
+    t_part = next((p for p in parts if p.startswith("t=")), None)
+    v1_part = next((p for p in parts if p.startswith("v1=")), None)
+    if t_part is None or v1_part is None:
+        raise SolvaPayError("Malformed webhook signature", code=WEBHOOK_ERROR_CODES["malformed"])
+    raw_timestamp, received = t_part[2:], v1_part[3:]
+    if not re.fullmatch(r"\d+", raw_timestamp, flags=re.ASCII) or not received:
+        raise SolvaPayError("Malformed webhook signature", code=WEBHOOK_ERROR_CODES["malformed"])
+
+    now_seconds = int(now.timestamp()) if now is not None else int(time.time())
+    if abs(now_seconds - int(raw_timestamp)) > WEBHOOK_TOLERANCE_SECONDS:
+        raise SolvaPayError(
+            "Webhook signature timestamp is more than "
+            f"{WEBHOOK_TOLERANCE_SECONDS} seconds from now",
+            code=WEBHOOK_ERROR_CODES["timestamp"],
+        )
+
+    expected = hmac.new(
+        secret.encode("utf-8"), raw_timestamp.encode("ascii") + b"." + raw, hashlib.sha256
+    ).hexdigest()
+    # compare_digest takes ASCII text only; anything else cannot be a hex digest.
+    if not received.isascii() or not hmac.compare_digest(expected, received):
+        raise SolvaPayError("Invalid webhook signature", code=WEBHOOK_ERROR_CODES["invalid"])
+
+    try:
+        return json.loads(raw, parse_constant=_reject_constant)
+    except ValueError as error:
+        raise SolvaPayError(
+            "Invalid webhook payload: body is not valid JSON", code=WEBHOOK_ERROR_CODES["payload"]
+        ) from error

solvapay-0.1.0.dev4.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: solvapay
+Version: 0.1.0.dev4
+Summary: SolvaPay for Python: paywalls, usage billing, webhooks and paid MCP tools.
+Project-URL: Homepage, https://solvapay.com
+Project-URL: Documentation, https://docs.solvapay.com
+Project-URL: Source, https://github.com/solvapay/solvapay-sdk/tree/main/python
+Author: SolvaPay
+License-Expression: MIT
+Keywords: agents,billing,mcp,payments,paywall,solvapay
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: agents
+Requires-Dist: pyjwt[crypto]<3,>=2.9; extra == 'agents'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
+Requires-Dist: starlette>=0.40; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# solvapay
+
+SolvaPay for Python: paywalls, usage billing, webhooks and paid MCP tools.
+
+```bash
+pip install solvapay            # API client, paywall, webhooks
+pip install 'solvapay[mcp]'     # paid tools for the official MCP Python SDK
+```
+
+Python 3.10+. Typed (`py.typed`), async-first, with blocking twins for the API client.
+
+## Configure
+
+```bash
+export SOLVAPAY_SECRET_KEY=sk_sandbox_...   # required
+export SOLVAPAY_PRODUCT_REF=prd_...         # the product paid calls bill against
+export SOLVAPAY_API_BASE_URL=...            # optional; defaults to https://api.solvapay.com
+```
+
+Run `npx solvapay init` to sign in and write these to `.env`.
+
+## Make a function paid
+
+```python
+from solvapay import PaywallError, create_solvapay
+
+solvapay = create_solvapay()
+
+
+@solvapay.payable()
+async def summarise(text: str, *, customer_ref: str) -> str:
+    return text[:100]
+
+
+try:
+    summary = await summarise("...", customer_ref="user_123")
+except PaywallError as error:
+    print(error.gate["message"])  # what the customer should see, with a checkout link
+```
+
+`customer_ref` is your own user id: SolvaPay creates the customer on first use.
+Each call is checked against the customer's plan, and billed when it succeeds.
+
+## Paid MCP tools
+
+```python
+from solvapay import create_solvapay
+from solvapay.mcp import ResponseContext, create_solvapay_mcp_server
+
+mcp = create_solvapay_mcp_server(
+    solvapay=create_solvapay(),
+    public_base_url="https://research.example.com",
+)
+
+
+async def quote(symbol: str, ctx: ResponseContext):
+    return ctx.respond({"symbol": symbol, "price": 101.5})
+
+
+mcp.register_payable("quote", handler=quote, description="Latest price for a symbol.")
+
+app = mcp.http_app()  # serve with uvicorn; the MCP endpoint is /mcp
+```
+
+Customers sign in with SolvaPay over OAuth, and every bearer token is verified
+with SolvaPay. A call over the customer's limit returns the paywall: a message
+naming the next step, with a checkout link. See
+[`examples/python-stock-research-mcp`](../examples/python-stock-research-mcp).
+
+The server also comes with SolvaPay's built-in tools, as the TypeScript server
+does: `account` shows the customer's plan, balance and usage with a checkout,
+top-up or account link (`view`: `checkout`, `account` or `topup`), and
+`activate_plan` activates a plan by `planRef`. The `/upgrade`,
+`/manage_account`, `/topup` and `/activate_plan` prompts and the
+`docs://solvapay/overview.md` resource come with them. Pass `views=[...]` to
+choose the views, or `views=[]` to leave `account` out.
+
+### The checkout widget
+
+On hosts that support MCP Apps (ChatGPT, Claude), `account` also opens
+SolvaPay's checkout and account widget in the chat, the same one the TypeScript
+SDK serves. It ships in this package (`solvapay/mcp/mcp-app.html`) and is
+served at `ui://<name>/mcp-app.html` (`resource_uri=` to change it). Text-only
+hosts get the same text as before; `mode: "text"` asks for text on any host.
+
+The widget pays, tops up, cancels and reactivates renewals through six tools
+only it calls: `create_payment_intent`, `process_payment`,
+`create_hosted_session`, `set_renewal`, `attach_business_details` and
+`get_history`. They are marked for the app (`_meta.ui.visibility: ["app"]`), so
+MCP Apps hosts keep them from the model. For a host that lists them anyway,
+`hide_tools_by_audience=["ui"]` leaves them out of `tools/list`; ChatGPT still
+gets them, since its widget can only call listed tools.
+
+Its Content Security Policy allows Stripe and the SolvaPay API. Add domains with
+`csp={"connectDomains": [...], "resourceDomains": [...], "frameDomains": [...]}`.
+
+### Paid by agents
+
+`solvapay.agents.mcp.create_agent_mcp_route` serves an MCP server that SolvaPay
+agents pay for per call: each paid tool call is authorized with SolvaPay before
+it runs and completed at the cost the upstream reports. Install
+`solvapay[agents,mcp]`.
+
+## Verify webhooks
+
+```python
+from solvapay import SolvaPayError, verify_webhook
+
+try:
+    event = verify_webhook(
+        body=raw_body,  # bytes or str, exactly as received
+        signature=request.headers["sv-signature"],
+        secret=os.environ["SOLVAPAY_WEBHOOK_SECRET"],
+    )
+except SolvaPayError as error:
+    ...  # error.code: webhook_signature_invalid, webhook_timestamp_out_of_tolerance, ...
+```
+
+## The API
+
+Every SolvaPay API operation, generated from the API spec:
+
+```python
+from solvapay import AsyncApiClient
+
+async with AsyncApiClient(api_key="sk_sandbox_...") as api:
+    customer = await api.get_customer(reference="cus_123")
+    balance = await api.get_customer_balance(reference="cus_123")
+```
+
+`ApiClient` is the blocking twin. Errors are `SolvaPayError` with a stable `code`
+and the HTTP `status`; branch on those, not on the message.
+
+## Same behaviour as the TypeScript SDK
+
+The paywall, its messages, the `account` and `activate_plan` narration, what
+the widget's tools answer and webhook verification are checked against the
+TypeScript SDK on every change by a shared conformance suite
+([`conformance/`](../conformance)). The API client is generated from the same
+spec as the TypeScript types ([`openapi/`](../openapi)).
+
+## Versions
+
+`solvapay` has its own version line, starting at 0.1.0. Its numbers don't
+follow the TypeScript packages: Python 0.3.0 and `@solvapay/server` 2.12.0 can
+behave the same. What the two share is the conformance suite (the version this
+package passes is pinned in [`conformance.lock`](conformance.lock)) and the API
+spec.
+
+Until 1.0.0, a minor release (0.x → 0.y) may change the API. Previews of the
+next release are published from the `dev` branch as `<next>.devN`:
+
+```bash
+pip install --pre solvapay
+```

solvapay-0.1.0.dev4.dist-info/RECORD

@@ -0,0 +1,39 @@
+solvapay/__init__.py,sha256=p39j5ZvKms5SRKhchZHusWaRaK2n-9SKHP1WUaCb-tc,755
+solvapay/_currencies.py,sha256=GdDf4FG2s5_OEmd2Gv8hOmfbk_epImkBT4juaxkNAGc,3417
+solvapay/_http.py,sha256=WK6OT90Mro6wpsKZlh8t75T9wQf4qgCqB2VaVaGJr0w,8404
+solvapay/_js.py,sha256=u-C1Y5YqLDWR2iSnC0YyifYCUdqB6AjTRsKuirVH4Q0,3489
+solvapay/_tax_ids.py,sha256=D0TVr3Gk4Qy6nNG-wAS7X-QFxZ6Cl20oJU6-uEJlXk8,11234
+solvapay/business_details.py,sha256=qmRhTc_xwvT53ZXz-J6RNBI_s7Uj7mnXEkqvJtLwqNg,4343
+solvapay/client.py,sha256=be8XfsHLRDo1YY4KLgvcbDVibTquZ0lCY4OgE1BhTKg,2753
+solvapay/errors.py,sha256=QovGghgtkGs4s1ipFlpoD0lKZwnwKKkbXt0iF9h6L5A,821
+solvapay/money.py,sha256=D9EIJfGUYj0w45wmkEeZadeBI8vQ2nY9lsSi2YQ4mmA,2157
+solvapay/pricing.py,sha256=2EWL2HZe5ZUYvlaOO2onLwyuswYJUiFMLdsvY0sdkOw,10375
+solvapay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+solvapay/solvapay.py,sha256=OW5XNGBRfJOPy2nDADp-c7UBOx09UaHxoKUqjutsxbo,5867
+solvapay/webhooks.py,sha256=uF1RCiNo0vlNHYTbm_6jEjWZd5J5echgu2Xgg8EGP3Y,3445
+solvapay/_generated/__init__.py,sha256=ocuVKIf-7sVBn7gvvPlDy1_hkPNm8UKRSzbqOjE5y-Y,92
+solvapay/_generated/models.py,sha256=7ISI0RixUpotXYO-rzUKdzHSANBuB3Noow8c3w82Y8s,108970
+solvapay/_generated/operations.py,sha256=xZ5chS9Dr8GHfvdo-FtrWxxNmOBycnhULnrTflEkxhI,57992
+solvapay/agents/__init__.py,sha256=7YB_yxDQOpoOoh6cgBzGjaVJzdeOGpveyCojnvCyHYU,1425
+solvapay/agents/calls.py,sha256=mVfaTGilCCiyijR7AzcH5qaZf-VMFM_pNALGaQBPj3Q,11473
+solvapay/agents/identity.py,sha256=TzSSuw2mynOPRk1fsvW4aDax5Cnj8TqUTv2UUCs1v_M,11090
+solvapay/agents/mcp.py,sha256=2Duibu9OuKH3gmNbpcNd_JxpGEmll1EVZOYJTJDDLg8,23079
+solvapay/agents/oauth.py,sha256=_dZObCLSMKDQ0b99lgewFnqbWVZZ-1oi49XKhvz4ywY,4280
+solvapay/mcp/__init__.py,sha256=HP7jierJQsUgk5mZO_CpLF89n6BkeVEkNEpP9piajUc,2301
+solvapay/mcp/app.py,sha256=mukkCleekLGhnB0VfBqwtRFr0-RU-IiwOI4JvwnJMow,9241
+solvapay/mcp/auth.py,sha256=izhI8JEiZFFAb259AsiOZQk1PSMkMSwLxJnmbzTynEE,23479
+solvapay/mcp/bootstrap.py,sha256=T_NkpcMejFy1oC5des_McghFS4Khyp05_vDQ0AVOtHU,18196
+solvapay/mcp/intent.py,sha256=ccumggLaMOj4tAUZVraua5dlp56EU8qc3zYNqThF8-Q,19196
+solvapay/mcp/mcp-app.html,sha256=4IbDS93ib2B7c-Ehym2god2ZvAIvq-U217cvPzxfj9o,848783
+solvapay/mcp/narrate.py,sha256=kDrsqSqPxrybPGO9Pr0OBNt81rNbVYwhGWxyGS87mDs,36358
+solvapay/mcp/response.py,sha256=kiSFWAa0IXlvd-EaUaCGBkE56fh9Di8smzLR5EK-1qA,7497
+solvapay/mcp/server.py,sha256=LupoijalrC6Cy0JHeijeXWhUAUKyIWNdawMmP6XkKEc,12901
+solvapay/mcp/tools.py,sha256=FBRtIcFXQvCB-wZLCxgn1ad9cxB0_4tacFsDcq0MDeM,9847
+solvapay/mcp/transport.py,sha256=4XYyhqqboOfbHVVUPMoi_U1dSeMOJUKKHKr7TS4kDXM,21477
+solvapay/paywall/__init__.py,sha256=aIxL6iS3DLkwOcewOu0XMIJM8DCzjQastIbmme2oH6g,591
+solvapay/paywall/decide.py,sha256=mcEG563R621B63e4D9OnV4TQpwr79DN9JERWvE6elsE,16697
+solvapay/paywall/gate.py,sha256=oFNFpOvhYg5m1gRgLsttqfdSV7YvEtOzvj3cSPzQk7E,6001
+solvapay/paywall/state.py,sha256=xqwziDE9EisPpAcC9to0EjG4flE1ijXaC62KohdZGwA,14135
+solvapay-0.1.0.dev4.dist-info/METADATA,sha256=kcm5FkyqbD3TQcmPPrRegQxC6syi0V2MtswVbk7U440,6738
+solvapay-0.1.0.dev4.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+solvapay-0.1.0.dev4.dist-info/RECORD,,

solvapay-0.1.0.dev4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any