paiment 0.2.0__py3-none-any.whl

paiment/__init__.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._errors import PaimentAuthError, PaimentError, PaimentNotFoundError, PaimentValidationError
+from ._http import AsyncHttpClient, HttpClient
+from ._models import FixedPrice, Page, Plan, Pagination, Subscription, Usage, UsageBasedPrice, User
+from .resources.plans import AsyncPlansResource, PlansResource
+from .resources.subscriptions import AsyncSubscriptionsResource, SubscriptionsResource
+from .resources.usage import AsyncUsageResource, UsageResource
+from .resources.users import AsyncUsersResource, UsersResource
+
+__all__ = [
+    "PaimentClient",
+    "AsyncPaimentClient",
+    "PaimentError",
+    "PaimentAuthError",
+    "PaimentNotFoundError",
+    "PaimentValidationError",
+    "User",
+    "Subscription",
+    "Plan",
+    "UsageBasedPrice",
+    "FixedPrice",
+    "Usage",
+    "Page",
+    "Pagination",
+]
+
+_DEFAULT_BASE_URL = "https://api.paiment.tech"
+
+
+class PaimentClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        workspace_id: str | None = None,
+    ) -> None:
+        self._http = HttpClient(api_key=api_key, base_url=base_url, workspace_id=workspace_id)
+        self.users = UsersResource(self._http)
+        self.subscriptions = SubscriptionsResource(self._http)
+        self.plans = PlansResource(self._http)
+        self.usage = UsageResource(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "PaimentClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class AsyncPaimentClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        workspace_id: str | None = None,
+    ) -> None:
+        self._http = AsyncHttpClient(api_key=api_key, base_url=base_url, workspace_id=workspace_id)
+        self.users = AsyncUsersResource(self._http)
+        self.subscriptions = AsyncSubscriptionsResource(self._http)
+        self.plans = AsyncPlansResource(self._http)
+        self.usage = AsyncUsageResource(self._http)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncPaimentClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()

paiment/_errors.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class PaimentError(Exception):
+    def __init__(self, message: str, status_code: int | None = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class PaimentAuthError(PaimentError):
+    def __init__(self, body: Any = None) -> None:
+        super().__init__("Authentication failed. Check your API key.", 401, body)
+
+
+class PaimentNotFoundError(PaimentError):
+    def __init__(self, resource: str = "Resource") -> None:
+        super().__init__(f"{resource} not found.", 404)
+
+
+class PaimentValidationError(PaimentError):
+    def __init__(self, body: Any = None) -> None:
+        super().__init__("Validation failed.", 400, body)

paiment/_http.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._errors import PaimentAuthError, PaimentError, PaimentNotFoundError, PaimentValidationError
+
+_DEFAULT_TIMEOUT = 30.0
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    try:
+        body: Any = response.json()
+    except Exception:
+        body = response.text
+
+    status = response.status_code
+    if status == 401:
+        raise PaimentAuthError(body)
+    if status == 404:
+        raise PaimentNotFoundError()
+    if status == 400:
+        raise PaimentValidationError(body)
+    raise PaimentError(f"Request failed with status {status}", status, body)
+
+
+class HttpClient:
+    def __init__(self, api_key: str, base_url: str, workspace_id: str | None = None) -> None:
+        headers: dict[str, str] = {"X-Api-Key": api_key, "Content-Type": "application/json"}
+        if workspace_id:
+            headers["X-Workspace-Id"] = workspace_id
+        self.workspace_id = workspace_id
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers=headers,
+            timeout=_DEFAULT_TIMEOUT,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        r = self._client.get(path, params={k: v for k, v in (params or {}).items() if v is not None})
+        _raise_for_status(r)
+        return r.json() if r.status_code != 204 else None
+
+    def post(self, path: str, body: Any = None) -> Any:
+        r = self._client.post(path, json=body)
+        _raise_for_status(r)
+        return r.json() if r.status_code != 204 else None
+
+    def patch(self, path: str, body: Any = None) -> Any:
+        r = self._client.patch(path, json=body)
+        _raise_for_status(r)
+        return r.json() if r.status_code != 204 else None
+
+    def put(self, path: str, body: Any = None) -> Any:
+        r = self._client.put(path, json=body)
+        _raise_for_status(r)
+        return r.json() if r.status_code != 204 else None
+
+    def delete(self, path: str) -> None:
+        r = self._client.delete(path)
+        _raise_for_status(r)
+
+
+class AsyncHttpClient:
+    def __init__(self, api_key: str, base_url: str, workspace_id: str | None = None) -> None:
+        headers: dict[str, str] = {"X-Api-Key": api_key, "Content-Type": "application/json"}
+        if workspace_id:
+            headers["X-Workspace-Id"] = workspace_id
+        self.workspace_id = workspace_id
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers=headers,
+            timeout=_DEFAULT_TIMEOUT,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHttpClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        r = await self._client.get(path, params={k: v for k, v in (params or {}).items() if v is not None})
+        _raise_for_status(r)
+        return r.json() if r.status_code != 204 else None
+
+    async def post(self, path: str, body: Any = None) -> Any:
+        r = await self._client.post(path, json=body)
+        _raise_for_status(r)
+        return r.json() if r.status_code != 204 else None
+
+    async def patch(self, path: str, body: Any = None) -> Any:
+        r = await self._client.patch(path, json=body)
+        _raise_for_status(r)
+        return r.json() if r.status_code != 204 else None
+
+    async def put(self, path: str, body: Any = None) -> Any:
+        r = await self._client.put(path, json=body)
+        _raise_for_status(r)
+        return r.json() if r.status_code != 204 else None
+
+    async def delete(self, path: str) -> None:
+        r = await self._client.delete(path)
+        _raise_for_status(r)

paiment/_models.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+def _get(d: dict[str, Any], key: str, default: Any = None) -> Any:
+    return d.get(key, default)
+
+
+@dataclass
+class Subscription:
+    id: int
+    tenant_id: str
+    workspace_id: str
+    user_id: str
+    plan_id: int | None
+    plan_name: str
+    status: str
+    subscription_start: str
+    subscription_end: str | None
+    billing_period_start: str | None
+    billing_period_end: str | None
+    trial_start: str | None
+    trial_end: str | None
+    price: int
+    currency: str
+    interval: str
+    source: str
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Subscription":
+        return cls(
+            id=d["id"],
+            tenant_id=d.get("tenantId", ""),
+            workspace_id=str(d.get("workspaceId", "")),
+            user_id=d.get("userId", ""),
+            plan_id=_get(d, "planId"),
+            plan_name=d.get("planName", ""),
+            status=d.get("status", "Active"),
+            subscription_start=d.get("subscriptionStart", ""),
+            subscription_end=_get(d, "subscriptionEnd"),
+            billing_period_start=_get(d, "billingPeriodStart"),
+            billing_period_end=_get(d, "billingPeriodEnd"),
+            trial_start=_get(d, "trialStart"),
+            trial_end=_get(d, "trialEnd"),
+            price=d.get("price", 0),
+            currency=d.get("currency", ""),
+            interval=d.get("interval", ""),
+            source=d.get("source", ""),
+            created_at=d.get("createdAt", ""),
+        )
+
+
+@dataclass
+class User:
+    id: int
+    user_id: str | None
+    tenant_id: str | None
+    user_name: str | None
+    user_email: str | None
+    workspace_id: str | None
+    created_at: str
+    subscriptions: list[Subscription]
+    plan_name: str
+    price: int
+    currency: str
+    interval: str
+    subscription_date: str
+    subscription_end_date: str | None
+    source: str
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "User":
+        return cls(
+            id=d["id"],
+            user_id=_get(d, "userId"),
+            tenant_id=_get(d, "tenantId"),
+            user_name=_get(d, "userName"),
+            user_email=_get(d, "userEmail"),
+            workspace_id=str(_get(d, "workspaceId")) if _get(d, "workspaceId") is not None else None,
+            created_at=d.get("createdAt", ""),
+            subscriptions=[Subscription.from_dict(s) for s in d.get("subscriptions", [])],
+            plan_name=d.get("planName", ""),
+            price=d.get("price", 0),
+            currency=d.get("currency", ""),
+            interval=d.get("interval", ""),
+            subscription_date=d.get("subscriptionDate", ""),
+            subscription_end_date=_get(d, "subscriptionEndDate"),
+            source=d.get("source", ""),
+        )
+
+
+@dataclass
+class UsageBasedPrice:
+    billable_metric: str
+    billing_cycle: str
+    recurring_period: str | None
+    price_model: str
+    per_unit: float
+    price_adjustments: dict[str, Any] | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "UsageBasedPrice":
+        return cls(
+            billable_metric=d.get("billableMetric", ""),
+            billing_cycle=d.get("billingCycle", ""),
+            recurring_period=_get(d, "recurringPeriod"),
+            price_model=d.get("priceModel", "unit-pricing"),
+            per_unit=float(d.get("perUnit", 0)),
+            price_adjustments=_get(d, "priceAdjustments"),
+        )
+
+
+@dataclass
+class FixedPrice:
+    item: str
+    price_model: str
+    quantity: int
+    per_unit: float
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "FixedPrice":
+        return cls(
+            item=d.get("item", ""),
+            price_model=d.get("priceModel", "unit-pricing"),
+            quantity=d.get("quantity", 1),
+            per_unit=float(d.get("perUnit", 0)),
+        )
+
+
+@dataclass
+class Plan:
+    id: int
+    name: str
+    tenant_id: str
+    external_plan_id: str | None
+    description: str | None
+    currency: str
+    list_price_cents: int
+    usage_based_prices: list[UsageBasedPrice] = field(default_factory=list)
+    fixed_prices: list[FixedPrice] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Plan":
+        return cls(
+            id=d["id"],
+            name=d.get("name", ""),
+            tenant_id=d.get("tenantId", ""),
+            external_plan_id=_get(d, "externalPlanId"),
+            description=_get(d, "description"),
+            currency=d.get("currency", ""),
+            list_price_cents=d.get("listPriceCents", 0),
+            usage_based_prices=[
+                UsageBasedPrice.from_dict(p) for p in d.get("usageBasedPrices", [])
+            ],
+            fixed_prices=[FixedPrice.from_dict(p) for p in d.get("fixedPrices", [])],
+        )
+
+
+@dataclass
+class Usage:
+    id: int
+    user_id: str
+    tenant_id: str | None
+    plan_id: int | None
+    workspace_id: str | None
+    input_tokens: int
+    output_tokens: int
+    llm_provider: str
+    llm_model: str
+    feature: str | None
+    feature_session: str | None
+    ts: int | None
+    total_cost: float | None
+    formatted_cost: str | None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Usage":
+        return cls(
+            id=d["id"],
+            user_id=d.get("userId", ""),
+            tenant_id=_get(d, "tenantId"),
+            plan_id=_get(d, "planId"),
+            workspace_id=str(_get(d, "workspaceId")) if _get(d, "workspaceId") is not None else None,
+            input_tokens=d.get("inputTokens", 0),
+            output_tokens=d.get("outputTokens", 0),
+            llm_provider=d.get("llmProvider", ""),
+            llm_model=d.get("llmModel", ""),
+            feature=_get(d, "feature"),
+            feature_session=_get(d, "featureSession"),
+            ts=_get(d, "ts"),
+            total_cost=_get(d, "totalCost"),
+            formatted_cost=_get(d, "formattedCost"),
+        )
+
+
+@dataclass
+class Pagination:
+    current_page: int
+    items_per_page: int
+    total_items: int
+    total_pages: int
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Pagination":
+        return cls(
+            current_page=d.get("currentPage", 1),
+            items_per_page=d.get("itemsPerPage", 20),
+            total_items=d.get("totalItems", 0),
+            total_pages=d.get("totalPages", 0),
+        )
+
+
+@dataclass
+class Page(Generic[T]):
+    data: list[T]
+    pagination: Pagination

paiment/resources/plans.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .._http import AsyncHttpClient, HttpClient
+from .._models import Plan
+
+
+def _build_plan_body(
+    *,
+    name: str | None = None,
+    currency: str | None = None,
+    external_plan_id: str | None = None,
+    description: str | None = None,
+    list_price_cents: int | None = None,
+    tokens: int | None = None,
+    usage_based_prices: list[dict[str, Any]] | None = None,
+    fixed_prices: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {}
+    if name is not None:
+        body["name"] = name
+    if currency is not None:
+        body["currency"] = currency
+    if external_plan_id is not None:
+        body["externalPlanId"] = external_plan_id
+    if description is not None:
+        body["description"] = description
+    if list_price_cents is not None:
+        body["listPriceCents"] = list_price_cents
+    if tokens is not None:
+        body["tokens"] = tokens
+    if usage_based_prices is not None:
+        body["usageBasedPrices"] = usage_based_prices
+    if fixed_prices is not None:
+        body["fixedPrices"] = fixed_prices
+    return body
+
+
+class PlansResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        name: str,
+        currency: str,
+        external_plan_id: str | None = None,
+        description: str | None = None,
+        list_price_cents: int | None = None,
+        tokens: int | None = None,
+        usage_based_prices: list[dict[str, Any]] | None = None,
+        fixed_prices: list[dict[str, Any]] | None = None,
+    ) -> Plan:
+        body = _build_plan_body(
+            name=name,
+            currency=currency,
+            external_plan_id=external_plan_id,
+            description=description,
+            list_price_cents=list_price_cents,
+            tokens=tokens,
+            usage_based_prices=usage_based_prices,
+            fixed_prices=fixed_prices,
+        )
+        return Plan.from_dict(self._http.post("/api/plans", body))
+
+    def list(self) -> list[Plan]:
+        return [Plan.from_dict(p) for p in self._http.get("/api/plans")]
+
+    def get(self, plan_id: int) -> Plan:
+        return Plan.from_dict(self._http.get(f"/api/plans/{plan_id}"))
+
+    def update(
+        self,
+        plan_id: int,
+        *,
+        name: str,
+        currency: str,
+        external_plan_id: str | None = None,
+        description: str | None = None,
+        list_price_cents: int | None = None,
+        tokens: int | None = None,
+        usage_based_prices: list[dict[str, Any]] | None = None,
+        fixed_prices: list[dict[str, Any]] | None = None,
+    ) -> Plan:
+        body = _build_plan_body(
+            name=name,
+            currency=currency,
+            external_plan_id=external_plan_id,
+            description=description,
+            list_price_cents=list_price_cents,
+            tokens=tokens,
+            usage_based_prices=usage_based_prices,
+            fixed_prices=fixed_prices,
+        )
+        return Plan.from_dict(self._http.put(f"/api/plans/{plan_id}", body))
+
+    def delete(self, plan_id: int) -> None:
+        self._http.delete(f"/api/plans/{plan_id}")
+
+
+class AsyncPlansResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(
+        self,
+        *,
+        name: str,
+        currency: str,
+        external_plan_id: str | None = None,
+        description: str | None = None,
+        list_price_cents: int | None = None,
+        tokens: int | None = None,
+        usage_based_prices: list[dict[str, Any]] | None = None,
+        fixed_prices: list[dict[str, Any]] | None = None,
+    ) -> Plan:
+        body = _build_plan_body(
+            name=name,
+            currency=currency,
+            external_plan_id=external_plan_id,
+            description=description,
+            list_price_cents=list_price_cents,
+            tokens=tokens,
+            usage_based_prices=usage_based_prices,
+            fixed_prices=fixed_prices,
+        )
+        return Plan.from_dict(await self._http.post("/api/plans", body))
+
+    async def list(self) -> list[Plan]:
+        return [Plan.from_dict(p) for p in await self._http.get("/api/plans")]
+
+    async def get(self, plan_id: int) -> Plan:
+        return Plan.from_dict(await self._http.get(f"/api/plans/{plan_id}"))
+
+    async def update(
+        self,
+        plan_id: int,
+        *,
+        name: str,
+        currency: str,
+        external_plan_id: str | None = None,
+        description: str | None = None,
+        list_price_cents: int | None = None,
+        tokens: int | None = None,
+        usage_based_prices: list[dict[str, Any]] | None = None,
+        fixed_prices: list[dict[str, Any]] | None = None,
+    ) -> Plan:
+        body = _build_plan_body(
+            name=name,
+            currency=currency,
+            external_plan_id=external_plan_id,
+            description=description,
+            list_price_cents=list_price_cents,
+            tokens=tokens,
+            usage_based_prices=usage_based_prices,
+            fixed_prices=fixed_prices,
+        )
+        return Plan.from_dict(await self._http.put(f"/api/plans/{plan_id}", body))
+
+    async def delete(self, plan_id: int) -> None:
+        await self._http.delete(f"/api/plans/{plan_id}")

paiment/resources/subscriptions.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+from urllib.parse import urlencode
+
+from .._http import AsyncHttpClient, HttpClient
+from .._models import Page, Pagination, Subscription
+
+
+def _with_workspace(path: str, workspace_id: str | None) -> str:
+    if not workspace_id:
+        return path
+    sep = "&" if "?" in path else "?"
+    return f"{path}{sep}{urlencode({'workspaceId': workspace_id})}"
+
+
+def _resolve_workspace(http: HttpClient | AsyncHttpClient, workspace_id: str | None) -> str | None:
+    return workspace_id or http.workspace_id
+
+
+def _parse_subscription_list(data: Any) -> Page[Subscription]:
+    if isinstance(data, dict) and "data" in data:
+        return Page(
+            data=[Subscription.from_dict(s) for s in data["data"]],
+            pagination=Pagination.from_dict(data["pagination"]),
+        )
+    items = data if isinstance(data, list) else [data]
+    return Page(
+        data=[Subscription.from_dict(s) for s in items],
+        pagination=Pagination(1, len(items), len(items), 1),
+    )
+
+
+class SubscriptionsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        user_id: str | None = None,
+        workspace_id: str | None = None,
+        status: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[Subscription]:
+        ws = _resolve_workspace(self._http, workspace_id)
+        data = self._http.get(
+            "/api/subscriptions",
+            {"userId": user_id, "workspaceId": ws, "status": status, "page": page, "limit": limit},
+        )
+        return _parse_subscription_list(data)
+
+    def get(self, subscription_id: int, *, workspace_id: str | None = None) -> Subscription:
+        ws = _resolve_workspace(self._http, workspace_id)
+        return Subscription.from_dict(
+            self._http.get(_with_workspace(f"/api/subscriptions/{subscription_id}", ws))
+        )
+
+    def create(
+        self,
+        *,
+        user_id: str,
+        price: int,
+        currency: str,
+        interval: str,
+        plan_id: int | None = None,
+        plan_name: str | None = None,
+        user_name: str | None = None,
+        user_email: str | None = None,
+        status: str = "Active",
+        subscription_start: str | None = None,
+        subscription_end: str | None = None,
+        source: str = "sdk",
+        workspace_id: str | None = None,
+    ) -> Subscription:
+        ws = _resolve_workspace(self._http, workspace_id)
+        body = {k: v for k, v in {
+            "userId": user_id,
+            "userName": user_name,
+            "userEmail": user_email,
+            "planId": plan_id,
+            "planName": plan_name,
+            "status": status,
+            "subscriptionStart": subscription_start,
+            "subscriptionEnd": subscription_end,
+            "price": price,
+            "currency": currency,
+            "interval": interval,
+            "source": source,
+        }.items() if v is not None}
+        return Subscription.from_dict(
+            self._http.post(_with_workspace("/api/subscriptions", ws), body)
+        )
+
+    def end(
+        self,
+        subscription_id: int,
+        *,
+        subscription_end: str | None = None,
+        workspace_id: str | None = None,
+    ) -> Subscription:
+        ws = _resolve_workspace(self._http, workspace_id)
+        body = {"subscriptionEnd": subscription_end} if subscription_end else {}
+        return Subscription.from_dict(
+            self._http.post(_with_workspace(f"/api/subscriptions/{subscription_id}/end", ws), body)
+        )
+
+    def update(
+        self,
+        subscription_id: int,
+        data: dict[str, Any],
+        *,
+        workspace_id: str | None = None,
+    ) -> Subscription:
+        ws = _resolve_workspace(self._http, workspace_id)
+        return Subscription.from_dict(
+            self._http.patch(_with_workspace(f"/api/subscriptions/{subscription_id}", ws), data)
+        )
+
+    def cancel(self, subscription_id: int, *, workspace_id: str | None = None) -> Subscription:
+        now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        return self.end(subscription_id, subscription_end=now, workspace_id=workspace_id)
+
+
+class AsyncSubscriptionsResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(
+        self,
+        *,
+        user_id: str | None = None,
+        workspace_id: str | None = None,
+        status: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[Subscription]:
+        ws = _resolve_workspace(self._http, workspace_id)
+        data = await self._http.get(
+            "/api/subscriptions",
+            {"userId": user_id, "workspaceId": ws, "status": status, "page": page, "limit": limit},
+        )
+        return _parse_subscription_list(data)
+
+    async def get(self, subscription_id: int, *, workspace_id: str | None = None) -> Subscription:
+        ws = _resolve_workspace(self._http, workspace_id)
+        return Subscription.from_dict(
+            await self._http.get(_with_workspace(f"/api/subscriptions/{subscription_id}", ws))
+        )
+
+    async def create(
+        self,
+        *,
+        user_id: str,
+        price: int,
+        currency: str,
+        interval: str,
+        plan_id: int | None = None,
+        plan_name: str | None = None,
+        user_name: str | None = None,
+        user_email: str | None = None,
+        status: str = "Active",
+        subscription_start: str | None = None,
+        subscription_end: str | None = None,
+        source: str = "sdk",
+        workspace_id: str | None = None,
+    ) -> Subscription:
+        ws = _resolve_workspace(self._http, workspace_id)
+        body = {k: v for k, v in {
+            "userId": user_id,
+            "userName": user_name,
+            "userEmail": user_email,
+            "planId": plan_id,
+            "planName": plan_name,
+            "status": status,
+            "subscriptionStart": subscription_start,
+            "subscriptionEnd": subscription_end,
+            "price": price,
+            "currency": currency,
+            "interval": interval,
+            "source": source,
+        }.items() if v is not None}
+        return Subscription.from_dict(
+            await self._http.post(_with_workspace("/api/subscriptions", ws), body)
+        )
+
+    async def end(
+        self,
+        subscription_id: int,
+        *,
+        subscription_end: str | None = None,
+        workspace_id: str | None = None,
+    ) -> Subscription:
+        ws = _resolve_workspace(self._http, workspace_id)
+        body = {"subscriptionEnd": subscription_end} if subscription_end else {}
+        return Subscription.from_dict(
+            await self._http.post(_with_workspace(f"/api/subscriptions/{subscription_id}/end", ws), body)
+        )
+
+    async def update(
+        self,
+        subscription_id: int,
+        data: dict[str, Any],
+        *,
+        workspace_id: str | None = None,
+    ) -> Subscription:
+        ws = _resolve_workspace(self._http, workspace_id)
+        return Subscription.from_dict(
+            await self._http.patch(_with_workspace(f"/api/subscriptions/{subscription_id}", ws), data)
+        )
+
+    async def cancel(self, subscription_id: int, *, workspace_id: str | None = None) -> Subscription:
+        now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        return await self.end(subscription_id, subscription_end=now, workspace_id=workspace_id)

paiment/resources/usage.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+from urllib.parse import urlencode
+
+from .._http import AsyncHttpClient, HttpClient
+from .._models import Page, Pagination, Usage
+
+
+def _resolve_workspace(http: HttpClient | AsyncHttpClient, workspace_id: str | None) -> str | None:
+    return workspace_id or http.workspace_id
+
+
+def _parse_usage_list(data: Any) -> Page[Usage]:
+    if isinstance(data, dict) and "data" in data:
+        return Page(
+            data=[Usage.from_dict(u) for u in data["data"]],
+            pagination=Pagination.from_dict(data["pagination"]),
+        )
+    items = data if isinstance(data, list) else [data]
+    return Page(data=[Usage.from_dict(u) for u in items], pagination=Pagination(1, len(items), len(items), 1))
+
+
+class UsageResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def report(
+        self,
+        *,
+        user_id: str,
+        input_tokens: int,
+        output_tokens: int,
+        provider: str,
+        model: str,
+        plan_id: int | None = None,
+        feature: str | None = None,
+        feature_session: str | None = None,
+        ts: int | None = None,
+        workspace_id: str | None = None,
+    ) -> Usage:
+        ws = _resolve_workspace(self._http, workspace_id)
+        path = "/api/usages"
+        if ws:
+            path = f"{path}?{urlencode({'workspaceId': ws})}"
+
+        body: dict[str, Any] = {
+            "userId": user_id,
+            "inputTokens": input_tokens,
+            "outputTokens": output_tokens,
+            "llmProvider": provider,
+            "llmModel": model,
+            "ts": ts if ts is not None else int(time.time() * 1000),
+        }
+        if plan_id is not None:
+            body["planId"] = plan_id
+        if feature is not None:
+            body["feature"] = feature
+        if feature_session is not None:
+            body["featureSession"] = feature_session
+
+        return Usage.from_dict(self._http.post(path, body))
+
+    def list(
+        self,
+        *,
+        user_id: str | None = None,
+        workspace_id: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[Usage]:
+        ws = _resolve_workspace(self._http, workspace_id)
+        return _parse_usage_list(
+            self._http.get("/api/usages", {"userId": user_id, "workspaceId": ws, "page": page, "limit": limit})
+        )
+
+
+class AsyncUsageResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def report(
+        self,
+        *,
+        user_id: str,
+        input_tokens: int,
+        output_tokens: int,
+        provider: str,
+        model: str,
+        plan_id: int | None = None,
+        feature: str | None = None,
+        feature_session: str | None = None,
+        ts: int | None = None,
+        workspace_id: str | None = None,
+    ) -> Usage:
+        ws = _resolve_workspace(self._http, workspace_id)
+        path = "/api/usages"
+        if ws:
+            path = f"{path}?{urlencode({'workspaceId': ws})}"
+
+        body: dict[str, Any] = {
+            "userId": user_id,
+            "inputTokens": input_tokens,
+            "outputTokens": output_tokens,
+            "llmProvider": provider,
+            "llmModel": model,
+            "ts": ts if ts is not None else int(time.time() * 1000),
+        }
+        if plan_id is not None:
+            body["planId"] = plan_id
+        if feature is not None:
+            body["feature"] = feature
+        if feature_session is not None:
+            body["featureSession"] = feature_session
+
+        return Usage.from_dict(await self._http.post(path, body))
+
+    async def list(
+        self,
+        *,
+        user_id: str | None = None,
+        workspace_id: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> Page[Usage]:
+        ws = _resolve_workspace(self._http, workspace_id)
+        return _parse_usage_list(
+            await self._http.get("/api/usages", {"userId": user_id, "workspaceId": ws, "page": page, "limit": limit})
+        )

paiment/resources/users.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+from urllib.parse import quote
+
+from .._http import AsyncHttpClient, HttpClient
+from .._models import Page, Pagination, User
+
+
+def _build_user_body(
+    *,
+    user_id: str | None = None,
+    user_name: str | None = None,
+    user_email: str | None = None,
+    plan_name: str | None = None,
+    plan_id: int | None = None,
+    price: int | None = None,
+    currency: str | None = None,
+    interval: str | None = None,
+    subscription_date: str | None = None,
+    subscription_end_date: str | None = None,
+    source: str | None = None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {}
+    if user_id is not None:
+        body["userId"] = user_id
+    if user_name is not None:
+        body["userName"] = user_name
+    if user_email is not None:
+        body["userEmail"] = user_email
+    if plan_name is not None:
+        body["planName"] = plan_name
+    if plan_id is not None:
+        body["planId"] = plan_id
+    if price is not None:
+        body["price"] = price
+    if currency is not None:
+        body["currency"] = currency
+    if interval is not None:
+        body["interval"] = interval
+    if subscription_date is not None:
+        body["subscriptionDate"] = subscription_date
+    if subscription_end_date is not None:
+        body["subscriptionEndDate"] = subscription_end_date
+    if source is not None:
+        body["source"] = source
+    return body
+
+
+def _parse_user_response(data: Any) -> User | Page[User]:
+    if isinstance(data, dict) and "data" in data and "pagination" in data:
+        return Page(
+            data=[User.from_dict(u) for u in data["data"]],
+            pagination=Pagination.from_dict(data["pagination"]),
+        )
+    if isinstance(data, list):
+        return Page(data=[User.from_dict(u) for u in data], pagination=Pagination(1, len(data), len(data), 1))
+    return User.from_dict(data)
+
+
+class UsersResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        user_id: str,
+        plan_name: str,
+        price: int,
+        currency: str,
+        interval: str,
+        user_name: str | None = None,
+        user_email: str | None = None,
+        plan_id: int | None = None,
+        subscription_date: str | None = None,
+        source: str = "sdk",
+    ) -> User:
+        body = _build_user_body(
+            user_id=user_id,
+            user_name=user_name,
+            user_email=user_email,
+            plan_name=plan_name,
+            plan_id=plan_id,
+            price=price,
+            currency=currency,
+            interval=interval,
+            subscription_date=subscription_date,
+            source=source,
+        )
+        body.setdefault("subscriptionDate", time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()))
+        return User.from_dict(self._http.post("/api/users", body))
+
+    def list(
+        self,
+        *,
+        page: int | None = None,
+        limit: int | None = None,
+        plan_name: str | None = None,
+    ) -> Page[User]:
+        data = self._http.get("/api/users", {"page": page, "limit": limit, "planName": plan_name})
+        result = _parse_user_response(data)
+        return result if isinstance(result, Page) else Page(data=[result], pagination=Pagination(1, 1, 1, 1))
+
+    def get(self, user_id: str) -> User:
+        return User.from_dict(self._http.get(f"/api/users/external/{quote(user_id, safe='')}"))
+
+    def update(
+        self,
+        user_id: str,
+        *,
+        user_name: str | None = None,
+        user_email: str | None = None,
+        plan_name: str | None = None,
+        plan_id: int | None = None,
+        price: int | None = None,
+        currency: str | None = None,
+        interval: str | None = None,
+        subscription_date: str | None = None,
+        subscription_end_date: str | None = None,
+        source: str | None = None,
+    ) -> User:
+        body = _build_user_body(
+            user_name=user_name,
+            user_email=user_email,
+            plan_name=plan_name,
+            plan_id=plan_id,
+            price=price,
+            currency=currency,
+            interval=interval,
+            subscription_date=subscription_date,
+            subscription_end_date=subscription_end_date,
+            source=source,
+        )
+        return User.from_dict(self._http.put(f"/api/users/external/{quote(user_id, safe='')}", body))
+
+    def delete(self, user_id: str) -> None:
+        self._http.delete(f"/api/users/external/{quote(user_id, safe='')}")
+
+
+class AsyncUsersResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(
+        self,
+        *,
+        user_id: str,
+        plan_name: str,
+        price: int,
+        currency: str,
+        interval: str,
+        user_name: str | None = None,
+        user_email: str | None = None,
+        plan_id: int | None = None,
+        subscription_date: str | None = None,
+        source: str = "sdk",
+    ) -> User:
+        body = _build_user_body(
+            user_id=user_id,
+            user_name=user_name,
+            user_email=user_email,
+            plan_name=plan_name,
+            plan_id=plan_id,
+            price=price,
+            currency=currency,
+            interval=interval,
+            subscription_date=subscription_date,
+            source=source,
+        )
+        body.setdefault("subscriptionDate", time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()))
+        return User.from_dict(await self._http.post("/api/users", body))
+
+    async def list(
+        self,
+        *,
+        page: int | None = None,
+        limit: int | None = None,
+        plan_name: str | None = None,
+    ) -> Page[User]:
+        data = await self._http.get("/api/users", {"page": page, "limit": limit, "planName": plan_name})
+        result = _parse_user_response(data)
+        return result if isinstance(result, Page) else Page(data=[result], pagination=Pagination(1, 1, 1, 1))
+
+    async def get(self, user_id: str) -> User:
+        return User.from_dict(await self._http.get(f"/api/users/external/{quote(user_id, safe='')}"))
+
+    async def update(
+        self,
+        user_id: str,
+        *,
+        user_name: str | None = None,
+        user_email: str | None = None,
+        plan_name: str | None = None,
+        plan_id: int | None = None,
+        price: int | None = None,
+        currency: str | None = None,
+        interval: str | None = None,
+        subscription_date: str | None = None,
+        subscription_end_date: str | None = None,
+        source: str | None = None,
+    ) -> User:
+        body = _build_user_body(
+            user_name=user_name,
+            user_email=user_email,
+            plan_name=plan_name,
+            plan_id=plan_id,
+            price=price,
+            currency=currency,
+            interval=interval,
+            subscription_date=subscription_date,
+            subscription_end_date=subscription_end_date,
+            source=source,
+        )
+        return User.from_dict(await self._http.put(f"/api/users/external/{quote(user_id, safe='')}", body))
+
+    async def delete(self, user_id: str) -> None:
+        await self._http.delete(f"/api/users/external/{quote(user_id, safe='')}")

paiment-0.2.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: paiment
+Version: 0.2.0
+Summary: Official Python SDK for the Paiment billing API
+Author: Paiment
+License-Expression: MIT
+Project-URL: Homepage, https://paiment.tech
+Project-URL: Documentation, https://paiment.tech
+Keywords: paiment,billing,sdk,llm,usage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: mypy>=1.9; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# paiment (Python SDK)
+
+Official Python SDK for the [Paiment](https://paiment.tech) billing API.
+
+> **npm users:** install `@paiment/sdk` instead. This package is the Python equivalent.
+
+Use it in your **backend** to register subscribers, report LLM usage, and manage plans.
+
+## Install
+
+```bash
+pip install paiment
+```
+
+Python 3.9+.
+
+## Setup
+
+Get an API key from **Settings → API Keys**.
+
+| Key format | Notes |
+|------------|--------|
+| `tenantId:workspaceId:secret` | **Recommended** |
+| `tenantId:secret` | Pass `workspace_id` on the client |
+
+```python
+from paiment import PaimentClient
+
+client = PaimentClient(api_key="tenantId:workspaceId:secret")
+# client = PaimentClient(api_key="...", base_url="http://localhost:5246")
+```
+
+## Quick start
+
+```python
+from paiment import PaimentClient
+
+with PaimentClient(api_key="tenantId:workspaceId:secret") as client:
+    sub = client.subscriptions.create(
+        user_id="user_123",
+        plan_name="Pro",
+        price=2999,
+        currency="USD",
+        interval="monthly",
+    )
+
+    client.usage.report(
+        user_id="user_123",
+        input_tokens=1250,
+        output_tokens=340,
+        provider="openai",
+        model="gpt-4o",
+        plan_id=sub.plan_id,
+    )
+
+    client.subscriptions.end(sub.id)
+```
+
+### Async
+
+```python
+from paiment import AsyncPaimentClient
+
+async with AsyncPaimentClient(api_key="tenantId:workspaceId:secret") as client:
+    sub = await client.subscriptions.create(
+        user_id="user_123",
+        plan_name="Pro",
+        price=2999,
+        currency="USD",
+        interval="monthly",
+    )
+    await client.usage.report(
+        user_id="user_123",
+        input_tokens=1250,
+        output_tokens=340,
+        provider="openai",
+        model="gpt-4o",
+    )
+```
+
+## API reference
+
+### Subscriptions
+
+| Method | Description |
+|--------|-------------|
+| `create(user_id, plan_name, price, currency, interval, ...)` | New subscription |
+| `list(user_id=..., status=...)` | List subscriptions |
+| `get(subscription_id)` | Get by id |
+| `update(subscription_id, data)` | Patch subscription |
+| `end(subscription_id)` | Close subscription |
+| `cancel(subscription_id)` | End immediately |
+
+### Users
+
+| Method | Description |
+|--------|-------------|
+| `create(user_id, plan_name, price, currency, interval, ...)` | User + subscription shortcut |
+| `get(user_id)` | Get by your user id |
+| `list(plan_name=..., page=..., limit=...)` | List users |
+| `update(user_id, ...)` | Partial update |
+| `delete(user_id)` | Delete user |
+
+### Usage
+
+| Method | Description |
+|--------|-------------|
+| `report(user_id, input_tokens, output_tokens, provider, model, ...)` | Record usage |
+| `list(user_id=..., page=..., limit=...)` | List usage rows |
+
+### Plans
+
+| Method | Description |
+|--------|-------------|
+| `create(name, currency, list_price_cents=..., ...)` | Create plan |
+| `list()` / `get(id)` / `update(id, ...)` / `delete(id)` | CRUD |
+
+## Fields
+
+| Field | Meaning |
+|-------|---------|
+| `user_id` | Your identifier for the end-user |
+| `plan_name` | Plan catalog name |
+| `price` | Subscription price in **cents** |
+| `list_price_cents` | Catalog list price on plans only |
+
+## Errors
+
+```python
+from paiment import PaimentAuthError, PaimentNotFoundError, PaimentValidationError, PaimentError
+```
+
+| Class | HTTP status |
+|-------|-------------|
+| `PaimentAuthError` | 401 |
+| `PaimentNotFoundError` | 404 |
+| `PaimentValidationError` | 400 |
+| `PaimentError` | other |

paiment-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+paiment/__init__.py,sha256=CFxl3p38owsvaL1Np57Pp5bdMm6VF4QsV_NH6EVqauw,2333
+paiment/_errors.py,sha256=CU0JTGvp1odMPdXed9FSSalwCJyV6SEFYOhc5nnc4Ec,772
+paiment/_http.py,sha256=VVFJKvLHGkndiH0zBxoJLn76DT0gYv8UY1j4Owho40U,4028
+paiment/_models.py,sha256=TNl4Xo0cRxecWUW7fHvyCTdkbTKe1KjKF1sjxz2MMwk,6511
+paiment/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+paiment/resources/plans.py,sha256=d0NXso9Q_11MJXwe0yxuibNGL_ha3mjE0eFPmmO9Ep8,5310
+paiment/resources/subscriptions.py,sha256=CCknfCZCIv_TssMjJG1JF6mJ-HZol5v2wB0bkyi90h4,7514
+paiment/resources/usage.py,sha256=u2Ucb02gkJykEFYkTi-ntG63nGPEolnzhDKQNAOV-ak,4082
+paiment/resources/users.py,sha256=uc3dhIrK-tGTueLghpf5R8aNZdogUeHn8GJN52i1kkE,7227
+paiment-0.2.0.dist-info/METADATA,sha256=gvVRcXuu6EtEwx7F2lkugcQo1Rz3n7P44Ib-FV2QuQY,4540
+paiment-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+paiment-0.2.0.dist-info/top_level.txt,sha256=GtbfxyFcWDyErOY1gORz2Tz1us6Gi8AUKOP5LlZ4uRk,8
+paiment-0.2.0.dist-info/RECORD,,

paiment-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

paiment-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+paiment