@wopr-network/platform-core 0.1.0

package/dist/metering/dlq.test.js

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Credit } from "../credits/credit.js";
+import { MeterDLQ } from "./dlq.js";
+describe("MeterDLQ", () => {
+    let tmpDir;
+    let dlqPath;
+    beforeEach(() => {
+        tmpDir = path.join(os.tmpdir(), `wopr-dlq-test-${Date.now()}`);
+        dlqPath = path.join(tmpDir, "meter-dlq.jsonl");
+    });
+    afterEach(() => {
+        if (existsSync(tmpDir)) {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    it("creates the directory when it does not exist", () => {
+        // tmpDir doesn't exist yet — constructor should create it
+        expect(existsSync(tmpDir)).toBe(false);
+        new MeterDLQ(dlqPath);
+        expect(existsSync(tmpDir)).toBe(true);
+    });
+    it("does not throw when directory already exists", () => {
+        mkdirSync(tmpDir, { recursive: true });
+        expect(() => new MeterDLQ(dlqPath)).not.toThrow();
+    });
+    it("readAll returns empty array when DLQ file does not exist", () => {
+        new MeterDLQ(dlqPath);
+        expect(existsSync(dlqPath)).toBe(false);
+        const dlq = new MeterDLQ(dlqPath);
+        expect(dlq.readAll()).toEqual([]);
+    });
+    it("readAll returns empty array when DLQ file is empty", () => {
+        mkdirSync(tmpDir, { recursive: true });
+        writeFileSync(dlqPath, "");
+        const dlq = new MeterDLQ(dlqPath);
+        expect(dlq.readAll()).toEqual([]);
+    });
+    it("readAll returns empty array when DLQ file contains only whitespace", () => {
+        mkdirSync(tmpDir, { recursive: true });
+        writeFileSync(dlqPath, "\n\n  \n");
+        const dlq = new MeterDLQ(dlqPath);
+        expect(dlq.readAll()).toEqual([]);
+    });
+    it("append writes a DLQ entry and readAll returns it", () => {
+        const dlq = new MeterDLQ(dlqPath);
+        const event = {
+            id: "evt-1",
+            tenant: "tenant-1",
+            capability: "tts",
+            provider: "elevenlabs",
+            cost: Credit.fromDollars(0.01),
+            charge: Credit.fromDollars(0.02),
+            timestamp: Date.now(),
+        };
+        dlq.append(event, "Stripe API 500", 3);
+        const entries = dlq.readAll();
+        expect(entries).toHaveLength(1);
+        expect(entries[0].id).toBe("evt-1");
+        expect(entries[0].dlq_error).toBe("Stripe API 500");
+        expect(entries[0].dlq_retries).toBe(3);
+    });
+    it("count returns 0 for empty DLQ", () => {
+        const dlq = new MeterDLQ(dlqPath);
+        expect(dlq.count()).toBe(0);
+    });
+    it("count returns correct count after appending", () => {
+        const dlq = new MeterDLQ(dlqPath);
+        const event = {
+            id: "evt-1",
+            tenant: "t1",
+            capability: "tts",
+            provider: "elevenlabs",
+            cost: Credit.fromDollars(0.01),
+            charge: Credit.fromDollars(0.02),
+            timestamp: Date.now(),
+        };
+        dlq.append(event, "err", 1);
+        dlq.append({ ...event, id: "evt-2" }, "err2", 2);
+        expect(dlq.count()).toBe(2);
+    });
+    it("count counts malformed lines (no JSON parsing)", () => {
+        mkdirSync(tmpDir, { recursive: true });
+        const goodLine = JSON.stringify({ id: "evt-1", dlq_error: "e", dlq_retries: 1, dlq_timestamp: 0 });
+        writeFileSync(dlqPath, `${goodLine}\nnot-valid-json\n`);
+        const dlq = new MeterDLQ(dlqPath);
+        // count should return 2 (line count), not 1 (parsed count)
+        // This verifies count() does NOT use JSON.parse
+        expect(dlq.count()).toBe(2);
+    });
+    it("count returns correct count when file has no trailing newline", () => {
+        mkdirSync(tmpDir, { recursive: true });
+        const line1 = JSON.stringify({ id: "evt-1", dlq_error: "e", dlq_retries: 1, dlq_timestamp: 0 });
+        const line2 = JSON.stringify({ id: "evt-2", dlq_error: "e", dlq_retries: 1, dlq_timestamp: 0 });
+        // Write two entries with no trailing newline
+        writeFileSync(dlqPath, `${line1}\n${line2}`);
+        const dlq = new MeterDLQ(dlqPath);
+        expect(dlq.count()).toBe(2);
+    });
+    it("count returns 0 when file is deleted between calls (ENOENT)", () => {
+        mkdirSync(tmpDir, { recursive: true });
+        const dlq = new MeterDLQ(dlqPath);
+        // File doesn't exist at all — should not throw, return 0
+        expect(dlq.count()).toBe(0);
+    });
+    it("readAll skips malformed lines", () => {
+        mkdirSync(tmpDir, { recursive: true });
+        const goodLine = JSON.stringify({ id: "evt-1", dlq_error: "e", dlq_retries: 1, dlq_timestamp: 0 });
+        writeFileSync(dlqPath, `${goodLine}\nnot-valid-json\n`);
+        const dlq = new MeterDLQ(dlqPath);
+        const entries = dlq.readAll();
+        expect(entries).toHaveLength(1);
+        expect(entries[0].id).toBe("evt-1");
+    });
+});

package/dist/metering/drizzle-usage-summary-repository.d.ts

@@ -0,0 +1,67 @@
+import type { PlatformDb } from "../db/index.js";
+import type { UsageSummary } from "./types.js";
+export interface AggregatedWindowRow {
+    tenant: string;
+    capability: string;
+    provider: string;
+    eventCount: number;
+    totalCost: number;
+    totalCharge: number;
+    totalDuration: number;
+}
+export interface UsageSummaryInsert {
+    id: string;
+    tenant: string;
+    capability: string;
+    provider: string;
+    eventCount: number;
+    totalCost: number;
+    totalCharge: number;
+    totalDuration: number;
+    windowStart: number;
+    windowEnd: number;
+}
+export interface IUsageSummaryRepository {
+    /** Get the maximum windowEnd across all usage summaries. Returns 0 if none. */
+    getLastWindowEnd(): Promise<number>;
+    /** Get the earliest meter event timestamp before the given time. Returns null if none. */
+    getEarliestEventTimestamp(before: number): Promise<number | null>;
+    /** Get aggregated event groups for a time window [start, end). */
+    getAggregatedEvents(windowStart: number, windowEnd: number): Promise<AggregatedWindowRow[]>;
+    /** Insert a single usage summary row. */
+    insertSummary(values: UsageSummaryInsert): Promise<void>;
+    /** Insert multiple usage summary rows in a transaction. */
+    insertSummariesBatch(rows: UsageSummaryInsert[]): Promise<void>;
+    /** Query usage summaries for a tenant within a time range. */
+    querySummaries(tenant: string, opts?: {
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Promise<UsageSummary[]>;
+    /** Get a tenant's total usage since a given time. */
+    getTenantTotal(tenant: string, since: number): Promise<{
+        totalCost: number;
+        totalCharge: number;
+        eventCount: number;
+    }>;
+}
+export declare class DrizzleUsageSummaryRepository implements IUsageSummaryRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    getLastWindowEnd(): Promise<number>;
+    getEarliestEventTimestamp(before: number): Promise<number | null>;
+    getAggregatedEvents(windowStart: number, windowEnd: number): Promise<AggregatedWindowRow[]>;
+    insertSummary(values: UsageSummaryInsert): Promise<void>;
+    insertSummariesBatch(rows: UsageSummaryInsert[]): Promise<void>;
+    querySummaries(tenant: string, opts?: {
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Promise<UsageSummary[]>;
+    getTenantTotal(tenant: string, since: number): Promise<{
+        totalCost: number;
+        totalCharge: number;
+        eventCount: number;
+    }>;
+}
+export { DrizzleUsageSummaryRepository as UsageSummaryRepository };

package/dist/metering/drizzle-usage-summary-repository.js

@@ -0,0 +1,98 @@
+import { and, count, desc, eq, gte, lt, lte, max, min, sql, sum } from "drizzle-orm";
+import { meterEvents, usageSummaries } from "../db/schema/meter-events.js";
+export class DrizzleUsageSummaryRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getLastWindowEnd() {
+        const row = (await this.db.select({ lastEnd: max(usageSummaries.windowEnd) }).from(usageSummaries))[0];
+        return row?.lastEnd ?? 0;
+    }
+    async getEarliestEventTimestamp(before) {
+        const row = (await this.db
+            .select({ ts: min(meterEvents.timestamp) })
+            .from(meterEvents)
+            .where(lt(meterEvents.timestamp, before)))[0];
+        return row?.ts ?? null;
+    }
+    async getAggregatedEvents(windowStart, windowEnd) {
+        const rows = await this.db
+            .select({
+            tenant: meterEvents.tenant,
+            capability: meterEvents.capability,
+            provider: meterEvents.provider,
+            eventCount: count(),
+            totalCost: sum(meterEvents.cost),
+            totalCharge: sum(meterEvents.charge),
+            totalDuration: sql `COALESCE(SUM(${meterEvents.duration}), 0)`,
+        })
+            .from(meterEvents)
+            .where(and(gte(meterEvents.timestamp, windowStart), lt(meterEvents.timestamp, windowEnd)))
+            .groupBy(meterEvents.tenant, meterEvents.capability, meterEvents.provider);
+        return rows.map((r) => ({
+            tenant: r.tenant,
+            capability: r.capability,
+            provider: r.provider,
+            eventCount: r.eventCount,
+            totalCost: Number(r.totalCost),
+            totalCharge: Number(r.totalCharge),
+            totalDuration: Number(r.totalDuration),
+        }));
+    }
+    async insertSummary(values) {
+        await this.db.insert(usageSummaries).values(values);
+    }
+    async insertSummariesBatch(rows) {
+        if (rows.length === 0)
+            return;
+        const CHUNK_SIZE = 1000; // safe limit: each row has ~10 columns, 1000*10 < 65535 param limit
+        await this.db.transaction(async (tx) => {
+            for (let i = 0; i < rows.length; i += CHUNK_SIZE) {
+                await tx.insert(usageSummaries).values(rows.slice(i, i + CHUNK_SIZE));
+            }
+        });
+    }
+    async querySummaries(tenant, opts = {}) {
+        const conditions = [eq(usageSummaries.tenant, tenant)];
+        if (opts.since != null) {
+            conditions.push(gte(usageSummaries.windowStart, opts.since));
+        }
+        if (opts.until != null) {
+            conditions.push(lte(usageSummaries.windowEnd, opts.until));
+        }
+        const limit = Math.min(Math.max(1, opts.limit ?? 100), 1000);
+        return this.db
+            .select({
+            tenant: usageSummaries.tenant,
+            capability: usageSummaries.capability,
+            provider: usageSummaries.provider,
+            event_count: usageSummaries.eventCount,
+            total_cost: usageSummaries.totalCost,
+            total_charge: usageSummaries.totalCharge,
+            total_duration: usageSummaries.totalDuration,
+            window_start: usageSummaries.windowStart,
+            window_end: usageSummaries.windowEnd,
+        })
+            .from(usageSummaries)
+            .where(and(...conditions))
+            .orderBy(desc(usageSummaries.windowStart))
+            .limit(limit);
+    }
+    async getTenantTotal(tenant, since) {
+        const row = (await this.db
+            .select({
+            totalCost: sql `COALESCE(SUM(${usageSummaries.totalCost}), 0)`,
+            totalCharge: sql `COALESCE(SUM(${usageSummaries.totalCharge}), 0)`,
+            eventCount: sql `COALESCE(SUM(${usageSummaries.eventCount}), 0)`,
+        })
+            .from(usageSummaries)
+            .where(and(eq(usageSummaries.tenant, tenant), gte(usageSummaries.windowStart, since))))[0];
+        return {
+            totalCost: Number(row?.totalCost ?? 0),
+            totalCharge: Number(row?.totalCharge ?? 0),
+            eventCount: Number(row?.eventCount ?? 0),
+        };
+    }
+}
+export { DrizzleUsageSummaryRepository as UsageSummaryRepository };

package/dist/metering/emitter.d.ts

@@ -0,0 +1,66 @@
+import type { IMeterEventRepository } from "./meter-event-repository.js";
+import type { MeterEvent, MeterEventRow } from "./types.js";
+export interface IMeterEmitter {
+    emit(event: MeterEvent): void;
+    flush(): Promise<number>;
+    readonly pending: number;
+    close(): void;
+    queryEvents(tenant: string, limit?: number): Promise<MeterEventRow[]>;
+}
+/**
+ * Fire-and-forget meter event emitter with fail-closed durability.
+ *
+ * Buffers events in memory and flushes them to the database in batches,
+ * ensuring zero latency impact on the observed API calls.
+ *
+ * FAIL-CLOSED POLICY:
+ * - Events are written to WAL (write-ahead log) on disk BEFORE buffering
+ * - If flush fails, events are retried up to MAX_RETRIES times
+ * - After MAX_RETRIES, events move to DLQ (dead-letter queue) for manual recovery
+ * - On startup, unflushed WAL events are replayed idempotently
+ */
+export declare class DrizzleMeterEmitter implements IMeterEmitter {
+    private readonly repo;
+    private buffer;
+    private flushTimer;
+    private readonly flushIntervalMs;
+    private readonly batchSize;
+    private readonly maxRetries;
+    private closed;
+    private readonly wal;
+    private readonly dlq;
+    private readonly retryCount;
+    /** Resolves when the initial WAL replay has completed. */
+    readonly ready: Promise<void>;
+    constructor(repo: IMeterEventRepository, opts?: {
+        flushIntervalMs?: number;
+        batchSize?: number;
+        walPath?: string;
+        dlqPath?: string;
+        maxRetries?: number;
+    });
+    /**
+     * Replay unflushed events from the WAL on startup.
+     * Idempotent: skips events already in the database.
+     * Returns a promise that resolves when the replay is complete.
+     */
+    private replayWAL;
+    /**
+     * Reconstitute Credit fields on WAL events after JSON deserialization.
+     * Credit.toJSON() serializes to a raw number, so after JSON.parse the
+     * cost/charge fields are plain numbers — convert them back to Credit.
+     */
+    private reconstituteCreditFields;
+    private replayWALAsync;
+    /** Emit a meter event. Non-blocking -- buffers in memory after WAL write. */
+    emit(event: MeterEvent): void;
+    /** Flush buffered events to the database with retry and DLQ logic. */
+    flush(): Promise<number>;
+    /** Number of events currently buffered. */
+    get pending(): number;
+    /** Stop the flush timer and flush remaining events. */
+    close(): void;
+    /** Query persisted events (for testing / diagnostics). */
+    queryEvents(tenant: string, limit?: number): Promise<MeterEventRow[]>;
+}
+export { DrizzleMeterEmitter as MeterEmitter };

package/dist/metering/emitter.js

@@ -0,0 +1,185 @@
+import { config } from "../config/index.js";
+import { Credit } from "../credits/credit.js";
+import { MeterDLQ } from "./dlq.js";
+import { MeterWAL } from "./wal.js";
+const DEFAULT_WAL_PATH = process.env.METER_WAL_PATH ?? "./data/meter-wal.jsonl";
+const DEFAULT_DLQ_PATH = process.env.METER_DLQ_PATH ?? "./data/meter-dlq.jsonl";
+const DEFAULT_MAX_RETRIES = config.billing.meterMaxRetries;
+/**
+ * Fire-and-forget meter event emitter with fail-closed durability.
+ *
+ * Buffers events in memory and flushes them to the database in batches,
+ * ensuring zero latency impact on the observed API calls.
+ *
+ * FAIL-CLOSED POLICY:
+ * - Events are written to WAL (write-ahead log) on disk BEFORE buffering
+ * - If flush fails, events are retried up to MAX_RETRIES times
+ * - After MAX_RETRIES, events move to DLQ (dead-letter queue) for manual recovery
+ * - On startup, unflushed WAL events are replayed idempotently
+ */
+export class DrizzleMeterEmitter {
+    repo;
+    buffer = [];
+    flushTimer = null;
+    flushIntervalMs;
+    batchSize;
+    maxRetries;
+    closed = false;
+    wal;
+    dlq;
+    retryCount = new Map();
+    /** Resolves when the initial WAL replay has completed. */
+    ready;
+    constructor(repo, opts = {}) {
+        this.repo = repo;
+        this.flushIntervalMs = opts.flushIntervalMs ?? 1000;
+        this.batchSize = opts.batchSize ?? 100;
+        this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.wal = new MeterWAL(opts.walPath ?? DEFAULT_WAL_PATH);
+        this.dlq = new MeterDLQ(opts.dlqPath ?? DEFAULT_DLQ_PATH);
+        // Replay any unflushed WAL events from a previous session.
+        this.ready = this.replayWAL();
+        this.flushTimer = setInterval(() => this.flush(), this.flushIntervalMs);
+        // Do not keep the process alive just for metering flushes.
+        if (this.flushTimer.unref) {
+            this.flushTimer.unref();
+        }
+    }
+    /**
+     * Replay unflushed events from the WAL on startup.
+     * Idempotent: skips events already in the database.
+     * Returns a promise that resolves when the replay is complete.
+     */
+    async replayWAL() {
+        const walEvents = this.wal.readAll();
+        if (walEvents.length === 0)
+            return;
+        await this.replayWALAsync(walEvents);
+    }
+    /**
+     * Reconstitute Credit fields on WAL events after JSON deserialization.
+     * Credit.toJSON() serializes to a raw number, so after JSON.parse the
+     * cost/charge fields are plain numbers — convert them back to Credit.
+     */
+    reconstituteCreditFields(events) {
+        return events.map((e) => ({
+            ...e,
+            cost: e.cost instanceof Credit ? e.cost : Credit.fromRaw(e.cost),
+            charge: e.charge instanceof Credit ? e.charge : Credit.fromRaw(e.charge),
+        }));
+    }
+    async replayWALAsync(walEvents) {
+        // Reconstitute Credit objects from raw numbers after JSON deserialization.
+        walEvents = this.reconstituteCreditFields(walEvents);
+        // Check which events are already in the database.
+        const existingIds = new Set();
+        for (const e of walEvents) {
+            if (await this.repo.existsById(e.id)) {
+                existingIds.add(e.id);
+            }
+        }
+        // Replay only new events.
+        const toReplay = walEvents.filter((e) => !existingIds.has(e.id));
+        if (toReplay.length > 0) {
+            this.buffer.push(...toReplay);
+            const flushed = await this.flush();
+            if (flushed === 0) {
+                // Flush failed -- events remain in WAL and buffer for retry.
+                return;
+            }
+        }
+        // Remove already-persisted events from WAL (idempotent cleanup).
+        if (existingIds.size > 0) {
+            await this.wal.remove(existingIds);
+        }
+    }
+    /** Emit a meter event. Non-blocking -- buffers in memory after WAL write. */
+    emit(event) {
+        if (this.closed)
+            return;
+        // FAIL-CLOSED: Write to WAL first, then buffer.
+        // append() is synchronous (appendFileSync), so the WAL write completes
+        // before buffer.push() — crash safety is guaranteed.
+        const eventWithId = this.wal.append(event);
+        this.buffer.push(eventWithId);
+        if (this.buffer.length >= this.batchSize) {
+            void this.flush();
+        }
+    }
+    /** Flush buffered events to the database with retry and DLQ logic. */
+    async flush() {
+        if (this.buffer.length === 0)
+            return 0;
+        const batch = this.buffer.splice(0);
+        try {
+            await this.repo.insertBatch(batch.map((e) => ({
+                id: e.id,
+                tenant: e.tenant,
+                cost: e.cost.toRaw(),
+                charge: e.charge.toRaw(),
+                capability: e.capability,
+                provider: e.provider,
+                timestamp: e.timestamp,
+                sessionId: e.sessionId ?? null,
+                duration: e.duration ?? null,
+                usageUnits: e.usage?.units ?? null,
+                usageUnitType: e.usage?.unitType ?? null,
+                tier: e.tier ?? null,
+                metadata: e.metadata ? JSON.stringify(e.metadata) : null,
+            })));
+            // Success: remove from WAL and reset retry counters.
+            const flushedIds = new Set(batch.map((e) => e.id));
+            await this.wal.remove(flushedIds);
+            for (const id of flushedIds) {
+                this.retryCount.delete(id);
+            }
+            return batch.length;
+        }
+        catch (error) {
+            // Failure: track retries and move to DLQ if max exceeded.
+            const toRetry = [];
+            const toDLQ = [];
+            for (const event of batch) {
+                const retries = (this.retryCount.get(event.id) ?? 0) + 1;
+                this.retryCount.set(event.id, retries);
+                if (retries >= this.maxRetries) {
+                    // Max retries exceeded -- move to DLQ.
+                    toDLQ.push(event);
+                    this.dlq.append(event, String(error), retries);
+                    this.retryCount.delete(event.id);
+                }
+                else {
+                    // Retry on next flush.
+                    toRetry.push(event);
+                }
+            }
+            // Remove DLQ events from WAL (they're now in DLQ).
+            if (toDLQ.length > 0) {
+                const dlqIds = new Set(toDLQ.map((e) => e.id));
+                await this.wal.remove(dlqIds);
+            }
+            // Re-add retry events to buffer.
+            this.buffer.unshift(...toRetry);
+            return 0;
+        }
+    }
+    /** Number of events currently buffered. */
+    get pending() {
+        return this.buffer.length;
+    }
+    /** Stop the flush timer and flush remaining events. */
+    close() {
+        this.closed = true;
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        void this.flush();
+    }
+    /** Query persisted events (for testing / diagnostics). */
+    async queryEvents(tenant, limit = 50) {
+        return this.repo.queryByTenant(tenant, limit);
+    }
+}
+// Backward-compat alias.
+export { DrizzleMeterEmitter as MeterEmitter };

package/dist/metering/emitter.test.d.ts

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