settlekit/examples/python-saas/app/settlekit_client.py

187 lines
6.1 KiB
Python
Raw Permalink Normal View History

2026-06-17 02:09:36 +03:00
"""Thin SettleKit SDK wiring for the AI Export Pro demo.
This module owns one process-wide :class:`AsyncSettleKit` client constructed from
environment variables and exposes a couple of helpers for the credit/usage
endpoints that the SDK does not yet wrap as first-class resources. Everything
here talks to the real SettleKit HTTP API — there are no stubs.
Environment
-----------
``SETTLEKIT_API_URL`` Base URL of the SettleKit API (default
``http://localhost:8787``).
``SETTLEKIT_API_KEY`` Bearer key sent on every request. **Required.**
``SETTLEKIT_ORG_ID`` Organization id customers/usage are scoped to.
**Required.**
``SETTLEKIT_PRODUCT_ID`` Product id recorded against metered usage. Optional
but recommended; defaults to ``"ai_export"``.
``AI_EXPORT_FEATURE`` Entitlement feature key checked by the paid route.
Defaults to ``"ai_export"``.
"""
from __future__ import annotations
import os
from dataclasses import dataclass
from functools import lru_cache
from typing import Any, Optional
from settlekit import AsyncSettleKit
from settlekit.errors import SettleKitConfigError
# The metric name we meter AI exports against in SettleKit usage records.
USAGE_METRIC = "ai_export"
@dataclass(frozen=True)
class Settings:
"""Immutable, validated runtime configuration for the demo."""
api_url: str
api_key: str
organization_id: str
product_id: str
feature: str
def _require_env(name: str) -> str:
"""Read a required environment variable or fail fast with a clear message."""
value = os.environ.get(name)
if not value:
raise SettleKitConfigError(
f"Missing required environment variable {name!r}. "
"See the README for the full list of env vars."
)
return value
@lru_cache(maxsize=1)
def get_settings() -> Settings:
"""Resolve and validate settings once per process."""
return Settings(
api_url=os.environ.get("SETTLEKIT_API_URL", "http://localhost:8787"),
api_key=_require_env("SETTLEKIT_API_KEY"),
organization_id=_require_env("SETTLEKIT_ORG_ID"),
product_id=os.environ.get("SETTLEKIT_PRODUCT_ID", "ai_export"),
feature=os.environ.get("AI_EXPORT_FEATURE", "ai_export"),
)
# Module-level singleton client. FastAPI's lifespan (see app.main) closes it on
# shutdown. We construct it lazily so importing the module never performs I/O.
_client: Optional[AsyncSettleKit] = None
def get_client() -> AsyncSettleKit:
"""Return the process-wide async SettleKit client, constructing it on first use."""
global _client
if _client is None:
settings = get_settings()
_client = AsyncSettleKit(
api_key=settings.api_key,
base_url=settings.api_url,
)
return _client
async def close_client() -> None:
"""Close the shared client (used by the FastAPI shutdown hook)."""
global _client
if _client is not None:
await _client.aclose()
_client = None
# ---------------------------------------------------------------------------
# Credit / usage helpers.
#
# The SDK exposes typed resources for products, customers, entitlements, etc.,
# but the prepaid-credit + metered-usage endpoints are reached through the
# client's low-level ``arequest`` method. These thin wrappers keep the call
# sites in deps.py / main.py declarative while still hitting the real API.
# ---------------------------------------------------------------------------
async def get_credits(customer_id: str) -> dict[str, Any]:
"""Return the customer's current prepaid credit balance.
``GET /v1/usage/credits?organizationId=&customerId=`` -> ``{"credits": int, ...}``.
"""
settings = get_settings()
result = await get_client().arequest(
"GET",
"/v1/usage/credits",
params={
"organizationId": settings.organization_id,
"customerId": customer_id,
},
)
return _as_dict(result)
async def grant_credits(customer_id: str, credits: int) -> dict[str, Any]:
"""Grant prepaid credits to a customer (admin operation).
``POST /v1/usage/credits/grant {organizationId, customerId, credits}``.
"""
settings = get_settings()
result = await get_client().arequest(
"POST",
"/v1/usage/credits/grant",
body={
"organizationId": settings.organization_id,
"customerId": customer_id,
"credits": credits,
},
)
return _as_dict(result)
async def consume_credits(customer_id: str, credits: int) -> dict[str, Any]:
"""Consume prepaid credits from a customer's balance.
``POST /v1/usage/credits/consume {organizationId, customerId, credits}``.
The API decrements the balance atomically and rejects the call (non-2xx,
surfaced as ``SettleKitError``) when the balance is insufficient.
"""
settings = get_settings()
result = await get_client().arequest(
"POST",
"/v1/usage/credits/consume",
body={
"organizationId": settings.organization_id,
"customerId": customer_id,
"credits": credits,
},
)
return _as_dict(result)
async def record_usage(customer_id: str, quantity: int = 1) -> dict[str, Any]:
"""Record a metered-usage event for analytics/billing.
``POST /v1/usage/record {organizationId, customerId, productId, metric, quantity}``.
"""
settings = get_settings()
result = await get_client().arequest(
"POST",
"/v1/usage/record",
body={
"organizationId": settings.organization_id,
"customerId": customer_id,
"productId": settings.product_id,
"metric": USAGE_METRIC,
"quantity": quantity,
},
)
return _as_dict(result)
def _as_dict(value: Any) -> dict[str, Any]:
"""Normalize an SDK payload to a plain dict for predictable downstream access."""
if isinstance(value, dict):
return value
if value is None:
return {}
return {"data": value}