Metadata-Version: 2.4
Name: vellumcharter
Version: 0.2.0
Summary: Thin, dependency-free server-side client for the VellumCharter entitlements + billing API
License-Expression: MIT
Project-URL: Homepage, https://vellumcharter.com
Project-URL: Repository, https://github.com/tdesposito/VellumCharter
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# vellumcharter

Thin, dependency-free (stdlib-only) server-side client for the VellumCharter
entitlements + billing API. **Server-side only** — it holds a secret API key.

## Install

```bash
pip install vellumcharter
```

Requires Python 3.11+.

## Usage

```python
from vellumcharter import VellumCharterClient

vellum = VellumCharterClient(
    api_key="vlm_sam.xxxxx",   # keep server-side, never ship to a browser
    tenant_id="sam",
    # base_url defaults to https://api.vellumcharter.com
)

# Gate a feature (cached with a short TTL):
if vellum.can("unit_1", "imports"):
    ...

ent = vellum.get_entitlements("unit_1")
ent.is_active()            # True for active/trialing
ent.has("imports")
ent.config("trial_days")
ent.found                  # False if the customer has no record (no exception)
```

A 404 returns an empty `EntitlementSet` (no exception), so gating never needs a
null check.

## Async

`AsyncVellumCharterClient` is the awaitable counterpart — same constructor and
methods, each `await`-ed. Use it from async frameworks (e.g. FastAPI):

```python
from vellumcharter import AsyncVellumCharterClient

vellum = AsyncVellumCharterClient(api_key="vlm_sam.xxxxx", tenant_id="sam")

if await vellum.can("unit_1", "imports"):
    ...

ent = await vellum.get_entitlements("unit_1")
vellum.invalidate("unit_1")   # cache op is synchronous (no await)
```

## What it covers

- **Entitlements:** `get_entitlements`, `can`, opt-in TTL cache + `invalidate`.
- **Checkout / subscriptions:** `create_checkout`, `create_setup_checkout`,
  `create_subscription`, `cancel_subscription`, `get_subscription`.
- **Provisioning:** `create_account`, `create_customer`, `set_account_status`,
  `set_customer_status`.
- **Billing:** `list_payment_methods`, `set_default_payment_method`,
  `remove_payment_method`, `set_subscription_payment_method`, `list_invoices`,
  `invoice_pdf_url`.
- **Webhook verification:** `verify_push_signature(raw_body, header, secret)` —
  validates a push and returns the parsed event (raises on a bad signature).

## Errors

`VellumCharterAuthError` on 401/403; `VellumCharterApiError` (with `.status` /
`.body`) on other non-2xx; `VellumCharterSignatureError` on a bad push signature.
The API key is sent as `x-api-key` on every request.

## API reference

Full endpoint + webhook contract: https://api.vellumcharter.com/openapi.json
