@shaferllc/keel 0.78.2 → 0.80.0

package/dist/billing/drivers/stripe.js

@@ -0,0 +1,278 @@
+/**
+ * The Stripe gateway. Talks to the Stripe REST API directly with `fetch` —
+ * form-encoded bodies, Bearer auth, no SDK — matching how the rest of Keel makes
+ * outbound calls. Everything is mapped to/from the gateway-neutral DTOs so the
+ * layers above never see a Stripe object.
+ *
+ * Amounts are already in the smallest currency unit; Stripe's `trial_end` is a
+ * Unix timestamp; webhook signatures are the `t`/`v1` scheme over the raw body.
+ */
+import { hmacSha256Hex, constantTimeEqual } from "../crypto.js";
+import { BillingError } from "../gateway.js";
+const API = "https://api.stripe.com/v1";
+/** Flatten nested objects/arrays into Stripe's `a[b][0][c]=v` form encoding. */
+function encodeForm(params, form = new URLSearchParams(), prefix = "") {
+    for (const [k, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        const key = prefix ? `${prefix}[${k}]` : k;
+        if (Array.isArray(value)) {
+            value.forEach((item, i) => {
+                if (item !== null && typeof item === "object") {
+                    encodeForm(item, form, `${key}[${i}]`);
+                }
+                else {
+                    form.append(`${key}[${i}]`, String(item));
+                }
+            });
+        }
+        else if (typeof value === "object") {
+            encodeForm(value, form, key);
+        }
+        else {
+            form.append(key, String(value));
+        }
+    }
+    return form;
+}
+function unix(date) {
+    return Math.floor(date.getTime() / 1000);
+}
+export class StripeGateway {
+    key;
+    name = "stripe";
+    constructor(key) {
+        this.key = key;
+    }
+    /* ------------------------------- transport ----------------------------- */
+    async call(method, path, params) {
+        if (!this.key)
+            throw new BillingError("Stripe secret key is not configured.", "stripe");
+        let url = `${API}${path}`;
+        const init = {
+            method,
+            headers: {
+                authorization: `Bearer ${this.key}`,
+                "content-type": "application/x-www-form-urlencoded",
+            },
+        };
+        if (params && method === "GET") {
+            url += `?${encodeForm(params).toString()}`;
+        }
+        else if (params) {
+            init.body = encodeForm(params);
+        }
+        const res = await fetch(url, init);
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            const err = (data.error ?? {});
+            throw new BillingError(err.message ?? `Stripe request failed (${res.status})`, "stripe");
+        }
+        return data;
+    }
+    /* ------------------------------- customers ----------------------------- */
+    async createCustomer(details) {
+        const c = await this.call("POST", "/customers", {
+            name: details.name,
+            email: details.email,
+            metadata: details.metadata,
+        });
+        return { id: String(c.id), email: c.email, name: c.name };
+    }
+    async updateCustomer(id, details) {
+        const c = await this.call("POST", `/customers/${id}`, {
+            name: details.name,
+            email: details.email,
+            metadata: details.metadata,
+        });
+        return { id: String(c.id), email: c.email, name: c.name };
+    }
+    /* ----------------------------- subscriptions --------------------------- */
+    async createSubscription(params) {
+        const sub = await this.call("POST", "/subscriptions", {
+            customer: params.customer,
+            items: params.items.map((i) => ({ price: i.price, quantity: i.quantity })),
+            trial_end: params.trialEnd ? unix(params.trialEnd) : undefined,
+            default_payment_method: params.paymentMethod,
+            metadata: params.metadata,
+            expand: ["items.data.price"],
+        });
+        return this.normalize(sub);
+    }
+    async swapSubscription(id, params) {
+        const current = await this.call("GET", `/subscriptions/${id}`, {
+            "expand": ["items.data.price"],
+        });
+        const currentItems = (current.items?.data ?? []).map((i) => String(i.id));
+        // Map new prices onto existing item slots; delete any leftover items.
+        const items = params.items.map((ref, i) => i < currentItems.length
+            ? { id: currentItems[i], price: ref.price, quantity: ref.quantity }
+            : { price: ref.price, quantity: ref.quantity });
+        for (let i = params.items.length; i < currentItems.length; i++) {
+            items.push({ id: currentItems[i], deleted: true });
+        }
+        const sub = await this.call("POST", `/subscriptions/${id}`, {
+            items,
+            proration_behavior: params.prorate === false ? "none" : "create_prorations",
+            expand: ["items.data.price"],
+        });
+        return this.normalize(sub);
+    }
+    async updateQuantity(id, quantity, opts) {
+        const current = await this.call("GET", `/subscriptions/${id}`);
+        const firstItem = current.items?.data?.[0];
+        if (!firstItem)
+            throw new BillingError("Subscription has no items to update.", "stripe");
+        const sub = await this.call("POST", `/subscriptions/${id}`, {
+            items: [{ id: String(firstItem.id), quantity }],
+            proration_behavior: opts?.prorate === false ? "none" : "create_prorations",
+            expand: ["items.data.price"],
+        });
+        return this.normalize(sub);
+    }
+    async cancelSubscription(id, params) {
+        if (params?.now) {
+            return this.normalize(await this.call("DELETE", `/subscriptions/${id}`));
+        }
+        return this.normalize(await this.call("POST", `/subscriptions/${id}`, {
+            cancel_at_period_end: true,
+            expand: ["items.data.price"],
+        }));
+    }
+    async resumeSubscription(id) {
+        return this.normalize(await this.call("POST", `/subscriptions/${id}`, {
+            cancel_at_period_end: false,
+            expand: ["items.data.price"],
+        }));
+    }
+    /* ------------------------------- charges ------------------------------- */
+    async charge(params) {
+        const intent = await this.call("POST", "/payment_intents", {
+            amount: params.amount,
+            currency: params.currency ?? "usd",
+            customer: params.customer,
+            payment_method: params.paymentMethod,
+            description: params.description,
+            metadata: params.metadata,
+            confirm: true,
+            off_session: true,
+        });
+        return {
+            id: String(intent.id),
+            status: String(intent.status),
+            amount: Number(intent.amount),
+            currency: String(intent.currency),
+        };
+    }
+    async refund(params) {
+        const key = params.charge.startsWith("pi_") ? "payment_intent" : "charge";
+        const refund = await this.call("POST", "/refunds", {
+            [key]: params.charge,
+            amount: params.amount,
+        });
+        return { id: String(refund.id), amount: Number(refund.amount ?? 0), status: String(refund.status) };
+    }
+    async listInvoices(customer) {
+        const res = await this.call("GET", "/invoices", { customer, limit: 100 });
+        const data = res.data ?? [];
+        return data.map((inv) => ({
+            id: String(inv.id),
+            number: inv.number ?? null,
+            total: Number(inv.total ?? 0),
+            currency: String(inv.currency ?? "usd"),
+            status: String(inv.status ?? ""),
+            date: inv.created ? new Date(Number(inv.created) * 1000) : null,
+            url: inv.hosted_invoice_url ?? null,
+        }));
+    }
+    /* ------------------------------ checkout ------------------------------- */
+    async createCheckoutSession(params) {
+        const session = await this.call("POST", "/checkout/sessions", {
+            mode: params.mode,
+            customer: params.customer,
+            line_items: params.items.map((i) => ({ price: i.price, quantity: i.quantity ?? 1 })),
+            success_url: params.successUrl,
+            cancel_url: params.cancelUrl,
+            allow_promotion_codes: params.allowPromotionCodes,
+            metadata: params.metadata,
+            subscription_data: params.mode === "subscription" && params.trialEnd
+                ? { trial_end: unix(params.trialEnd) }
+                : undefined,
+        });
+        return { id: String(session.id), url: session.url ?? null, raw: session };
+    }
+    /* ------------------- optional gateway capabilities -------------------- */
+    async createSetupIntent(customer) {
+        const intent = await this.call("POST", "/setup_intents", { customer });
+        return { id: String(intent.id), clientSecret: intent.client_secret ?? null };
+    }
+    async paymentMethods(customer) {
+        const res = await this.call("GET", "/payment_methods", { customer, type: "card" });
+        const data = res.data ?? [];
+        return data.map((pm) => {
+            const card = pm.card ?? {};
+            return {
+                id: String(pm.id),
+                type: String(pm.type ?? "card"),
+                last4: card.last4 ?? null,
+                brand: card.brand ?? null,
+            };
+        });
+    }
+    /* ------------------------------ webhooks ------------------------------- */
+    async verifyWebhook(rawBody, headers, secret) {
+        const header = headers("stripe-signature");
+        if (!header || !secret)
+            return null;
+        const parts = Object.fromEntries(header.split(",").map((p) => {
+            const [k, v] = p.split("=");
+            return [k?.trim(), v?.trim()];
+        }));
+        if (!parts.t || !parts.v1)
+            return null;
+        const expected = await hmacSha256Hex(secret, `${parts.t}.${rawBody}`);
+        if (!constantTimeEqual(parts.v1, expected))
+            return null;
+        const event = JSON.parse(rawBody);
+        const object = event.data?.object ?? {};
+        const subscription = event.type.startsWith("customer.subscription.")
+            ? this.normalize(object)
+            : undefined;
+        return {
+            id: event.id,
+            type: event.type,
+            payload: event,
+            subscription,
+            customer: subscription?.customer ?? object.customer,
+        };
+    }
+    /* ------------------------------ mapping -------------------------------- */
+    normalize(sub) {
+        const items = (sub.items?.data ?? []).map((i) => {
+            const price = i.price ?? {};
+            return {
+                id: String(i.id),
+                product: String(price.product ?? ""),
+                price: String(price.id ?? ""),
+                quantity: i.quantity != null ? Number(i.quantity) : undefined,
+            };
+        });
+        const cancelAtPeriodEnd = Boolean(sub.cancel_at_period_end);
+        const endsAt = cancelAtPeriodEnd
+            ? sub.current_period_end
+                ? new Date(Number(sub.current_period_end) * 1000)
+                : null
+            : sub.canceled_at
+                ? new Date(Number(sub.canceled_at) * 1000)
+                : null;
+        return {
+            id: String(sub.id),
+            status: String(sub.status ?? ""),
+            items,
+            quantity: sub.quantity != null ? Number(sub.quantity) : (items[0]?.quantity ?? null),
+            trialEndsAt: sub.trial_end ? new Date(Number(sub.trial_end) * 1000) : null,
+            endsAt,
+            customer: sub.customer ? String(sub.customer) : undefined,
+        };
+    }
+}

package/dist/billing/events.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Billing events. Augmenting Keel's `EventsList` makes these payloads typed
+ * wherever `emit`/`listen` are used — `listen("billing.subscription.updated",
+ * (e) => …)` gets a checked `e`. Apps subscribe to drive their own side effects
+ * (grant access, send a receipt) off a verified webhook.
+ */
+export interface SubscriptionEvent {
+    gateway: string;
+    subscriptionId: number | string;
+    providerId: string;
+    status: string;
+}
+export interface WebhookReceivedEvent {
+    gateway: string;
+    type: string;
+    id: string;
+}
+declare module "../core/events.js" {
+    interface EventsList {
+        "billing.webhook.received": WebhookReceivedEvent;
+        "billing.subscription.created": SubscriptionEvent;
+        "billing.subscription.updated": SubscriptionEvent;
+        "billing.subscription.deleted": SubscriptionEvent;
+    }
+}

package/dist/billing/events.js

@@ -0,0 +1,7 @@
+/**
+ * Billing events. Augmenting Keel's `EventsList` makes these payloads typed
+ * wherever `emit`/`listen` are used — `listen("billing.subscription.updated",
+ * (e) => …)` gets a checked `e`. Apps subscribe to drive their own side effects
+ * (grant access, send a receipt) off a verified webhook.
+ */
+export {};

package/dist/billing/gateway.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The gateway seam. `BillingGateway` is the one interface every payment
+ * provider implements — Stripe, Paddle, or the in-memory Fake used in tests.
+ * Everything above it (the `Billable` mixin, the `Subscription` model, the
+ * webhook handler) is written against these gateway-neutral DTOs and never
+ * touches a provider SDK.
+ *
+ * Money is always an integer in the smallest currency unit (cents), matching
+ * both Stripe and Paddle. Dates are real `Date`s. Provider-specific identifiers
+ * are opaque strings.
+ *
+ * Optional methods (`createSetupIntent`, `paymentMethods`) are capabilities not
+ * every gateway has — Paddle is hosted-checkout and never sees a raw card. The
+ * `Billable` mixin throws a `BillingError` when the active gateway lacks one.
+ */
+/** A lookup over request headers (Hono's `c.req.header` satisfies this). */
+export type HeaderBag = (name: string) => string | undefined | null;
+/** Customer details we sync up to the gateway. */
+export interface CustomerDetails {
+    name?: string;
+    email?: string;
+    metadata?: Record<string, string>;
+}
+export interface GatewayCustomer {
+    id: string;
+    email?: string;
+    name?: string;
+}
+/** A price and how many of it — one line of a subscription. */
+export interface PriceRef {
+    price: string;
+    quantity?: number;
+}
+export interface CreateSubscriptionParams {
+    customer: string;
+    items: PriceRef[];
+    /** Absolute trial end; omit for no trial. */
+    trialEnd?: Date;
+    /** A payment method to bill (Stripe pm id). */
+    paymentMethod?: string;
+    metadata?: Record<string, string>;
+}
+export interface GatewaySubscriptionItem {
+    id: string;
+    product: string;
+    price: string;
+    quantity?: number;
+}
+/** The normalized shape a gateway returns for any subscription read/write. */
+export interface GatewaySubscription {
+    id: string;
+    /** Provider status verbatim (`active`, `trialing`, `past_due`, `paused`, …). */
+    status: string;
+    items: GatewaySubscriptionItem[];
+    quantity?: number | null;
+    trialEndsAt?: Date | null;
+    /** When a cancel-at-period-end subscription actually ends (the grace period). */
+    endsAt?: Date | null;
+    /** The gateway customer this subscription belongs to, when known. */
+    customer?: string;
+}
+export interface SwapParams {
+    items: PriceRef[];
+    /** Prorate the change; gateways default to true. */
+    prorate?: boolean;
+}
+export interface CancelParams {
+    /** Cancel immediately instead of at period end. */
+    now?: boolean;
+}
+export interface ChargeParams {
+    customer: string;
+    amount: number;
+    currency?: string;
+    paymentMethod?: string;
+    description?: string;
+    metadata?: Record<string, string>;
+}
+export interface GatewayCharge {
+    id: string;
+    status: string;
+    amount: number;
+    currency: string;
+}
+export interface RefundParams {
+    /** The charge or payment-intent id to refund. */
+    charge: string;
+    /** Partial amount; omit to refund in full. */
+    amount?: number;
+}
+export interface GatewayRefund {
+    id: string;
+    amount: number;
+    status: string;
+}
+export interface GatewayInvoice {
+    id: string;
+    number?: string | null;
+    total: number;
+    currency: string;
+    status: string;
+    date?: Date | null;
+    /** Hosted invoice / PDF url when the gateway exposes one. */
+    url?: string | null;
+}
+export interface CheckoutParams {
+    mode: "subscription" | "payment";
+    customer?: string;
+    items: PriceRef[];
+    successUrl?: string;
+    cancelUrl?: string;
+    trialEnd?: Date;
+    metadata?: Record<string, string>;
+    allowPromotionCodes?: boolean;
+}
+/** A hosted checkout handle: a redirect `url` (Stripe) or a `clientToken` (Paddle). */
+export interface CheckoutSession {
+    id: string;
+    url?: string | null;
+    clientToken?: string | null;
+    raw?: unknown;
+}
+export interface SetupIntent {
+    id: string;
+    clientSecret: string | null;
+}
+export interface PaymentMethod {
+    id: string;
+    type: string;
+    last4?: string | null;
+    brand?: string | null;
+}
+/**
+ * A verified inbound webhook, normalized. When the event concerns a
+ * subscription the gateway extracts it into `subscription` so the webhook
+ * handler can upsert local state without any provider-specific parsing.
+ */
+export interface WebhookEvent {
+    id: string;
+    type: string;
+    payload: Record<string, unknown>;
+    subscription?: GatewaySubscription;
+    customer?: string;
+}
+export interface BillingGateway {
+    /** The registry name — "stripe", "paddle", "fake". */
+    readonly name: string;
+    createCustomer(details: CustomerDetails): Promise<GatewayCustomer>;
+    updateCustomer(id: string, details: CustomerDetails): Promise<GatewayCustomer>;
+    createSubscription(params: CreateSubscriptionParams): Promise<GatewaySubscription>;
+    swapSubscription(id: string, params: SwapParams): Promise<GatewaySubscription>;
+    updateQuantity(id: string, quantity: number, opts?: {
+        prorate?: boolean;
+    }): Promise<GatewaySubscription>;
+    cancelSubscription(id: string, params?: CancelParams): Promise<GatewaySubscription>;
+    resumeSubscription(id: string): Promise<GatewaySubscription>;
+    charge(params: ChargeParams): Promise<GatewayCharge>;
+    refund(params: RefundParams): Promise<GatewayRefund>;
+    listInvoices(customer: string): Promise<GatewayInvoice[]>;
+    createCheckoutSession(params: CheckoutParams): Promise<CheckoutSession>;
+    /** Verify a raw webhook body + headers against `secret`; null if unrecognized. */
+    verifyWebhook(rawBody: string, headers: HeaderBag, secret: string): Promise<WebhookEvent | null>;
+    createSetupIntent?(customer: string): Promise<SetupIntent>;
+    paymentMethods?(customer: string): Promise<PaymentMethod[]>;
+}
+/** Raised for gateway/config problems and unsupported-capability calls. */
+export declare class BillingError extends Error {
+    readonly gateway?: string | undefined;
+    constructor(message: string, gateway?: string | undefined);
+}

package/dist/billing/gateway.js

@@ -0,0 +1,24 @@
+/**
+ * The gateway seam. `BillingGateway` is the one interface every payment
+ * provider implements — Stripe, Paddle, or the in-memory Fake used in tests.
+ * Everything above it (the `Billable` mixin, the `Subscription` model, the
+ * webhook handler) is written against these gateway-neutral DTOs and never
+ * touches a provider SDK.
+ *
+ * Money is always an integer in the smallest currency unit (cents), matching
+ * both Stripe and Paddle. Dates are real `Date`s. Provider-specific identifiers
+ * are opaque strings.
+ *
+ * Optional methods (`createSetupIntent`, `paymentMethods`) are capabilities not
+ * every gateway has — Paddle is hosted-checkout and never sees a raw card. The
+ * `Billable` mixin throws a `BillingError` when the active gateway lacks one.
+ */
+/** Raised for gateway/config problems and unsupported-capability calls. */
+export class BillingError extends Error {
+    gateway;
+    constructor(message, gateway) {
+        super(message);
+        this.gateway = gateway;
+        this.name = "BillingError";
+    }
+}

package/dist/billing/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Keel Billing — public surface, imported from `@shaferllc/keel/billing`.
+ *
+ *   import { BillingServiceProvider, Billable } from "@shaferllc/keel/billing";
+ *   class User extends Billable(Model) { static table = "users"; }
+ */
+import "./events.js";
+export { BillingServiceProvider } from "./provider.js";
+export { Billable } from "./billable.js";
+export type { ChargeOptions, ProductCheckoutOptions } from "./billable.js";
+export { Subscription, toRefs } from "./subscription.js";
+export type { PriceArg } from "./subscription.js";
+export { SubscriptionItem } from "./subscription-item.js";
+export { SubscriptionBuilder } from "./builder.js";
+export type { BillableTarget, CheckoutOptions } from "./builder.js";
+export { BillingManager, billing, setBilling } from "./manager.js";
+export type { GatewayFactory } from "./manager.js";
+export { BillingError } from "./gateway.js";
+export type { BillingGateway, HeaderBag, CustomerDetails, GatewayCustomer, PriceRef, CreateSubscriptionParams, GatewaySubscription, GatewaySubscriptionItem, SwapParams, CancelParams, ChargeParams, GatewayCharge, RefundParams, GatewayRefund, GatewayInvoice, CheckoutParams, CheckoutSession, SetupIntent, PaymentMethod, WebhookEvent, } from "./gateway.js";
+export { registerDefaultGateways, StripeGateway, PaddleGateway, FakeGateway } from "./drivers/index.js";
+export type { FakeCall } from "./drivers/index.js";
+export { handleWebhook, resolveBillableUsing } from "./webhooks.js";
+export type { WebhookResult, BillableResolver } from "./webhooks.js";
+export { registerBillingRoutes } from "./routes.js";
+export { billingMigration } from "./migration.js";
+export { defaultConfig, resolveConfig } from "./config.js";
+export type { BillingConfig, StripeGatewayConfig, PaddleGatewayConfig } from "./config.js";
+export type { SubscriptionEvent, WebhookReceivedEvent } from "./events.js";

package/dist/billing/index.js

@@ -0,0 +1,19 @@
+/**
+ * Keel Billing — public surface, imported from `@shaferllc/keel/billing`.
+ *
+ *   import { BillingServiceProvider, Billable } from "@shaferllc/keel/billing";
+ *   class User extends Billable(Model) { static table = "users"; }
+ */
+import "./events.js"; // load the EventsList augmentation
+export { BillingServiceProvider } from "./provider.js";
+export { Billable } from "./billable.js";
+export { Subscription, toRefs } from "./subscription.js";
+export { SubscriptionItem } from "./subscription-item.js";
+export { SubscriptionBuilder } from "./builder.js";
+export { BillingManager, billing, setBilling } from "./manager.js";
+export { BillingError } from "./gateway.js";
+export { registerDefaultGateways, StripeGateway, PaddleGateway, FakeGateway } from "./drivers/index.js";
+export { handleWebhook, resolveBillableUsing } from "./webhooks.js";
+export { registerBillingRoutes } from "./routes.js";
+export { billingMigration } from "./migration.js";
+export { defaultConfig, resolveConfig } from "./config.js";

package/dist/billing/manager.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The billing manager — a small driver registry, exactly like Keel's mail and
+ * queue managers. It holds the configured `default` gateway and lazily builds
+ * each driver from a registered factory. Drivers register themselves via
+ * `registerDefaultGateways` (see `drivers/index.ts`) so this module stays free
+ * of any provider SDK.
+ *
+ * A model instance has no DI container, so — following the framework's
+ * `setConnection`/`setLogger`/`setScheduler` pattern — the active manager also
+ * lives in a module-level singleton. The `Billable` mixin and `Subscription`
+ * model reach it with `billing()`.
+ */
+import type { BillingConfig } from "./config.js";
+import { type BillingGateway } from "./gateway.js";
+/** Builds a gateway from its slice of config. */
+export type GatewayFactory = (gatewayConfig: Record<string, unknown>, billing: BillingConfig) => BillingGateway;
+export declare class BillingManager {
+    private cfg;
+    private factories;
+    private resolved;
+    constructor(cfg: BillingConfig);
+    /** Register (or replace) a gateway factory under `name`. */
+    register(name: string, factory: GatewayFactory): this;
+    /** The effective billing config. */
+    config(): BillingConfig;
+    /** The webhook signing secret for a gateway (empty string if unset). */
+    webhookSecret(name?: string): string;
+    /** Resolve a gateway driver, building and caching it on first use. */
+    gateway(name?: string): BillingGateway;
+}
+/** Install the active billing manager (called by the provider's `register`). */
+export declare function setBilling(manager: BillingManager | undefined): void;
+/** The active billing manager. Throws if the billing provider isn't registered. */
+export declare function billing(): BillingManager;

package/dist/billing/manager.js

@@ -0,0 +1,61 @@
+/**
+ * The billing manager — a small driver registry, exactly like Keel's mail and
+ * queue managers. It holds the configured `default` gateway and lazily builds
+ * each driver from a registered factory. Drivers register themselves via
+ * `registerDefaultGateways` (see `drivers/index.ts`) so this module stays free
+ * of any provider SDK.
+ *
+ * A model instance has no DI container, so — following the framework's
+ * `setConnection`/`setLogger`/`setScheduler` pattern — the active manager also
+ * lives in a module-level singleton. The `Billable` mixin and `Subscription`
+ * model reach it with `billing()`.
+ */
+import { BillingError } from "./gateway.js";
+export class BillingManager {
+    cfg;
+    factories = new Map();
+    resolved = new Map();
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** Register (or replace) a gateway factory under `name`. */
+    register(name, factory) {
+        this.factories.set(name, factory);
+        this.resolved.delete(name);
+        return this;
+    }
+    /** The effective billing config. */
+    config() {
+        return this.cfg;
+    }
+    /** The webhook signing secret for a gateway (empty string if unset). */
+    webhookSecret(name = this.cfg.default) {
+        const gw = this.cfg.gateways[name];
+        return gw?.webhookSecret ?? "";
+    }
+    /** Resolve a gateway driver, building and caching it on first use. */
+    gateway(name = this.cfg.default) {
+        const cached = this.resolved.get(name);
+        if (cached)
+            return cached;
+        const factory = this.factories.get(name);
+        if (!factory) {
+            throw new BillingError(`No billing gateway registered for "${name}". Registered: ${[...this.factories.keys()].join(", ") || "none"}.`, name);
+        }
+        const gateway = factory(this.cfg.gateways[name] ?? {}, this.cfg);
+        this.resolved.set(name, gateway);
+        return gateway;
+    }
+}
+let current;
+/** Install the active billing manager (called by the provider's `register`). */
+export function setBilling(manager) {
+    current = manager;
+}
+/** The active billing manager. Throws if the billing provider isn't registered. */
+export function billing() {
+    if (!current) {
+        throw new BillingError("Billing is not configured. Register BillingServiceProvider (or call setBilling()) first.");
+    }
+    return current;
+}

package/dist/billing/migration.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The billing schema — gateway-neutral so one set of tables serves Stripe and
+ * Paddle. `subscriptions` and `subscription_items` are created through the
+ * fluent builder; the columns added to the existing billable table (`users`)
+ * and the secondary indexes go through `schema.raw()` because the builder has
+ * no `alterTable`/`index` (see src/core/migrations.ts).
+ *
+ * The `ADD COLUMN` / `CREATE INDEX` SQL is kept to the intersection that sqlite,
+ * mysql, and postgres all accept, and each runs exactly once (the migrator
+ * tracks applied migrations by name).
+ */
+import type { Migration } from "../core/migrations.js";
+export declare function billingMigration(billableTable?: string): Migration;