@wopr-network/platform-core 1.45.0 → 1.47.0

package/src/billing/stripe/index.ts

@@ -1,3 +1,8 @@
+export type {
+  BillingPeriodSummaryRow,
+  IBillingPeriodSummaryRepository,
+} from "./billing-period-summary-repository.js";
+export { DrizzleBillingPeriodSummaryRepository } from "./billing-period-summary-repository.js";
 export { createCreditCheckoutSession, createVpsCheckoutSession } from "./checkout.js";
 export { createStripeClient, loadStripeConfig } from "./client.js";
 export type { CreditPriceMap, CreditPricePoint } from "./credit-prices.js";
@@ -8,6 +13,8 @@ export {
   loadCreditPriceMap,
   lookupCreditPrice,
 } from "./credit-prices.js";
+export type { MeteredPriceConfig, MeteredPriceMap } from "./metered-price-map.js";
+export { loadMeteredPriceMap } from "./metered-price-map.js";
 export type { DetachPaymentMethodOpts } from "./payment-methods.js";
 export { detachAllPaymentMethods, detachPaymentMethod } from "./payment-methods.js";
 export { createPortalSession } from "./portal.js";
@@ -15,6 +22,8 @@ export type { SetupIntentOpts } from "./setup-intent.js";
 export { createSetupIntent } from "./setup-intent.js";
 export type { StripePaymentProcessorDeps, StripeWebhookHandlerResult } from "./stripe-payment-processor.js";
 export { StripePaymentProcessor } from "./stripe-payment-processor.js";
+export type { StripeUsageReconciliationConfig, UsageReconciliationResult } from "./stripe-usage-reconciliation.js";
+export { runStripeUsageReconciliation } from "./stripe-usage-reconciliation.js";
 export type { ITenantCustomerRepository } from "./tenant-store.js";
 export { DrizzleTenantCustomerRepository, TenantCustomerRepository } from "./tenant-store.js";
 export type {
@@ -24,3 +33,11 @@ export type {
   TenantCustomerRow,
   VpsCheckoutOpts,
 } from "./types.js";
+export type {
+  IStripeUsageReportRepository,
+  StripeUsageReportInsert,
+  StripeUsageReportRow,
+} from "./usage-report-repository.js";
+export { DrizzleStripeUsageReportRepository } from "./usage-report-repository.js";
+export type { UsageReportResult, UsageReportWriterConfig } from "./usage-report-writer.js";
+export { runUsageReportWriter } from "./usage-report-writer.js";

package/src/billing/stripe/metered-price-map.ts

@@ -0,0 +1,95 @@
+/**
+ * Metered billing price configuration.
+ *
+ * Maps capability names to their Stripe Billing Meter event names.
+ * Stripe v20 uses the Billing Meters API (stripe.billing.meterEvents.create)
+ * instead of the legacy subscriptionItems.createUsageRecord API.
+ *
+ * Pattern follows loadCreditPriceMap() in credit-prices.ts.
+ */
+
+/** Maps capability name to its metered Stripe configuration. */
+export interface MeteredPriceConfig {
+  /** Stripe Billing Meter event name (e.g., "chat_completions_usage"). */
+  eventName: string;
+  /** Stripe Billing Meter ID for reconciliation lookups (e.g., mtr_xxx). Optional. */
+  meterId?: string;
+}
+
+/** Maps capability name to MeteredPriceConfig. */
+export type MeteredPriceMap = ReadonlyMap<string, MeteredPriceConfig>;
+
+const METERED_CAPABILITIES: Array<{
+  capability: string;
+  eventEnvVar: string;
+  meterEnvVar: string;
+  defaultEvent: string;
+}> = [
+  {
+    capability: "chat-completions",
+    eventEnvVar: "STRIPE_METERED_EVENT_CHAT",
+    meterEnvVar: "STRIPE_METERED_METER_CHAT",
+    defaultEvent: "chat_completions_usage",
+  },
+  {
+    capability: "tts",
+    eventEnvVar: "STRIPE_METERED_EVENT_TTS",
+    meterEnvVar: "STRIPE_METERED_METER_TTS",
+    defaultEvent: "tts_usage",
+  },
+  {
+    capability: "transcription",
+    eventEnvVar: "STRIPE_METERED_EVENT_TRANSCRIPTION",
+    meterEnvVar: "STRIPE_METERED_METER_TRANSCRIPTION",
+    defaultEvent: "transcription_usage",
+  },
+  {
+    capability: "image-generation",
+    eventEnvVar: "STRIPE_METERED_EVENT_IMAGE",
+    meterEnvVar: "STRIPE_METERED_METER_IMAGE",
+    defaultEvent: "image_generation_usage",
+  },
+  {
+    capability: "embeddings",
+    eventEnvVar: "STRIPE_METERED_EVENT_EMBEDDINGS",
+    meterEnvVar: "STRIPE_METERED_METER_EMBEDDINGS",
+    defaultEvent: "embeddings_usage",
+  },
+  {
+    capability: "phone-inbound",
+    eventEnvVar: "STRIPE_METERED_EVENT_PHONE_IN",
+    meterEnvVar: "STRIPE_METERED_METER_PHONE_IN",
+    defaultEvent: "phone_inbound_usage",
+  },
+  {
+    capability: "phone-outbound",
+    eventEnvVar: "STRIPE_METERED_EVENT_PHONE_OUT",
+    meterEnvVar: "STRIPE_METERED_METER_PHONE_OUT",
+    defaultEvent: "phone_outbound_usage",
+  },
+  {
+    capability: "sms",
+    eventEnvVar: "STRIPE_METERED_EVENT_SMS",
+    meterEnvVar: "STRIPE_METERED_METER_SMS",
+    defaultEvent: "sms_usage",
+  },
+];
+
+/**
+ * Load metered price mappings from environment variables.
+ *
+ * Returns a Map from capability name -> MeteredPriceConfig.
+ * All capabilities are included with default event names.
+ * meterId is only populated when the env var is set.
+ */
+export function loadMeteredPriceMap(): MeteredPriceMap {
+  const map = new Map<string, MeteredPriceConfig>();
+
+  for (const { capability, eventEnvVar, meterEnvVar, defaultEvent } of METERED_CAPABILITIES) {
+    const eventName = process.env[eventEnvVar] ?? defaultEvent;
+    const meterId = process.env[meterEnvVar];
+    map.set(capability, { eventName, ...(meterId ? { meterId } : {}) });
+  }
+
+  return map;
+}

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

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

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

@@ -0,0 +1,127 @@
+import crypto from "node:crypto";
+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 { runStripeUsageReconciliation } from "./stripe-usage-reconciliation.js";
+import { DrizzleStripeUsageReportRepository } from "./usage-report-repository.js";
+
+vi.mock("../../config/logger.js", () => ({
+  logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn(), debug: vi.fn() },
+}));
+
+describe("runStripeUsageReconciliation", () => {
+  let db: PlatformDb;
+  let pool: import("@electric-sql/pglite").PGlite;
+  let reportRepo: DrizzleStripeUsageReportRepository;
+
+  const NOW = Date.now();
+
+  beforeAll(async () => {
+    const t = await createTestDb();
+    pool = t.pool;
+    db = t.db;
+    reportRepo = new DrizzleStripeUsageReportRepository(db);
+  });
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    vi.clearAllMocks();
+  });
+
+  afterAll(async () => {
+    await pool.close();
+  });
+
+  it("returns empty result when no local reports exist", async () => {
+    const mockStripe = {
+      billing: {
+        meters: { listEventSummaries: vi.fn().mockResolvedValue({ data: [] }) },
+      },
+    } as unknown as import("stripe").default;
+
+    const result = await runStripeUsageReconciliation({
+      stripe: mockStripe,
+      usageReportRepo: reportRepo,
+      targetDate: new Date().toISOString().slice(0, 10),
+      flagThresholdCents: 10,
+    });
+
+    expect(result.tenantsChecked).toBe(0);
+    expect(result.discrepancies).toEqual([]);
+  });
+
+  it("detects drift when local valueCents differs from Stripe aggregated_value", async () => {
+    await reportRepo.insert({
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      capability: "chat-completions",
+      provider: "openrouter",
+      periodStart: 1700000000000,
+      periodEnd: 1700003600000,
+      eventName: "chat_completions_usage",
+      valueCents: 100,
+      reportedAt: NOW,
+    });
+
+    // Stripe says it only received 80
+    const mockStripe = {
+      billing: {
+        meters: {
+          listEventSummaries: vi.fn().mockResolvedValue({
+            data: [{ aggregated_value: 80 }],
+          }),
+        },
+      },
+    } as unknown as import("stripe").default;
+
+    const targetDate = new Date(NOW).toISOString().slice(0, 10);
+    // meterLookup returns "meterId:customerId"
+    const result = await runStripeUsageReconciliation({
+      stripe: mockStripe,
+      usageReportRepo: reportRepo,
+      meterLookup: vi.fn().mockResolvedValue({ meterId: "mtr_123", customerId: "cus_t1" }),
+      targetDate,
+      flagThresholdCents: 10,
+    });
+
+    expect(result.discrepancies).toHaveLength(1);
+    expect(result.discrepancies[0].driftCents).toBe(20);
+    expect(result.flagged).toContain("t1");
+  });
+
+  it("no discrepancy when values match", async () => {
+    await reportRepo.insert({
+      id: crypto.randomUUID(),
+      tenant: "t1",
+      capability: "chat-completions",
+      provider: "openrouter",
+      periodStart: 1700000000000,
+      periodEnd: 1700003600000,
+      eventName: "chat_completions_usage",
+      valueCents: 100,
+      reportedAt: NOW,
+    });
+
+    const mockStripe = {
+      billing: {
+        meters: {
+          listEventSummaries: vi.fn().mockResolvedValue({
+            data: [{ aggregated_value: 100 }],
+          }),
+        },
+      },
+    } as unknown as import("stripe").default;
+
+    const targetDate = new Date(NOW).toISOString().slice(0, 10);
+    const result = await runStripeUsageReconciliation({
+      stripe: mockStripe,
+      usageReportRepo: reportRepo,
+      meterLookup: vi.fn().mockResolvedValue({ meterId: "mtr_123", customerId: "cus_t1" }),
+      targetDate,
+      flagThresholdCents: 10,
+    });
+
+    expect(result.discrepancies).toHaveLength(0);
+    expect(result.flagged).toHaveLength(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)));
+  }
+}