@wopr-network/platform-core 0.1.0

package/dist/billing/stripe/credit-prices.d.ts

@@ -0,0 +1,63 @@
+/**
+ * WOPR Credit price points and bonus tiers.
+ *
+ * One Stripe Product ("WOPR Credits") with 5 preset Price objects.
+ * Each price maps to a dollar amount and a credit value (with optional bonus).
+ *
+ * Price IDs are loaded from environment variables so they can differ
+ * between Stripe test/live modes.
+ */
+/**
+ * A preset credit purchase option.
+ *
+ * IMPORTANT — naming convention (WOP-1058):
+ * - amountCents: USD cents charged to Stripe (monetary — DO NOT rename to _credits).
+ *   This value is passed to Stripe's checkout session and PaymentIntent APIs.
+ * - creditCents: USD cents worth of platform credits granted (includes bonus).
+ *   Named _cents because the platform credit unit = 1 USD cent.
+ *   Passed to Credit.fromCents() — NOT a raw Credit nanodollar value.
+ */
+export interface CreditPricePoint {
+    /** Human-readable label. */
+    label: string;
+    /** Amount charged in USD cents (Stripe monetary — DO NOT rename to _credits). */
+    amountCents: number;
+    /** Platform credits granted in USD cents (includes bonus — DO NOT rename to _credits). */
+    creditCents: number;
+    /** Bonus percentage (0 for no bonus). */
+    bonusPercent: number;
+}
+/**
+ * The 5 preset credit tiers.
+ *
+ * Bonus logic:
+ *   $5   -> $5.00 credit   (0% bonus)
+ *   $10  -> $10.00 credit  (0% bonus)
+ *   $25  -> $25.50 credit  (2% bonus)
+ *   $50  -> $52.50 credit  (5% bonus)
+ *   $100 -> $110.00 credit (10% bonus)
+ */
+export declare const CREDIT_PRICE_POINTS: readonly CreditPricePoint[];
+/** Mapping from Stripe Price ID -> CreditPricePoint. */
+export type CreditPriceMap = ReadonlyMap<string, CreditPricePoint>;
+/**
+ * Load credit price mappings from environment variables.
+ *
+ * Returns a Map from Stripe Price ID -> CreditPricePoint.
+ * Only includes entries where the env var is set.
+ */
+export declare function loadCreditPriceMap(): CreditPriceMap;
+/**
+ * Get the credit amount (in cents) for a given purchase amount (in cents).
+ *
+ * Uses the bonus tiers to determine the credit value.
+ * Falls back to 1:1 if no matching tier is found.
+ */
+export declare function getCreditAmountForPurchase(amountCents: number): number;
+/**
+ * Look up a CreditPricePoint by Stripe Price ID using the price map.
+ * Returns null if the price ID is not recognized.
+ */
+export declare function lookupCreditPrice(priceMap: CreditPriceMap, priceId: string): CreditPricePoint | null;
+/** Get all configured Stripe Price IDs (for validation). */
+export declare function getConfiguredPriceIds(): string[];

package/dist/billing/stripe/credit-prices.js

@@ -0,0 +1,81 @@
+/**
+ * WOPR Credit price points and bonus tiers.
+ *
+ * One Stripe Product ("WOPR Credits") with 5 preset Price objects.
+ * Each price maps to a dollar amount and a credit value (with optional bonus).
+ *
+ * Price IDs are loaded from environment variables so they can differ
+ * between Stripe test/live modes.
+ */
+/**
+ * The 5 preset credit tiers.
+ *
+ * Bonus logic:
+ *   $5   -> $5.00 credit   (0% bonus)
+ *   $10  -> $10.00 credit  (0% bonus)
+ *   $25  -> $25.50 credit  (2% bonus)
+ *   $50  -> $52.50 credit  (5% bonus)
+ *   $100 -> $110.00 credit (10% bonus)
+ */
+export const CREDIT_PRICE_POINTS = [
+    { label: "$5", amountCents: 500, creditCents: 500, bonusPercent: 0 },
+    { label: "$10", amountCents: 1000, creditCents: 1000, bonusPercent: 0 },
+    { label: "$25", amountCents: 2500, creditCents: 2550, bonusPercent: 2 },
+    { label: "$50", amountCents: 5000, creditCents: 5250, bonusPercent: 5 },
+    { label: "$100", amountCents: 10000, creditCents: 11000, bonusPercent: 10 },
+];
+/**
+ * Map of env var name -> index into CREDIT_PRICE_POINTS.
+ * Each env var holds the Stripe Price ID for that tier.
+ */
+const PRICE_ENV_VARS = [
+    "STRIPE_CREDIT_PRICE_5",
+    "STRIPE_CREDIT_PRICE_10",
+    "STRIPE_CREDIT_PRICE_25",
+    "STRIPE_CREDIT_PRICE_50",
+    "STRIPE_CREDIT_PRICE_100",
+];
+/**
+ * Load credit price mappings from environment variables.
+ *
+ * Returns a Map from Stripe Price ID -> CreditPricePoint.
+ * Only includes entries where the env var is set.
+ */
+export function loadCreditPriceMap() {
+    const map = new Map();
+    for (let i = 0; i < PRICE_ENV_VARS.length; i++) {
+        const priceId = process.env[PRICE_ENV_VARS[i]];
+        if (priceId) {
+            map.set(priceId, CREDIT_PRICE_POINTS[i]);
+        }
+    }
+    return map;
+}
+/**
+ * Get the credit amount (in cents) for a given purchase amount (in cents).
+ *
+ * Uses the bonus tiers to determine the credit value.
+ * Falls back to 1:1 if no matching tier is found.
+ */
+export function getCreditAmountForPurchase(amountCents) {
+    const tier = CREDIT_PRICE_POINTS.find((p) => p.amountCents === amountCents);
+    return tier ? tier.creditCents : amountCents;
+}
+/**
+ * Look up a CreditPricePoint by Stripe Price ID using the price map.
+ * Returns null if the price ID is not recognized.
+ */
+export function lookupCreditPrice(priceMap, priceId) {
+    return priceMap.get(priceId) ?? null;
+}
+/** Get all configured Stripe Price IDs (for validation). */
+export function getConfiguredPriceIds() {
+    const ids = [];
+    for (const envVar of PRICE_ENV_VARS) {
+        const priceId = process.env[envVar];
+        if (priceId) {
+            ids.push(priceId);
+        }
+    }
+    return ids;
+}

package/dist/billing/stripe/credit-prices.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/billing/stripe/credit-prices.test.js

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from "vitest";
+import { CREDIT_PRICE_POINTS, getConfiguredPriceIds, getCreditAmountForPurchase, loadCreditPriceMap, lookupCreditPrice, } from "./credit-prices.js";
+describe("CREDIT_PRICE_POINTS", () => {
+    it("has 5 tiers", () => {
+        expect(CREDIT_PRICE_POINTS).toHaveLength(5);
+    });
+    it("tiers have correct bonus percentages", () => {
+        expect(CREDIT_PRICE_POINTS[0].bonusPercent).toBe(0);
+        expect(CREDIT_PRICE_POINTS[1].bonusPercent).toBe(0);
+        expect(CREDIT_PRICE_POINTS[2].bonusPercent).toBe(2);
+        expect(CREDIT_PRICE_POINTS[3].bonusPercent).toBe(5);
+        expect(CREDIT_PRICE_POINTS[4].bonusPercent).toBe(10);
+    });
+    it("credit amounts include bonus correctly", () => {
+        expect(CREDIT_PRICE_POINTS[0].creditCents).toBe(500);
+        expect(CREDIT_PRICE_POINTS[2].creditCents).toBe(2550);
+        expect(CREDIT_PRICE_POINTS[4].creditCents).toBe(11000);
+    });
+});
+describe("getCreditAmountForPurchase", () => {
+    it("returns bonus credits for matching tier", () => {
+        expect(getCreditAmountForPurchase(2500)).toBe(2550);
+        expect(getCreditAmountForPurchase(5000)).toBe(5250);
+        expect(getCreditAmountForPurchase(10000)).toBe(11000);
+    });
+    it("returns 1:1 for non-matching amount", () => {
+        expect(getCreditAmountForPurchase(7777)).toBe(7777);
+        expect(getCreditAmountForPurchase(1)).toBe(1);
+        expect(getCreditAmountForPurchase(99999)).toBe(99999);
+    });
+    it("returns exact amount for tiers without bonus", () => {
+        expect(getCreditAmountForPurchase(500)).toBe(500);
+        expect(getCreditAmountForPurchase(1000)).toBe(1000);
+    });
+});
+describe("loadCreditPriceMap", () => {
+    it("loads prices from environment variables", () => {
+        vi.stubEnv("STRIPE_CREDIT_PRICE_5", "price_5_test");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_25", "price_25_test");
+        const map = loadCreditPriceMap();
+        expect(map.get("price_5_test")).toEqual(expect.objectContaining({ amountCents: 500, creditCents: 500 }));
+        expect(map.get("price_25_test")).toEqual(expect.objectContaining({ amountCents: 2500, creditCents: 2550 }));
+        vi.unstubAllEnvs();
+    });
+    it("skips unset environment variables", () => {
+        vi.stubEnv("STRIPE_CREDIT_PRICE_5", "");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_10", "");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_25", "");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_50", "");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_100", "");
+        const map = loadCreditPriceMap();
+        expect(map.size).toBe(0);
+        vi.unstubAllEnvs();
+    });
+});
+describe("lookupCreditPrice", () => {
+    it("returns price point for known price ID", () => {
+        const priceMap = new Map([["price_abc", CREDIT_PRICE_POINTS[2]]]);
+        const point = lookupCreditPrice(priceMap, "price_abc");
+        expect(point).not.toBeNull();
+        expect(point?.amountCents).toBe(2500);
+    });
+    it("returns null for unknown price ID", () => {
+        const priceMap = new Map();
+        expect(lookupCreditPrice(priceMap, "price_unknown")).toBeNull();
+    });
+});
+describe("getConfiguredPriceIds", () => {
+    it("returns configured price IDs from env", () => {
+        vi.stubEnv("STRIPE_CREDIT_PRICE_5", "price_5_id");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_100", "price_100_id");
+        const ids = getConfiguredPriceIds();
+        expect(ids).toContain("price_5_id");
+        expect(ids).toContain("price_100_id");
+        vi.unstubAllEnvs();
+    });
+    it("returns empty array when no prices configured", () => {
+        vi.stubEnv("STRIPE_CREDIT_PRICE_5", "");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_10", "");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_25", "");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_50", "");
+        vi.stubEnv("STRIPE_CREDIT_PRICE_100", "");
+        const ids = getConfiguredPriceIds();
+        expect(ids).toHaveLength(0);
+        vi.unstubAllEnvs();
+    });
+});

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

@@ -0,0 +1,14 @@
+export { createCreditCheckoutSession, createVpsCheckoutSession } from "./checkout.js";
+export { createStripeClient, loadStripeConfig } from "./client.js";
+export type { CreditPricePoint, CreditPriceMap } from "./credit-prices.js";
+export { CREDIT_PRICE_POINTS, loadCreditPriceMap, getCreditAmountForPurchase, lookupCreditPrice, getConfiguredPriceIds } from "./credit-prices.js";
+export { detachPaymentMethod, detachAllPaymentMethods } from "./payment-methods.js";
+export type { DetachPaymentMethodOpts } from "./payment-methods.js";
+export { createPortalSession } from "./portal.js";
+export type { SetupIntentOpts } from "./setup-intent.js";
+export { createSetupIntent } from "./setup-intent.js";
+export type { StripeWebhookHandlerResult, StripePaymentProcessorDeps } from "./stripe-payment-processor.js";
+export { StripePaymentProcessor } from "./stripe-payment-processor.js";
+export type { ITenantCustomerRepository } from "./tenant-store.js";
+export { DrizzleTenantCustomerRepository, TenantCustomerRepository } from "./tenant-store.js";
+export type { TenantCustomerRow, CreditCheckoutOpts, PortalSessionOpts, VpsCheckoutOpts, StripeBillingConfig } from "./types.js";

package/dist/billing/stripe/index.js

@@ -0,0 +1,8 @@
+export { createCreditCheckoutSession, createVpsCheckoutSession } from "./checkout.js";
+export { createStripeClient, loadStripeConfig } from "./client.js";
+export { CREDIT_PRICE_POINTS, loadCreditPriceMap, getCreditAmountForPurchase, lookupCreditPrice, getConfiguredPriceIds } from "./credit-prices.js";
+export { detachPaymentMethod, detachAllPaymentMethods } from "./payment-methods.js";
+export { createPortalSession } from "./portal.js";
+export { createSetupIntent } from "./setup-intent.js";
+export { StripePaymentProcessor } from "./stripe-payment-processor.js";
+export { DrizzleTenantCustomerRepository, TenantCustomerRepository } from "./tenant-store.js";

package/dist/billing/stripe/payment-methods-detach-all.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/billing/stripe/payment-methods-detach-all.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from "vitest";
+import { detachAllPaymentMethods } from "./payment-methods.js";
+function mockStripe(paymentMethods = []) {
+    return {
+        customers: {
+            listPaymentMethods: vi.fn().mockResolvedValue({ data: paymentMethods }),
+        },
+        paymentMethods: {
+            detach: vi.fn().mockResolvedValue({}),
+        },
+    };
+}
+function mockTenantStore(customerId = "cus_123") {
+    return {
+        getByTenant: vi.fn().mockResolvedValue(customerId ? { tenant: "t1", processor_customer_id: customerId } : null),
+    };
+}
+describe("detachAllPaymentMethods", () => {
+    it("detaches all payment methods for a tenant", async () => {
+        const stripe = mockStripe([{ id: "pm_1" }, { id: "pm_2" }]);
+        const tenantRepo = mockTenantStore();
+        const count = await detachAllPaymentMethods(stripe, tenantRepo, "t1");
+        expect(count).toBe(2);
+        expect(stripe.paymentMethods.detach).toHaveBeenCalledWith("pm_1");
+        expect(stripe.paymentMethods.detach).toHaveBeenCalledWith("pm_2");
+    });
+    it("returns 0 when tenant has no Stripe customer", async () => {
+        const stripe = mockStripe();
+        const tenantRepo = mockTenantStore(null);
+        const count = await detachAllPaymentMethods(stripe, tenantRepo, "t1");
+        expect(count).toBe(0);
+        expect(stripe.paymentMethods.detach).not.toHaveBeenCalled();
+    });
+    it("returns 0 when tenant has no payment methods", async () => {
+        const stripe = mockStripe([]);
+        const tenantRepo = mockTenantStore();
+        const count = await detachAllPaymentMethods(stripe, tenantRepo, "t1");
+        expect(count).toBe(0);
+    });
+});

package/dist/billing/stripe/payment-methods.d.ts

@@ -0,0 +1,25 @@
+import type Stripe from "stripe";
+import type { ITenantCustomerRepository, TenantCustomerRepository } from "./tenant-store.js";
+export declare class PaymentMethodOwnershipError extends Error {
+    readonly code: "PAYMENT_METHOD_NOT_OWNED";
+    constructor();
+}
+export interface DetachPaymentMethodOpts {
+    tenant: string;
+    paymentMethodId: string;
+}
+/**
+ * Detach a payment method from a Stripe customer.
+ *
+ * Validates the payment method belongs to the tenant's Stripe customer
+ * before detaching to prevent cross-tenant attacks.
+ */
+export declare function detachPaymentMethod(stripe: Stripe, tenantRepo: TenantCustomerRepository, opts: DetachPaymentMethodOpts): Promise<void>;
+/**
+ * Detach ALL payment methods from a tenant's Stripe customer.
+ *
+ * Used during ban cascade to prevent any future charges.
+ * Returns the number of payment methods detached.
+ * Returns 0 (does not throw) if tenant has no Stripe customer or no methods.
+ */
+export declare function detachAllPaymentMethods(stripe: Stripe, tenantRepo: ITenantCustomerRepository, tenantId: string): Promise<number>;

package/dist/billing/stripe/payment-methods.js

@@ -0,0 +1,53 @@
+export class PaymentMethodOwnershipError extends Error {
+    code = "PAYMENT_METHOD_NOT_OWNED";
+    constructor() {
+        super("Payment method does not belong to this tenant");
+        this.name = "PaymentMethodOwnershipError";
+    }
+}
+/**
+ * Detach a payment method from a Stripe customer.
+ *
+ * Validates the payment method belongs to the tenant's Stripe customer
+ * before detaching to prevent cross-tenant attacks.
+ */
+export async function detachPaymentMethod(stripe, tenantRepo, opts) {
+    const mapping = await tenantRepo.getByTenant(opts.tenant);
+    if (!mapping) {
+        throw new Error(`No Stripe customer found for tenant: ${opts.tenant}`);
+    }
+    // Retrieve the payment method to verify it belongs to this customer
+    const pm = await stripe.paymentMethods.retrieve(opts.paymentMethodId);
+    if (!pm.customer || pm.customer !== mapping.processor_customer_id) {
+        throw new PaymentMethodOwnershipError();
+    }
+    await stripe.paymentMethods.detach(opts.paymentMethodId);
+}
+/**
+ * Detach ALL payment methods from a tenant's Stripe customer.
+ *
+ * Used during ban cascade to prevent any future charges.
+ * Returns the number of payment methods detached.
+ * Returns 0 (does not throw) if tenant has no Stripe customer or no methods.
+ */
+export async function detachAllPaymentMethods(stripe, tenantRepo, tenantId) {
+    const mapping = await tenantRepo.getByTenant(tenantId);
+    if (!mapping)
+        return 0;
+    let detached = 0;
+    let startingAfter;
+    while (true) {
+        const methods = await stripe.customers.listPaymentMethods(mapping.processor_customer_id, {
+            limit: 100,
+            ...(startingAfter ? { starting_after: startingAfter } : {}),
+        });
+        for (const pm of methods.data) {
+            await stripe.paymentMethods.detach(pm.id);
+            detached++;
+        }
+        if (!methods.has_more)
+            break;
+        startingAfter = methods.data[methods.data.length - 1].id;
+    }
+    return detached;
+}

package/dist/billing/stripe/payment-methods.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/billing/stripe/payment-methods.test.js

@@ -0,0 +1,122 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { detachAllPaymentMethods, detachPaymentMethod } from "./payment-methods.js";
+import { TenantCustomerRepository } from "./tenant-store.js";
+function mockStripe(overrides = {}) {
+    return {
+        paymentMethods: {
+            retrieve: overrides.paymentMethodRetrieve ??
+                vi.fn().mockResolvedValue({
+                    id: "pm_test_123",
+                    customer: "cus_abc123",
+                }),
+            detach: overrides.paymentMethodDetach ?? vi.fn().mockResolvedValue({ id: "pm_test_123" }),
+        },
+    };
+}
+// TOP OF FILE - shared across ALL describes
+let pool;
+let db;
+beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+    await beginTestTransaction(pool);
+});
+afterAll(async () => {
+    await endTestTransaction(pool);
+    await pool.close();
+});
+describe("detachPaymentMethod", () => {
+    let store;
+    beforeEach(async () => {
+        await rollbackTestTransaction(pool);
+        store = new TenantCustomerRepository(db);
+    });
+    it("calls stripe.paymentMethods.detach with the correct ID", async () => {
+        await store.upsert({ tenant: "t-1", processorCustomerId: "cus_abc123" });
+        const stripe = mockStripe();
+        await detachPaymentMethod(stripe, store, {
+            tenant: "t-1",
+            paymentMethodId: "pm_test_123",
+        });
+        expect(stripe.paymentMethods.retrieve).toHaveBeenCalledWith("pm_test_123");
+        expect(stripe.paymentMethods.detach).toHaveBeenCalledWith("pm_test_123");
+    });
+    it("throws when tenant has no Stripe customer mapping", async () => {
+        const stripe = mockStripe();
+        await expect(detachPaymentMethod(stripe, store, {
+            tenant: "t-unknown",
+            paymentMethodId: "pm_test_123",
+        })).rejects.toThrow("No Stripe customer found for tenant: t-unknown");
+    });
+    it("throws when payment method belongs to a different customer (cross-tenant guard)", async () => {
+        await store.upsert({ tenant: "t-1", processorCustomerId: "cus_abc123" });
+        const paymentMethodRetrieve = vi.fn().mockResolvedValue({
+            id: "pm_other",
+            customer: "cus_other_customer",
+        });
+        const stripe = mockStripe({ paymentMethodRetrieve });
+        await expect(detachPaymentMethod(stripe, store, {
+            tenant: "t-1",
+            paymentMethodId: "pm_other",
+        })).rejects.toThrow("Payment method does not belong to this tenant");
+        expect(stripe.paymentMethods.detach).not.toHaveBeenCalled();
+    });
+});
+describe("detachAllPaymentMethods", () => {
+    let store;
+    beforeEach(async () => {
+        await rollbackTestTransaction(pool);
+        store = new TenantCustomerRepository(db);
+    });
+    it("returns 0 when tenant has no Stripe customer mapping", async () => {
+        const stripe = {
+            customers: { listPaymentMethods: vi.fn() },
+            paymentMethods: { detach: vi.fn() },
+        };
+        const result = await detachAllPaymentMethods(stripe, store, "t-unknown");
+        expect(result).toBe(0);
+        expect(stripe.customers.listPaymentMethods).not.toHaveBeenCalled();
+    });
+    it("detaches all payment methods on a single page", async () => {
+        await store.upsert({ tenant: "t-1", processorCustomerId: "cus_abc" });
+        const listPaymentMethods = vi.fn().mockResolvedValue({
+            data: [{ id: "pm_1" }, { id: "pm_2" }],
+            has_more: false,
+        });
+        const detach = vi.fn().mockResolvedValue({});
+        const stripe = {
+            customers: { listPaymentMethods },
+            paymentMethods: { detach },
+        };
+        const result = await detachAllPaymentMethods(stripe, store, "t-1");
+        expect(result).toBe(2);
+        expect(detach).toHaveBeenCalledWith("pm_1");
+        expect(detach).toHaveBeenCalledWith("pm_2");
+        expect(listPaymentMethods).toHaveBeenCalledTimes(1);
+    });
+    it("paginates when has_more is true", async () => {
+        await store.upsert({ tenant: "t-1", processorCustomerId: "cus_abc" });
+        const listPaymentMethods = vi
+            .fn()
+            .mockResolvedValueOnce({
+            data: [{ id: "pm_1" }, { id: "pm_2" }],
+            has_more: true,
+        })
+            .mockResolvedValueOnce({
+            data: [{ id: "pm_3" }],
+            has_more: false,
+        });
+        const detach = vi.fn().mockResolvedValue({});
+        const stripe = {
+            customers: { listPaymentMethods },
+            paymentMethods: { detach },
+        };
+        const result = await detachAllPaymentMethods(stripe, store, "t-1");
+        expect(result).toBe(3);
+        expect(listPaymentMethods).toHaveBeenCalledTimes(2);
+        expect(listPaymentMethods).toHaveBeenNthCalledWith(2, "cus_abc", { limit: 100, starting_after: "pm_2" });
+        expect(detach).toHaveBeenCalledWith("pm_1");
+        expect(detach).toHaveBeenCalledWith("pm_2");
+        expect(detach).toHaveBeenCalledWith("pm_3");
+    });
+});

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

@@ -0,0 +1,10 @@
+import type Stripe from "stripe";
+import type { TenantCustomerRepository } from "./tenant-store.js";
+import type { PortalSessionOpts } from "./types.js";
+/**
+ * Create a Stripe Customer Portal session so the user can manage their billing.
+ *
+ * Users can update payment methods, view invoices, cancel subscriptions, etc.
+ * All via Stripe's hosted UI -- zero billing UI code in WOPR.
+ */
+export declare function createPortalSession(stripe: Stripe, tenantRepo: TenantCustomerRepository, opts: PortalSessionOpts): Promise<Stripe.BillingPortal.Session>;

package/dist/billing/stripe/portal.js

@@ -0,0 +1,16 @@
+/**
+ * Create a Stripe Customer Portal session so the user can manage their billing.
+ *
+ * Users can update payment methods, view invoices, cancel subscriptions, etc.
+ * All via Stripe's hosted UI -- zero billing UI code in WOPR.
+ */
+export async function createPortalSession(stripe, tenantRepo, opts) {
+    const mapping = await tenantRepo.getByTenant(opts.tenant);
+    if (!mapping) {
+        throw new Error(`No Stripe customer found for tenant: ${opts.tenant}`);
+    }
+    return stripe.billingPortal.sessions.create({
+        customer: mapping.processor_customer_id,
+        return_url: opts.returnUrl,
+    });
+}

package/dist/billing/stripe/portal.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/billing/stripe/portal.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from "vitest";
+import { createPortalSession } from "./portal.js";
+describe("createPortalSession", () => {
+    function mockStripe(portalResult = { url: "https://billing.stripe.com/session_xyz" }) {
+        return {
+            billingPortal: {
+                sessions: {
+                    create: vi.fn().mockResolvedValue(portalResult),
+                },
+            },
+        };
+    }
+    function mockTenantStore(mapping = null) {
+        return {
+            getByTenant: vi.fn().mockReturnValue(mapping),
+        };
+    }
+    it("creates a portal session for an existing customer", async () => {
+        const stripe = mockStripe();
+        const store = mockTenantStore({ processor_customer_id: "cus_abc" });
+        const session = await createPortalSession(stripe, store, {
+            tenant: "t-1",
+            returnUrl: "https://example.com/billing",
+        });
+        expect(session.url).toBe("https://billing.stripe.com/session_xyz");
+        expect(stripe.billingPortal.sessions.create).toHaveBeenCalledWith({
+            customer: "cus_abc",
+            return_url: "https://example.com/billing",
+        });
+    });
+    it("throws when no Stripe customer mapping exists", async () => {
+        const stripe = mockStripe();
+        const store = mockTenantStore(null);
+        await expect(createPortalSession(stripe, store, {
+            tenant: "unknown-tenant",
+            returnUrl: "https://example.com/billing",
+        })).rejects.toThrow("No Stripe customer found for tenant: unknown-tenant");
+    });
+    it("propagates Stripe API errors", async () => {
+        const stripe = mockStripe();
+        stripe.billingPortal.sessions.create.mockRejectedValue(new Error("Portal API error"));
+        const store = mockTenantStore({ processor_customer_id: "cus_abc" });
+        await expect(createPortalSession(stripe, store, {
+            tenant: "t-1",
+            returnUrl: "https://example.com/billing",
+        })).rejects.toThrow("Portal API error");
+    });
+});

package/dist/billing/stripe/setup-intent.d.ts

@@ -0,0 +1,16 @@
+import type Stripe from "stripe";
+import type { TenantCustomerRepository } from "./tenant-store.js";
+export interface SetupIntentOpts {
+    tenant: string;
+}
+/**
+ * Create a Stripe SetupIntent so the user can save a payment method.
+ *
+ * Requires an existing Stripe customer (created during credit checkout).
+ * Returns the client_secret for use with Stripe Elements on the frontend.
+ *
+ * Note: payment_method_types is omitted to allow dynamic payment methods
+ * configured in the Stripe Dashboard. This enables the best payment options
+ * for each user's location and preferences.
+ */
+export declare function createSetupIntent(stripe: Stripe, tenantRepo: TenantCustomerRepository, opts: SetupIntentOpts): Promise<Stripe.SetupIntent>;

package/dist/billing/stripe/setup-intent.js

@@ -0,0 +1,22 @@
+/**
+ * Create a Stripe SetupIntent so the user can save a payment method.
+ *
+ * Requires an existing Stripe customer (created during credit checkout).
+ * Returns the client_secret for use with Stripe Elements on the frontend.
+ *
+ * Note: payment_method_types is omitted to allow dynamic payment methods
+ * configured in the Stripe Dashboard. This enables the best payment options
+ * for each user's location and preferences.
+ */
+export async function createSetupIntent(stripe, tenantRepo, opts) {
+    const mapping = await tenantRepo.getByTenant(opts.tenant);
+    if (!mapping) {
+        throw new Error(`No Stripe customer found for tenant: ${opts.tenant}`);
+    }
+    return stripe.setupIntents.create({
+        customer: mapping.processor_customer_id,
+        metadata: {
+            wopr_tenant: opts.tenant,
+        },
+    });
+}

package/dist/billing/stripe/setup-intent.test.d.ts

@@ -0,0 +1 @@
+export {};