vellumcharter 0.2.0

Thin, dependency-free server-side client for the VellumCharter entitlements + billing API

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

pip install vellumcharter

Requires Python 3.11+.

Usage

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):

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