@wopr-network/platform-core 1.45.0 → 1.46.0

package/src/billing/stripe/stripe-usage-reconciliation.ts

@@ -0,0 +1,129 @@
+import type Stripe from "stripe";
+import { logger } from "../../config/logger.js";
+import type { IStripeUsageReportRepository, StripeUsageReportRow } from "./usage-report-repository.js";
+
+export interface StripeUsageReconciliationConfig {
+  stripe: Stripe;
+  usageReportRepo: IStripeUsageReportRepository;
+  /** Date to reconcile, as YYYY-MM-DD. */
+  targetDate: string;
+  /** Drift threshold in cents before flagging a tenant. Default: 10. */
+  flagThresholdCents?: number;
+  /**
+   * Lookup function: (tenant, eventName) -> { meterId, customerId } | null.
+   * Used to look up the meter and customer for listEventSummaries.
+   */
+  meterLookup?: (tenant: string, eventName: string) => Promise<{ meterId: string; customerId: string } | null>;
+}
+
+export interface UsageReconciliationResult {
+  date: string;
+  tenantsChecked: number;
+  discrepancies: Array<{
+    tenant: string;
+    capability: string;
+    localValueCents: number;
+    stripeQuantity: number;
+    driftCents: number;
+  }>;
+  flagged: string[];
+}
+
+export async function runStripeUsageReconciliation(
+  cfg: StripeUsageReconciliationConfig,
+): Promise<UsageReconciliationResult> {
+  const threshold = cfg.flagThresholdCents ?? 10;
+  const dayStart = new Date(`${cfg.targetDate}T00:00:00Z`).getTime();
+  const dayEnd = dayStart + 24 * 60 * 60 * 1000;
+
+  const result: UsageReconciliationResult = {
+    date: cfg.targetDate,
+    tenantsChecked: 0,
+    discrepancies: [],
+    flagged: [],
+  };
+
+  // Get all local reports for this day (by reportedAt — when we submitted to Stripe)
+  const localReports = await cfg.usageReportRepo.listAll({ since: dayStart, until: dayEnd });
+
+  if (localReports.length === 0) return result;
+
+  // Group by tenant+capability+eventName so each distinct meter is reconciled separately
+  const grouped = new Map<string, StripeUsageReportRow[]>();
+  for (const report of localReports) {
+    const key = `${report.tenant}:${report.capability}:${report.eventName}`;
+    const arr = grouped.get(key) ?? [];
+    arr.push(report);
+    grouped.set(key, arr);
+  }
+
+  const checkedTenants = new Set<string>();
+
+  for (const [key, reports] of grouped) {
+    const parts = key.split(":");
+    const tenant = parts[0];
+    const capability = parts[1];
+    checkedTenants.add(tenant);
+
+    const localTotal = reports.reduce((sum, r) => sum + r.valueCents, 0);
+
+    // Need a customer ID and meter lookup to reconcile against Stripe
+    if (!cfg.meterLookup) continue;
+
+    const eventName = reports[0]?.eventName;
+    if (!eventName) continue;
+
+    const lookup = await cfg.meterLookup(tenant, eventName);
+    if (!lookup) {
+      logger.warn("Cannot reconcile: no meter ID for tenant+capability", { tenant, capability });
+      continue;
+    }
+
+    const { meterId: resolvedMeterId, customerId } = lookup;
+
+    try {
+      const startSec = Math.floor(dayStart / 1000);
+      const endSec = Math.floor(dayEnd / 1000);
+
+      const summaries = await cfg.stripe.billing.meters.listEventSummaries(resolvedMeterId, {
+        customer: customerId,
+        start_time: startSec,
+        end_time: endSec,
+        limit: 1,
+      });
+
+      const stripeTotal = summaries.data[0]?.aggregated_value ?? 0;
+      const drift = Math.abs(localTotal - stripeTotal);
+
+      if (drift > 0) {
+        result.discrepancies.push({
+          tenant,
+          capability,
+          localValueCents: localTotal,
+          stripeQuantity: stripeTotal,
+          driftCents: drift,
+        });
+
+        if (drift >= threshold) {
+          if (!result.flagged.includes(tenant)) {
+            result.flagged.push(tenant);
+          }
+          logger.warn("Stripe usage reconciliation: drift exceeds threshold", {
+            tenant,
+            capability,
+            localTotal,
+            stripeTotal,
+            drift,
+            threshold,
+          });
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.error("Failed to reconcile Stripe usage", { tenant, capability, error: msg });
+    }
+  }
+
+  result.tenantsChecked = checkedTenants.size;
+  return result;
+}

package/src/billing/stripe/tenant-store.ts

@@ -14,6 +14,7 @@ export interface ITenantCustomerRepository {
   setInferenceMode(tenant: string, mode: string): Promise<void>;
   list(): Promise<TenantCustomerRow[]>;
   buildCustomerIdMap(): Promise<Record<string, string>>;
+  listMetered(): Promise<Array<{ tenant: string; processorCustomerId: string }>>;
 }
 
 /**
@@ -116,6 +117,14 @@ export class DrizzleTenantCustomerRepository implements ITenantCustomerRepositor
     return rows.map(mapRow);
   }
 
+  /** Return all tenants with inferenceMode === "metered". */
+  async listMetered(): Promise<Array<{ tenant: string; processorCustomerId: string }>> {
+    return this.db
+      .select({ tenant: tenantCustomers.tenant, processorCustomerId: tenantCustomers.processorCustomerId })
+      .from(tenantCustomers)
+      .where(eq(tenantCustomers.inferenceMode, "metered"));
+  }
+
   /** Build a tenant -> processor_customer_id map for use with UsageAggregationWorker. */
   async buildCustomerIdMap(): Promise<Record<string, string>> {
     const rows = await this.db

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

@@ -0,0 +1,87 @@
+import crypto from "node:crypto";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { DrizzleStripeUsageReportRepository } from "./usage-report-repository.js";
+
+describe("DrizzleStripeUsageReportRepository", () => {
+  let db: PlatformDb;
+  let pool: import("@electric-sql/pglite").PGlite;
+  let repo: DrizzleStripeUsageReportRepository;
+
+  beforeAll(async () => {
+    const t = await createTestDb();
+    pool = t.pool;
+    db = t.db;
+    repo = new DrizzleStripeUsageReportRepository(db);
+  });
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  it("inserts a usage report row", async () => {
+    const row = {
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      capability: "chat-completions",
+      provider: "openrouter",
+      periodStart: 1700000000000,
+      periodEnd: 1700003600000,
+      eventName: "chat_completions_usage",
+      valueCents: 150,
+      reportedAt: Date.now(),
+    };
+    await repo.insert(row);
+    const found = await repo.getByTenantAndPeriod("t1", "chat-completions", "openrouter", 1700000000000);
+    expect(found).toBeTruthy();
+    expect(found?.valueCents).toBe(150);
+  });
+
+  it("returns null for non-existent report", async () => {
+    const found = await repo.getByTenantAndPeriod("t1", "chat-completions", "openrouter", 1700000000000);
+    expect(found).toBeNull();
+  });
+
+  it("rejects duplicate (tenant, capability, provider, periodStart)", async () => {
+    const base = {
+      tenant: "t1",
+      capability: "chat-completions",
+      provider: "openrouter",
+      periodStart: 1700000000000,
+      periodEnd: 1700003600000,
+      eventName: "chat_completions_usage",
+      valueCents: 100,
+      reportedAt: Date.now(),
+    };
+    await repo.insert({ ...base, id: crypto.randomUUID() });
+    await expect(repo.insert({ ...base, id: crypto.randomUUID() })).rejects.toThrow();
+  });
+
+  it("lists reports for a tenant in a date range", async () => {
+    const base = {
+      tenant: "t1",
+      capability: "chat-completions",
+      provider: "openrouter",
+      eventName: "chat_completions_usage",
+      valueCents: 50,
+    };
+    await repo.insert({ ...base, id: crypto.randomUUID(), periodStart: 100, periodEnd: 200, reportedAt: 300 });
+    await repo.insert({ ...base, id: crypto.randomUUID(), periodStart: 200, periodEnd: 300, reportedAt: 400 });
+    await repo.insert({
+      ...base,
+      id: crypto.randomUUID(),
+      periodStart: 300,
+      periodEnd: 400,
+      reportedAt: 500,
+      tenant: "t2",
+    });
+
+    const results = await repo.listByTenant("t1", { since: 0, until: 500 });
+    expect(results).toHaveLength(2);
+  });
+});

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

@@ -0,0 +1,77 @@
+import { and, eq, gte, lt } from "drizzle-orm";
+import type { PlatformDb } from "../../db/index.js";
+import { stripeUsageReports } from "../../db/schema/tenant-customers.js";
+
+export interface StripeUsageReportRow {
+  id: string;
+  tenant: string;
+  capability: string;
+  provider: string;
+  periodStart: number;
+  periodEnd: number;
+  eventName: string;
+  valueCents: number;
+  reportedAt: number;
+}
+
+export type StripeUsageReportInsert = StripeUsageReportRow;
+
+export interface IStripeUsageReportRepository {
+  insert(row: StripeUsageReportInsert): Promise<void>;
+  getByTenantAndPeriod(
+    tenant: string,
+    capability: string,
+    provider: string,
+    periodStart: number,
+  ): Promise<StripeUsageReportRow | null>;
+  listByTenant(tenant: string, opts: { since: number; until: number }): Promise<StripeUsageReportRow[]>;
+  listAll(opts: { since: number; until: number }): Promise<StripeUsageReportRow[]>;
+}
+
+export class DrizzleStripeUsageReportRepository implements IStripeUsageReportRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  async insert(row: StripeUsageReportInsert): Promise<void> {
+    await this.db.insert(stripeUsageReports).values(row);
+  }
+
+  async getByTenantAndPeriod(
+    tenant: string,
+    capability: string,
+    provider: string,
+    periodStart: number,
+  ): Promise<StripeUsageReportRow | null> {
+    const rows = await this.db
+      .select()
+      .from(stripeUsageReports)
+      .where(
+        and(
+          eq(stripeUsageReports.tenant, tenant),
+          eq(stripeUsageReports.capability, capability),
+          eq(stripeUsageReports.provider, provider),
+          eq(stripeUsageReports.periodStart, periodStart),
+        ),
+      );
+    return rows[0] ?? null;
+  }
+
+  async listByTenant(tenant: string, opts: { since: number; until: number }): Promise<StripeUsageReportRow[]> {
+    return this.db
+      .select()
+      .from(stripeUsageReports)
+      .where(
+        and(
+          eq(stripeUsageReports.tenant, tenant),
+          gte(stripeUsageReports.reportedAt, opts.since),
+          lt(stripeUsageReports.reportedAt, opts.until),
+        ),
+      );
+  }
+
+  async listAll(opts: { since: number; until: number }): Promise<StripeUsageReportRow[]> {
+    return this.db
+      .select()
+      .from(stripeUsageReports)
+      .where(and(gte(stripeUsageReports.reportedAt, opts.since), lt(stripeUsageReports.reportedAt, opts.until)));
+  }
+}

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;
+}