@wopr-network/platform-core 1.45.0 → 1.47.0

package/src/billing/stripe/usage-report-writer.test.ts

@@ -0,0 +1,194 @@
+import crypto from "node:crypto";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { Credit } from "../../credits/credit.js";
+import type { PlatformDb } from "../../db/index.js";
+import { billingPeriodSummaries } from "../../db/schema/meter-events.js";
+import { tenantCustomers } from "../../db/schema/tenant-customers.js";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { DrizzleBillingPeriodSummaryRepository } from "./billing-period-summary-repository.js";
+import type { MeteredPriceConfig } from "./metered-price-map.js";
+import { DrizzleTenantCustomerRepository } from "./tenant-store.js";
+import { DrizzleStripeUsageReportRepository } from "./usage-report-repository.js";
+import { runUsageReportWriter } from "./usage-report-writer.js";
+
+vi.mock("../../config/logger.js", () => ({
+  logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn(), debug: vi.fn() },
+}));
+
+describe("runUsageReportWriter", () => {
+  let db: PlatformDb;
+  let pool: import("@electric-sql/pglite").PGlite;
+  let reportRepo: DrizzleStripeUsageReportRepository;
+  let tenantRepo: DrizzleTenantCustomerRepository;
+  let billingPeriodSummaryRepo: DrizzleBillingPeriodSummaryRepository;
+
+  const NOW = Date.now();
+  const PERIOD_START = 1700000000000;
+  const PERIOD_END = 1700003600000;
+
+  const mockCreateMeterEvent = vi.fn().mockResolvedValue({ identifier: "evt_xxx" });
+
+  const mockStripe = {
+    billing: {
+      meterEvents: { create: mockCreateMeterEvent },
+    },
+  } as unknown as import("stripe").default;
+
+  const priceMap = new Map<string, MeteredPriceConfig>([["chat-completions", { eventName: "chat_completions_usage" }]]);
+
+  beforeAll(async () => {
+    const t = await createTestDb();
+    pool = t.pool;
+    db = t.db;
+    reportRepo = new DrizzleStripeUsageReportRepository(db);
+    tenantRepo = new DrizzleTenantCustomerRepository(db);
+    billingPeriodSummaryRepo = new DrizzleBillingPeriodSummaryRepository(db);
+  });
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    vi.clearAllMocks();
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  async function seedMeteredTenant(tenant: string) {
+    await db.insert(tenantCustomers).values({
+      tenant,
+      processorCustomerId: `cus_${tenant}`,
+      processor: "stripe",
+      inferenceMode: "metered",
+      createdAt: NOW,
+      updatedAt: NOW,
+    });
+  }
+
+  async function seedBillingPeriod(tenant: string, opts?: { capability?: string; totalCharge?: number }) {
+    await db.insert(billingPeriodSummaries).values({
+      id: crypto.randomUUID(),
+      tenant,
+      capability: opts?.capability ?? "chat-completions",
+      provider: "openrouter",
+      eventCount: 10,
+      totalCost: opts?.totalCharge ?? Credit.fromCents(100).toRaw(),
+      totalCharge: opts?.totalCharge ?? Credit.fromCents(100).toRaw(),
+      totalDuration: 0,
+      periodStart: PERIOD_START,
+      periodEnd: PERIOD_END,
+      updatedAt: NOW,
+    });
+  }
+
+  it("reports usage for metered tenants to Stripe and inserts local record", async () => {
+    await seedMeteredTenant("t1");
+    await seedBillingPeriod("t1");
+
+    const result = await runUsageReportWriter({
+      stripe: mockStripe,
+      tenantRepo,
+      billingPeriodSummaryRepo,
+      usageReportRepo: reportRepo,
+      meteredPriceMap: priceMap,
+      periodStart: PERIOD_START,
+      periodEnd: PERIOD_END,
+    });
+
+    expect(result.reportsCreated).toBe(1);
+    expect(result.errors).toHaveLength(0);
+    expect(mockCreateMeterEvent).toHaveBeenCalledOnce();
+
+    const stored = await reportRepo.getByTenantAndPeriod("t1", "chat-completions", "openrouter", PERIOD_START);
+    expect(stored).toBeTruthy();
+    expect(stored?.valueCents).toBe(100);
+  });
+
+  it("skips non-metered tenants", async () => {
+    // Insert a managed-mode tenant
+    await db.insert(tenantCustomers).values({
+      tenant: "t2",
+      processorCustomerId: "cus_t2",
+      processor: "stripe",
+      inferenceMode: "managed",
+      createdAt: NOW,
+      updatedAt: NOW,
+    });
+    await seedBillingPeriod("t2");
+
+    const result = await runUsageReportWriter({
+      stripe: mockStripe,
+      tenantRepo,
+      billingPeriodSummaryRepo,
+      usageReportRepo: reportRepo,
+      meteredPriceMap: priceMap,
+      periodStart: PERIOD_START,
+      periodEnd: PERIOD_END,
+    });
+
+    expect(result.tenantsProcessed).toBe(0);
+    expect(mockCreateMeterEvent).not.toHaveBeenCalled();
+  });
+
+  it("skips already-reported periods (idempotent)", async () => {
+    await seedMeteredTenant("t1");
+    await seedBillingPeriod("t1");
+
+    // Pre-insert a report for this period
+    await reportRepo.insert({
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      capability: "chat-completions",
+      provider: "openrouter",
+      periodStart: PERIOD_START,
+      periodEnd: PERIOD_END,
+      eventName: "chat_completions_usage",
+      valueCents: 100,
+      reportedAt: NOW,
+    });
+
+    const result = await runUsageReportWriter({
+      stripe: mockStripe,
+      tenantRepo,
+      billingPeriodSummaryRepo,
+      usageReportRepo: reportRepo,
+      meteredPriceMap: priceMap,
+      periodStart: PERIOD_START,
+      periodEnd: PERIOD_END,
+    });
+
+    expect(result.reportsSkipped).toBe(1);
+    expect(result.reportsCreated).toBe(0);
+    expect(mockCreateMeterEvent).not.toHaveBeenCalled();
+  });
+
+  it("skips zero-usage periods", async () => {
+    await seedMeteredTenant("t1");
+    await db.insert(billingPeriodSummaries).values({
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      capability: "chat-completions",
+      provider: "openrouter",
+      eventCount: 0,
+      totalCost: 0,
+      totalCharge: 0,
+      totalDuration: 0,
+      periodStart: PERIOD_START,
+      periodEnd: PERIOD_END,
+      updatedAt: NOW,
+    });
+
+    const result = await runUsageReportWriter({
+      stripe: mockStripe,
+      tenantRepo,
+      billingPeriodSummaryRepo,
+      usageReportRepo: reportRepo,
+      meteredPriceMap: priceMap,
+      periodStart: PERIOD_START,
+      periodEnd: PERIOD_END,
+    });
+
+    expect(result.reportsCreated).toBe(0);
+    expect(mockCreateMeterEvent).not.toHaveBeenCalled();
+  });
+});

package/src/billing/stripe/usage-report-writer.ts

@@ -0,0 +1,139 @@
+import crypto from "node:crypto";
+import type Stripe from "stripe";
+import { logger } from "../../config/logger.js";
+import { Credit } from "../../credits/credit.js";
+import type { IBillingPeriodSummaryRepository } from "./billing-period-summary-repository.js";
+import type { MeteredPriceConfig } from "./metered-price-map.js";
+import type { ITenantCustomerRepository } from "./tenant-store.js";
+import type { IStripeUsageReportRepository } from "./usage-report-repository.js";
+
+export interface UsageReportWriterConfig {
+  stripe: Stripe;
+  tenantRepo: ITenantCustomerRepository;
+  billingPeriodSummaryRepo: IBillingPeriodSummaryRepository;
+  usageReportRepo: IStripeUsageReportRepository;
+  meteredPriceMap: ReadonlyMap<string, MeteredPriceConfig>;
+  /** Start of the billing period to report (unix epoch ms, inclusive). */
+  periodStart: number;
+  /** End of the billing period to report (unix epoch ms, exclusive). */
+  periodEnd: number;
+}
+
+export interface UsageReportResult {
+  tenantsProcessed: number;
+  reportsCreated: number;
+  reportsSkipped: number;
+  errors: Array<{ tenant: string; capability: string; error: string }>;
+}
+
+/**
+ * Report metered usage to Stripe for all metered tenants in a given billing period.
+ *
+ * Uses Stripe's Billing Meters API (stripe.billing.meterEvents.create) — the v20
+ * replacement for the legacy subscriptionItems.createUsageRecord API.
+ *
+ * Flow:
+ * 1. Query billingPeriodSummaries for the period window
+ * 2. Filter to tenants with inferenceMode === "metered"
+ * 3. For each (tenant, capability, provider) tuple:
+ *    a. Check if already reported (idempotent via stripeUsageReports unique index)
+ *    b. Submit meter event to Stripe with idempotency identifier
+ *    c. Insert into stripeUsageReports
+ */
+export async function runUsageReportWriter(cfg: UsageReportWriterConfig): Promise<UsageReportResult> {
+  const result: UsageReportResult = {
+    tenantsProcessed: 0,
+    reportsCreated: 0,
+    reportsSkipped: 0,
+    errors: [],
+  };
+
+  // 1. Find all metered tenants
+  const meteredTenants = await cfg.tenantRepo.listMetered();
+
+  if (meteredTenants.length === 0) return result;
+
+  const meteredTenantIds = new Set(meteredTenants.map((t) => t.tenant));
+  const customerIdMap = new Map(meteredTenants.map((t) => [t.tenant, t.processorCustomerId]));
+
+  // 2. Query billing period summaries for this period
+  const summaries = await cfg.billingPeriodSummaryRepo.listByPeriodWindow(cfg.periodStart, cfg.periodEnd);
+
+  // 3. Filter to metered tenants only
+  const meteredSummaries = summaries.filter((s) => meteredTenantIds.has(s.tenant));
+
+  const processedTenants = new Set<string>();
+
+  for (const summary of meteredSummaries) {
+    const { tenant, capability, provider, totalCharge } = summary;
+
+    // Skip zero usage
+    if (totalCharge <= 0) continue;
+
+    // Skip capabilities without a metered price config
+    const priceConfig = cfg.meteredPriceMap.get(capability);
+    if (!priceConfig) continue;
+
+    processedTenants.add(tenant);
+
+    try {
+      // Check if already reported (idempotent)
+      const existing = await cfg.usageReportRepo.getByTenantAndPeriod(
+        tenant,
+        capability,
+        provider,
+        summary.periodStart,
+      );
+      if (existing) {
+        result.reportsSkipped++;
+        continue;
+      }
+
+      // Look up Stripe customer ID
+      const customerId = customerIdMap.get(tenant);
+      if (!customerId) {
+        result.errors.push({ tenant, capability, error: "No Stripe customer ID" });
+        continue;
+      }
+
+      // Convert nanodollars to cents
+      const valueCents = Credit.fromRaw(totalCharge).toCentsRounded();
+
+      // Build a stable idempotency identifier: tenant + capability + provider + periodStart
+      const identifier = `${tenant}:${capability}:${provider}:${summary.periodStart}`;
+
+      // Submit to Stripe Billing Meters API (v20+)
+      await cfg.stripe.billing.meterEvents.create({
+        event_name: priceConfig.eventName,
+        payload: {
+          stripe_customer_id: customerId,
+          value: String(valueCents),
+        },
+        identifier,
+        timestamp: Math.floor(summary.periodStart / 1000),
+      });
+
+      // Insert local record
+      await cfg.usageReportRepo.insert({
+        id: crypto.randomUUID(),
+        tenant,
+        capability,
+        provider,
+        periodStart: summary.periodStart,
+        periodEnd: summary.periodEnd,
+        eventName: priceConfig.eventName,
+        valueCents,
+        reportedAt: Date.now(),
+      });
+
+      result.reportsCreated++;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.error("Failed to report usage to Stripe", { tenant, capability, error: msg });
+      result.errors.push({ tenant, capability, error: msg });
+    }
+  }
+
+  result.tenantsProcessed = processedTenants.size;
+  return result;
+}

package/src/gateway/credit-gate.test.ts

@@ -240,3 +240,65 @@ describe("debitCredits with allowNegative and onBalanceExhausted", () => {
     expect(onBalanceExhausted).not.toHaveBeenCalled();
   });
 });
+
+// ---------------------------------------------------------------------------
+// creditBalanceCheck — metered tenant bypass
+// ---------------------------------------------------------------------------
+
+async function buildHonoContextWithMode(
+  tenantId: string,
+  inferenceMode: string,
+): Promise<import("hono").Context<GatewayAuthEnv>> {
+  let capturedCtx!: import("hono").Context<GatewayAuthEnv>;
+  const app = new Hono<GatewayAuthEnv>();
+  app.get("/test", (c) => {
+    c.set("gatewayTenant", {
+      id: tenantId,
+      spendLimits: { maxSpendPerHour: null, maxSpendPerMonth: null },
+      inferenceMode,
+    } as GatewayTenant);
+    capturedCtx = c;
+    return c.json({});
+  });
+  await app.request("/test");
+  return capturedCtx;
+}
+
+describe("creditBalanceCheck metered tenant bypass", () => {
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    await new DrizzleLedger(db).seedSystemAccounts();
+  });
+
+  it("skips balance check for metered tenants even with zero balance", async () => {
+    const ledger = new DrizzleLedger(db);
+    // No credits — would normally fail with credits_exhausted
+    const c = await buildHonoContextWithMode("metered-t1", "metered");
+    const deps: CreditGateDeps = { creditLedger: ledger, topUpUrl: "/billing" };
+    const error = await creditBalanceCheck(c, deps, 0);
+    expect(error).toBeNull();
+  });
+
+  it("still debits metered tenants for P&L tracking", async () => {
+    const ledger = new DrizzleLedger(db);
+    await ledger.credit("metered-t1", Credit.fromCents(0), "purchase", { description: "setup" }).catch(() => {});
+    const mockLedger = {
+      debit: vi.fn().mockResolvedValue(undefined),
+      balance: vi.fn(),
+      credit: vi.fn(),
+    } as unknown as import("@wopr-network/platform-core/credits").ILedger;
+    const deps: CreditGateDeps = { creditLedger: mockLedger, topUpUrl: "/billing" };
+    await debitCredits(deps, "metered-tenant", 0.05, 1.5, "chat-completions", "openrouter");
+    expect(mockLedger.debit).toHaveBeenCalled();
+  });
+
+  it("non-metered (managed) tenant still gets balance checked", async () => {
+    const ledger = new DrizzleLedger(db);
+    // No credits seeded — should fail
+    const c = await buildHonoContextWithMode("managed-t1", "managed");
+    const deps: CreditGateDeps = { creditLedger: ledger, topUpUrl: "/billing" };
+    const error = await creditBalanceCheck(c, deps, 0);
+    // Balance is 0, within grace buffer — passes
+    expect(error).toBeNull();
+  });
+});

package/src/gateway/credit-gate.ts

@@ -61,6 +61,12 @@ export async function creditBalanceCheck(
     return null;
   }
 
+  // Metered tenants are invoiced via Stripe subscription, not prepaid credits.
+  // Skip balance enforcement but still allow debit (for P&L tracking).
+  if (tenant.inferenceMode === "metered") {
+    return null;
+  }
+
   const balance = await deps.creditLedger.balance(tenant.id);
   const required = Math.max(0, estimatedCostCents);
   const graceBuffer = deps.graceBufferCents ?? 50; // default -$0.50

package/src/gateway/types.ts

@@ -57,6 +57,8 @@ export interface GatewayTenant {
   instanceId?: string;
   /** User-configured spending caps (null fields = no cap). */
   spendingCaps?: SpendingCaps;
+  /** Billing mode — "metered" tenants are invoiced via Stripe, not prepaid credits. */
+  inferenceMode?: "metered" | "managed" | "byok";
 }
 
 /** Fetch function type for dependency injection in tests. */

package/src/monetization/stripe/stripe-payment-processor.test.ts

@@ -59,6 +59,7 @@ function createMocks() {
     setInferenceMode: vi.fn(),
     list: vi.fn(),
     buildCustomerIdMap: vi.fn(),
+    listMetered: vi.fn(),
   };
 
   const creditLedger: ILedger = {

package/src/trpc/index.ts

@@ -13,3 +13,7 @@ export {
   tenantProcedure,
 } from "./init.js";
 export { createNotificationTemplateRouter } from "./notification-template-router.js";
+export {
+  createOrgRemovePaymentMethodRouter,
+  type OrgRemovePaymentMethodDeps,
+} from "./org-remove-payment-method-router.js";

package/src/trpc/org-remove-payment-method-router.test.ts

@@ -0,0 +1,188 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { IPaymentProcessor, SavedPaymentMethod } from "../billing/payment-processor.js";
+import type { AutoTopupSettings, IAutoTopupSettingsRepository } from "../credits/auto-topup-settings-repository.js";
+import type { IOrgMemberRepository } from "../tenancy/org-member-repository.js";
+import { createCallerFactory, router, setTrpcOrgMemberRepo } from "./init.js";
+import { createOrgRemovePaymentMethodRouter } from "./org-remove-payment-method-router.js";
+
+// ---------------------------------------------------------------------------
+// Mock helpers
+// ---------------------------------------------------------------------------
+
+function makeMockOrgMemberRepo(overrides?: Partial<IOrgMemberRepository>): IOrgMemberRepository {
+  return {
+    listMembers: vi.fn().mockResolvedValue([]),
+    addMember: vi.fn().mockResolvedValue(undefined),
+    updateMemberRole: vi.fn().mockResolvedValue(undefined),
+    removeMember: vi.fn().mockResolvedValue(undefined),
+    findMember: vi.fn().mockResolvedValue({ userId: "u1", role: "owner" }),
+    countAdminsAndOwners: vi.fn().mockResolvedValue(1),
+    listInvites: vi.fn().mockResolvedValue([]),
+    createInvite: vi.fn().mockResolvedValue(undefined),
+    findInviteById: vi.fn().mockResolvedValue(null),
+    findInviteByToken: vi.fn().mockResolvedValue(null),
+    deleteInvite: vi.fn().mockResolvedValue(undefined),
+    deleteAllMembers: vi.fn().mockResolvedValue(undefined),
+    deleteAllInvites: vi.fn().mockResolvedValue(undefined),
+    listOrgsByUser: vi.fn().mockResolvedValue([]),
+    markInviteAccepted: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
+function makeMockProcessor(methods: SavedPaymentMethod[]): IPaymentProcessor {
+  return {
+    name: "mock",
+    createCheckoutSession: vi.fn(),
+    handleWebhook: vi.fn(),
+    supportsPortal: vi.fn().mockReturnValue(false),
+    createPortalSession: vi.fn(),
+    setupPaymentMethod: vi.fn(),
+    listPaymentMethods: vi.fn().mockResolvedValue(methods),
+    charge: vi.fn(),
+    detachPaymentMethod: vi.fn().mockResolvedValue(undefined),
+    getCustomerEmail: vi.fn().mockResolvedValue(""),
+    updateCustomerEmail: vi.fn(),
+    listInvoices: vi.fn().mockResolvedValue([]),
+  };
+}
+
+function makeMockAutoTopupSettings(overrides?: Partial<AutoTopupSettings>): IAutoTopupSettingsRepository {
+  const settings: AutoTopupSettings | null = overrides
+    ? ({
+        tenantId: "org-1",
+        usageEnabled: false,
+        usageThreshold: { toCentsRounded: () => 0 },
+        usageTopup: { toCentsRounded: () => 0 },
+        usageConsecutiveFailures: 0,
+        usageChargeInFlight: false,
+        scheduleEnabled: false,
+        scheduleAmount: { toCentsRounded: () => 0 },
+        scheduleIntervalHours: 0,
+        scheduleNextAt: null,
+        scheduleConsecutiveFailures: 0,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        ...overrides,
+      } as AutoTopupSettings)
+    : null;
+
+  return {
+    getByTenant: vi.fn().mockResolvedValue(settings),
+    upsert: vi.fn(),
+    setUsageChargeInFlight: vi.fn(),
+    tryAcquireUsageInFlight: vi.fn(),
+    incrementUsageFailures: vi.fn(),
+    resetUsageFailures: vi.fn(),
+    disableUsage: vi.fn(),
+    incrementScheduleFailures: vi.fn(),
+    resetScheduleFailures: vi.fn(),
+    disableSchedule: vi.fn(),
+    advanceScheduleNextAt: vi.fn(),
+    listDueScheduled: vi.fn().mockResolvedValue([]),
+    getMaxConsecutiveFailures: vi.fn().mockResolvedValue(0),
+  };
+}
+
+function authedContext() {
+  return { user: { id: "u1", roles: ["user"] }, tenantId: "org-1" };
+}
+
+function unauthedContext() {
+  return { user: undefined, tenantId: undefined };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("orgRemovePaymentMethod router", () => {
+  let processor: IPaymentProcessor;
+  let autoTopupStore: IAutoTopupSettingsRepository;
+
+  beforeEach(() => {
+    processor = makeMockProcessor([{ id: "pm_1", label: "Visa ending 4242", isDefault: true }]);
+    autoTopupStore = makeMockAutoTopupSettings();
+    setTrpcOrgMemberRepo(makeMockOrgMemberRepo());
+  });
+
+  function buildCaller(deps: { processor: IPaymentProcessor; autoTopupSettingsStore?: IAutoTopupSettingsRepository }) {
+    const subRouter = createOrgRemovePaymentMethodRouter(() => ({
+      processor: deps.processor,
+      autoTopupSettingsStore: deps.autoTopupSettingsStore,
+    }));
+    const appRouter = router({ org: subRouter });
+    return createCallerFactory(appRouter);
+  }
+
+  it("successfully removes a payment method", async () => {
+    const caller = buildCaller({ processor, autoTopupSettingsStore: autoTopupStore })(authedContext());
+    const result = await caller.org.orgRemovePaymentMethod({
+      orgId: "org-1",
+      paymentMethodId: "pm_1",
+    });
+    expect(result).toEqual({ removed: true });
+    expect(processor.detachPaymentMethod).toHaveBeenCalledWith("org-1", "pm_1");
+  });
+
+  it("rejects unauthenticated users", async () => {
+    const caller = buildCaller({ processor, autoTopupSettingsStore: autoTopupStore })(unauthedContext());
+    await expect(caller.org.orgRemovePaymentMethod({ orgId: "org-1", paymentMethodId: "pm_1" })).rejects.toMatchObject({
+      code: "UNAUTHORIZED",
+    });
+  });
+
+  it("rejects when removing last PM with auto-topup usage enabled", async () => {
+    const usageStore = makeMockAutoTopupSettings({ usageEnabled: true });
+    const caller = buildCaller({
+      processor,
+      autoTopupSettingsStore: usageStore,
+    })(authedContext());
+    await expect(caller.org.orgRemovePaymentMethod({ orgId: "org-1", paymentMethodId: "pm_1" })).rejects.toMatchObject({
+      code: "FORBIDDEN",
+    });
+  });
+
+  it("rejects when removing last PM with auto-topup schedule enabled", async () => {
+    const scheduleStore = makeMockAutoTopupSettings({ scheduleEnabled: true });
+    const caller = buildCaller({
+      processor,
+      autoTopupSettingsStore: scheduleStore,
+    })(authedContext());
+    await expect(caller.org.orgRemovePaymentMethod({ orgId: "org-1", paymentMethodId: "pm_1" })).rejects.toMatchObject({
+      code: "FORBIDDEN",
+    });
+  });
+
+  it("allows removing non-last PM even with auto-topup enabled", async () => {
+    const multiProcessor = makeMockProcessor([
+      { id: "pm_1", label: "Visa ending 4242", isDefault: true },
+      { id: "pm_2", label: "Mastercard ending 5555", isDefault: false },
+    ]);
+    const usageStore = makeMockAutoTopupSettings({ usageEnabled: true });
+    const caller = buildCaller({
+      processor: multiProcessor,
+      autoTopupSettingsStore: usageStore,
+    })(authedContext());
+    const result = await caller.org.orgRemovePaymentMethod({
+      orgId: "org-1",
+      paymentMethodId: "pm_1",
+    });
+    expect(result).toEqual({ removed: true });
+  });
+
+  it("returns FORBIDDEN when detachPaymentMethod throws PaymentMethodOwnershipError", async () => {
+    const { PaymentMethodOwnershipError } = await import("../billing/payment-processor.js");
+    const ownershipErrorProcessor = makeMockProcessor([]);
+    (ownershipErrorProcessor.detachPaymentMethod as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new PaymentMethodOwnershipError(),
+    );
+    const caller = buildCaller({
+      processor: ownershipErrorProcessor,
+      autoTopupSettingsStore: autoTopupStore,
+    })(authedContext());
+    await expect(caller.org.orgRemovePaymentMethod({ orgId: "org-1", paymentMethodId: "pm_1" })).rejects.toMatchObject({
+      code: "FORBIDDEN",
+    });
+  });
+});