@shaferllc/keel 0.78.2 → 0.80.0

package/dist/billing/drivers/fake.js

@@ -0,0 +1,190 @@
+/**
+ * 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 { hmacSha256Hex, constantTimeEqual } from "../crypto.js";
+const DAY = 86_400_000;
+export class FakeGateway {
+    name = "fake";
+    calls = [];
+    customers = new Map();
+    subscriptions = new Map();
+    invoices = new Map();
+    seq = 0;
+    id(prefix) {
+        return `${prefix}_${++this.seq}`;
+    }
+    record(method, ...args) {
+        this.calls.push({ method, args });
+    }
+    items(refs) {
+        return refs.map((r) => ({
+            id: this.id("si"),
+            product: `prod_${r.price}`,
+            price: r.price,
+            quantity: r.quantity ?? 1,
+        }));
+    }
+    async createCustomer(details) {
+        this.record("createCustomer", details);
+        const customer = {
+            id: this.id("cus"),
+            email: details.email,
+            name: details.name,
+        };
+        this.customers.set(customer.id, customer);
+        return customer;
+    }
+    async updateCustomer(id, details) {
+        this.record("updateCustomer", id, details);
+        const customer = { ...this.customers.get(id), id, ...details };
+        this.customers.set(id, customer);
+        return customer;
+    }
+    async createSubscription(params) {
+        this.record("createSubscription", params);
+        const trialing = params.trialEnd ? params.trialEnd.getTime() > Date.now() : false;
+        const items = this.items(params.items);
+        const sub = {
+            id: this.id("sub"),
+            status: trialing ? "trialing" : "active",
+            items,
+            quantity: items[0]?.quantity ?? 1,
+            trialEndsAt: params.trialEnd ?? null,
+            endsAt: null,
+            customer: params.customer,
+        };
+        this.subscriptions.set(sub.id, sub);
+        return sub;
+    }
+    async swapSubscription(id, params) {
+        this.record("swapSubscription", id, params);
+        const sub = this.require(id);
+        const items = this.items(params.items);
+        const next = { ...sub, items, quantity: items[0]?.quantity ?? 1 };
+        this.subscriptions.set(id, next);
+        return next;
+    }
+    async updateQuantity(id, quantity, opts) {
+        this.record("updateQuantity", id, quantity, opts);
+        const sub = this.require(id);
+        const items = sub.items.map((it, i) => (i === 0 ? { ...it, quantity } : it));
+        const next = { ...sub, items, quantity };
+        this.subscriptions.set(id, next);
+        return next;
+    }
+    async cancelSubscription(id, params) {
+        this.record("cancelSubscription", id, params);
+        const sub = this.require(id);
+        const now = new Date();
+        const next = params?.now
+            ? { ...sub, status: "canceled", endsAt: now }
+            : { ...sub, endsAt: new Date(now.getTime() + 30 * DAY) };
+        this.subscriptions.set(id, next);
+        return next;
+    }
+    async resumeSubscription(id) {
+        this.record("resumeSubscription", id);
+        const sub = this.require(id);
+        const trialing = sub.trialEndsAt ? sub.trialEndsAt.getTime() > Date.now() : false;
+        const next = {
+            ...sub,
+            status: trialing ? "trialing" : "active",
+            endsAt: null,
+        };
+        this.subscriptions.set(id, next);
+        return next;
+    }
+    async charge(params) {
+        this.record("charge", params);
+        return {
+            id: this.id("ch"),
+            status: "succeeded",
+            amount: params.amount,
+            currency: params.currency ?? "usd",
+        };
+    }
+    async refund(params) {
+        this.record("refund", params);
+        return { id: this.id("re"), amount: params.amount ?? 0, status: "succeeded" };
+    }
+    async listInvoices(customer) {
+        this.record("listInvoices", customer);
+        return this.invoices.get(customer) ?? [];
+    }
+    async createCheckoutSession(params) {
+        this.record("createCheckoutSession", params);
+        const id = this.id("cs");
+        return { id, url: `https://fake.checkout/${id}`, clientToken: `ctok_${id}` };
+    }
+    async createSetupIntent(customer) {
+        this.record("createSetupIntent", customer);
+        const id = this.id("seti");
+        return { id, clientSecret: `${id}_secret` };
+    }
+    async paymentMethods(customer) {
+        this.record("paymentMethods", customer);
+        return [{ id: this.id("pm"), type: "card", last4: "4242", brand: "visa" }];
+    }
+    async verifyWebhook(rawBody, headers, secret) {
+        const provided = headers("fake-signature") ?? "";
+        const expected = await hmacSha256Hex(secret, rawBody);
+        if (!constantTimeEqual(provided, expected))
+            return null;
+        const body = JSON.parse(rawBody);
+        const data = body.data;
+        const subscription = data && data.id
+            ? {
+                id: data.id,
+                status: data.status ?? "active",
+                items: data.items ?? [],
+                quantity: data.quantity ?? null,
+                trialEndsAt: data.trialEndsAt ? new Date(data.trialEndsAt) : null,
+                endsAt: data.endsAt ? new Date(data.endsAt) : null,
+                customer: data.customer,
+            }
+            : undefined;
+        return {
+            id: body.id ?? this.id("evt"),
+            type: body.type,
+            payload: body,
+            subscription,
+            customer: data?.customer,
+        };
+    }
+    /** Build a signed webhook body + headers pair for tests. */
+    async signWebhook(secret, event) {
+        const body = JSON.stringify(event);
+        const signature = await hmacSha256Hex(secret, body);
+        return { body, headers: { "fake-signature": signature } };
+    }
+    require(id) {
+        const sub = this.subscriptions.get(id);
+        if (sub)
+            return sub;
+        // Not created through this instance (e.g. hydrated from a fixture) — mint a
+        // minimal record so lifecycle calls still resolve.
+        const seed = {
+            id,
+            status: "active",
+            items: [],
+            quantity: 1,
+            trialEndsAt: null,
+            endsAt: null,
+        };
+        this.subscriptions.set(id, seed);
+        return seed;
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Registers the built-in gateways on a manager. Kept out of `manager.ts` so the
+ * manager module carries no provider SDK; the provider (and tests) call this to
+ * wire Stripe, Paddle, and the Fake gateway from config.
+ */
+import type { BillingManager } from "../manager.js";
+export { StripeGateway } from "./stripe.js";
+export { PaddleGateway } from "./paddle.js";
+export { FakeGateway } from "./fake.js";
+export type { FakeCall } from "./fake.js";
+export declare function registerDefaultGateways(manager: BillingManager): void;

package/dist/billing/drivers/index.js

@@ -0,0 +1,22 @@
+/**
+ * Registers the built-in gateways on a manager. Kept out of `manager.ts` so the
+ * manager module carries no provider SDK; the provider (and tests) call this to
+ * wire Stripe, Paddle, and the Fake gateway from config.
+ */
+import { StripeGateway } from "./stripe.js";
+import { PaddleGateway } from "./paddle.js";
+import { FakeGateway } from "./fake.js";
+export { StripeGateway } from "./stripe.js";
+export { PaddleGateway } from "./paddle.js";
+export { FakeGateway } from "./fake.js";
+export function registerDefaultGateways(manager) {
+    manager.register("stripe", (cfg) => new StripeGateway(cfg.key ?? ""));
+    manager.register("paddle", (cfg) => {
+        const c = cfg;
+        return new PaddleGateway(c.key ?? "", {
+            ...(c.sandbox != null ? { sandbox: c.sandbox } : {}),
+            ...(c.clientToken ? { clientToken: c.clientToken } : {}),
+        });
+    });
+    manager.register("fake", () => new FakeGateway());
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The Paddle (Billing) gateway. Paddle is a merchant-of-record with a
+ * client-driven checkout, so its model differs from Stripe in two honest ways:
+ * new subscriptions are born from a completed checkout/transaction (not created
+ * server-side), and one-off charges go through transactions. Those methods throw
+ * a clear `BillingError` pointing at `checkout()`; everything else maps onto the
+ * Paddle REST API with JSON + Bearer auth.
+ *
+ * Webhook signatures use Paddle's `ts;h1` scheme: HMAC-SHA256 hex of
+ * `${ts}:${rawBody}` under the notification secret.
+ */
+import type { BillingGateway, CustomerDetails, GatewayCustomer, CreateSubscriptionParams, GatewaySubscription, SwapParams, CancelParams, ChargeParams, GatewayCharge, RefundParams, GatewayRefund, GatewayInvoice, CheckoutParams, CheckoutSession, HeaderBag, WebhookEvent } from "../gateway.js";
+export interface PaddleOptions {
+    sandbox?: boolean;
+    clientToken?: string;
+}
+export declare class PaddleGateway implements BillingGateway {
+    private key;
+    private options;
+    readonly name = "paddle";
+    private base;
+    constructor(key: string, options?: PaddleOptions);
+    private call;
+    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>;
+    verifyWebhook(rawBody: string, headers: HeaderBag, secret: string): Promise<WebhookEvent | null>;
+    private normalize;
+}

package/dist/billing/drivers/paddle.js

@@ -0,0 +1,197 @@
+/**
+ * The Paddle (Billing) gateway. Paddle is a merchant-of-record with a
+ * client-driven checkout, so its model differs from Stripe in two honest ways:
+ * new subscriptions are born from a completed checkout/transaction (not created
+ * server-side), and one-off charges go through transactions. Those methods throw
+ * a clear `BillingError` pointing at `checkout()`; everything else maps onto the
+ * Paddle REST API with JSON + Bearer auth.
+ *
+ * Webhook signatures use Paddle's `ts;h1` scheme: HMAC-SHA256 hex of
+ * `${ts}:${rawBody}` under the notification secret.
+ */
+import { hmacSha256Hex, constantTimeEqual } from "../crypto.js";
+import { BillingError } from "../gateway.js";
+export class PaddleGateway {
+    key;
+    options;
+    name = "paddle";
+    base;
+    constructor(key, options = {}) {
+        this.key = key;
+        this.options = options;
+        this.base = options.sandbox ? "https://sandbox-api.paddle.com" : "https://api.paddle.com";
+    }
+    /* ------------------------------- transport ----------------------------- */
+    async call(method, path, body) {
+        if (!this.key)
+            throw new BillingError("Paddle API key is not configured.", "paddle");
+        const res = await fetch(`${this.base}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.key}`,
+                "content-type": "application/json",
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            const err = (data.error ?? {});
+            throw new BillingError(err.detail ?? `Paddle request failed (${res.status})`, "paddle");
+        }
+        return (data.data ?? data);
+    }
+    /* ------------------------------- customers ----------------------------- */
+    async createCustomer(details) {
+        const c = await this.call("POST", "/customers", {
+            email: details.email,
+            name: details.name,
+        });
+        return { id: String(c.id), email: c.email, name: c.name };
+    }
+    async updateCustomer(id, details) {
+        const c = await this.call("PATCH", `/customers/${id}`, {
+            email: details.email,
+            name: details.name,
+        });
+        return { id: String(c.id), email: c.email, name: c.name };
+    }
+    /* ----------------------------- subscriptions --------------------------- */
+    createSubscription(_params) {
+        throw new BillingError("Paddle subscriptions are created from a completed checkout. Use newSubscription(...).checkout() and let the webhook create the local record.", "paddle");
+    }
+    async swapSubscription(id, params) {
+        const sub = await this.call("PATCH", `/subscriptions/${id}`, {
+            items: params.items.map((i) => ({ price_id: i.price, quantity: i.quantity ?? 1 })),
+            proration_billing_mode: params.prorate === false ? "do_not_bill" : "prorated_immediately",
+        });
+        return this.normalize(sub);
+    }
+    async updateQuantity(id, quantity, opts) {
+        const current = await this.call("GET", `/subscriptions/${id}`);
+        const items = (current.items ?? []).map((it, i) => ({
+            price_id: String(it.price?.id ?? ""),
+            quantity: i === 0 ? quantity : Number(it.quantity ?? 1),
+        }));
+        const sub = await this.call("PATCH", `/subscriptions/${id}`, {
+            items,
+            proration_billing_mode: opts?.prorate === false ? "do_not_bill" : "prorated_immediately",
+        });
+        return this.normalize(sub);
+    }
+    async cancelSubscription(id, params) {
+        const sub = await this.call("POST", `/subscriptions/${id}/cancel`, {
+            effective_from: params?.now ? "immediately" : "next_billing_period",
+        });
+        return this.normalize(sub);
+    }
+    async resumeSubscription(id) {
+        // Removing the scheduled cancellation resumes the subscription.
+        const sub = await this.call("PATCH", `/subscriptions/${id}`, { scheduled_change: null });
+        return this.normalize(sub);
+    }
+    /* ------------------------------- charges ------------------------------- */
+    charge(_params) {
+        throw new BillingError("Paddle one-off charges are collected via a transaction/checkout. Use checkout() with mode 'payment'.", "paddle");
+    }
+    async refund(params) {
+        const adj = await this.call("POST", "/adjustments", {
+            action: "refund",
+            transaction_id: params.charge,
+            reason: "requested_by_customer",
+            type: params.amount != null ? "partial" : "full",
+        });
+        return {
+            id: String(adj.id),
+            amount: Number(adj.totals?.total ?? params.amount ?? 0),
+            status: String(adj.status ?? "pending"),
+        };
+    }
+    async listInvoices(customer) {
+        const res = await this.call("GET", `/transactions?customer_id=${customer}&per_page=100`);
+        const data = Array.isArray(res) ? res : [];
+        return data.map((tx) => {
+            const totals = tx.details?.totals;
+            return {
+                id: String(tx.id),
+                number: tx.invoice_number ?? null,
+                total: Number(totals?.grand_total ?? 0),
+                currency: String(tx.currency_code ?? "usd").toLowerCase(),
+                status: String(tx.status ?? ""),
+                date: tx.created_at ? new Date(String(tx.created_at)) : null,
+                url: null,
+            };
+        });
+    }
+    /* ------------------------------ checkout ------------------------------- */
+    async createCheckoutSession(params) {
+        // A transaction is Paddle's server-side checkout handle; the overlay/inline
+        // widget completes it client-side with the client token.
+        const tx = await this.call("POST", "/transactions", {
+            items: params.items.map((i) => ({ price_id: i.price, quantity: i.quantity ?? 1 })),
+            customer_id: params.customer,
+            collection_mode: "automatic",
+            custom_data: params.metadata,
+        });
+        const checkout = tx.checkout ?? {};
+        return {
+            id: String(tx.id),
+            url: checkout.url ?? null,
+            clientToken: this.options.clientToken ?? null,
+            raw: tx,
+        };
+    }
+    /* ------------------------------ webhooks ------------------------------- */
+    async verifyWebhook(rawBody, headers, secret) {
+        const header = headers("paddle-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.ts || !parts.h1)
+            return null;
+        const expected = await hmacSha256Hex(secret, `${parts.ts}:${rawBody}`);
+        if (!constantTimeEqual(parts.h1, expected))
+            return null;
+        const event = JSON.parse(rawBody);
+        const subscription = event.event_type.startsWith("subscription.")
+            ? this.normalize(event.data)
+            : undefined;
+        return {
+            id: event.event_id ?? "",
+            type: event.event_type,
+            payload: event,
+            subscription,
+            customer: subscription?.customer ?? event.data.customer_id,
+        };
+    }
+    /* ------------------------------ mapping -------------------------------- */
+    normalize(sub) {
+        const items = (sub.items ?? []).map((it) => {
+            const price = it.price ?? {};
+            return {
+                id: String(price.id ?? ""),
+                product: String(price.product_id ?? ""),
+                price: String(price.id ?? ""),
+                quantity: it.quantity != null ? Number(it.quantity) : undefined,
+            };
+        });
+        const scheduled = sub.scheduled_change ?? null;
+        const endsAt = scheduled && scheduled.action === "cancel" && scheduled.effective_at
+            ? new Date(String(scheduled.effective_at))
+            : sub.canceled_at
+                ? new Date(String(sub.canceled_at))
+                : null;
+        const trialEnd = sub.items?.[0]?.trial_dates;
+        return {
+            id: String(sub.id),
+            status: String(sub.status ?? ""),
+            items,
+            quantity: items[0]?.quantity ?? null,
+            trialEndsAt: trialEnd?.ends_at ? new Date(String(trialEnd.ends_at)) : null,
+            endsAt,
+            customer: sub.customer_id ? String(sub.customer_id) : undefined,
+        };
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * 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 type { BillingGateway, CustomerDetails, GatewayCustomer, CreateSubscriptionParams, GatewaySubscription, SwapParams, CancelParams, ChargeParams, GatewayCharge, RefundParams, GatewayRefund, GatewayInvoice, CheckoutParams, CheckoutSession, SetupIntent, PaymentMethod, HeaderBag, WebhookEvent } from "../gateway.js";
+export declare class StripeGateway implements BillingGateway {
+    private key;
+    readonly name = "stripe";
+    constructor(key: string);
+    private call;
+    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<WebhookEvent | null>;
+    private normalize;
+}