@wopr-network/platform-core 1.45.0 → 1.47.0

package/dist/billing/stripe/billing-period-summary-repository.d.ts

@@ -0,0 +1,22 @@
+import type { PlatformDb } from "../../db/index.js";
+export interface BillingPeriodSummaryRow {
+    id: string;
+    tenant: string;
+    capability: string;
+    provider: string;
+    eventCount: number;
+    totalCost: number;
+    totalCharge: number;
+    totalDuration: number;
+    periodStart: number;
+    periodEnd: number;
+    updatedAt: number;
+}
+export interface IBillingPeriodSummaryRepository {
+    listByPeriodWindow(start: number, end: number): Promise<BillingPeriodSummaryRow[]>;
+}
+export declare class DrizzleBillingPeriodSummaryRepository implements IBillingPeriodSummaryRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    listByPeriodWindow(start: number, end: number): Promise<BillingPeriodSummaryRow[]>;
+}

package/dist/billing/stripe/billing-period-summary-repository.js

@@ -0,0 +1,14 @@
+import { and, gte, lte } from "drizzle-orm";
+import { billingPeriodSummaries } from "../../db/schema/meter-events.js";
+export class DrizzleBillingPeriodSummaryRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async listByPeriodWindow(start, end) {
+        return this.db
+            .select()
+            .from(billingPeriodSummaries)
+            .where(and(gte(billingPeriodSummaries.periodStart, start), lte(billingPeriodSummaries.periodEnd, end)));
+    }
+}

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

@@ -1,7 +1,11 @@
+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";
 export { CREDIT_PRICE_POINTS, getConfiguredPriceIds, getCreditAmountForPurchase, 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";
@@ -9,6 +13,12 @@ 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 { CreditCheckoutOpts, PortalSessionOpts, StripeBillingConfig, 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/dist/billing/stripe/index.js

@@ -1,8 +1,13 @@
+export { DrizzleBillingPeriodSummaryRepository } from "./billing-period-summary-repository.js";
 export { createCreditCheckoutSession, createVpsCheckoutSession } from "./checkout.js";
 export { createStripeClient, loadStripeConfig } from "./client.js";
 export { CREDIT_PRICE_POINTS, getConfiguredPriceIds, getCreditAmountForPurchase, loadCreditPriceMap, lookupCreditPrice, } from "./credit-prices.js";
+export { loadMeteredPriceMap } from "./metered-price-map.js";
 export { detachAllPaymentMethods, detachPaymentMethod } from "./payment-methods.js";
 export { createPortalSession } from "./portal.js";
 export { createSetupIntent } from "./setup-intent.js";
 export { StripePaymentProcessor } from "./stripe-payment-processor.js";
+export { runStripeUsageReconciliation } from "./stripe-usage-reconciliation.js";
 export { DrizzleTenantCustomerRepository, TenantCustomerRepository } from "./tenant-store.js";
+export { DrizzleStripeUsageReportRepository } from "./usage-report-repository.js";
+export { runUsageReportWriter } from "./usage-report-writer.js";

package/dist/billing/stripe/metered-price-map.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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>;
+/**
+ * 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 declare function loadMeteredPriceMap(): MeteredPriceMap;

package/dist/billing/stripe/metered-price-map.js

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+const METERED_CAPABILITIES = [
+    {
+        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() {
+    const map = new Map();
+    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/dist/billing/stripe/stripe-payment-processor.test.js

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

package/dist/billing/stripe/stripe-usage-reconciliation.d.ts

@@ -0,0 +1,31 @@
+import type Stripe from "stripe";
+import type { IStripeUsageReportRepository } 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 declare function runStripeUsageReconciliation(cfg: StripeUsageReconciliationConfig): Promise<UsageReconciliationResult>;

package/dist/billing/stripe/stripe-usage-reconciliation.js

@@ -0,0 +1,84 @@
+import { logger } from "../../config/logger.js";
+export async function runStripeUsageReconciliation(cfg) {
+    const threshold = cfg.flagThresholdCents ?? 10;
+    const dayStart = new Date(`${cfg.targetDate}T00:00:00Z`).getTime();
+    const dayEnd = dayStart + 24 * 60 * 60 * 1000;
+    const result = {
+        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();
+    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();
+    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/dist/billing/stripe/stripe-usage-reconciliation.test.d.ts

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

package/dist/billing/stripe/stripe-usage-reconciliation.test.js

@@ -0,0 +1,109 @@
+import crypto from "node:crypto";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+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;
+    let pool;
+    let reportRepo;
+    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: [] }) },
+            },
+        };
+        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 }],
+                    }),
+                },
+            },
+        };
+        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 }],
+                    }),
+                },
+            },
+        };
+        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/dist/billing/stripe/tenant-store.d.ts

@@ -15,6 +15,10 @@ 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;
+    }>>;
 }
 /**
  * Manages tenant-to-payment-processor customer mappings in PostgreSQL.
@@ -50,6 +54,11 @@ export declare class DrizzleTenantCustomerRepository implements ITenantCustomerR
     setInferenceMode(tenant: string, mode: string): Promise<void>;
     /** List all tenants with processor mappings. */
     list(): Promise<TenantCustomerRow[]>;
+    /** Return all tenants with inferenceMode === "metered". */
+    listMetered(): Promise<Array<{
+        tenant: string;
+        processorCustomerId: string;
+    }>>;
     /** Build a tenant -> processor_customer_id map for use with UsageAggregationWorker. */
     buildCustomerIdMap(): Promise<Record<string, string>>;
 }

package/dist/billing/stripe/tenant-store.js

@@ -87,6 +87,13 @@ export class DrizzleTenantCustomerRepository {
         const rows = await this.db.select().from(tenantCustomers).orderBy(desc(tenantCustomers.createdAt));
         return rows.map(mapRow);
     }
+    /** Return all tenants with inferenceMode === "metered". */
+    async listMetered() {
+        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() {
         const rows = await this.db

package/dist/billing/stripe/usage-report-repository.d.ts

@@ -0,0 +1,39 @@
+import type { PlatformDb } from "../../db/index.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 declare class DrizzleStripeUsageReportRepository implements IStripeUsageReportRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    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[]>;
+}

package/dist/billing/stripe/usage-report-repository.js

@@ -0,0 +1,30 @@
+import { and, eq, gte, lt } from "drizzle-orm";
+import { stripeUsageReports } from "../../db/schema/tenant-customers.js";
+export class DrizzleStripeUsageReportRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async insert(row) {
+        await this.db.insert(stripeUsageReports).values(row);
+    }
+    async getByTenantAndPeriod(tenant, capability, provider, periodStart) {
+        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, opts) {
+        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) {
+        return this.db
+            .select()
+            .from(stripeUsageReports)
+            .where(and(gte(stripeUsageReports.reportedAt, opts.since), lt(stripeUsageReports.reportedAt, opts.until)));
+    }
+}

package/dist/billing/stripe/usage-report-repository.test.d.ts

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

package/dist/billing/stripe/usage-report-repository.test.js

@@ -0,0 +1,77 @@
+import crypto from "node:crypto";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { createTestDb, truncateAllTables } from "../../test/db.js";
+import { DrizzleStripeUsageReportRepository } from "./usage-report-repository.js";
+describe("DrizzleStripeUsageReportRepository", () => {
+    let db;
+    let pool;
+    let repo;
+    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/dist/billing/stripe/usage-report-writer.d.ts

@@ -0,0 +1,41 @@
+import type Stripe from "stripe";
+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 declare function runUsageReportWriter(cfg: UsageReportWriterConfig): Promise<UsageReportResult>;