@shaferllc/keel 0.79.0 → 0.80.0

package/README.md

@@ -160,11 +160,12 @@ src/core/            The framework
 src/db/              Database adapters (D1, Postgres, libSQL)
 src/api/             CRUD REST resources from a model
 src/openapi/         Generates an OpenAPI spec from the routes
+src/billing/         Subscription billing — Stripe + Paddle (Cashier port)
 src/watch/           The debug dashboard
 src/mcp/             The MCP server (docs + API for AI agents)
 src/vite/            The Vite plugin
 
-tests/               740 tests
+tests/               767 tests
 docs/                Every guide, plus type-checked examples of each
 scripts/             build-ai (llms.txt, the MCP manifest), verify-release
 ```
@@ -227,6 +228,7 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Internationalization](./docs/i18n.md) | ICU messages, `Intl` formatters, locale detection |
 | [Pages](./docs/pages.md) | Page-based routing — a file is a route |
 | [Packages](./docs/packages.md) | Redistributable slices of an app: routes, migrations, commands |
+| [Billing](./docs/billing.md) | Subscriptions, charges & webhooks — Stripe + Paddle (Cashier port) |
 | [Watch](./docs/watch.md) | Debug dashboard — requests, queries, jobs, logs at `/watch` |
 | [Views](./docs/views.md) | Hono JSX components, layouts, the View service |
 | [Templates](./docs/templates.md) | `{{ }}` + `@`-tag templating engine, edge-safe |

package/dist/billing/billable.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The `Billable` mixin — Cashier's Billable trait, as a TypeScript mixin. Apply
+ * it to a model to give that model a gateway customer, subscriptions, charges,
+ * and checkout:
+ *
+ *   class User extends Billable(Model) {
+ *     static table = "users";
+ *     declare email: string;
+ *   }
+ *
+ *   if (user.subscribed()) { ... }
+ *   await user.newSubscription("default", "price_pro").trialDays(14).create(pmId);
+ *   await user.charge(2000, { paymentMethod: pmId });
+ *
+ * Methods are thin: they resolve the active gateway (a model has no DI, so this
+ * goes through the `billing()` module singleton), call it, and persist local
+ * `Subscription` state. Customer-detail hooks (`billingEmail`, `billingName`)
+ * are overridable on the model.
+ */
+import { Model } from "../core/model.js";
+import { Subscription } from "./subscription.js";
+import { SubscriptionBuilder } from "./builder.js";
+import type { BillingGateway, GatewayCharge, GatewayInvoice, GatewayRefund, SetupIntent, PaymentMethod, CheckoutSession, PriceRef } from "./gateway.js";
+type ModelCtor = new (...args: any[]) => Model;
+export interface ChargeOptions {
+    currency?: string;
+    paymentMethod?: string;
+    description?: string;
+    metadata?: Record<string, string>;
+}
+export interface ProductCheckoutOptions {
+    successUrl?: string;
+    cancelUrl?: string;
+    metadata?: Record<string, string>;
+    allowPromotionCodes?: boolean;
+}
+/**
+ * The instance surface the mixin adds. Declared explicitly so the mixin's
+ * generated `.d.ts` references this named type rather than trying to emit the
+ * anonymous returned class — the latter fails (TS4094) because `Model` has
+ * private members.
+ */
+export interface BillableInstance {
+    billing_gateway: string | null;
+    billing_customer_id: string | null;
+    pm_type: string | null;
+    pm_last_four: string | null;
+    trial_ends_at: Date | null;
+    billingName(): string | undefined;
+    billingEmail(): string | undefined;
+    gatewayName(): string;
+    billingGateway(): BillingGateway;
+    hasBillingId(): boolean;
+    createAsCustomer(): Promise<string>;
+    getCustomerId(): Promise<string>;
+    billableId(): number | string;
+    billableType(): string;
+    subscriptions(): Promise<Subscription[]>;
+    subscription(type?: string): Promise<Subscription | null>;
+    newSubscription(type: string, prices: string | PriceRef | (string | PriceRef)[]): SubscriptionBuilder;
+    subscribed(type?: string): Promise<boolean>;
+    subscribedToPrice(price: string, type?: string): Promise<boolean>;
+    onTrial(type?: string): Promise<boolean>;
+    onGenericTrial(): boolean;
+    charge(amount: number, options?: ChargeOptions): Promise<GatewayCharge>;
+    refund(chargeId: string, amount?: number): Promise<GatewayRefund>;
+    invoices(): Promise<GatewayInvoice[]>;
+    checkout(prices: string | PriceRef | (string | PriceRef)[], options?: ProductCheckoutOptions): Promise<CheckoutSession>;
+    createSetupIntent(): Promise<SetupIntent>;
+    paymentMethods(): Promise<PaymentMethod[]>;
+}
+/**
+ * The class a `Billable(Base)` call returns: billing instances plus all of
+ * `Base`. The widening construct signature comes first so `extends` derives the
+ * instance type from it (`InstanceType<TBase> & BillableInstance`); intersecting
+ * `TBase` last carries `Base`'s statics *and* its private-member brand, so
+ * `this`-typed statics like `Model.create` still resolve. An explicit return
+ * type is required regardless — the inferred anonymous mixin class can't be
+ * emitted to a `.d.ts` because `Model` has private members (TS4094).
+ */
+export type BillableClass<TBase extends ModelCtor> = (new (...args: any[]) => InstanceType<TBase> & BillableInstance) & TBase;
+export declare function Billable<TBase extends ModelCtor>(Base: TBase): BillableClass<TBase>;
+export {};

package/dist/billing/billable.js

@@ -0,0 +1,177 @@
+/**
+ * The `Billable` mixin — Cashier's Billable trait, as a TypeScript mixin. Apply
+ * it to a model to give that model a gateway customer, subscriptions, charges,
+ * and checkout:
+ *
+ *   class User extends Billable(Model) {
+ *     static table = "users";
+ *     declare email: string;
+ *   }
+ *
+ *   if (user.subscribed()) { ... }
+ *   await user.newSubscription("default", "price_pro").trialDays(14).create(pmId);
+ *   await user.charge(2000, { paymentMethod: pmId });
+ *
+ * Methods are thin: they resolve the active gateway (a model has no DI, so this
+ * goes through the `billing()` module singleton), call it, and persist local
+ * `Subscription` state. Customer-detail hooks (`billingEmail`, `billingName`)
+ * are overridable on the model.
+ */
+import { billing } from "./manager.js";
+import { Subscription } from "./subscription.js";
+import { SubscriptionBuilder } from "./builder.js";
+import { BillingError } from "./gateway.js";
+export function Billable(Base) {
+    class BillableModel extends Base {
+        /* --------------------- overridable customer detail -------------------- */
+        /** The name to sync to the gateway customer. Override as needed. */
+        billingName() {
+            return this.name;
+        }
+        /** The email to sync to the gateway customer. Override as needed. */
+        billingEmail() {
+            return this.email;
+        }
+        /* ---------------------------- gateway wiring -------------------------- */
+        /** The gateway this billable uses (its own, or the configured default). */
+        gatewayName() {
+            return this.billing_gateway ?? billing().config().default;
+        }
+        billingGateway() {
+            return billing().gateway(this.gatewayName());
+        }
+        /* ------------------------------- customer ----------------------------- */
+        hasBillingId() {
+            return this.billing_customer_id != null && this.billing_customer_id !== "";
+        }
+        /** Create the gateway customer and store its id on this model. */
+        async createAsCustomer() {
+            const gateway = this.billingGateway();
+            const customer = await gateway.createCustomer({
+                ...(this.billingName() ? { name: this.billingName() } : {}),
+                ...(this.billingEmail() ? { email: this.billingEmail() } : {}),
+            });
+            this.billing_gateway = gateway.name;
+            this.billing_customer_id = customer.id;
+            await this.save();
+            return customer.id;
+        }
+        /** The gateway customer id, creating the customer if it doesn't exist yet. */
+        async getCustomerId() {
+            if (this.hasBillingId())
+                return this.billing_customer_id;
+            return this.createAsCustomer();
+        }
+        billableId() {
+            return this[this.constructor.primaryKey];
+        }
+        billableType() {
+            return this.constructor.name;
+        }
+        /* ----------------------------- subscriptions -------------------------- */
+        /** Every subscription this billable owns, newest first. */
+        async subscriptions() {
+            const rows = await Subscription.query()
+                .where("billable_id", this.billableId())
+                .where("billable_type", this.billableType())
+                .orderBy("id", "desc")
+                .get();
+            return rows.map((r) => new Subscription(r));
+        }
+        /** The named subscription (default: "default"), or null. */
+        async subscription(type = "default") {
+            const rows = await Subscription.query()
+                .where("billable_id", this.billableId())
+                .where("billable_type", this.billableType())
+                .where("type", type)
+                .orderBy("id", "desc")
+                .get();
+            return rows[0] ? new Subscription(rows[0]) : null;
+        }
+        /** Begin building a new subscription. */
+        newSubscription(type, prices) {
+            return new SubscriptionBuilder(this, type, prices);
+        }
+        /** Is the named subscription currently valid (active/trial/grace)? */
+        async subscribed(type = "default") {
+            return (await this.subscription(type))?.valid() ?? false;
+        }
+        /** Is the named subscription on the given price? */
+        async subscribedToPrice(price, type = "default") {
+            const sub = await this.subscription(type);
+            return !!sub && sub.valid() && sub.hasPrice(price);
+        }
+        /** On a trial of the named subscription? */
+        async onTrial(type = "default") {
+            return (await this.subscription(type))?.onTrial() ?? false;
+        }
+        /** On a generic trial (a `trial_ends_at` on the billable, no subscription yet)? */
+        onGenericTrial() {
+            return this.trial_ends_at != null && this.trial_ends_at.getTime() > Date.now();
+        }
+        /* ------------------------------- charges ------------------------------ */
+        /** Charge the customer a one-off amount (smallest currency unit). */
+        async charge(amount, options = {}) {
+            const customer = await this.getCustomerId();
+            return this.billingGateway().charge({
+                customer,
+                amount,
+                currency: options.currency ?? billing().config().currency,
+                ...(options.paymentMethod ? { paymentMethod: options.paymentMethod } : {}),
+                ...(options.description ? { description: options.description } : {}),
+                ...(options.metadata ? { metadata: options.metadata } : {}),
+            });
+        }
+        /** Refund a prior charge (full, or a partial `amount`). */
+        async refund(chargeId, amount) {
+            return this.billingGateway().refund({
+                charge: chargeId,
+                ...(amount != null ? { amount } : {}),
+            });
+        }
+        /** The customer's invoices. */
+        async invoices() {
+            if (!this.hasBillingId())
+                return [];
+            return this.billingGateway().listInvoices(this.billing_customer_id);
+        }
+        /* ------------------------------ checkout ------------------------------ */
+        /** Hosted checkout for a one-off product purchase. */
+        async checkout(prices, options = {}) {
+            const customer = await this.getCustomerId();
+            const items = (Array.isArray(prices) ? prices : [prices]).map((p) => typeof p === "string" ? { price: p } : p);
+            const params = {
+                mode: "payment",
+                customer,
+                items,
+                ...(options.successUrl ? { successUrl: options.successUrl } : {}),
+                ...(options.cancelUrl ? { cancelUrl: options.cancelUrl } : {}),
+                ...(options.metadata ? { metadata: options.metadata } : {}),
+                ...(options.allowPromotionCodes != null
+                    ? { allowPromotionCodes: options.allowPromotionCodes }
+                    : {}),
+            };
+            return this.billingGateway().createCheckoutSession(params);
+        }
+        /* ------------------- optional gateway capabilities -------------------- */
+        /** Create a SetupIntent to collect a payment method (Stripe). */
+        async createSetupIntent() {
+            const gateway = this.billingGateway();
+            if (!gateway.createSetupIntent) {
+                throw new BillingError(`The "${gateway.name}" gateway does not support setup intents.`, gateway.name);
+            }
+            return gateway.createSetupIntent(await this.getCustomerId());
+        }
+        /** The customer's stored payment methods (Stripe). */
+        async paymentMethods() {
+            const gateway = this.billingGateway();
+            if (!gateway.paymentMethods) {
+                throw new BillingError(`The "${gateway.name}" gateway does not expose payment methods.`, gateway.name);
+            }
+            if (!this.hasBillingId())
+                return [];
+            return gateway.paymentMethods(this.billing_customer_id);
+        }
+    }
+    return BillableModel;
+}

package/dist/billing/billing.config.stub

@@ -0,0 +1,33 @@
+import { env } from "@shaferllc/keel/core";
+
+/**
+ * Billing configuration — a Cashier-style port covering Stripe and Paddle.
+ * Published with `keel vendor:publish --tag billing-config`.
+ */
+export default {
+  // Which gateway is active: "stripe" | "paddle".
+  default: env("BILLING_GATEWAY", "stripe"),
+
+  // Default currency for one-off charges (ISO 4217, lowercase).
+  currency: env("BILLING_CURRENCY", "usd"),
+
+  // The model class stored in subscriptions.billable_type.
+  billableModel: "User",
+
+  // Webhook routes mount at `${path}/${gateway}` — e.g. /billing/webhook/stripe.
+  webhook: { path: "billing/webhook" },
+
+  gateways: {
+    stripe: {
+      key: env("STRIPE_SECRET_KEY", ""),
+      webhookSecret: env("STRIPE_WEBHOOK_SECRET", ""),
+      publishableKey: env("STRIPE_PUBLISHABLE_KEY", ""),
+    },
+    paddle: {
+      key: env("PADDLE_API_KEY", ""),
+      webhookSecret: env("PADDLE_WEBHOOK_SECRET", ""),
+      clientToken: env("PADDLE_CLIENT_TOKEN", ""),
+      sandbox: env("PADDLE_SANDBOX", false),
+    },
+  },
+};

package/dist/billing/builder.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The fluent subscription builder — Cashier's `newSubscription(...)->create()`.
+ * The `Billable` mixin hands it a small `BillableTarget` (so this file needn't
+ * import the mixin, avoiding a cycle); the builder shapes the request, calls the
+ * gateway, and persists a local `Subscription` synced from the result.
+ *
+ *   await user.newSubscription("default", "price_pro")
+ *     .trialDays(14)
+ *     .quantity(3)
+ *     .create(paymentMethodId);
+ */
+import { Subscription, type PriceArg } from "./subscription.js";
+import type { CheckoutSession } from "./gateway.js";
+/** What the builder needs from the billable that started it. */
+export interface BillableTarget {
+    /** Ensure a gateway customer exists and return its id. */
+    getCustomerId(): Promise<string>;
+    gatewayName(): string;
+    billableId(): number | string;
+    billableType(): string;
+}
+export interface CheckoutOptions {
+    successUrl?: string;
+    cancelUrl?: string;
+    allowPromotionCodes?: boolean;
+    metadata?: Record<string, string>;
+}
+export declare class SubscriptionBuilder {
+    private owner;
+    private type;
+    private refs;
+    private _trialEnd?;
+    private _skipTrial;
+    private _quantity?;
+    private _metadata?;
+    constructor(owner: BillableTarget, type: string, prices: PriceArg | PriceArg[]);
+    /** Trial for N days from now. */
+    trialDays(days: number): this;
+    /** Trial until a specific moment. */
+    trialUntil(date: Date): this;
+    /** Start without any trial. */
+    skipTrial(): this;
+    /** Quantity for a single-price subscription. */
+    quantity(quantity: number): this;
+    withMetadata(metadata: Record<string, string>): this;
+    /** Create the subscription, billing `paymentMethod` (or the default on file). */
+    create(paymentMethod?: string): Promise<Subscription>;
+    /** Add a subscription for a customer who already has a payment method. */
+    add(): Promise<Subscription>;
+    /** Start a hosted checkout for this subscription instead of creating it now. */
+    checkout(options?: CheckoutOptions): Promise<CheckoutSession>;
+    private items;
+    private trialEnd;
+}

package/dist/billing/builder.js

@@ -0,0 +1,104 @@
+/**
+ * The fluent subscription builder — Cashier's `newSubscription(...)->create()`.
+ * The `Billable` mixin hands it a small `BillableTarget` (so this file needn't
+ * import the mixin, avoiding a cycle); the builder shapes the request, calls the
+ * gateway, and persists a local `Subscription` synced from the result.
+ *
+ *   await user.newSubscription("default", "price_pro")
+ *     .trialDays(14)
+ *     .quantity(3)
+ *     .create(paymentMethodId);
+ */
+import { billing } from "./manager.js";
+import { Subscription, toRefs } from "./subscription.js";
+const DAY = 86_400_000;
+export class SubscriptionBuilder {
+    owner;
+    type;
+    refs;
+    _trialEnd;
+    _skipTrial = false;
+    _quantity;
+    _metadata;
+    constructor(owner, type, prices) {
+        this.owner = owner;
+        this.type = type;
+        this.refs = toRefs(prices);
+    }
+    /** Trial for N days from now. */
+    trialDays(days) {
+        this._trialEnd = new Date(Date.now() + days * DAY);
+        return this;
+    }
+    /** Trial until a specific moment. */
+    trialUntil(date) {
+        this._trialEnd = date;
+        return this;
+    }
+    /** Start without any trial. */
+    skipTrial() {
+        this._skipTrial = true;
+        return this;
+    }
+    /** Quantity for a single-price subscription. */
+    quantity(quantity) {
+        this._quantity = quantity;
+        return this;
+    }
+    withMetadata(metadata) {
+        this._metadata = metadata;
+        return this;
+    }
+    /** Create the subscription, billing `paymentMethod` (or the default on file). */
+    async create(paymentMethod) {
+        const customer = await this.owner.getCustomerId();
+        const gateway = billing().gateway(this.owner.gatewayName());
+        const remote = await gateway.createSubscription({
+            customer,
+            items: this.items(),
+            ...(this.trialEnd() ? { trialEnd: this.trialEnd() } : {}),
+            ...(paymentMethod ? { paymentMethod } : {}),
+            ...(this._metadata ? { metadata: this._metadata } : {}),
+        });
+        const subscription = await Subscription.create({
+            billable_id: this.owner.billableId(),
+            billable_type: this.owner.billableType(),
+            type: this.type,
+            gateway: this.owner.gatewayName(),
+            provider_id: remote.id,
+            provider_status: remote.status,
+            starts_at: new Date(),
+        });
+        await subscription.syncFromGateway(remote);
+        return subscription;
+    }
+    /** Add a subscription for a customer who already has a payment method. */
+    add() {
+        return this.create();
+    }
+    /** Start a hosted checkout for this subscription instead of creating it now. */
+    async checkout(options = {}) {
+        const customer = await this.owner.getCustomerId();
+        const gateway = billing().gateway(this.owner.gatewayName());
+        return gateway.createCheckoutSession({
+            mode: "subscription",
+            customer,
+            items: this.items(),
+            ...(this.trialEnd() ? { trialEnd: this.trialEnd() } : {}),
+            ...(options.successUrl ? { successUrl: options.successUrl } : {}),
+            ...(options.cancelUrl ? { cancelUrl: options.cancelUrl } : {}),
+            ...(options.allowPromotionCodes != null
+                ? { allowPromotionCodes: options.allowPromotionCodes }
+                : {}),
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+        });
+    }
+    items() {
+        if (this._quantity == null)
+            return this.refs;
+        return this.refs.map((r, i) => (i === 0 ? { ...r, quantity: this._quantity } : r));
+    }
+    trialEnd() {
+        return this._skipTrial ? undefined : this._trialEnd;
+    }
+}

package/dist/billing/config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Billing configuration. Defaults live here and are merged under
+ * `config("billing")` by the provider; an app overrides any of them in
+ * `config/billing.ts` (publish it with `keel vendor:publish --tag billing-config`).
+ *
+ * The shape mirrors Keel's other multi-driver managers (mail, queue, database):
+ * a `default` gateway plus a `gateways` map the drivers read their keys from.
+ */
+export interface StripeGatewayConfig {
+    key: string;
+    webhookSecret: string;
+    publishableKey?: string;
+    /** Drivers read only what they know; extra keys are allowed. */
+    [k: string]: unknown;
+}
+export interface PaddleGatewayConfig {
+    key: string;
+    webhookSecret: string;
+    clientToken?: string;
+    sandbox?: boolean;
+    [k: string]: unknown;
+}
+export interface BillingConfig {
+    /** Which gateway is active: "stripe" | "paddle" | "fake". */
+    default: string;
+    /** Default currency for one-off charges, ISO 4217 lowercase. */
+    currency: string;
+    /** The class name stored in `subscriptions.billable_type`. */
+    billableModel: string;
+    /** Base URL path the webhook routes mount under; the gateway name is appended. */
+    webhook: {
+        path: string;
+    };
+    gateways: {
+        stripe: StripeGatewayConfig;
+        paddle: PaddleGatewayConfig;
+        /** Custom gateways may add their own loosely-typed config. */
+        [name: string]: Record<string, unknown>;
+    };
+}
+export declare const defaultConfig: BillingConfig;
+/** Read the effective billing config off the application, filling any gaps. */
+export declare function resolveConfig(): BillingConfig;

package/dist/billing/config.js

@@ -0,0 +1,35 @@
+/**
+ * Billing configuration. Defaults live here and are merged under
+ * `config("billing")` by the provider; an app overrides any of them in
+ * `config/billing.ts` (publish it with `keel vendor:publish --tag billing-config`).
+ *
+ * The shape mirrors Keel's other multi-driver managers (mail, queue, database):
+ * a `default` gateway plus a `gateways` map the drivers read their keys from.
+ */
+import { config } from "../core/helpers.js";
+export const defaultConfig = {
+    default: "stripe",
+    currency: "usd",
+    billableModel: "User",
+    webhook: { path: "billing/webhook" },
+    gateways: {
+        stripe: { key: "", webhookSecret: "" },
+        paddle: { key: "", webhookSecret: "", sandbox: false },
+    },
+};
+/** Read the effective billing config off the application, filling any gaps. */
+export function resolveConfig() {
+    const raw = config("billing", {});
+    const gateways = (raw.gateways ?? {});
+    return {
+        ...defaultConfig,
+        ...raw,
+        webhook: { ...defaultConfig.webhook, ...(raw.webhook ?? {}) },
+        gateways: {
+            ...defaultConfig.gateways,
+            ...gateways,
+            stripe: { ...defaultConfig.gateways.stripe, ...(gateways.stripe ?? {}) },
+            paddle: { ...defaultConfig.gateways.paddle, ...(gateways.paddle ?? {}) },
+        },
+    };
+}

package/dist/billing/crypto.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Webhook-signature primitives. Stripe and Paddle both sign webhooks with
+ * HMAC-SHA256 rendered as lowercase hex. The framework's own hex-HMAC helper
+ * (`src/core/http/router.ts`) and constant-time compare (`src/core/crypto.ts`)
+ * aren't exported, so we vendor tiny copies here — edge-safe Web Crypto, no
+ * `node:crypto`, consistent with how the rest of Keel signs.
+ */
+/** HMAC-SHA256 of `data` under `secret`, as lowercase hex. */
+export declare function hmacSha256Hex(secret: string, data: string): Promise<string>;
+/** Length-independent, constant-time string comparison (avoids timing leaks). */
+export declare function constantTimeEqual(a: string, b: string): boolean;

package/dist/billing/crypto.js

@@ -0,0 +1,27 @@
+/**
+ * Webhook-signature primitives. Stripe and Paddle both sign webhooks with
+ * HMAC-SHA256 rendered as lowercase hex. The framework's own hex-HMAC helper
+ * (`src/core/http/router.ts`) and constant-time compare (`src/core/crypto.ts`)
+ * aren't exported, so we vendor tiny copies here — edge-safe Web Crypto, no
+ * `node:crypto`, consistent with how the rest of Keel signs.
+ */
+/** HMAC-SHA256 of `data` under `secret`, as lowercase hex. */
+export async function hmacSha256Hex(secret, data) {
+    const enc = new TextEncoder();
+    const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await crypto.subtle.sign("HMAC", key, enc.encode(data));
+    return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Length-independent, constant-time string comparison (avoids timing leaks). */
+export function constantTimeEqual(a, b) {
+    const enc = new TextEncoder();
+    const av = enc.encode(a);
+    const bv = enc.encode(b);
+    // Compare against the longer length so mismatched lengths still take the same
+    // path; the length inequality alone decides the result.
+    let diff = av.length ^ bv.length;
+    const len = Math.max(av.length, bv.length);
+    for (let i = 0; i < len; i++)
+        diff |= (av[i] ?? 0) ^ (bv[i] ?? 0);
+    return diff === 0;
+}

package/dist/billing/drivers/fake.d.ts

@@ -0,0 +1,58 @@
+/**
+ * An in-memory gateway for tests and local development. It implements the whole
+ * `BillingGateway` surface deterministically (ids are sequential, no clock or
+ * randomness in the identifiers) and records every call on `.calls` so tests can
+ * assert what the higher layers asked of it — the billing analogue of
+ * `MemoryDriver`/`ArrayTransport`.
+ *
+ *   const gw = new FakeGateway();
+ *   manager.register("fake", () => gw);
+ *   // …exercise Billable…
+ *   gw.calls.filter((c) => c.method === "charge");
+ *
+ * Webhooks are signed exactly like a real gateway: HMAC-SHA256 hex of the raw
+ * body under the secret, in a `fake-signature` header. `signWebhook()` builds a
+ * matching body+headers pair for tests.
+ */
+import type { BillingGateway, CustomerDetails, GatewayCustomer, CreateSubscriptionParams, GatewaySubscription, SwapParams, CancelParams, ChargeParams, GatewayCharge, RefundParams, GatewayRefund, GatewayInvoice, CheckoutParams, CheckoutSession, SetupIntent, PaymentMethod, HeaderBag } from "../gateway.js";
+export interface FakeCall {
+    method: string;
+    args: unknown[];
+}
+export declare class FakeGateway implements BillingGateway {
+    readonly name = "fake";
+    readonly calls: FakeCall[];
+    readonly customers: Map<string, GatewayCustomer>;
+    readonly subscriptions: Map<string, GatewaySubscription>;
+    readonly invoices: Map<string, GatewayInvoice[]>;
+    private seq;
+    private id;
+    private record;
+    private items;
+    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>;
+    createSetupIntent(customer: string): Promise<SetupIntent>;
+    paymentMethods(customer: string): Promise<PaymentMethod[]>;
+    verifyWebhook(rawBody: string, headers: HeaderBag, secret: string): Promise<import("../gateway.js").WebhookEvent | null>;
+    /** Build a signed webhook body + headers pair for tests. */
+    signWebhook(secret: string, event: {
+        id?: string;
+        type: string;
+        data?: Record<string, unknown>;
+    }): Promise<{
+        body: string;
+        headers: Record<string, string>;
+    }>;
+    private require;
+}