paiment 0.2.0__tar.gz

paiment-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,138 @@
+# 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/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-0.2.0/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-0.2.0/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)