@wopr-network/platform-core 0.1.0

package/src/billing/payram/webhook.test.ts

@@ -0,0 +1,318 @@
+/**
+ * Unit tests for PayRam webhook handler (WOP-407).
+ *
+ * Covers FILLED/OVER_FILLED crediting the ledger, PARTIALLY_FILLED/CANCELLED
+ * no-op status, idempotency, replay guard, and bot reactivation.
+ */
+
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { CreditLedger } from "../../credits/credit-ledger.js";
+import { DrizzleWebhookSeenRepository } from "../drizzle-webhook-seen-repository.js";
+import { noOpReplayGuard } from "../webhook-seen-repository.js";
+import { PayRamChargeRepository } from "./charge-store.js";
+import type { PayRamWebhookDeps, PayRamWebhookPayload } from "./index.js";
+import { handlePayRamWebhook } from "./webhook.js";
+
+function makePayload(overrides: Partial<PayRamWebhookPayload> = {}): PayRamWebhookPayload {
+  return {
+    reference_id: "ref-test-001",
+    status: "FILLED",
+    amount: "25.00",
+    currency: "USDC",
+    filled_amount: "25.00",
+    ...overrides,
+  };
+}
+
+// TOP OF FILE - shared across ALL describes
+let pool: PGlite;
+let db: PlatformDb;
+
+beforeAll(async () => {
+  ({ db, pool } = await createTestDb());
+});
+
+afterAll(async () => {
+  await pool.close();
+});
+
+describe("handlePayRamWebhook", () => {
+  let chargeStore: PayRamChargeRepository;
+  let creditLedger: CreditLedger;
+  let deps: PayRamWebhookDeps;
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    chargeStore = new PayRamChargeRepository(db);
+    creditLedger = new CreditLedger(db);
+    deps = { chargeStore, creditLedger, replayGuard: noOpReplayGuard };
+
+    // Create a default test charge
+    await chargeStore.create("ref-test-001", "tenant-a", 2500);
+  });
+
+  // ---------------------------------------------------------------------------
+  // FILLED / OVER_FILLED — should credit ledger
+  // ---------------------------------------------------------------------------
+
+  describe("FILLED status", () => {
+    it("credits the ledger with the requested USD amount", async () => {
+      const result = await handlePayRamWebhook(deps, makePayload({ status: "FILLED" }));
+
+      expect(result.handled).toBe(true);
+      expect(result.status).toBe("FILLED");
+      expect(result.tenant).toBe("tenant-a");
+      expect(result.creditedCents).toBe(2500);
+
+      const balance = await creditLedger.balance("tenant-a");
+      expect(balance.toCents()).toBe(2500);
+    });
+
+    it("uses payram: prefix on reference ID in credit transaction", async () => {
+      await handlePayRamWebhook(deps, makePayload({ status: "FILLED" }));
+
+      const history = await creditLedger.history("tenant-a");
+      expect(history).toHaveLength(1);
+      expect(history[0].referenceId).toBe("payram:ref-test-001");
+      expect(history[0].type).toBe("purchase");
+    });
+
+    it("records fundingSource as payram", async () => {
+      await handlePayRamWebhook(deps, makePayload({ status: "FILLED" }));
+
+      const history = await creditLedger.history("tenant-a");
+      expect(history[0].fundingSource).toBe("payram");
+    });
+
+    it("marks the charge as credited after FILLED", async () => {
+      await handlePayRamWebhook(deps, makePayload({ status: "FILLED" }));
+      expect(await chargeStore.isCredited("ref-test-001")).toBe(true);
+    });
+
+    it("is idempotent — duplicate FILLED webhook does not double-credit", async () => {
+      await handlePayRamWebhook(deps, makePayload({ status: "FILLED" }));
+      const result2 = await handlePayRamWebhook(deps, makePayload({ status: "FILLED" }));
+
+      expect(result2.handled).toBe(true);
+      expect(result2.creditedCents).toBe(0);
+
+      const balance = await creditLedger.balance("tenant-a");
+      expect(balance.toCents()).toBe(2500); // Only credited once
+    });
+  });
+
+  describe("OVER_FILLED status", () => {
+    it("credits the requested USD amount (not the overpayment)", async () => {
+      await chargeStore.create("ref-over-001", "tenant-b", 1000);
+
+      const result = await handlePayRamWebhook(
+        deps,
+        makePayload({
+          reference_id: "ref-over-001",
+          status: "OVER_FILLED",
+          filled_amount: "12.50", // Overpaid by $2.50
+          currency: "ETH",
+        }),
+      );
+
+      expect(result.handled).toBe(true);
+      expect(result.creditedCents).toBe(1000); // Only the requested amount
+      expect((await creditLedger.balance("tenant-b")).toCents()).toBe(1000);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Statuses that should NOT credit the ledger
+  // ---------------------------------------------------------------------------
+
+  describe("PARTIALLY_FILLED status", () => {
+    it("does NOT credit the ledger", async () => {
+      const result = await handlePayRamWebhook(deps, makePayload({ status: "PARTIALLY_FILLED" }));
+
+      expect(result.handled).toBe(true);
+      expect(result.tenant).toBe("tenant-a");
+      expect(result.creditedCents).toBeUndefined();
+      expect((await creditLedger.balance("tenant-a")).toCents()).toBe(0);
+    });
+  });
+
+  describe("VERIFYING status", () => {
+    it("does NOT credit the ledger", async () => {
+      const result = await handlePayRamWebhook(deps, makePayload({ status: "VERIFYING" }));
+
+      expect(result.handled).toBe(true);
+      expect(result.creditedCents).toBeUndefined();
+      expect((await creditLedger.balance("tenant-a")).toCents()).toBe(0);
+    });
+  });
+
+  describe("OPEN status", () => {
+    it("does NOT credit the ledger", async () => {
+      const result = await handlePayRamWebhook(deps, makePayload({ status: "OPEN" }));
+
+      expect(result.handled).toBe(true);
+      expect(result.creditedCents).toBeUndefined();
+      expect((await creditLedger.balance("tenant-a")).toCents()).toBe(0);
+    });
+  });
+
+  describe("CANCELLED status", () => {
+    it("does NOT credit the ledger", async () => {
+      const result = await handlePayRamWebhook(deps, makePayload({ status: "CANCELLED" }));
+
+      expect(result.handled).toBe(true);
+      expect(result.creditedCents).toBeUndefined();
+      expect((await creditLedger.balance("tenant-a")).toCents()).toBe(0);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Unknown reference ID
+  // ---------------------------------------------------------------------------
+
+  describe("unknown reference_id", () => {
+    it("returns handled:false when charge not found", async () => {
+      const result = await handlePayRamWebhook(deps, makePayload({ reference_id: "ref-unknown-999" }));
+
+      expect(result.handled).toBe(false);
+      expect(result.tenant).toBeUndefined();
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Charge store updates
+  // ---------------------------------------------------------------------------
+
+  describe("charge store updates", () => {
+    it("updates charge status on every webhook call", async () => {
+      await handlePayRamWebhook(deps, makePayload({ status: "VERIFYING" }));
+
+      const charge = await chargeStore.getByReferenceId("ref-test-001");
+      expect(charge?.status).toBe("VERIFYING");
+    });
+
+    it("updates currency and filled_amount on FILLED", async () => {
+      await handlePayRamWebhook(deps, makePayload({ status: "FILLED", currency: "USDT", filled_amount: "25.00" }));
+
+      const charge = await chargeStore.getByReferenceId("ref-test-001");
+      expect(charge?.currency).toBe("USDT");
+      expect(charge?.filledAmount).toBe("25.00");
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Multiple tenants / reference IDs
+  // ---------------------------------------------------------------------------
+
+  describe("different reference IDs", () => {
+    it("processes multiple reference IDs independently", async () => {
+      await chargeStore.create("ref-b-001", "tenant-b", 5000);
+      await chargeStore.create("ref-c-001", "tenant-c", 1500);
+
+      await handlePayRamWebhook(deps, makePayload({ reference_id: "ref-b-001", status: "FILLED" }));
+      await handlePayRamWebhook(deps, makePayload({ reference_id: "ref-c-001", status: "FILLED" }));
+
+      expect((await creditLedger.balance("tenant-b")).toCents()).toBe(5000);
+      expect((await creditLedger.balance("tenant-c")).toCents()).toBe(1500);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Replay guard
+  // ---------------------------------------------------------------------------
+
+  describe("replay guard", () => {
+    it("blocks duplicate reference_id + status combos", async () => {
+      const replayGuard = new DrizzleWebhookSeenRepository(db);
+      const depsWithGuard: PayRamWebhookDeps = { ...deps, replayGuard };
+
+      const first = await handlePayRamWebhook(depsWithGuard, makePayload({ status: "FILLED" }));
+      expect(first.handled).toBe(true);
+      expect(first.creditedCents).toBe(2500);
+      expect(first.duplicate).toBeUndefined();
+
+      const second = await handlePayRamWebhook(depsWithGuard, makePayload({ status: "FILLED" }));
+      expect(second.handled).toBe(true);
+      expect(second.duplicate).toBe(true);
+      expect(second.creditedCents).toBeUndefined();
+
+      // Only credited once
+      expect((await creditLedger.balance("tenant-a")).toCents()).toBe(2500);
+    });
+
+    it("same reference_id with different status is not blocked by replay guard", async () => {
+      const replayGuard = new DrizzleWebhookSeenRepository(db);
+      const depsWithGuard: PayRamWebhookDeps = { ...deps, replayGuard };
+
+      await handlePayRamWebhook(depsWithGuard, makePayload({ status: "VERIFYING" }));
+      const result = await handlePayRamWebhook(depsWithGuard, makePayload({ status: "FILLED" }));
+
+      expect(result.duplicate).toBeUndefined();
+      expect(result.creditedCents).toBe(2500);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Bot reactivation
+  // ---------------------------------------------------------------------------
+
+  describe("resource reactivation via onCreditsPurchased", () => {
+    it("calls onCreditsPurchased on FILLED and includes reactivatedBots in result", async () => {
+      const mockOnCreditsPurchased = vi.fn().mockResolvedValue(["bot-1", "bot-2"]);
+      const depsWithCallback: PayRamWebhookDeps = {
+        ...deps,
+        onCreditsPurchased: mockOnCreditsPurchased,
+      };
+
+      const result = await handlePayRamWebhook(depsWithCallback, makePayload({ status: "FILLED" }));
+
+      expect(mockOnCreditsPurchased).toHaveBeenCalledWith("tenant-a", creditLedger);
+      expect(result.reactivatedBots).toEqual(["bot-1", "bot-2"]);
+    });
+
+    it("does not include reactivatedBots when no resources reactivated", async () => {
+      const mockOnCreditsPurchased = vi.fn().mockResolvedValue([]);
+      const depsWithCallback: PayRamWebhookDeps = {
+        ...deps,
+        onCreditsPurchased: mockOnCreditsPurchased,
+      };
+
+      const result = await handlePayRamWebhook(depsWithCallback, makePayload({ status: "FILLED" }));
+
+      expect(result.reactivatedBots).toBeUndefined();
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DrizzleWebhookSeenRepository unit tests (replaces PayRamReplayGuard)
+// ---------------------------------------------------------------------------
+
+describe("DrizzleWebhookSeenRepository (payram replay guard)", () => {
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+  });
+
+  it("reports unseen keys as not duplicate", async () => {
+    const guard = new DrizzleWebhookSeenRepository(db);
+    expect(await guard.isDuplicate("ref-001:FILLED", "payram")).toBe(false);
+  });
+
+  it("reports seen keys as duplicate", async () => {
+    const guard = new DrizzleWebhookSeenRepository(db);
+    await guard.markSeen("ref-001:FILLED", "payram");
+    expect(await guard.isDuplicate("ref-001:FILLED", "payram")).toBe(true);
+  });
+
+  it("purges expired entries via purgeExpired", async () => {
+    const guard = new DrizzleWebhookSeenRepository(db);
+    await guard.markSeen("ref-expire:FILLED", "payram");
+    expect(await guard.isDuplicate("ref-expire:FILLED", "payram")).toBe(true);
+    // Negative TTL pushes cutoff into the future — entry is expired
+    await guard.purgeExpired(-24 * 60 * 60 * 1000);
+    expect(await guard.isDuplicate("ref-expire:FILLED", "payram")).toBe(false);
+  });
+});

package/src/billing/payram/webhook.ts

@@ -0,0 +1,97 @@
+import { Credit } from "../../credits/credit.js";
+import type { ICreditLedger } from "../../credits/credit-ledger.js";
+import type { IWebhookSeenRepository } from "../webhook-seen-repository.js";
+import type { PayRamChargeRepository } from "./charge-store.js";
+import type { PayRamWebhookPayload, PayRamWebhookResult } from "./types.js";
+
+export interface PayRamWebhookDeps {
+  chargeStore: PayRamChargeRepository;
+  creditLedger: ICreditLedger;
+  replayGuard: IWebhookSeenRepository;
+  /** Called after credits are purchased — consumer can reactivate suspended resources. Returns reactivated resource IDs. */
+  onCreditsPurchased?: (tenantId: string, ledger: ICreditLedger) => Promise<string[]>;
+}
+
+/**
+ * Process a PayRam webhook event.
+ *
+ * Only credits the ledger on FILLED or OVER_FILLED status.
+ * Uses the PayRam reference_id mapped to the stored charge record
+ * for tenant resolution and idempotency.
+ */
+export async function handlePayRamWebhook(
+  deps: PayRamWebhookDeps,
+  payload: PayRamWebhookPayload,
+): Promise<PayRamWebhookResult> {
+  const { chargeStore, creditLedger } = deps;
+
+  // Replay guard: deduplicate by reference_id + status combination.
+  const dedupeKey = `${payload.reference_id}:${payload.status}`;
+  if (await deps.replayGuard.isDuplicate(dedupeKey, "payram")) {
+    return { handled: true, status: payload.status, duplicate: true };
+  }
+
+  // Look up the charge record to find the tenant.
+  const charge = await chargeStore.getByReferenceId(payload.reference_id);
+  if (!charge) {
+    return { handled: false, status: payload.status };
+  }
+
+  // Update charge status regardless of payment state.
+  await chargeStore.updateStatus(payload.reference_id, payload.status, payload.currency, payload.filled_amount);
+
+  let result: PayRamWebhookResult;
+
+  if (payload.status === "FILLED" || payload.status === "OVER_FILLED") {
+    // Idempotency: skip if already credited.
+    if (await chargeStore.isCredited(payload.reference_id)) {
+      result = {
+        handled: true,
+        status: payload.status,
+        tenant: charge.tenantId,
+        creditedCents: 0,
+      };
+    } else {
+      // Credit the original USD amount requested (not the crypto amount).
+      // For OVER_FILLED, we still credit the requested amount — the
+      // overpayment stays in the PayRam wallet as a buffer.
+      const creditCents = charge.amountUsdCents;
+
+      await creditLedger.credit(
+        charge.tenantId,
+        Credit.fromCents(creditCents),
+        "purchase",
+        `Crypto credit purchase via PayRam (ref: ${payload.reference_id}, ${payload.currency ?? "crypto"})`,
+        `payram:${payload.reference_id}`,
+        "payram",
+      );
+
+      await chargeStore.markCredited(payload.reference_id);
+
+      // Reactivate suspended resources after credit purchase.
+      let reactivatedBots: string[] | undefined;
+      if (deps.onCreditsPurchased) {
+        reactivatedBots = await deps.onCreditsPurchased(charge.tenantId, creditLedger);
+        if (reactivatedBots.length === 0) reactivatedBots = undefined;
+      }
+
+      result = {
+        handled: true,
+        status: payload.status,
+        tenant: charge.tenantId,
+        creditedCents: creditCents,
+        reactivatedBots,
+      };
+    }
+  } else {
+    // OPEN, VERIFYING, PARTIALLY_FILLED, CANCELLED — just track status.
+    result = {
+      handled: true,
+      status: payload.status,
+      tenant: charge.tenantId,
+    };
+  }
+
+  await deps.replayGuard.markSeen(dedupeKey, "payram");
+  return result;
+}

package/src/billing/stripe/cents-credits-boundary.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { CREDIT_PRICE_POINTS, getCreditAmountForPurchase } from "./credit-prices.js";
+
+/**
+ * Regression tests for the cents/credits boundary (WOP-1058).
+ *
+ * These tests verify that:
+ * 1. CreditPricePoint.amountCents values are valid USD cent amounts (not nanodollars)
+ * 2. CreditPricePoint.creditCents values are >= amountCents (bonus never negative)
+ * 3. getCreditAmountForPurchase returns creditCents (not some other unit)
+ * 4. No price point value approaches nanodollar scale (SCALE = 1_000_000_000)
+ *
+ * If any of these tests fail after a rename/refactor, a _cents field was
+ * incorrectly changed to store Credit raw units (nanodollars) instead of
+ * USD cents. See src/monetization/credits/credit-ledger.ts for naming convention.
+ */
+describe("WOP-1058: Stripe cents/credits boundary", () => {
+  it("all amountCents values are positive integers representing USD cents", () => {
+    for (const point of CREDIT_PRICE_POINTS) {
+      expect(point.amountCents).toBeGreaterThan(0);
+      expect(Number.isInteger(point.amountCents)).toBe(true);
+      // Sanity: no tier charges more than $1000 (100_000 cents)
+      expect(point.amountCents).toBeLessThanOrEqual(100_000);
+    }
+  });
+
+  it("amountCents values are never in nanodollar range (would indicate unit confusion)", () => {
+    for (const point of CREDIT_PRICE_POINTS) {
+      // Credit.SCALE = 1_000_000_000. If a value is in this range,
+      // a _cents field was mistakenly assigned a Credit.toRaw() value.
+      expect(point.amountCents).toBeLessThan(1_000_000);
+    }
+  });
+
+  it("all creditCents values are >= amountCents (bonus is non-negative)", () => {
+    for (const point of CREDIT_PRICE_POINTS) {
+      expect(point.creditCents).toBeGreaterThanOrEqual(point.amountCents);
+    }
+  });
+
+  it("creditCents values are never in nanodollar range (would indicate unit confusion)", () => {
+    for (const point of CREDIT_PRICE_POINTS) {
+      expect(point.creditCents).toBeLessThan(1_000_000);
+    }
+  });
+
+  it("getCreditAmountForPurchase returns creditCents for known tiers", () => {
+    for (const point of CREDIT_PRICE_POINTS) {
+      const result = getCreditAmountForPurchase(point.amountCents);
+      expect(result).toBe(point.creditCents);
+    }
+  });
+
+  it("getCreditAmountForPurchase returns input for unknown amounts (1:1 fallback)", () => {
+    const unknownAmount = 1234;
+    expect(getCreditAmountForPurchase(unknownAmount)).toBe(unknownAmount);
+  });
+
+  it("bonus tier percentages produce correct creditCents (not raw credit units)", () => {
+    // $25 + 2% bonus = $25.50 = 2550 cents (NOT 25_500_000_000 nanodollars)
+    const tier25 = CREDIT_PRICE_POINTS.find((p) => p.amountCents === 2500);
+    expect(tier25).not.toBeNull();
+    expect(tier25?.creditCents).toBe(2550);
+
+    // $100 + 10% bonus = $110 = 11000 cents (NOT 110_000_000_000 nanodollars)
+    const tier100 = CREDIT_PRICE_POINTS.find((p) => p.amountCents === 10000);
+    expect(tier100).not.toBeNull();
+    expect(tier100?.creditCents).toBe(11000);
+  });
+});

package/src/billing/stripe/checkout.test.ts

@@ -0,0 +1,186 @@
+import type Stripe from "stripe";
+import { describe, expect, it, vi } from "vitest";
+import { createCreditCheckoutSession, createVpsCheckoutSession } from "./checkout.js";
+import type { ITenantCustomerRepository, TenantCustomerRepository } from "./tenant-store.js";
+
+describe("createCreditCheckoutSession", () => {
+  function mockStripe(sessionCreateResult: unknown = { id: "cs_test", url: "https://checkout.stripe.com/cs_test" }) {
+    return {
+      checkout: {
+        sessions: {
+          create: vi.fn().mockResolvedValue(sessionCreateResult),
+        },
+      },
+    } as unknown as Stripe;
+  }
+
+  function mockTenantStore(existingMapping: { processor_customer_id: string } | null = null) {
+    return {
+      getByTenant: vi.fn().mockReturnValue(existingMapping),
+    } as unknown as TenantCustomerRepository;
+  }
+
+  it("creates a payment-mode checkout session", async () => {
+    const stripe = mockStripe();
+    const store = mockTenantStore();
+
+    const session = await createCreditCheckoutSession(stripe, store, {
+      tenant: "t-1",
+      priceId: "price_abc",
+      successUrl: "https://example.com/success",
+      cancelUrl: "https://example.com/cancel",
+    });
+
+    expect(session.id).toBe("cs_test");
+    expect(stripe.checkout.sessions.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mode: "payment",
+        line_items: [{ price: "price_abc", quantity: 1 }],
+        success_url: "https://example.com/success",
+        cancel_url: "https://example.com/cancel",
+        client_reference_id: "t-1",
+        metadata: expect.objectContaining({ wopr_tenant: "t-1" }),
+      }),
+    );
+  });
+
+  it("reuses existing Stripe customer when available", async () => {
+    const stripe = mockStripe();
+    const store = mockTenantStore({ processor_customer_id: "cus_existing" });
+
+    await createCreditCheckoutSession(stripe, store, {
+      tenant: "t-1",
+      priceId: "price_abc",
+      successUrl: "https://example.com/s",
+      cancelUrl: "https://example.com/c",
+    });
+
+    expect(stripe.checkout.sessions.create).toHaveBeenCalledWith(expect.objectContaining({ customer: "cus_existing" }));
+  });
+
+  it("does not set customer when no existing mapping", async () => {
+    const stripe = mockStripe();
+    const store = mockTenantStore(null);
+
+    await createCreditCheckoutSession(stripe, store, {
+      tenant: "t-new",
+      priceId: "price_abc",
+      successUrl: "https://example.com/s",
+      cancelUrl: "https://example.com/c",
+    });
+
+    const callArgs = (stripe.checkout.sessions.create as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(callArgs.customer).toBeUndefined();
+  });
+
+  it("propagates Stripe API errors", async () => {
+    const stripe = mockStripe();
+    (stripe.checkout.sessions.create as ReturnType<typeof vi.fn>).mockRejectedValue(new Error("Stripe error"));
+    const store = mockTenantStore();
+
+    await expect(
+      createCreditCheckoutSession(stripe, store, {
+        tenant: "t-1",
+        priceId: "price_abc",
+        successUrl: "https://example.com/s",
+        cancelUrl: "https://example.com/c",
+      }),
+    ).rejects.toThrow("Stripe error");
+  });
+});
+
+describe("createVpsCheckoutSession", () => {
+  function mockStripe(
+    sessionCreateResult: unknown = { id: "cs_vps_test", url: "https://checkout.stripe.com/cs_vps_test" },
+  ) {
+    return {
+      checkout: {
+        sessions: {
+          create: vi.fn().mockResolvedValue(sessionCreateResult),
+        },
+      },
+    } as unknown as Stripe;
+  }
+
+  function mockTenantStore(existingMapping: { processor_customer_id: string } | null = null) {
+    return {
+      getByTenant: vi.fn().mockReturnValue(existingMapping),
+    } as unknown as ITenantCustomerRepository;
+  }
+
+  it("creates a subscription-mode checkout session", async () => {
+    const stripe = mockStripe();
+    const store = mockTenantStore();
+
+    const session = await createVpsCheckoutSession(stripe, store, {
+      tenant: "t-1",
+      botId: "bot-abc",
+      vpsPriceId: "price_vps_15",
+      successUrl: "https://example.com/success",
+      cancelUrl: "https://example.com/cancel",
+    });
+
+    expect(session.id).toBe("cs_vps_test");
+    expect(stripe.checkout.sessions.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        mode: "subscription",
+        line_items: [{ price: "price_vps_15", quantity: 1 }],
+        success_url: "https://example.com/success",
+        cancel_url: "https://example.com/cancel",
+        client_reference_id: "t-1",
+        metadata: expect.objectContaining({
+          wopr_tenant: "t-1",
+          wopr_bot_id: "bot-abc",
+          wopr_purchase_type: "vps",
+        }),
+      }),
+    );
+  });
+
+  it("reuses existing Stripe customer when available", async () => {
+    const stripe = mockStripe();
+    const store = mockTenantStore({ processor_customer_id: "cus_existing" });
+
+    await createVpsCheckoutSession(stripe, store, {
+      tenant: "t-1",
+      botId: "bot-abc",
+      vpsPriceId: "price_vps_15",
+      successUrl: "https://example.com/s",
+      cancelUrl: "https://example.com/c",
+    });
+
+    expect(stripe.checkout.sessions.create).toHaveBeenCalledWith(expect.objectContaining({ customer: "cus_existing" }));
+  });
+
+  it("does not set customer when no existing mapping", async () => {
+    const stripe = mockStripe();
+    const store = mockTenantStore(null);
+
+    await createVpsCheckoutSession(stripe, store, {
+      tenant: "t-new",
+      botId: "bot-xyz",
+      vpsPriceId: "price_vps_15",
+      successUrl: "https://example.com/s",
+      cancelUrl: "https://example.com/c",
+    });
+
+    const callArgs = (stripe.checkout.sessions.create as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(callArgs.customer).toBeUndefined();
+  });
+
+  it("propagates Stripe API errors", async () => {
+    const stripe = mockStripe();
+    (stripe.checkout.sessions.create as ReturnType<typeof vi.fn>).mockRejectedValue(new Error("VPS Stripe error"));
+    const store = mockTenantStore();
+
+    await expect(
+      createVpsCheckoutSession(stripe, store, {
+        tenant: "t-1",
+        botId: "bot-abc",
+        vpsPriceId: "price_vps_15",
+        successUrl: "https://example.com/s",
+        cancelUrl: "https://example.com/c",
+      }),
+    ).rejects.toThrow("VPS Stripe error");
+  });
+});