solvapay 0.1.0.dev4__py3-none-any.whl

solvapay/agents/oauth.py

@@ -0,0 +1,105 @@
+"""OAuth helpers for a server agents call: its resource URL and the RFC 9728 document.
+
+Ported from ``@solvapay/agents``' ``oauth.ts``, which reads URLs as browsers do (the
+WHATWG URL standard); the canonical form below follows it for the URLs a server
+can have.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote, urljoin, urlsplit
+
+AGENT_SCOPE = "usage"
+METADATA_PREFIX = "/.well-known/oauth-protected-resource"
+
+# What the URL standard leaves unescaped in a path and in a query (everything printable
+# but space, ``"``, ``#``, ``<``, ``>``, and ``?``, `````, ``{``, ``}`` in a path or ``'`` in a
+# query); ``%`` stays, so an escape is never escaped twice.
+_PATH_SAFE = "!$%&'()*+,-./:;=@[\\]^_|~"
+_QUERY_SAFE = "!$%&()*+,-./:;=?@[\\]^_`{|}~"
+
+
+def _remove_dot_segments(path: str) -> str:
+    """RFC 3986 section 5.2.4: ``/a/../b/./c`` is ``/b/c``."""
+    out: list[str] = []
+    segments = path.split("/")
+    for i, segment in enumerate(segments):
+        last = i == len(segments) - 1
+        if segment == ".":
+            if last:
+                out.append("")
+        elif segment == "..":
+            if len(out) > 1:
+                out.pop()
+            if last:
+                out.append("")
+        else:
+            out.append(segment)
+    return "/".join(out)
+
+
+def canonical_resource(resource: str) -> str:
+    """The form SolvaPay compares resources in: scheme and host lowercased, default
+    port dropped, no trailing slash. A fragment or credentials make it unusable."""
+    parts = urlsplit(resource)
+    if parts.fragment or parts.username or parts.password:
+        raise ValueError(f"{resource} cannot be an OAuth resource: no fragment or credentials")
+    if not parts.scheme or not parts.hostname:
+        raise ValueError(f"{resource} is not an absolute URL")
+    scheme = parts.scheme.lower()
+    host = parts.hostname.lower()
+    if ":" in host:
+        host = f"[{host}]"  # an IPv6 address keeps its brackets
+    default = {"http": 80, "https": 443}.get(scheme)
+    port = f":{parts.port}" if parts.port and parts.port != default else ""
+    path = quote(_remove_dot_segments(parts.path or "/"), safe=_PATH_SAFE).rstrip("/")
+    query = f"?{quote(parts.query, safe=_QUERY_SAFE)}" if parts.query else ""
+    return f"{scheme}://{host}{port}{path}{query}"
+
+
+def protected_resource_metadata_path(resource: str, metadata_path: str | None = None) -> str:
+    """Where the metadata is served: ``metadata_path``, else the RFC 9728 path-suffixed
+    form hosts try first, ``/.well-known/oauth-protected-resource/mcp``."""
+    if metadata_path:
+        return metadata_path
+    return f"{METADATA_PREFIX}{urlsplit(canonical_resource(resource)).path}"
+
+
+def protected_resource_metadata_url(resource: str, metadata_path: str | None = None) -> str:
+    """The absolute URL a challenge points hosts at, on the resource's origin."""
+    path = protected_resource_metadata_path(resource, metadata_path)
+    return urljoin(canonical_resource(resource), path)
+
+
+def protected_resource_metadata(
+    *,
+    resource: str,
+    authorization_server: str,
+    server_name: str | None = None,
+    documentation: str | None = None,
+) -> dict[str, Any]:
+    """The RFC 9728 document naming SolvaPay's agent issuer as the authorization server."""
+    out: dict[str, Any] = {
+        "resource": canonical_resource(resource),
+        "authorization_servers": [authorization_server],
+        "scopes_supported": [AGENT_SCOPE],
+        "bearer_methods_supported": ["header"],
+    }
+    if server_name:
+        out["resource_name"] = server_name
+    if documentation:
+        out["resource_documentation"] = documentation
+    return out
+
+
+def challenge_header(*, resource: str, description: str, metadata_url: str | None = None) -> str:
+    """The ``WWW-Authenticate`` value hosts look for, with ``error``, ``error_description``,
+    the metadata URL (default: the path-suffixed form on the resource's origin) and the
+    one scope."""
+    metadata = metadata_url or protected_resource_metadata_url(resource)
+    quoted = description.replace("\\", "\\\\").replace('"', '\\"')
+    return (
+        f'Bearer error="invalid_token", error_description="{quoted}", '
+        f'resource_metadata="{metadata}", scope="{AGENT_SCOPE}"'
+    )

solvapay/business_details.py

@@ -0,0 +1,124 @@
+"""Business purchase details, checked and normalised as ``@solvapay/core``'s
+``validateBusinessDetails`` does (``packages/core/src/business-details.ts``).
+
+The tax-ID tables come from the TypeScript source (``_tax_ids.py``, generated
+by ``scripts/tax_ids.mjs``), so both SDKs accept and reject the same input.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._tax_ids import (
+    BUYER_COUNTRIES,
+    COUNTRY_TO_TAX_ID_TYPE,
+    EU_MEMBER_COUNTRIES,
+    EU_VAT_FORMAT_BY_COUNTRY,
+    TAX_ID_FORMAT_BY_TYPE,
+    TAX_ID_TYPES,
+)
+from .errors import SolvaPayError
+
+Json = dict[str, Any]
+
+CUSTOMER_NAME_MAX = 100
+
+__all__ = [
+    "TAX_ID_TYPES",
+    "is_buyer_country",
+    "is_valid_tax_id_for_country",
+    "normalize_tax_id",
+    "validate_business_details",
+]
+
+
+def is_buyer_country(value: str) -> bool:
+    """A country Stripe Tax calculates tax for, as a buyer's country."""
+    return value.strip().upper() in BUYER_COUNTRIES
+
+
+def normalize_tax_id(tax_id: str) -> str:
+    return "".join(tax_id.strip().upper().split())
+
+
+def is_valid_tax_id_for_country(country: str, tax_id: str) -> bool:
+    tax_id_type = COUNTRY_TO_TAX_ID_TYPE.get(country)
+    if tax_id_type is None:
+        return False
+    normalized = normalize_tax_id(tax_id)
+    if tax_id_type == "eu_vat" and country in EU_MEMBER_COUNTRIES:
+        return EU_VAT_FORMAT_BY_COUNTRY[country].fullmatch(normalized) is not None
+    return TAX_ID_FORMAT_BY_TYPE[tax_id_type].fullmatch(normalized) is not None
+
+
+def _stripped(value: str | None) -> str:
+    return value.strip() if value else ""
+
+
+def _invalid(message: str) -> SolvaPayError:
+    return SolvaPayError(message, code="invalid_business_details", status=400)
+
+
+def validate_business_details(
+    *,
+    is_business: bool,
+    business_name: str | None = None,
+    country: str | None = None,
+    customer_country: str | None = None,
+    customer_name: str | None = None,
+    customer_state: str | None = None,
+    customer_postal_code: str | None = None,
+    tax_id: str | None = None,
+) -> Json:
+    """The details to send the API, with camelCase keys.
+
+    Raises ``SolvaPayError`` (code ``invalid_business_details``, status 400)
+    with the first problem as its message, the one TypeScript reports.
+    """
+    if customer_name is not None and len(customer_name) > CUSTOMER_NAME_MAX:
+        raise _invalid(f"Too big: expected string to have <={CUSTOMER_NAME_MAX} characters")
+
+    name = _stripped(customer_name)
+    address: Json = {}
+    if _stripped(customer_state):
+        address["customerState"] = _stripped(customer_state)
+    if _stripped(customer_postal_code):
+        address["customerPostalCode"] = _stripped(customer_postal_code)
+
+    if not is_business:
+        billing_country = _stripped(customer_country).upper()
+        if billing_country and not is_buyer_country(billing_country):
+            raise _invalid("Billing country is not supported for tax calculation")
+        if billing_country:
+            consumer: Json = {"isBusiness": False, "customerCountry": billing_country}
+            if name:
+                consumer["customerName"] = name
+            return {**consumer, **address}
+        return {"isBusiness": False, **({"customerName": name} if name else {})}
+
+    business_country = _stripped(country).upper()
+    if not business_country:
+        raise _invalid("Country is required")
+    if not is_buyer_country(business_country):
+        raise _invalid("Country is not supported for business purchases")
+    if _stripped(tax_id) and not is_valid_tax_id_for_country(business_country, tax_id or ""):
+        raise _invalid(f"Enter a valid tax ID for {business_country}")
+
+    billing_country = _stripped(customer_country).upper()
+    details: Json = {
+        "isBusiness": True,
+        "country": business_country,
+        "customerCountry": billing_country
+        if billing_country and is_buyer_country(billing_country)
+        else business_country,
+    }
+    if _stripped(business_name):
+        details["businessName"] = _stripped(business_name)
+    if _stripped(tax_id):
+        details["taxId"] = normalize_tax_id(tax_id or "")
+        tax_id_type = COUNTRY_TO_TAX_ID_TYPE.get(business_country)
+        if tax_id_type:
+            details["taxIdType"] = tax_id_type
+    if name:
+        details["customerName"] = name
+    return {**details, **address}

solvapay/client.py

@@ -0,0 +1,107 @@
+"""The SolvaPay API client: every operation in the spec, async or blocking.
+
+```python
+from solvapay import AsyncApiClient
+
+async with AsyncApiClient(api_key="sk_sandbox_...") as api:
+    customer = await api.get_customer(reference="cus_123")
+```
+
+The methods are generated from ``openapi/sdk-v1.json``; this module only
+adds construction and lifecycle.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from ._generated.operations import AsyncSolvaPayApi, SolvaPayApi
+from ._http import (
+    DEFAULT_API_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT_SECONDS,
+    AsyncTransport,
+    SyncTransport,
+)
+
+__all__ = ["ApiClient", "AsyncApiClient"]
+
+
+class AsyncApiClient(AsyncSolvaPayApi):
+    """Async client. Use it as an async context manager, or call ``aclose()``."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        api_base_url: str = DEFAULT_API_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            AsyncTransport(
+                api_key=api_key,
+                api_base_url=api_base_url,
+                timeout=timeout,
+                max_retries=max_retries,
+                client=http_client,
+            )
+        )
+
+    @property
+    def api_base_url(self) -> str:
+        return self._transport.api_base_url
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncApiClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+
+class ApiClient(SolvaPayApi):
+    """Blocking client. Use it as a context manager, or call ``close()``."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        api_base_url: str = DEFAULT_API_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            SyncTransport(
+                api_key=api_key,
+                api_base_url=api_base_url,
+                timeout=timeout,
+                max_retries=max_retries,
+                client=http_client,
+            )
+        )
+
+    @property
+    def api_base_url(self) -> str:
+        return self._transport.api_base_url
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> ApiClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

solvapay/errors.py

@@ -0,0 +1,33 @@
+"""Errors raised by the SolvaPay SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class SolvaPayError(Exception):
+    """Every error the SDK raises.
+
+    Branch on ``code`` (a stable identifier) and ``status`` (the HTTP status,
+    when the error came from the API), never on the message, which is for
+    people and may change.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        status: int | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status = status
+        self.body = body
+
+    def __repr__(self) -> str:
+        return (
+            f"SolvaPayError(code={self.code!r}, status={self.status!r}, message={self.message!r})"
+        )

solvapay/mcp/__init__.py

@@ -0,0 +1,90 @@
+"""Paid MCP tools for the official MCP Python SDK. Install with ``pip install 'solvapay[mcp]'``."""
+
+from .app import (
+    BOOTSTRAP_URI,
+    DEFAULT_CSP,
+    RESOURCE_MIME_TYPE,
+    HideToolsByAudience,
+    is_chatgpt_request,
+    merge_csp,
+    widget_html,
+)
+from .auth import SolvaPayTokenVerifier, authorization_server_metadata, oauth_bridge_routes
+from .bootstrap import (
+    build_bootstrap_payload,
+    derive_default_view,
+    enrich_purchase,
+    select_active_plan_purchase,
+)
+from .intent import (
+    OVERVIEW_MARKDOWN,
+    OVERVIEW_URI,
+    build_solvapay_prompts,
+    narrated_tool_result,
+    register_intent_tools,
+    tool_error_result,
+)
+from .narrate import (
+    NARRATORS,
+    NarratorOutput,
+    narrate_activate_plan,
+    narrate_auto_recharge,
+    narrate_manage_account,
+    narrate_topup,
+    narrate_upgrade,
+    ui_placeholder,
+)
+from .response import CustomerSnapshot, Nudge, ResponseContext, ResponseResult
+from .server import SolvaPayMcpServer, create_solvapay_mcp_server
+from .tools import (
+    PAID_TOOL_HINT,
+    default_customer_ref,
+    free_tool_description_suffix,
+    register_free_tool,
+    register_payable_tool,
+)
+from .transport import TRANSPORT_TOOL_NAMES, register_transport_tools
+
+__all__ = [
+    "BOOTSTRAP_URI",
+    "DEFAULT_CSP",
+    "NARRATORS",
+    "OVERVIEW_MARKDOWN",
+    "OVERVIEW_URI",
+    "PAID_TOOL_HINT",
+    "RESOURCE_MIME_TYPE",
+    "TRANSPORT_TOOL_NAMES",
+    "CustomerSnapshot",
+    "HideToolsByAudience",
+    "NarratorOutput",
+    "Nudge",
+    "ResponseContext",
+    "ResponseResult",
+    "SolvaPayMcpServer",
+    "SolvaPayTokenVerifier",
+    "authorization_server_metadata",
+    "build_bootstrap_payload",
+    "build_solvapay_prompts",
+    "create_solvapay_mcp_server",
+    "default_customer_ref",
+    "derive_default_view",
+    "enrich_purchase",
+    "free_tool_description_suffix",
+    "is_chatgpt_request",
+    "merge_csp",
+    "narrate_activate_plan",
+    "narrate_auto_recharge",
+    "narrate_manage_account",
+    "narrate_topup",
+    "narrate_upgrade",
+    "narrated_tool_result",
+    "oauth_bridge_routes",
+    "register_free_tool",
+    "register_intent_tools",
+    "register_payable_tool",
+    "register_transport_tools",
+    "select_active_plan_purchase",
+    "tool_error_result",
+    "ui_placeholder",
+    "widget_html",
+]