@vellumcharter/sdk 0.6.0

package/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.

package/README.md

@@ -0,0 +1,137 @@
+# @vellumcharter/sdk
+
+Thin, dependency-free TypeScript client for the VellumCharter entitlements +
+billing API. **Server-side only** — it carries a secret API key; never ship it to
+a browser.
+
+## Install
+
+```bash
+npm install @vellumcharter/sdk
+```
+
+Requires Node 18+ (uses the global `fetch`).
+
+## Usage
+
+```ts
+import { VellumCharterClient } from '@vellumcharter/sdk';
+
+const vellum = new VellumCharterClient({
+  apiKey: process.env.VELLUM_API_KEY!,    // vlm_<tenantId>.<secret>
+  tenantId: 'sideproj1',
+  cacheTtlMs: 30_000,                     // optional (default 30s; 0 disables)
+  // baseUrl defaults to https://api.vellumcharter.com
+});
+
+// Gate a feature:
+if (await vellum.can('cust_123', 'exports')) {
+  // ...allow the export
+}
+
+// Or inspect the full set:
+const ent = await vellum.getEntitlements('cust_123');
+ent.isActive();                  // true for active/trialing
+ent.has('reports');              // boolean
+ent.config<number>('max_users'); // typed config read
+ent.found;                       // false when the customer has no record
+
+// Start a Checkout Session (returns the hosted checkout URL to redirect to):
+const { url } = await vellum.createCheckout({
+  accountId: 'acme',
+  planId: 'pro',
+  planVersion: 1,
+  seats: 3,
+  successUrl: 'https://app.example.com/billing/ok',
+  cancelUrl: 'https://app.example.com/billing/cancel',
+});
+
+// Drop a cached read once you know it changed:
+vellum.invalidate('cust_123');
+```
+
+Reads are cached with a short TTL (default 30s), and a customer with no
+entitlements returns an empty, no-access set rather than throwing — so `can()`
+and `has()` are always safe.
+
+## Billing facade
+
+Uncached pass-throughs to the billing endpoints (the payment platform still
+owns invoicing/proration/dunning). Shapes are typed (`SubscriptionView`,
+`PaymentMethod`, `Invoice`) in the server's camelCase / ISO-timestamp form:
+
+```ts
+const sub = await vellum.getSubscription('acme', 'unit_1');    // SubscriptionView
+const methods = await vellum.listPaymentMethods('acme');       // PaymentMethod[]
+const invoices = await vellum.listInvoices('acme', 'unit_1');  // Invoice[]
+const pdf = await vellum.invoicePdfUrl('acme', 'in_123');      // hosted PDF URL
+
+await vellum.setDefaultPaymentMethod('acme', 'pm_123');
+await vellum.setSubscriptionPaymentMethod('acme', 'unit_1', 'pm_123');
+await vellum.removePaymentMethod('acme', 'pm_123');
+await vellum.cancelSubscription('acme', 'unit_1', /* atPeriodEnd */ true);
+```
+
+## Provisioning & subscriptions
+
+Register accounts and customers, manage their status, and create subscriptions
+server-side (no hosted page; the account must have a saved card):
+
+```ts
+await vellum.createAccount({
+  accountId: 'acme',
+  email: 'billing@acme.test',
+  createBillingCustomer: true,
+});
+await vellum.createCustomer({ accountId: 'acme', customerId: 'unit_1', email: 'ada@acme.test' });
+await vellum.setAccountStatus('acme', 'suspended');
+await vellum.setCustomerStatus('acme', 'unit_1', 'disabled');
+
+// Capture a card without charging, then subscribe directly:
+const { url } = await vellum.createSetupCheckout({
+  accountId: 'acme',
+  successUrl: 'https://app.example.com/billing/ok',
+  cancelUrl: 'https://app.example.com/billing/cancel',
+});
+const { subscriptionId } = await vellum.createSubscription({
+  accountId: 'acme',
+  customerId: 'unit_1',
+  planId: 'pro',
+  planVersion: 1,
+  seats: 2,
+});
+```
+
+## Credits
+
+Prepaid, pay-as-you-go balances. `consumeCredits` is idempotent on your key and
+all-or-nothing — it throws `VellumCharterApiError` with `status === 409` on an
+insufficient balance (nothing is deducted):
+
+```ts
+const { url } = await vellum.createCreditCheckout({
+  accountId: 'acme',
+  customerId: 'unit_1',
+  creditTypeId: 'render_minutes',
+  packId: 'pack_1000',
+  quantity: 2,
+  successUrl: 'https://app.example.com/credits/ok',
+  cancelUrl: 'https://app.example.com/credits/cancel',
+});
+const credits = await vellum.listCredits('unit_1');                    // CreditBalance[]
+const bal = await vellum.getCreditBalance('unit_1', 'render_minutes'); // CreditBalance
+const r = await vellum.consumeCredits('unit_1', {
+  creditTypeId: 'render_minutes',
+  amount: 30,
+  idempotencyKey: 'render:job_42',
+});
+```
+
+## Errors
+
+`VellumCharterAuthError` on 401/403; `VellumCharterApiError` (with `status` and
+`body`) on other non-2xx responses.
+
+## API reference
+
+Full endpoint + webhook contract: https://api.vellumcharter.com/openapi.json

package/dist/index.d.ts

@@ -0,0 +1,244 @@
+export interface Entitlements {
+    accountId?: string;
+    planId?: string;
+    planVersion?: number;
+    status?: string;
+    currentPeriodEnd?: string;
+    modules: string[];
+    config: Record<string, unknown>;
+    billingSubscriptionId?: string;
+    updatedAt?: string;
+}
+export interface HttpResponse {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    /** Response headers; only needed to read `Location` on the invoice-PDF redirect. */
+    headers?: {
+        get(name: string): string | null;
+    };
+}
+export type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    redirect?: 'follow' | 'manual' | 'error';
+}) => Promise<HttpResponse>;
+export declare class VellumCharterError extends Error {
+}
+export declare class VellumCharterAuthError extends VellumCharterError {
+}
+export declare class VellumCharterApiError extends VellumCharterError {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+export declare class EntitlementSet {
+    readonly data: Entitlements;
+    readonly found: boolean;
+    constructor(data: Entitlements, found: boolean);
+    get status(): string | undefined;
+    isActive(): boolean;
+    has(moduleId: string): boolean;
+    config<T = unknown>(key: string): T | undefined;
+}
+export interface VellumCharterClientOptions {
+    apiKey: string;
+    tenantId: string;
+    /** API root. Defaults to the production VellumCharter stack; override for tests/staging. */
+    baseUrl?: string;
+    /** Read cache TTL in ms (default 30000). Set 0 to disable. */
+    cacheTtlMs?: number;
+    fetch?: FetchLike;
+}
+export interface CheckoutParams {
+    accountId: string;
+    customerId: string;
+    planId: string;
+    planVersion: number;
+    seats?: number;
+    successUrl: string;
+    cancelUrl: string;
+}
+export interface SubscribeParams {
+    accountId: string;
+    customerId: string;
+    planId: string;
+    planVersion: number;
+    seats?: number;
+}
+export interface SetupCheckoutParams {
+    accountId: string;
+    successUrl: string;
+    cancelUrl: string;
+}
+export interface CreateAccountParams {
+    accountId: string;
+    name?: string;
+    email?: string;
+    /** Adopt an existing billing customer (e.g. migrating live data). */
+    billingCustomerId?: string;
+    /** Create a new billing customer (ignored when billingCustomerId is given). */
+    createBillingCustomer?: boolean;
+}
+export interface CreateCustomerParams {
+    accountId: string;
+    customerId: string;
+    email?: string;
+}
+export interface CreditCheckoutParams {
+    accountId: string;
+    customerId: string;
+    creditTypeId: string;
+    packId: string;
+    /** How many packs to buy at once (default 1); grants grantQty × quantity. */
+    quantity?: number;
+    successUrl: string;
+    cancelUrl: string;
+}
+export interface CreditBalance {
+    creditTypeId: string;
+    balance: number;
+}
+export interface ConsumeResult {
+    creditTypeId: string;
+    consumed: number;
+    balance: number;
+    /** True when the idempotencyKey was already applied (no new deduction). */
+    duplicate: boolean;
+}
+export interface PaymentMethod {
+    id: string;
+    brand?: string;
+    last4?: string;
+    expMonth?: number;
+    expYear?: number;
+    /** Cardholder name from the billing details, when set. */
+    name?: string;
+    isDefault: boolean;
+}
+export interface Invoice {
+    id: string;
+    number: string | null;
+    status: string | null;
+    amountDue: number;
+    amountPaid: number;
+    subtotal: number;
+    total: number;
+    tax: number | null;
+    paid: boolean;
+    currency: string;
+    created: string;
+    hostedInvoiceUrl: string | null;
+    invoicePdf: string | null;
+}
+export interface SubscriptionView {
+    id: string;
+    status: string;
+    cancelAtPeriodEnd: boolean;
+    seats?: number;
+    /** Recurring price per seat in the smallest currency unit (e.g. cents). */
+    amount?: number;
+    currency?: string;
+    /** Billing interval of the recurring price, e.g. `month` or `year`. */
+    interval?: string;
+    currentPeriodStart?: string;
+    currentPeriodEnd?: string;
+    /** When the trial ends (ISO), if the subscription is trialing. */
+    trialEnd?: string;
+    /** When the subscription was canceled (ISO), if it has been. */
+    canceledAt?: string;
+    /** The subscription's default payment-method id, when one is set. */
+    defaultPaymentMethod?: string;
+}
+export declare class VellumCharterClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly tenantId;
+    private readonly ttl;
+    private readonly doFetch;
+    private readonly cache;
+    constructor(opts: VellumCharterClientOptions);
+    getEntitlements(customerId: string): Promise<EntitlementSet>;
+    /** Shorthand: does the customer currently have access to a module? */
+    can(customerId: string, moduleId: string): Promise<boolean>;
+    /** Drop a cached read (e.g. after a webhook tells you it changed). */
+    invalidate(customerId?: string): void;
+    createCheckout(params: CheckoutParams): Promise<{
+        url: string;
+    }>;
+    /** Subscribe a customer server-side (no hosted page; the account must have a saved card). */
+    createSubscription(params: SubscribeParams): Promise<{
+        subscriptionId: string;
+    }>;
+    /** Create a setup-mode Checkout session to capture or update a card (no charge). */
+    createSetupCheckout(params: SetupCheckoutParams): Promise<{
+        url: string;
+    }>;
+    /** Create a billing account; optionally create or adopt its billing customer. */
+    createAccount(params: CreateAccountParams): Promise<{
+        accountId: string;
+        billingCustomerId?: string;
+    }>;
+    /** Create a customer (member) under an account. */
+    createCustomer(params: CreateCustomerParams): Promise<{
+        customerId: string;
+    }>;
+    /** Set an account's operational status. */
+    setAccountStatus(accountId: string, status: string): Promise<{
+        accountId: string;
+        status: string;
+    }>;
+    /** Set a customer's operational status. */
+    setCustomerStatus(accountId: string, customerId: string, status: string): Promise<{
+        customerId: string;
+        status: string;
+    }>;
+    /** The customer's current subscription. */
+    getSubscription(accountId: string, customerId: string): Promise<SubscriptionView>;
+    /** Cancel a customer's subscription, immediately or at period end. */
+    cancelSubscription(accountId: string, customerId: string, atPeriodEnd?: boolean): Promise<{
+        canceled: string;
+        atPeriodEnd: boolean;
+    }>;
+    /** The account's saved card payment methods. */
+    listPaymentMethods(accountId: string): Promise<PaymentMethod[]>;
+    /** Make a payment method the account's default for future invoices. */
+    setDefaultPaymentMethod(accountId: string, methodId: string): Promise<{
+        default: string;
+    }>;
+    /** Detach a payment method from the account. */
+    removePaymentMethod(accountId: string, methodId: string): Promise<{
+        removed: string;
+    }>;
+    /** Override the default payment method for one customer's subscription. */
+    setSubscriptionPaymentMethod(accountId: string, customerId: string, methodId: string): Promise<{
+        subscription: string;
+        default: string;
+    }>;
+    /** Invoices for the account, or scoped to one customer's subscription. */
+    listInvoices(accountId: string, customerId?: string): Promise<Invoice[]>;
+    /** Resolve the hosted-PDF URL for an invoice (follows the 302 `Location`). */
+    invoicePdfUrl(accountId: string, invoiceId: string): Promise<string>;
+    /** Create a one-time Checkout session to buy a credit pack for a customer. */
+    createCreditCheckout(params: CreditCheckoutParams): Promise<{
+        url: string;
+    }>;
+    /** All of a customer's prepaid credit balances. */
+    listCredits(customerId: string): Promise<CreditBalance[]>;
+    /** One credit balance (0 if the customer has never bought this type). */
+    getCreditBalance(customerId: string, creditTypeId: string): Promise<CreditBalance>;
+    /**
+     * Consume credits, all-or-nothing. Pass a stable `idempotencyKey` (e.g. the
+     * game id) so a retry is a safe no-op (returns the already-applied balance with
+     * `duplicate: true`). Throws VellumCharterApiError with `status === 409` when
+     * the balance is insufficient (nothing is deducted).
+     */
+    consumeCredits(customerId: string, params: {
+        creditTypeId: string;
+        amount: number;
+        idempotencyKey: string;
+    }): Promise<ConsumeResult>;
+    private billingFetch;
+    private parse;
+}

package/dist/index.js

@@ -0,0 +1,257 @@
+"use strict";
+// Thin HTTP client for consuming apps (server-side — it holds a secret API key).
+// Wraps the entitlements read + checkout endpoints, adds the x-api-key header,
+// and caches reads with a short TTL (the docs' pull-first model; resolves Q3).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VellumCharterClient = exports.EntitlementSet = exports.VellumCharterApiError = exports.VellumCharterAuthError = exports.VellumCharterError = void 0;
+class VellumCharterError extends Error {
+}
+exports.VellumCharterError = VellumCharterError;
+class VellumCharterAuthError extends VellumCharterError {
+}
+exports.VellumCharterAuthError = VellumCharterAuthError;
+class VellumCharterApiError extends VellumCharterError {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.VellumCharterApiError = VellumCharterApiError;
+const ACCESS_STATUSES = new Set(['active', 'trialing']);
+// 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('exports')` is just false.
+class EntitlementSet {
+    data;
+    found;
+    constructor(data, found) {
+        this.data = data;
+        this.found = found;
+    }
+    get status() {
+        return this.data.status;
+    }
+    isActive() {
+        return this.data.status !== undefined && ACCESS_STATUSES.has(this.data.status);
+    }
+    has(moduleId) {
+        return this.data.modules.includes(moduleId);
+    }
+    config(key) {
+        return this.data.config[key];
+    }
+}
+exports.EntitlementSet = EntitlementSet;
+const DEFAULT_TTL_MS = 30_000;
+const DEFAULT_BASE_URL = 'https://api.vellumcharter.com';
+class VellumCharterClient {
+    baseUrl;
+    apiKey;
+    tenantId;
+    ttl;
+    doFetch;
+    cache = new Map();
+    constructor(opts) {
+        if (!opts.apiKey || !opts.tenantId) {
+            throw new VellumCharterError('apiKey and tenantId are required');
+        }
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.apiKey = opts.apiKey;
+        this.tenantId = opts.tenantId;
+        this.ttl = opts.cacheTtlMs ?? DEFAULT_TTL_MS;
+        this.doFetch =
+            opts.fetch ?? ((url, init) => fetch(url, init));
+    }
+    async getEntitlements(customerId) {
+        const cached = this.cache.get(customerId);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.set;
+        const url = `${this.baseUrl}/tenants/${enc(this.tenantId)}/customers/${enc(customerId)}/entitlements`;
+        const res = await this.doFetch(url, { headers: { 'x-api-key': this.apiKey } });
+        let set;
+        if (res.status === 404) {
+            set = new EntitlementSet({ modules: [], config: {} }, false);
+        }
+        else {
+            set = new EntitlementSet(await this.parse(res), true);
+        }
+        if (this.ttl > 0)
+            this.cache.set(customerId, { set, expiresAt: Date.now() + this.ttl });
+        return set;
+    }
+    /** Shorthand: does the customer currently have access to a module? */
+    async can(customerId, moduleId) {
+        return (await this.getEntitlements(customerId)).has(moduleId);
+    }
+    /** Drop a cached read (e.g. after a webhook tells you it changed). */
+    invalidate(customerId) {
+        if (customerId)
+            this.cache.delete(customerId);
+        else
+            this.cache.clear();
+    }
+    async createCheckout(params) {
+        const { accountId, ...body } = params;
+        const url = `${this.baseUrl}/tenants/${enc(this.tenantId)}/accounts/${enc(accountId)}/checkout`;
+        const res = await this.doFetch(url, {
+            method: 'POST',
+            headers: { 'x-api-key': this.apiKey, 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        return this.parse(res);
+    }
+    /** Subscribe a customer server-side (no hosted page; the account must have a saved card). */
+    async createSubscription(params) {
+        const { accountId, customerId, ...body } = params;
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/customers/${enc(customerId)}/subscribe`, { method: 'POST', body: JSON.stringify(body) });
+        return this.parse(res);
+    }
+    /** Create a setup-mode Checkout session to capture or update a card (no charge). */
+    async createSetupCheckout(params) {
+        const { accountId, ...body } = params;
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/billing/setup-checkout`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return this.parse(res);
+    }
+    // --- provisioning ---------------------------------------------------------
+    // Register accounts (orgs) and customers (members) and manage their lifecycle
+    // status. Create the account first, then its customers, then subscribe.
+    /** Create a billing account; optionally create or adopt its billing customer. */
+    async createAccount(params) {
+        const res = await this.billingFetch('/accounts', {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+        return this.parse(res);
+    }
+    /** Create a customer (member) under an account. */
+    async createCustomer(params) {
+        const { accountId, ...body } = params;
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/customers`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return this.parse(res);
+    }
+    /** Set an account's operational status. */
+    async setAccountStatus(accountId, status) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}`, {
+            method: 'PATCH',
+            body: JSON.stringify({ status }),
+        });
+        return this.parse(res);
+    }
+    /** Set a customer's operational status. */
+    async setCustomerStatus(accountId, customerId, status) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/customers/${enc(customerId)}`, { method: 'PATCH', body: JSON.stringify({ status }) });
+        return this.parse(res);
+    }
+    // --- billing facade -------------------------------------------------------
+    // Uncached pass-throughs to the billing endpoints (unlike getEntitlements).
+    // Shapes mirror the server Views; Stripe still owns invoicing/proration/dunning.
+    /** The customer's current subscription. */
+    async getSubscription(accountId, customerId) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/customers/${enc(customerId)}/subscription`);
+        return this.parse(res);
+    }
+    /** Cancel a customer's subscription, immediately or at period end. */
+    async cancelSubscription(accountId, customerId, atPeriodEnd = false) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/customers/${enc(customerId)}/subscription${atPeriodEnd ? '?atPeriodEnd=true' : ''}`, { method: 'DELETE' });
+        return this.parse(res);
+    }
+    /** The account's saved card payment methods. */
+    async listPaymentMethods(accountId) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/payment-methods`);
+        return (await this.parse(res)).methods;
+    }
+    /** Make a payment method the account's default for future invoices. */
+    async setDefaultPaymentMethod(accountId, methodId) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/payment-methods/${enc(methodId)}`, { method: 'PATCH' });
+        return this.parse(res);
+    }
+    /** Detach a payment method from the account. */
+    async removePaymentMethod(accountId, methodId) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/payment-methods/${enc(methodId)}`, { method: 'DELETE' });
+        return this.parse(res);
+    }
+    /** Override the default payment method for one customer's subscription. */
+    async setSubscriptionPaymentMethod(accountId, customerId, methodId) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/customers/${enc(customerId)}/payment-method`, { method: 'PATCH', body: JSON.stringify({ methodId }) });
+        return this.parse(res);
+    }
+    /** Invoices for the account, or scoped to one customer's subscription. */
+    async listInvoices(accountId, customerId) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/invoices${customerId ? `?customerId=${enc(customerId)}` : ''}`);
+        return (await this.parse(res)).invoices;
+    }
+    /** Resolve the hosted-PDF URL for an invoice (follows the 302 `Location`). */
+    async invoicePdfUrl(accountId, invoiceId) {
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/invoices/${enc(invoiceId)}/pdf`, { redirect: 'manual' });
+        if (res.status === 401 || res.status === 403) {
+            throw new VellumCharterAuthError(`VellumCharter auth failed (${res.status})`);
+        }
+        const location = res.headers?.get('location');
+        if (location)
+            return location;
+        throw new VellumCharterApiError(`VellumCharter API error (${res.status})`, res.status, await res.text());
+    }
+    // --- credits --------------------------------------------------------------
+    // Prepaid one-time-use credits. Uncached (a balance changes out-of-band via
+    // purchase/consume, unlike getEntitlements). consume is idempotent on the
+    // caller-supplied key and all-or-nothing.
+    /** Create a one-time Checkout session to buy a credit pack for a customer. */
+    async createCreditCheckout(params) {
+        const { accountId, ...body } = params;
+        const res = await this.billingFetch(`/accounts/${enc(accountId)}/credit-checkout`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return this.parse(res);
+    }
+    /** All of a customer's prepaid credit balances. */
+    async listCredits(customerId) {
+        const res = await this.billingFetch(`/customers/${enc(customerId)}/credits`);
+        return (await this.parse(res)).credits;
+    }
+    /** One credit balance (0 if the customer has never bought this type). */
+    async getCreditBalance(customerId, creditTypeId) {
+        const res = await this.billingFetch(`/customers/${enc(customerId)}/credits/${enc(creditTypeId)}`);
+        return this.parse(res);
+    }
+    /**
+     * Consume credits, all-or-nothing. Pass a stable `idempotencyKey` (e.g. the
+     * game id) so a retry is a safe no-op (returns the already-applied balance with
+     * `duplicate: true`). Throws VellumCharterApiError with `status === 409` when
+     * the balance is insufficient (nothing is deducted).
+     */
+    async consumeCredits(customerId, params) {
+        const { creditTypeId, ...body } = params;
+        const res = await this.billingFetch(`/customers/${enc(customerId)}/credits/${enc(creditTypeId)}/consume`, { method: 'POST', body: JSON.stringify(body) });
+        return this.parse(res);
+    }
+    billingFetch(path, init) {
+        const headers = { 'x-api-key': this.apiKey };
+        if (init?.body)
+            headers['content-type'] = 'application/json';
+        return this.doFetch(`${this.baseUrl}/tenants/${enc(this.tenantId)}${path}`, {
+            ...init,
+            headers,
+        });
+    }
+    async parse(res) {
+        if (res.status === 401 || res.status === 403) {
+            throw new VellumCharterAuthError(`VellumCharter auth failed (${res.status})`);
+        }
+        const text = await res.text();
+        if (!res.ok)
+            throw new VellumCharterApiError(`VellumCharter API error (${res.status})`, res.status, text);
+        return JSON.parse(text);
+    }
+}
+exports.VellumCharterClient = VellumCharterClient;
+const enc = encodeURIComponent;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@vellumcharter/sdk",
+  "version": "0.6.0",
+  "description": "Thin HTTP client for the VellumCharter entitlements + billing API",
+  "license": "MIT",
+  "author": "Todd Esposito",
+  "homepage": "https://vellumcharter.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tdesposito/VellumCharter.git",
+    "directory": "sdks/js"
+  },
+  "keywords": ["vellum", "entitlements", "billing", "subscriptions", "saas"],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --require ts-node/register --test test/*.test.ts",
+    "example": "ts-node examples/quickstart.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "ts-node": "^10",
+    "typescript": "^5"
+  }
+}