vellumcharter 0.1.0__tar.gz

vellumcharter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Todd Esposito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vellumcharter-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+prune tests
+prune .venv
+prune .ruff_cache
+global-exclude *.py[cod]

vellumcharter-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: vellumcharter
+Version: 0.1.0
+Summary: Thin, dependency-free server-side client for the Vellum entitlements + billing API
+License-Expression: MIT
+Project-URL: Homepage, https://vellumcharter.com
+Project-URL: Repository, https://github.com/tdesposito/Vellum
+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 (Python SDK)
+
+A thin, **dependency-free** (stdlib `urllib` + `hmac`) server-side client for the
+Vellum entitlements + billing API. The Python counterpart to `sdks/js/` (TypeScript);
+built for Python consumers such as SAM2-SalesImport. **Server-side only** — it
+holds a secret API key.
+
+```python
+from vellumcharter import VellumClient, verify_push_signature
+
+vellum = VellumClient(
+    api_key="vlm_sam.xxxxx",   # from SSM, never shipped to a browser
+    tenant_id="sam",
+    # base_url defaults to https://api.vellumcharter.com; override for tests/staging.
+)
+
+# Gate a feature (pull-first; 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)
+```
+
+## Async
+
+`AsyncVellumClient` is the awaitable counterpart — same constructor and methods,
+each `await`-ed. It wraps the sync client on a worker thread (`asyncio.to_thread`),
+so the SDK stays dependency-free. Use it from async frameworks (e.g. FastAPI):
+
+```python
+from vellumcharter import AsyncVellumClient
+
+vellum = AsyncVellumClient(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)
+```
+
+It is "async-compatible" (each call runs in a worker thread), not single-socket
+async IO — the right trade-off for server-side entitlement checks while keeping
+zero dependencies.
+
+## What it covers
+
+- **Entitlements:** `get_entitlements`, `can`, opt-in TTL cache + `invalidate`.
+  A 404 returns an empty `EntitlementSet` (no exception), so gating never needs a
+  null check.
+- **Checkout / subscriptions:** `create_checkout`, `create_setup_checkout`
+  (payment method, no charge), `create_subscription` (server-side trial),
+  `cancel_subscription`, `get_subscription`.
+- **Provisioning:** `create_account` (adopt or create the Stripe customer),
+  `create_customer`, `set_account_status`, `set_customer_status`.
+- **Billing facade:** `list_payment_methods`, `set_default_payment_method`,
+  `remove_payment_method`, `set_subscription_payment_method`, `list_invoices`,
+  `invoice_pdf_url` (returns Stripe's hosted PDF URL).
+- **Push verification:** `verify_push_signature(raw_body, header, secret)` for the
+  consumer's `/webhooks/vellum` endpoint (mirrors `api/src/lib/notify.ts`).
+
+`VellumAuthError` is raised on 401/403; `VellumApiError` (with `.status`/`.body`)
+on other non-2xx; `VellumSignatureError` on a bad push signature.
+
+## Auth & errors
+
+The API key is sent as `x-api-key` on every request. Keep it server-side.
+
+## Requirements & tooling
+
+Python **3.11+** (3.9/3.10 are end-of-life). Managed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync                                   # create the venv (pinned to 3.11 via .python-version)
+uv run python -m unittest discover -s tests
+```
+
+The SDK itself has no third-party dependencies — `uv` is just for the dev/test
+environment and interpreter pinning.

vellumcharter-0.1.0/README.md

@@ -0,0 +1,83 @@
+# vellumcharter (Python SDK)
+
+A thin, **dependency-free** (stdlib `urllib` + `hmac`) server-side client for the
+Vellum entitlements + billing API. The Python counterpart to `sdks/js/` (TypeScript);
+built for Python consumers such as SAM2-SalesImport. **Server-side only** — it
+holds a secret API key.
+
+```python
+from vellumcharter import VellumClient, verify_push_signature
+
+vellum = VellumClient(
+    api_key="vlm_sam.xxxxx",   # from SSM, never shipped to a browser
+    tenant_id="sam",
+    # base_url defaults to https://api.vellumcharter.com; override for tests/staging.
+)
+
+# Gate a feature (pull-first; 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)
+```
+
+## Async
+
+`AsyncVellumClient` is the awaitable counterpart — same constructor and methods,
+each `await`-ed. It wraps the sync client on a worker thread (`asyncio.to_thread`),
+so the SDK stays dependency-free. Use it from async frameworks (e.g. FastAPI):
+
+```python
+from vellumcharter import AsyncVellumClient
+
+vellum = AsyncVellumClient(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)
+```
+
+It is "async-compatible" (each call runs in a worker thread), not single-socket
+async IO — the right trade-off for server-side entitlement checks while keeping
+zero dependencies.
+
+## What it covers
+
+- **Entitlements:** `get_entitlements`, `can`, opt-in TTL cache + `invalidate`.
+  A 404 returns an empty `EntitlementSet` (no exception), so gating never needs a
+  null check.
+- **Checkout / subscriptions:** `create_checkout`, `create_setup_checkout`
+  (payment method, no charge), `create_subscription` (server-side trial),
+  `cancel_subscription`, `get_subscription`.
+- **Provisioning:** `create_account` (adopt or create the Stripe customer),
+  `create_customer`, `set_account_status`, `set_customer_status`.
+- **Billing facade:** `list_payment_methods`, `set_default_payment_method`,
+  `remove_payment_method`, `set_subscription_payment_method`, `list_invoices`,
+  `invoice_pdf_url` (returns Stripe's hosted PDF URL).
+- **Push verification:** `verify_push_signature(raw_body, header, secret)` for the
+  consumer's `/webhooks/vellum` endpoint (mirrors `api/src/lib/notify.ts`).
+
+`VellumAuthError` is raised on 401/403; `VellumApiError` (with `.status`/`.body`)
+on other non-2xx; `VellumSignatureError` on a bad push signature.
+
+## Auth & errors
+
+The API key is sent as `x-api-key` on every request. Keep it server-side.
+
+## Requirements & tooling
+
+Python **3.11+** (3.9/3.10 are end-of-life). Managed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync                                   # create the venv (pinned to 3.11 via .python-version)
+uv run python -m unittest discover -s tests
+```
+
+The SDK itself has no third-party dependencies — `uv` is just for the dev/test
+environment and interpreter pinning.

vellumcharter-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+# setuptools >= 77 supports the PEP 639 SPDX `license` string + license-files.
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vellumcharter"
+version = "0.1.0"
+description = "Thin, dependency-free server-side client for the Vellum entitlements + billing API"
+readme = "README.md"
+# 3.11 is the minimum supported runtime (3.9/3.10 are past end-of-life).
+requires-python = ">=3.11"
+license = "MIT"
+# Intentionally dependency-free — stdlib urllib + hmac only (mirrors the TS SDK).
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://vellumcharter.com"
+Repository = "https://github.com/tdesposito/Vellum"
+
+[tool.setuptools]
+packages = ["vellumcharter"]
+
+[tool.ruff]
+target-version = "py311"
+extend-exclude = [".venv"]
+
+[tool.ruff.lint]
+# Errors (E), pyflakes (F), import sorting (I). Modest on purpose — tighten later.
+select = ["E", "F", "I"]
+# Don't enforce line length on the existing (wider) code; adopt `ruff format` later
+# if a hard width is wanted.
+ignore = ["E501"]
+

vellumcharter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vellumcharter-0.1.0/vellumcharter/__init__.py

@@ -0,0 +1,24 @@
+"""vellumcharter — the Python SDK for the Vellum entitlements + billing API.
+A thin, dependency-free server-side client plus push-webhook signature verification."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .aio import AsyncVellumClient
+from .client import EntitlementSet, HttpResponse, Transport, VellumClient
+from .errors import VellumApiError, VellumAuthError, VellumError, VellumSignatureError
+from .push import verify_push_signature
+
+__all__ = [
+    "VellumClient",
+    "AsyncVellumClient",
+    "EntitlementSet",
+    "HttpResponse",
+    "Transport",
+    "VellumError",
+    "VellumAuthError",
+    "VellumApiError",
+    "VellumSignatureError",
+    "verify_push_signature",
+]

vellumcharter-0.1.0/vellumcharter/aio.py

@@ -0,0 +1,215 @@
+"""Async client for the Vellum entitlements + billing API.
+
+AsyncVellumClient is a thin wrapper over the synchronous VellumClient: every
+network call is delegated to a worker thread via asyncio.to_thread, so it reuses
+all of the sync client's logic (URL building, x-api-key, error mapping, TTL
+cache) and keeps the SDK dependency-free. Server-side only — it holds a secret
+API key.
+
+This is "async-compatible" rather than single-socket async IO (each call hops to
+a thread); for server-side entitlement checks that is the right trade-off. The
+cache is shared with the inner sync client; under the GIL its dict ops are
+atomic, so concurrent access is safe — the only race is two concurrent misses
+for the same customer both fetching (a harmless duplicate request).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TTL_MS,
+    EntitlementSet,
+    Transport,
+    VellumClient,
+)
+
+__all__ = ["AsyncVellumClient"]
+
+
+class AsyncVellumClient:
+    """Async wrapper over :class:`VellumClient`. Same constructor; each network
+    method is awaitable and delegates to a worker thread."""
+
+    def __init__(
+        self,
+        api_key: str,
+        tenant_id: str,
+        base_url: str = DEFAULT_BASE_URL,
+        cache_ttl_ms: int = DEFAULT_TTL_MS,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self._sync = VellumClient(
+            api_key=api_key,
+            tenant_id=tenant_id,
+            base_url=base_url,
+            cache_ttl_ms=cache_ttl_ms,
+            transport=transport,
+        )
+
+    # --- entitlements (hot path) -------------------------------------------
+
+    async def get_entitlements(self, customer_id: str) -> EntitlementSet:
+        return await asyncio.to_thread(self._sync.get_entitlements, customer_id)
+
+    async def can(self, customer_id: str, module_id: str) -> bool:
+        return await asyncio.to_thread(self._sync.can, customer_id, module_id)
+
+    def invalidate(self, customer_id: Optional[str] = None) -> None:
+        """Synchronous — only mutates the in-memory cache (no IO, no await)."""
+        self._sync.invalidate(customer_id)
+
+    # --- checkout / subscriptions ------------------------------------------
+
+    async def create_checkout(
+        self,
+        *,
+        account_id: str,
+        customer_id: str,
+        plan_id: str,
+        plan_version: int,
+        success_url: str,
+        cancel_url: str,
+        seats: int = 1,
+    ) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.create_checkout(
+                account_id=account_id,
+                customer_id=customer_id,
+                plan_id=plan_id,
+                plan_version=plan_version,
+                success_url=success_url,
+                cancel_url=cancel_url,
+                seats=seats,
+            )
+        )
+
+    async def create_setup_checkout(
+        self, *, account_id: str, success_url: str, cancel_url: str
+    ) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.create_setup_checkout(
+                account_id=account_id, success_url=success_url, cancel_url=cancel_url
+            )
+        )
+
+    async def create_subscription(
+        self,
+        *,
+        account_id: str,
+        customer_id: str,
+        plan_id: str,
+        plan_version: int,
+        seats: int = 1,
+    ) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.create_subscription(
+                account_id=account_id,
+                customer_id=customer_id,
+                plan_id=plan_id,
+                plan_version=plan_version,
+                seats=seats,
+            )
+        )
+
+    async def cancel_subscription(
+        self, *, account_id: str, customer_id: str, at_period_end: bool = False
+    ) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.cancel_subscription(
+                account_id=account_id, customer_id=customer_id, at_period_end=at_period_end
+            )
+        )
+
+    async def get_subscription(self, *, account_id: str, customer_id: str) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.get_subscription(account_id=account_id, customer_id=customer_id)
+        )
+
+    # --- provisioning -------------------------------------------------------
+
+    async def create_account(
+        self,
+        *,
+        account_id: str,
+        name: Optional[str] = None,
+        email: Optional[str] = None,
+        stripe_customer_id: Optional[str] = None,
+        create_stripe_customer: bool = False,
+    ) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.create_account(
+                account_id=account_id,
+                name=name,
+                email=email,
+                stripe_customer_id=stripe_customer_id,
+                create_stripe_customer=create_stripe_customer,
+            )
+        )
+
+    async def create_customer(
+        self, *, account_id: str, customer_id: str, email: Optional[str] = None
+    ) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.create_customer(
+                account_id=account_id, customer_id=customer_id, email=email
+            )
+        )
+
+    async def set_account_status(self, *, account_id: str, status: str) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.set_account_status(account_id=account_id, status=status)
+        )
+
+    async def set_customer_status(
+        self, *, account_id: str, customer_id: str, status: str
+    ) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.set_customer_status(
+                account_id=account_id, customer_id=customer_id, status=status
+            )
+        )
+
+    # --- billing facade -----------------------------------------------------
+
+    async def list_payment_methods(self, *, account_id: str) -> List[Dict[str, Any]]:
+        return await asyncio.to_thread(
+            lambda: self._sync.list_payment_methods(account_id=account_id)
+        )
+
+    async def set_default_payment_method(
+        self, *, account_id: str, method_id: str
+    ) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.set_default_payment_method(
+                account_id=account_id, method_id=method_id
+            )
+        )
+
+    async def remove_payment_method(self, *, account_id: str, method_id: str) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.remove_payment_method(account_id=account_id, method_id=method_id)
+        )
+
+    async def set_subscription_payment_method(
+        self, *, account_id: str, customer_id: str, method_id: str
+    ) -> Dict[str, Any]:
+        return await asyncio.to_thread(
+            lambda: self._sync.set_subscription_payment_method(
+                account_id=account_id, customer_id=customer_id, method_id=method_id
+            )
+        )
+
+    async def list_invoices(
+        self, *, account_id: str, customer_id: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        return await asyncio.to_thread(
+            lambda: self._sync.list_invoices(account_id=account_id, customer_id=customer_id)
+        )
+
+    async def invoice_pdf_url(self, *, account_id: str, invoice_id: str) -> str:
+        return await asyncio.to_thread(
+            lambda: self._sync.invoice_pdf_url(account_id=account_id, invoice_id=invoice_id)
+        )

vellumcharter-0.1.0/vellumcharter/client.py

@@ -0,0 +1,346 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+from urllib.parse import quote
+
+from .errors import VellumApiError, VellumAuthError, VellumError
+
+DEFAULT_TTL_MS = 30_000
+DEFAULT_BASE_URL = "https://api.vellumcharter.com"
+_REDIRECT_CODES = {301, 302, 303, 307, 308}
+
+
+@dataclass
+class HttpResponse:
+    status: int
+    headers: Dict[str, str]
+    body: str
+
+
+# (method, url, headers, body) -> HttpResponse. Injectable for tests; the default
+# uses urllib and does NOT follow redirects (so invoice_pdf can read Location).
+Transport = Callable[[str, str, Dict[str, str], Optional[str]], HttpResponse]
+
+
+@dataclass
+class EntitlementSet:
+    """Ergonomic view over a customer's resolved entitlements. A customer with no
+    record (404) yields an empty, no-access set, so gating never needs a null
+    check: ``set.has('imports')`` is just False."""
+
+    data: Dict[str, Any] = field(default_factory=dict)
+    found: bool = False
+
+    @property
+    def status(self) -> Optional[str]:
+        return self.data.get("status")
+
+    def is_active(self) -> bool:
+        return self.status in ("active", "trialing")
+
+    def has(self, module_id: str) -> bool:
+        return module_id in self.data.get("modules", [])
+
+    def config(self, key: str, default: Any = None) -> Any:
+        return self.data.get("config", {}).get(key, default)
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D401, ANN001
+        return None  # surface the 3xx instead of following it
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+
+def _default_transport(
+    method: str, url: str, headers: Dict[str, str], body: Optional[str]
+) -> HttpResponse:
+    req = urllib.request.Request(
+        url, data=body.encode() if body is not None else None, method=method, headers=headers
+    )
+    try:
+        resp = _opener.open(req, timeout=15)
+        return HttpResponse(resp.status, _lower(resp.headers.items()), resp.read().decode())
+    except urllib.error.HTTPError as exc:
+        # Non-2xx (and our intentionally-unfollowed 3xx) land here.
+        raw = exc.read().decode() if exc.fp else ""
+        return HttpResponse(exc.code, _lower((exc.headers or {}).items()), raw)
+
+
+def _lower(items) -> Dict[str, str]:  # noqa: ANN001
+    return {k.lower(): v for k, v in items}
+
+
+class VellumClient:
+    """Thin, dependency-free HTTP client for consuming apps (server-side — it
+    holds a secret API key). Wraps the entitlements read, checkout/subscribe,
+    billing, and provisioning endpoints, adds the x-api-key header, and caches
+    reads with a short TTL (the pull-first model)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        tenant_id: str,
+        base_url: str = DEFAULT_BASE_URL,
+        cache_ttl_ms: int = DEFAULT_TTL_MS,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        if not api_key or not tenant_id:
+            raise VellumError("api_key and tenant_id are required")
+        self._base = base_url.rstrip("/")
+        self._api_key = api_key
+        self._tenant = tenant_id
+        self._ttl_ms = cache_ttl_ms
+        self._transport = transport or _default_transport
+        self._cache: Dict[str, Any] = {}
+
+    # --- entitlements (hot path) -------------------------------------------
+
+    def get_entitlements(self, customer_id: str) -> EntitlementSet:
+        import time
+
+        cached = self._cache.get(customer_id)
+        if cached and cached["expires_at"] > time.time():
+            return cached["set"]
+
+        resp = self._request(
+            "GET", f"/tenants/{self._t}/customers/{quote(customer_id)}/entitlements"
+        )
+        if resp.status == 404:
+            result = EntitlementSet({}, False)
+        else:
+            result = EntitlementSet(self._parse(resp), True)
+
+        if self._ttl_ms > 0:
+            self._cache[customer_id] = {"set": result, "expires_at": time.time() + self._ttl_ms / 1000}
+        return result
+
+    def can(self, customer_id: str, module_id: str) -> bool:
+        return self.get_entitlements(customer_id).has(module_id)
+
+    def invalidate(self, customer_id: Optional[str] = None) -> None:
+        if customer_id is None:
+            self._cache.clear()
+        else:
+            self._cache.pop(customer_id, None)
+
+    # --- checkout / subscriptions ------------------------------------------
+
+    def create_checkout(
+        self,
+        *,
+        account_id: str,
+        customer_id: str,
+        plan_id: str,
+        plan_version: int,
+        success_url: str,
+        cancel_url: str,
+        seats: int = 1,
+    ) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "POST",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/checkout",
+                body={
+                    "customerId": customer_id,
+                    "planId": plan_id,
+                    "planVersion": plan_version,
+                    "seats": seats,
+                    "successUrl": success_url,
+                    "cancelUrl": cancel_url,
+                },
+            )
+        )
+
+    def create_setup_checkout(
+        self, *, account_id: str, success_url: str, cancel_url: str
+    ) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "POST",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/billing/setup-checkout",
+                body={"successUrl": success_url, "cancelUrl": cancel_url},
+            )
+        )
+
+    def create_subscription(
+        self,
+        *,
+        account_id: str,
+        customer_id: str,
+        plan_id: str,
+        plan_version: int,
+        seats: int = 1,
+    ) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "POST",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/customers/{quote(customer_id)}/subscribe",
+                body={"planId": plan_id, "planVersion": plan_version, "seats": seats},
+            )
+        )
+
+    def cancel_subscription(
+        self, *, account_id: str, customer_id: str, at_period_end: bool = False
+    ) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "DELETE",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/customers/{quote(customer_id)}/subscription",
+                query={"atPeriodEnd": "true"} if at_period_end else None,
+            )
+        )
+
+    def get_subscription(self, *, account_id: str, customer_id: str) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "GET",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/customers/{quote(customer_id)}/subscription",
+            )
+        )
+
+    # --- provisioning -------------------------------------------------------
+
+    def create_account(
+        self,
+        *,
+        account_id: str,
+        name: Optional[str] = None,
+        email: Optional[str] = None,
+        stripe_customer_id: Optional[str] = None,
+        create_stripe_customer: bool = False,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"accountId": account_id}
+        if name is not None:
+            body["name"] = name
+        if email is not None:
+            body["email"] = email
+        if stripe_customer_id is not None:
+            body["stripeCustomerId"] = stripe_customer_id
+        if create_stripe_customer:
+            body["createStripeCustomer"] = True
+        return self._parse(self._request("POST", f"/tenants/{self._t}/accounts", body=body))
+
+    def create_customer(
+        self, *, account_id: str, customer_id: str, email: Optional[str] = None
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"customerId": customer_id}
+        if email is not None:
+            body["email"] = email
+        return self._parse(
+            self._request(
+                "POST", f"/tenants/{self._t}/accounts/{quote(account_id)}/customers", body=body
+            )
+        )
+
+    def set_account_status(self, *, account_id: str, status: str) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "PATCH", f"/tenants/{self._t}/accounts/{quote(account_id)}", body={"status": status}
+            )
+        )
+
+    def set_customer_status(
+        self, *, account_id: str, customer_id: str, status: str
+    ) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "PATCH",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/customers/{quote(customer_id)}",
+                body={"status": status},
+            )
+        )
+
+    # --- billing facade -----------------------------------------------------
+
+    def list_payment_methods(self, *, account_id: str) -> List[Dict[str, Any]]:
+        return self._parse(
+            self._request("GET", f"/tenants/{self._t}/accounts/{quote(account_id)}/payment-methods")
+        )["methods"]
+
+    def set_default_payment_method(self, *, account_id: str, method_id: str) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "PATCH",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/payment-methods/{quote(method_id)}",
+            )
+        )
+
+    def remove_payment_method(self, *, account_id: str, method_id: str) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "DELETE",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/payment-methods/{quote(method_id)}",
+            )
+        )
+
+    def set_subscription_payment_method(
+        self, *, account_id: str, customer_id: str, method_id: str
+    ) -> Dict[str, Any]:
+        return self._parse(
+            self._request(
+                "PATCH",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/customers/{quote(customer_id)}/payment-method",
+                body={"methodId": method_id},
+            )
+        )
+
+    def list_invoices(
+        self, *, account_id: str, customer_id: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        return self._parse(
+            self._request(
+                "GET",
+                f"/tenants/{self._t}/accounts/{quote(account_id)}/invoices",
+                query={"customerId": customer_id} if customer_id else None,
+            )
+        )["invoices"]
+
+    def invoice_pdf_url(self, *, account_id: str, invoice_id: str) -> str:
+        resp = self._request(
+            "GET",
+            f"/tenants/{self._t}/accounts/{quote(account_id)}/invoices/{quote(invoice_id)}/pdf",
+        )
+        if resp.status in _REDIRECT_CODES:
+            location = resp.headers.get("location")
+            if location:
+                return location
+        self._parse(resp)  # raises on a non-2xx that wasn't a redirect
+        raise VellumApiError("invoice has no PDF location", resp.status, resp.body)
+
+    # --- internals ----------------------------------------------------------
+
+    @property
+    def _t(self) -> str:
+        return quote(self._tenant)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, str]] = None,
+    ) -> HttpResponse:
+        url = self._base + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        headers = {"x-api-key": self._api_key}
+        payload: Optional[str] = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            payload = json.dumps(body)
+        return self._transport(method, url, headers, payload)
+
+    def _parse(self, resp: HttpResponse) -> Any:
+        if resp.status in (401, 403):
+            raise VellumAuthError(f"Vellum auth failed ({resp.status})")
+        if not 200 <= resp.status < 300:
+            raise VellumApiError(f"Vellum API error ({resp.status})", resp.status, resp.body)
+        return json.loads(resp.body)

vellumcharter-0.1.0/vellumcharter/errors.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+
+class VellumError(Exception):
+    """Base class for all Vellum SDK errors."""
+
+
+class VellumAuthError(VellumError):
+    """The API key was rejected (HTTP 401/403)."""
+
+
+class VellumApiError(VellumError):
+    """A non-2xx response that isn't an auth failure."""
+
+    def __init__(self, message: str, status: int, body: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class VellumSignatureError(VellumError):
+    """A push webhook signature failed verification."""

vellumcharter-0.1.0/vellumcharter/push.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Union
+
+from .errors import VellumSignatureError
+
+
+def verify_push_signature(
+    payload: Union[str, bytes, bytearray],
+    header: str,
+    secret: str,
+    tolerance_s: int = 300,
+) -> Dict[str, Any]:
+    """Verify a Vellum push webhook and return the parsed event.
+
+    The signature header is ``t=<unix>,v1=<hex>`` where the hex is
+    ``HMAC-SHA256(secret, "<t>.<raw-body>")`` — mirroring lib/notify.ts on the
+    server. Pass the *raw* request body (bytes or str), not a re-serialized dict,
+    so the bytes match what was signed. Raises VellumSignatureError on any
+    mismatch, a malformed header, or a timestamp outside ``tolerance_s`` seconds
+    (set ``tolerance_s=0`` to skip the freshness check).
+    """
+    body = payload.decode() if isinstance(payload, (bytes, bytearray)) else payload
+
+    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
+    timestamp, signature = parts.get("t"), parts.get("v1")
+    if not timestamp or not signature:
+        raise VellumSignatureError("malformed signature header")
+
+    try:
+        ts = int(timestamp)
+    except ValueError as exc:
+        raise VellumSignatureError("invalid signature timestamp") from exc
+
+    if tolerance_s and abs(time.time() - ts) > tolerance_s:
+        raise VellumSignatureError("signature timestamp outside tolerance")
+
+    expected = hmac.new(secret.encode(), f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, signature):
+        raise VellumSignatureError("signature mismatch")
+
+    return json.loads(body)

vellumcharter-0.1.0/vellumcharter.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: vellumcharter
+Version: 0.1.0
+Summary: Thin, dependency-free server-side client for the Vellum entitlements + billing API
+License-Expression: MIT
+Project-URL: Homepage, https://vellumcharter.com
+Project-URL: Repository, https://github.com/tdesposito/Vellum
+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 (Python SDK)
+
+A thin, **dependency-free** (stdlib `urllib` + `hmac`) server-side client for the
+Vellum entitlements + billing API. The Python counterpart to `sdks/js/` (TypeScript);
+built for Python consumers such as SAM2-SalesImport. **Server-side only** — it
+holds a secret API key.
+
+```python
+from vellumcharter import VellumClient, verify_push_signature
+
+vellum = VellumClient(
+    api_key="vlm_sam.xxxxx",   # from SSM, never shipped to a browser
+    tenant_id="sam",
+    # base_url defaults to https://api.vellumcharter.com; override for tests/staging.
+)
+
+# Gate a feature (pull-first; 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)
+```
+
+## Async
+
+`AsyncVellumClient` is the awaitable counterpart — same constructor and methods,
+each `await`-ed. It wraps the sync client on a worker thread (`asyncio.to_thread`),
+so the SDK stays dependency-free. Use it from async frameworks (e.g. FastAPI):
+
+```python
+from vellumcharter import AsyncVellumClient
+
+vellum = AsyncVellumClient(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)
+```
+
+It is "async-compatible" (each call runs in a worker thread), not single-socket
+async IO — the right trade-off for server-side entitlement checks while keeping
+zero dependencies.
+
+## What it covers
+
+- **Entitlements:** `get_entitlements`, `can`, opt-in TTL cache + `invalidate`.
+  A 404 returns an empty `EntitlementSet` (no exception), so gating never needs a
+  null check.
+- **Checkout / subscriptions:** `create_checkout`, `create_setup_checkout`
+  (payment method, no charge), `create_subscription` (server-side trial),
+  `cancel_subscription`, `get_subscription`.
+- **Provisioning:** `create_account` (adopt or create the Stripe customer),
+  `create_customer`, `set_account_status`, `set_customer_status`.
+- **Billing facade:** `list_payment_methods`, `set_default_payment_method`,
+  `remove_payment_method`, `set_subscription_payment_method`, `list_invoices`,
+  `invoice_pdf_url` (returns Stripe's hosted PDF URL).
+- **Push verification:** `verify_push_signature(raw_body, header, secret)` for the
+  consumer's `/webhooks/vellum` endpoint (mirrors `api/src/lib/notify.ts`).
+
+`VellumAuthError` is raised on 401/403; `VellumApiError` (with `.status`/`.body`)
+on other non-2xx; `VellumSignatureError` on a bad push signature.
+
+## Auth & errors
+
+The API key is sent as `x-api-key` on every request. Keep it server-side.
+
+## Requirements & tooling
+
+Python **3.11+** (3.9/3.10 are end-of-life). Managed with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync                                   # create the venv (pinned to 3.11 via .python-version)
+uv run python -m unittest discover -s tests
+```
+
+The SDK itself has no third-party dependencies — `uv` is just for the dev/test
+environment and interpreter pinning.

vellumcharter-0.1.0/vellumcharter.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+vellumcharter/__init__.py
+vellumcharter/aio.py
+vellumcharter/client.py
+vellumcharter/errors.py
+vellumcharter/push.py
+vellumcharter.egg-info/PKG-INFO
+vellumcharter.egg-info/SOURCES.txt
+vellumcharter.egg-info/dependency_links.txt
+vellumcharter.egg-info/top_level.txt

vellumcharter-0.1.0/vellumcharter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vellumcharter-0.1.0/vellumcharter.egg-info/top_level.txt

@@ -0,0 +1 @@
+vellumcharter