@wopr-network/platform-core 0.1.0

package/dist/metering/emitter.test.js

@@ -0,0 +1,171 @@
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { Credit } from "../credits/credit.js";
+import { MeterDLQ } from "./dlq.js";
+import { DrizzleMeterEmitter } from "./emitter.js";
+import { DrizzleMeterEventRepository } from "./meter-event-repository.js";
+function makeTempDir() {
+    const dir = join(tmpdir(), `emitter-test-${crypto.randomUUID()}`);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function makeEvent(overrides = {}) {
+    return {
+        tenant: "t1",
+        cost: Credit.fromCents(1),
+        charge: Credit.fromCents(2),
+        capability: "llm",
+        provider: "openai",
+        timestamp: Date.now(),
+        ...overrides,
+    };
+}
+describe("DrizzleMeterEmitter — happy path", () => {
+    let pool;
+    let db;
+    let emitter;
+    let tempDir;
+    beforeEach(async () => {
+        ({ db, pool } = await createTestDb());
+        await beginTestTransaction(pool);
+        await rollbackTestTransaction(pool);
+        tempDir = makeTempDir();
+        const repo = new DrizzleMeterEventRepository(db);
+        emitter = new DrizzleMeterEmitter(repo, {
+            flushIntervalMs: 60_000,
+            batchSize: 100,
+            walPath: join(tempDir, "wal.jsonl"),
+            dlqPath: join(tempDir, "dlq.jsonl"),
+            maxRetries: 3,
+        });
+        await emitter.ready;
+    });
+    afterEach(async () => {
+        // Flush remaining events before close() to drain the buffer synchronously
+        await emitter.flush();
+        emitter.close();
+        await endTestTransaction(pool);
+        await pool.close();
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    });
+    it("writes a meter event to the database after flush", async () => {
+        emitter.emit(makeEvent({ tenant: "t1", capability: "voice" }));
+        expect(emitter.pending).toBe(1);
+        const flushed = await emitter.flush();
+        expect(flushed).toBe(1);
+        expect(emitter.pending).toBe(0);
+        const rows = await emitter.queryEvents("t1");
+        expect(rows).toHaveLength(1);
+        expect(rows[0].tenant).toBe("t1");
+        expect(rows[0].capability).toBe("voice");
+        expect(rows[0].cost).toBe(Credit.fromCents(1).toRaw());
+        expect(rows[0].charge).toBe(Credit.fromCents(2).toRaw());
+    });
+    it("persists multiple events in one flush", async () => {
+        emitter.emit(makeEvent({ tenant: "t1" }));
+        emitter.emit(makeEvent({ tenant: "t1" }));
+        emitter.emit(makeEvent({ tenant: "t2" }));
+        const flushed = await emitter.flush();
+        expect(flushed).toBe(3);
+        const t1Rows = await emitter.queryEvents("t1");
+        expect(t1Rows).toHaveLength(2);
+        const t2Rows = await emitter.queryEvents("t2");
+        expect(t2Rows).toHaveLength(1);
+    });
+    it("flush returns 0 when buffer is empty", async () => {
+        expect(await emitter.flush()).toBe(0);
+    });
+    it("silently drops events emitted after close", async () => {
+        emitter.close();
+        emitter.emit(makeEvent());
+        expect(emitter.pending).toBe(0);
+    });
+    it("persists sessionId, duration, usage, tier, and metadata", async () => {
+        emitter.emit(makeEvent({
+            sessionId: "sess-1",
+            duration: 5000,
+            usage: { units: 100, unitType: "tokens" },
+            tier: "wopr",
+            metadata: { model: "gpt-4" },
+        }));
+        await emitter.flush();
+        const rows = await emitter.queryEvents("t1");
+        expect(rows[0].session_id).toBe("sess-1");
+        expect(rows[0].duration).toBe(5000);
+        expect(rows[0].usage_units).toBe(100);
+        expect(rows[0].usage_unit_type).toBe("tokens");
+        expect(rows[0].tier).toBe("wopr");
+        expect(JSON.parse(rows[0].metadata)).toEqual({ model: "gpt-4" });
+    });
+});
+describe("DrizzleMeterEmitter — DLQ failure paths", () => {
+    it("moves events to DLQ after maxRetries failures", async () => {
+        const { db: failDb, pool: failPool } = await createTestDb();
+        const failTempDir = makeTempDir();
+        const dlqPath = join(failTempDir, "dlq.jsonl");
+        const failRepo = new DrizzleMeterEventRepository(failDb);
+        const em = new DrizzleMeterEmitter(failRepo, {
+            flushIntervalMs: 60_000,
+            walPath: join(failTempDir, "wal.jsonl"),
+            dlqPath,
+            maxRetries: 1,
+        });
+        await em.ready;
+        em.emit(makeEvent());
+        // Drop the table so flush fails
+        await failPool.query("DROP TABLE meter_events CASCADE");
+        await em.flush();
+        // maxRetries=1: first failure hits the limit => DLQ
+        const dlq = new MeterDLQ(dlqPath);
+        expect(dlq.count()).toBe(1);
+        expect(em.pending).toBe(0);
+        em.close();
+        await failPool.close();
+        try {
+            rmSync(failTempDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    it("retries failed events before moving to DLQ", async () => {
+        const { db: failDb, pool: failPool } = await createTestDb();
+        const failTempDir = makeTempDir();
+        const dlqPath = join(failTempDir, "dlq.jsonl");
+        const failRepo2 = new DrizzleMeterEventRepository(failDb);
+        const em = new DrizzleMeterEmitter(failRepo2, {
+            flushIntervalMs: 60_000,
+            walPath: join(failTempDir, "wal.jsonl"),
+            dlqPath,
+            maxRetries: 2,
+        });
+        await em.ready;
+        em.emit(makeEvent());
+        // First flush fails
+        await failPool.query("DROP TABLE meter_events CASCADE");
+        await em.flush();
+        // After first failure (maxRetries=2): still in buffer for retry
+        expect(em.pending).toBe(1);
+        // DLQ should be empty — not yet reached maxRetries
+        const dlq = new MeterDLQ(dlqPath);
+        expect(dlq.count()).toBe(0);
+        // Clear the buffer before close to avoid a DLQ write race during cleanup
+        em.buffer = [];
+        em.close();
+        await failPool.close();
+        try {
+            rmSync(failTempDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+});

package/dist/metering/index.d.ts

@@ -0,0 +1,11 @@
+export type { IMeterAggregator } from "./aggregator.js";
+export { DrizzleMeterAggregator, MeterAggregator } from "./aggregator.js";
+export type { AggregatedWindowRow, IUsageSummaryRepository, UsageSummaryInsert, } from "./drizzle-usage-summary-repository.js";
+export { DrizzleUsageSummaryRepository, UsageSummaryRepository } from "./drizzle-usage-summary-repository.js";
+export type { IMeterEmitter } from "./emitter.js";
+export { DrizzleMeterEmitter, MeterEmitter } from "./emitter.js";
+export type { IMeterEventRepository, MeterEventInsert } from "./meter-event-repository.js";
+export { DrizzleMeterEventRepository } from "./meter-event-repository.js";
+export type { ReconciliationConfig, ReconciliationResult } from "./reconciliation-cron.js";
+export { runReconciliation } from "./reconciliation-cron.js";
+export type { BillingPeriod, BillingPeriodSummary, MeterEvent, MeterEventRow, UsageSummary, } from "./types.js";

package/dist/metering/index.js

@@ -0,0 +1,5 @@
+export { DrizzleMeterAggregator, MeterAggregator } from "./aggregator.js";
+export { DrizzleUsageSummaryRepository, UsageSummaryRepository } from "./drizzle-usage-summary-repository.js";
+export { DrizzleMeterEmitter, MeterEmitter } from "./emitter.js";
+export { DrizzleMeterEventRepository } from "./meter-event-repository.js";
+export { runReconciliation } from "./reconciliation-cron.js";

package/dist/metering/load-test.bench.d.ts

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

package/dist/metering/load-test.bench.js

@@ -0,0 +1,103 @@
+import { unlinkSync } from "node:fs";
+import { afterEach, beforeEach, bench, describe } from "vitest";
+import { createTestDb } from "../test/db.js";
+import { Credit } from "../credits/credit.js";
+import { MeterAggregator } from "./aggregator.js";
+import { DrizzleUsageSummaryRepository } from "./drizzle-usage-summary-repository.js";
+import { MeterEmitter } from "./emitter.js";
+import { DrizzleMeterEventRepository } from "./meter-event-repository.js";
+function makeEvent(i) {
+    return {
+        tenant: `tenant-${i % 100}`,
+        cost: Credit.fromDollars(0.001 * (i % 10)),
+        charge: Credit.fromDollars(0.002 * (i % 10)),
+        capability: ["chat", "voice", "embeddings", "tts", "stt"][i % 5],
+        provider: ["openai", "deepgram", "elevenlabs", "openrouter"][i % 4],
+        timestamp: Date.now() - 120_000 + i,
+        sessionId: `session-${i % 50}`,
+        duration: i % 2 === 0 ? 1000 + i : undefined,
+        usage: i % 3 === 0 ? { units: 100 + i, unitType: "tokens" } : undefined,
+        tier: ["branded", "wopr", "byok"][i % 3],
+    };
+}
+describe("MeterEmitter throughput", () => {
+    let db;
+    let pool;
+    let emitter;
+    const walPath = `/tmp/wopr-bench-wal-${process.pid}.jsonl`;
+    const dlqPath = `/tmp/wopr-bench-dlq-${process.pid}.jsonl`;
+    beforeEach(async () => {
+        ({ db, pool } = await createTestDb());
+        emitter = new MeterEmitter(new DrizzleMeterEventRepository(db), {
+            flushIntervalMs: 60_000,
+            batchSize: 1000,
+            walPath,
+            dlqPath,
+        });
+    });
+    afterEach(async () => {
+        emitter.close();
+        await pool.close();
+        try {
+            unlinkSync(walPath);
+        }
+        catch {
+            /* */
+        }
+        try {
+            unlinkSync(dlqPath);
+        }
+        catch {
+            /* */
+        }
+    });
+    let eventCounter = 0;
+    bench("emit single event (includes WAL write)", () => {
+        emitter.emit(makeEvent(eventCounter++));
+    }, { iterations: 10_000 });
+    bench("emit + flush batch of 100", async () => {
+        for (let i = 0; i < 100; i++) {
+            emitter.emit(makeEvent(eventCounter++));
+        }
+        await emitter.flush();
+    }, { iterations: 100 });
+    bench("emit + flush batch of 1000", async () => {
+        for (let i = 0; i < 1000; i++) {
+            emitter.emit(makeEvent(eventCounter++));
+        }
+        await emitter.flush();
+    }, { iterations: 50 });
+});
+describe("MeterAggregator throughput", () => {
+    let db;
+    let pool;
+    let emitter;
+    let aggregator;
+    const walPath = `/tmp/wopr-bench-agg-wal-${process.pid}.jsonl`;
+    const dlqPath = `/tmp/wopr-bench-agg-dlq-${process.pid}.jsonl`;
+    beforeEach(async () => {
+        ({ db, pool } = await createTestDb());
+        emitter = new MeterEmitter(new DrizzleMeterEventRepository(db), { flushIntervalMs: 60_000, walPath, dlqPath });
+        aggregator = new MeterAggregator(new DrizzleUsageSummaryRepository(db), { windowMs: 60_000 });
+    });
+    afterEach(async () => {
+        aggregator.stop();
+        emitter.close();
+        await pool.close();
+        try {
+            unlinkSync(walPath);
+        }
+        catch {
+            /* */
+        }
+        try {
+            unlinkSync(dlqPath);
+        }
+        catch {
+            /* */
+        }
+    });
+    bench("aggregate 10K events", async () => {
+        await aggregator.aggregate();
+    }, { iterations: 10 });
+});

package/dist/metering/meter-event-repository.d.ts

@@ -0,0 +1,33 @@
+import type { PlatformDb } from "../db/index.js";
+import type { MeterEventRow } from "./types.js";
+/** Values needed to insert a single meter event row. */
+export interface MeterEventInsert {
+    id: string;
+    tenant: string;
+    cost: number;
+    charge: number;
+    capability: string;
+    provider: string;
+    timestamp: number;
+    sessionId: string | null;
+    duration: number | null;
+    usageUnits: number | null;
+    usageUnitType: string | null;
+    tier: string | null;
+    metadata: string | null;
+}
+export interface IMeterEventRepository {
+    /** Check if an event ID already exists in the database. */
+    existsById(id: string): Promise<boolean>;
+    /** Insert a batch of events in a single transaction. */
+    insertBatch(events: MeterEventInsert[]): Promise<void>;
+    /** Query persisted events for a tenant, ordered by timestamp desc. */
+    queryByTenant(tenant: string, limit: number): Promise<MeterEventRow[]>;
+}
+export declare class DrizzleMeterEventRepository implements IMeterEventRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    existsById(id: string): Promise<boolean>;
+    insertBatch(events: MeterEventInsert[]): Promise<void>;
+    queryByTenant(tenant: string, limit: number): Promise<MeterEventRow[]>;
+}

package/dist/metering/meter-event-repository.js

@@ -0,0 +1,58 @@
+import { desc, eq } from "drizzle-orm";
+import { meterEvents } from "../db/schema/meter-events.js";
+export class DrizzleMeterEventRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async existsById(id) {
+        const row = (await this.db.select({ id: meterEvents.id }).from(meterEvents).where(eq(meterEvents.id, id)))[0];
+        return !!row;
+    }
+    async insertBatch(events) {
+        if (events.length === 0)
+            return;
+        await this.db.transaction(async (tx) => {
+            for (const e of events) {
+                await tx.insert(meterEvents).values({
+                    id: e.id,
+                    tenant: e.tenant,
+                    cost: e.cost,
+                    charge: e.charge,
+                    capability: e.capability,
+                    provider: e.provider,
+                    timestamp: e.timestamp,
+                    sessionId: e.sessionId,
+                    duration: e.duration,
+                    usageUnits: e.usageUnits,
+                    usageUnitType: e.usageUnitType,
+                    tier: e.tier,
+                    metadata: e.metadata,
+                });
+            }
+        });
+    }
+    async queryByTenant(tenant, limit) {
+        const rows = await this.db
+            .select()
+            .from(meterEvents)
+            .where(eq(meterEvents.tenant, tenant))
+            .orderBy(desc(meterEvents.timestamp))
+            .limit(limit);
+        return rows.map((r) => ({
+            id: r.id,
+            tenant: r.tenant,
+            cost: r.cost,
+            charge: r.charge,
+            capability: r.capability,
+            provider: r.provider,
+            timestamp: r.timestamp,
+            session_id: r.sessionId,
+            duration: r.duration,
+            usage_units: r.usageUnits,
+            usage_unit_type: r.usageUnitType,
+            tier: r.tier,
+            metadata: r.metadata,
+        }));
+    }
+}

package/dist/metering/meter-repositories.test.d.ts

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