@wopr-network/platform-core 0.1.0

package/dist/email/verification.test.js

@@ -0,0 +1,141 @@
+import { PGlite } from "@electric-sql/pglite";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { generateVerificationToken, getUserEmail, initVerificationSchema, isEmailVerified, verifyToken, } from "./verification.js";
+/** Minimal Pool-like wrapper around PGlite for testing. */
+// biome-ignore lint/suspicious/noExplicitAny: test helper wrapping PGlite as Pool
+function pgliteAsPool(pg) {
+    return { query: (text, params) => pg.query(text, params) };
+}
+describe("email verification", () => {
+    let pg;
+    // biome-ignore lint/suspicious/noExplicitAny: test pool wrapper
+    let pool;
+    beforeEach(async () => {
+        pg = new PGlite();
+        pool = pgliteAsPool(pg);
+        // Create a minimal user table mimicking better-auth's schema
+        await pg.query(`
+      CREATE TABLE "user" (
+        id TEXT PRIMARY KEY,
+        email TEXT NOT NULL,
+        name TEXT,
+        "createdAt" TEXT,
+        "emailVerified" boolean DEFAULT false
+      )
+    `);
+        await initVerificationSchema(pool);
+        // Insert test users
+        await pg.query(`INSERT INTO "user" (id, email, name) VALUES ($1, $2, $3)`, ["user-1", "alice@test.com", "Alice"]);
+        await pg.query(`INSERT INTO "user" (id, email, name) VALUES ($1, $2, $3)`, ["user-2", "bob@test.com", "Bob"]);
+    });
+    afterEach(async () => {
+        await pg.close();
+    });
+    describe("initVerificationSchema", () => {
+        it("should add verification columns idempotently", async () => {
+            // Call again — should not throw
+            await initVerificationSchema(pool);
+            const { rows } = await pg.query(`SELECT column_name FROM information_schema.columns WHERE table_name = 'user' ORDER BY ordinal_position`);
+            const names = rows.map((r) => r.column_name);
+            expect(names).toContain("email_verified");
+            expect(names).toContain("verification_token");
+            expect(names).toContain("verification_expires");
+        });
+    });
+    describe("generateVerificationToken", () => {
+        it("should generate a 64-char hex token", async () => {
+            const result = await generateVerificationToken(pool, "user-1");
+            expect(result.token).toHaveLength(64);
+            expect(result.token).toMatch(/^[a-f0-9]+$/);
+        });
+        it("should store token and expiry in the database", async () => {
+            const result = await generateVerificationToken(pool, "user-1");
+            const { rows } = await pg.query(`SELECT verification_token, verification_expires FROM "user" WHERE id = $1`, [
+                "user-1",
+            ]);
+            const row = rows[0];
+            expect(row.verification_token).toBe(result.token);
+            expect(row.verification_expires).toBe(result.expiresAt);
+        });
+        it("should set expiry 24 hours in the future", async () => {
+            const before = Date.now();
+            const result = await generateVerificationToken(pool, "user-1");
+            const after = Date.now();
+            const expiresMs = new Date(result.expiresAt).getTime();
+            const twentyFourHours = 24 * 60 * 60 * 1000;
+            expect(expiresMs).toBeGreaterThanOrEqual(before + twentyFourHours);
+            expect(expiresMs).toBeLessThanOrEqual(after + twentyFourHours);
+        });
+        it("should overwrite previous token on re-generation", async () => {
+            const first = await generateVerificationToken(pool, "user-1");
+            const second = await generateVerificationToken(pool, "user-1");
+            expect(first.token).not.toBe(second.token);
+            const { rows } = await pg.query(`SELECT verification_token FROM "user" WHERE id = $1`, ["user-1"]);
+            const row = rows[0];
+            expect(row.verification_token).toBe(second.token);
+        });
+    });
+    describe("verifyToken", () => {
+        it("should verify a valid token and mark user as verified", async () => {
+            const { token } = await generateVerificationToken(pool, "user-1");
+            const result = await verifyToken(pool, token);
+            expect(result).toEqual({ userId: "user-1", email: "alice@test.com" });
+            const { rows } = await pg.query(`SELECT email_verified, verification_token FROM "user" WHERE id = $1`, [
+                "user-1",
+            ]);
+            const row = rows[0];
+            expect(row.email_verified).toBe(true);
+            expect(row.verification_token).toBeNull();
+        });
+        it("should return null for non-existent token", async () => {
+            expect(await verifyToken(pool, "a".repeat(64))).toBeNull();
+        });
+        it("should return null for empty token", async () => {
+            expect(await verifyToken(pool, "")).toBeNull();
+        });
+        it("should return null for wrong-length token", async () => {
+            expect(await verifyToken(pool, "abc")).toBeNull();
+        });
+        it("should return null for expired token", async () => {
+            const { token } = await generateVerificationToken(pool, "user-1");
+            await pg.query(`UPDATE "user" SET verification_expires = $1 WHERE id = $2`, [
+                new Date(Date.now() - 1000).toISOString(),
+                "user-1",
+            ]);
+            expect(await verifyToken(pool, token)).toBeNull();
+        });
+        it("should return null for already-verified user", async () => {
+            const { token } = await generateVerificationToken(pool, "user-1");
+            await pg.query(`UPDATE "user" SET email_verified = true WHERE id = $1`, ["user-1"]);
+            expect(await verifyToken(pool, token)).toBeNull();
+        });
+        it("should only allow single verification per token", async () => {
+            const { token } = await generateVerificationToken(pool, "user-1");
+            const first = await verifyToken(pool, token);
+            const second = await verifyToken(pool, token);
+            expect(first).toEqual({ userId: "user-1", email: "alice@test.com" });
+            expect(second).toBeNull();
+        });
+    });
+    describe("isEmailVerified", () => {
+        it("should return false for unverified user", async () => {
+            expect(await isEmailVerified(pool, "user-1")).toBe(false);
+        });
+        it("should return true after verification", async () => {
+            const { token } = await generateVerificationToken(pool, "user-1");
+            await verifyToken(pool, token);
+            expect(await isEmailVerified(pool, "user-1")).toBe(true);
+        });
+        it("should return false for non-existent user", async () => {
+            expect(await isEmailVerified(pool, "no-such-user")).toBe(false);
+        });
+    });
+    describe("getUserEmail", () => {
+        it("should return email for existing user", async () => {
+            expect(await getUserEmail(pool, "user-1")).toBe("alice@test.com");
+        });
+        it("should return null for non-existent user", async () => {
+            expect(await getUserEmail(pool, "no-such-user")).toBeNull();
+        });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type { PlatformDb, PlatformSchema } from "./db/index.js";
+export { createDb, schema } from "./db/index.js";
+export * from "./admin/index.js";
+export * from "./auth/index.js";
+export { PaymentMethodOwnershipError, noOpReplayGuard, DrizzleWebhookSeenRepository, type SavedPaymentMethod, type CheckoutOpts, type CheckoutSession, type ChargeOpts, type ChargeResult, type SetupResult, type PortalOpts, type WebhookResult, type IPaymentProcessor, type Invoice, type IWebhookSeenRepository, } from "./billing/index.js";
+export { config, billingConfigSchema, type PlatformConfig } from "./config/index.js";
+export * from "./credits/index.js";
+export * from "./email/index.js";
+export * from "./metering/index.js";
+export * from "./middleware/index.js";
+export * from "./security/index.js";
+export * from "./tenancy/index.js";
+export * from "./trpc/index.js";

package/dist/index.js

@@ -0,0 +1,23 @@
+export { createDb, schema } from "./db/index.js";
+// Admin
+export * from "./admin/index.js";
+// Auth
+export * from "./auth/index.js";
+// Billing (selective — ITenantCustomerRepository/TenantCustomerRow also in credits)
+export { PaymentMethodOwnershipError, noOpReplayGuard, DrizzleWebhookSeenRepository, } from "./billing/index.js";
+// Config
+export { config, billingConfigSchema } from "./config/index.js";
+// Credits
+export * from "./credits/index.js";
+// Email
+export * from "./email/index.js";
+// Metering
+export * from "./metering/index.js";
+// Middleware
+export * from "./middleware/index.js";
+// Security
+export * from "./security/index.js";
+// Tenancy
+export * from "./tenancy/index.js";
+// tRPC
+export * from "./trpc/index.js";

package/dist/metering/aggregator.d.ts

@@ -0,0 +1,54 @@
+import type { IUsageSummaryRepository } from "./drizzle-usage-summary-repository.js";
+import type { UsageSummary } from "./types.js";
+export interface IMeterAggregator {
+    aggregate(now?: number): Promise<number>;
+    start(intervalMs?: number): void;
+    stop(): 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;
+    }>;
+}
+/**
+ * Background aggregator that rolls up raw meter events into per-tenant
+ * usage summaries over fixed time windows.
+ *
+ * Designed to run periodically (e.g., every minute). Each run aggregates
+ * events from a completed window that haven't been summarized yet.
+ */
+export declare class DrizzleMeterAggregator implements IMeterAggregator {
+    private readonly repo;
+    private readonly windowMs;
+    private timer;
+    constructor(repo: IUsageSummaryRepository, opts?: {
+        windowMs?: number;
+    });
+    /**
+     * Aggregate all events in completed windows up to `now`.
+     * Returns the number of summary rows inserted.
+     */
+    aggregate(now?: number): Promise<number>;
+    /** Start periodic aggregation. */
+    start(intervalMs?: number): void;
+    /** Stop periodic aggregation. */
+    stop(): 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 across all capabilities since a given time. */
+    getTenantTotal(tenant: string, since: number): Promise<{
+        totalCost: number;
+        totalCharge: number;
+        eventCount: number;
+    }>;
+}
+export { DrizzleMeterAggregator as MeterAggregator };

package/dist/metering/aggregator.js

@@ -0,0 +1,123 @@
+import crypto from "node:crypto";
+/**
+ * Background aggregator that rolls up raw meter events into per-tenant
+ * usage summaries over fixed time windows.
+ *
+ * Designed to run periodically (e.g., every minute). Each run aggregates
+ * events from a completed window that haven't been summarized yet.
+ */
+export class DrizzleMeterAggregator {
+    repo;
+    windowMs;
+    timer = null;
+    constructor(repo, opts = {}) {
+        this.repo = repo;
+        this.windowMs = opts.windowMs ?? 60_000; // 1 minute default
+    }
+    /**
+     * Aggregate all events in completed windows up to `now`.
+     * Returns the number of summary rows inserted.
+     */
+    async aggregate(now = Date.now()) {
+        let lastEnd = await this.repo.getLastWindowEnd();
+        // Calculate the current window boundary. We only aggregate *completed* windows.
+        const currentWindowStart = Math.floor(now / this.windowMs) * this.windowMs;
+        if (lastEnd >= currentWindowStart) {
+            // Nothing new to aggregate.
+            return 0;
+        }
+        let totalInserted = 0;
+        // Process one window at a time to respect fixed time window boundaries.
+        // On first run (lastEnd === 0), align to the first window boundary at or
+        // before currentWindowStart so we don't create thousands of empty sentinels.
+        if (lastEnd === 0) {
+            // Find earliest event to anchor the first window.
+            const earliest = await this.repo.getEarliestEventTimestamp(currentWindowStart);
+            if (earliest != null) {
+                lastEnd = Math.floor(earliest / this.windowMs) * this.windowMs;
+            }
+            else {
+                // No events at all -- insert a single sentinel to mark we've processed up to now.
+                await this.repo.insertSummary({
+                    id: crypto.randomUUID(),
+                    tenant: "__sentinel__",
+                    capability: "__none__",
+                    provider: "__none__",
+                    eventCount: 0,
+                    totalCost: 0,
+                    totalCharge: 0,
+                    totalDuration: 0,
+                    windowStart: 0,
+                    windowEnd: currentWindowStart,
+                });
+                return 0;
+            }
+        }
+        while (lastEnd < currentWindowStart) {
+            const windowStart = lastEnd;
+            const windowEnd = Math.min(lastEnd + this.windowMs, currentWindowStart);
+            // Group events by tenant + capability + provider within this single window.
+            const rows = await this.repo.getAggregatedEvents(windowStart, windowEnd);
+            if (rows.length === 0) {
+                // Advance past this empty window by inserting a sentinel with zero counts.
+                await this.repo.insertSummary({
+                    id: crypto.randomUUID(),
+                    tenant: "__sentinel__",
+                    capability: "__none__",
+                    provider: "__none__",
+                    eventCount: 0,
+                    totalCost: 0,
+                    totalCharge: 0,
+                    totalDuration: 0,
+                    windowStart,
+                    windowEnd,
+                });
+            }
+            else {
+                await this.repo.insertSummariesBatch(rows.map((s) => ({
+                    id: crypto.randomUUID(),
+                    tenant: s.tenant,
+                    capability: s.capability,
+                    provider: s.provider,
+                    eventCount: s.eventCount,
+                    totalCost: s.totalCost,
+                    totalCharge: s.totalCharge,
+                    totalDuration: s.totalDuration,
+                    windowStart,
+                    windowEnd,
+                })));
+                totalInserted += rows.length;
+            }
+            lastEnd = windowEnd;
+        }
+        return totalInserted;
+    }
+    /** Start periodic aggregation. */
+    start(intervalMs) {
+        if (this.timer) {
+            return; // Already running -- avoid leaking a second interval timer.
+        }
+        const interval = intervalMs ?? this.windowMs;
+        this.timer = setInterval(() => this.aggregate(), interval);
+        if (this.timer.unref) {
+            this.timer.unref();
+        }
+    }
+    /** Stop periodic aggregation. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Query usage summaries for a tenant within a time range. */
+    async querySummaries(tenant, opts = {}) {
+        return this.repo.querySummaries(tenant, opts);
+    }
+    /** Get a tenant's total usage across all capabilities since a given time. */
+    async getTenantTotal(tenant, since) {
+        return this.repo.getTenantTotal(tenant, since);
+    }
+}
+// Backward-compat alias.
+export { DrizzleMeterAggregator as MeterAggregator };

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

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

package/dist/metering/aggregator.test.js

@@ -0,0 +1,179 @@
+import crypto from "node:crypto";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { meterEvents, usageSummaries } from "../db/schema/meter-events.js";
+import { createTestDb } from "../test/db.js";
+import { Credit } from "../credits/credit.js";
+import { DrizzleMeterAggregator } from "./aggregator.js";
+import { DrizzleUsageSummaryRepository } from "./drizzle-usage-summary-repository.js";
+const WINDOW_MS = 60_000; // 1-minute windows
+describe("DrizzleMeterAggregator edge cases", () => {
+    let db;
+    let pool;
+    let aggregator;
+    beforeEach(async () => {
+        const testDb = await createTestDb();
+        db = testDb.db;
+        pool = testDb.pool;
+        aggregator = new DrizzleMeterAggregator(new DrizzleUsageSummaryRepository(db), { windowMs: WINDOW_MS });
+    });
+    afterEach(async () => {
+        aggregator.stop();
+        await pool.close();
+    });
+    async function insertEvent(overrides) {
+        await db.insert(meterEvents).values({
+            id: overrides.id ?? crypto.randomUUID(),
+            tenant: overrides.tenant ?? "tenant-1",
+            cost: overrides.cost ?? Credit.fromDollars(0.001).toRaw(),
+            charge: overrides.charge ?? Credit.fromDollars(0.002).toRaw(),
+            capability: overrides.capability ?? "embeddings",
+            provider: overrides.provider ?? "openai",
+            timestamp: overrides.timestamp,
+        });
+    }
+    it("sums events correctly within a single completed window", async () => {
+        const baseTime = 0;
+        await insertEvent({ timestamp: baseTime + 10_000, cost: 1_000_000, charge: 2_000_000 });
+        await insertEvent({ timestamp: baseTime + 20_000, cost: 3_000_000, charge: 4_000_000 });
+        await insertEvent({ timestamp: baseTime + 30_000, cost: 5_000_000, charge: 6_000_000 });
+        const inserted = await aggregator.aggregate(WINDOW_MS + 1);
+        expect(inserted).toBe(1);
+        const summaries = await db.select().from(usageSummaries);
+        const real = summaries.filter((s) => s.tenant !== "__sentinel__");
+        expect(real).toHaveLength(1);
+        expect(real[0].tenant).toBe("tenant-1");
+        expect(real[0].eventCount).toBe(3);
+        expect(real[0].totalCost).toBe(9_000_000);
+        expect(real[0].totalCharge).toBe(12_000_000);
+        expect(real[0].windowStart).toBe(0);
+        expect(real[0].windowEnd).toBe(WINDOW_MS);
+    });
+    it("returns zero and inserts sentinel when no events exist", async () => {
+        const inserted = await aggregator.aggregate(WINDOW_MS + 1);
+        expect(inserted).toBe(0);
+        const summaries = await db.select().from(usageSummaries);
+        expect(summaries).toHaveLength(1);
+        expect(summaries[0].tenant).toBe("__sentinel__");
+        expect(summaries[0].eventCount).toBe(0);
+    });
+    it("rejects duplicate event IDs via primary key constraint", async () => {
+        const eventId = crypto.randomUUID();
+        await insertEvent({ timestamp: 10_000, id: eventId });
+        await expect(insertEvent({ timestamp: 10_000, id: eventId })).rejects.toThrow();
+        const inserted = await aggregator.aggregate(WINDOW_MS + 1);
+        expect(inserted).toBe(1);
+        const summaries = await db.select().from(usageSummaries);
+        const real = summaries.filter((s) => s.tenant !== "__sentinel__");
+        expect(real).toHaveLength(1);
+        expect(real[0].eventCount).toBe(1);
+    });
+    it("handles very large cost totals without overflow", async () => {
+        const largeCost = 1_000_000_000_000;
+        const largeCharge = 2_000_000_000_000;
+        for (let i = 0; i < 5; i++) {
+            await insertEvent({ timestamp: 10_000 + i * 1000, cost: largeCost, charge: largeCharge });
+        }
+        const inserted = await aggregator.aggregate(WINDOW_MS + 1);
+        expect(inserted).toBe(1);
+        const summaries = await db.select().from(usageSummaries);
+        const real = summaries.filter((s) => s.tenant !== "__sentinel__");
+        expect(real).toHaveLength(1);
+        expect(real[0].totalCost).toBe(5_000_000_000_000);
+        expect(real[0].totalCharge).toBe(10_000_000_000_000);
+        expect(real[0].eventCount).toBe(5);
+    });
+    it("isolates aggregation per tenant", async () => {
+        await insertEvent({ tenant: "tenant-A", timestamp: 10_000, cost: 1_000_000, charge: 2_000_000 });
+        await insertEvent({ tenant: "tenant-A", timestamp: 20_000, cost: 3_000_000, charge: 4_000_000 });
+        await insertEvent({ tenant: "tenant-B", timestamp: 15_000, cost: 5_000_000, charge: 6_000_000 });
+        const inserted = await aggregator.aggregate(WINDOW_MS + 1);
+        expect(inserted).toBe(2);
+        const summaries = await db.select().from(usageSummaries);
+        const real = summaries.filter((s) => s.tenant !== "__sentinel__");
+        expect(real).toHaveLength(2);
+        const tenantA = real.find((s) => s.tenant === "tenant-A");
+        expect(tenantA).toEqual(expect.objectContaining({
+            tenant: "tenant-A",
+            eventCount: 2,
+            totalCost: 4_000_000,
+            totalCharge: 6_000_000,
+        }));
+        const tenantB = real.find((s) => s.tenant === "tenant-B");
+        expect(tenantB).toEqual(expect.objectContaining({
+            tenant: "tenant-B",
+            eventCount: 1,
+            totalCost: 5_000_000,
+            totalCharge: 6_000_000,
+        }));
+    });
+    it("includes events at window start, excludes events at window end", async () => {
+        await insertEvent({ timestamp: 0, cost: 1_000_000, charge: 1_000_000 });
+        await insertEvent({ timestamp: 59_999, cost: 2_000_000, charge: 2_000_000 });
+        await insertEvent({ timestamp: 60_000, cost: 100_000_000, charge: 100_000_000 });
+        const inserted = await aggregator.aggregate(2 * WINDOW_MS + 1);
+        const summaries = await db.select().from(usageSummaries);
+        const real = summaries.filter((s) => s.tenant !== "__sentinel__");
+        const window0 = real.find((s) => s.windowStart === 0);
+        expect(window0).toEqual(expect.objectContaining({
+            windowStart: 0,
+            eventCount: 2,
+            totalCost: 3_000_000,
+        }));
+        const window1 = real.find((s) => s.windowStart === 60_000);
+        expect(window1).toEqual(expect.objectContaining({
+            windowStart: 60_000,
+            eventCount: 1,
+            totalCost: 100_000_000,
+        }));
+        // window0: 1 tenant/capability/provider group = 1 row
+        // window1: 1 tenant/capability/provider group = 1 row
+        expect(inserted).toBe(2);
+    });
+    it("aggregates zero-cost events correctly", async () => {
+        await insertEvent({ timestamp: 10_000, cost: 0, charge: 0 });
+        await insertEvent({ timestamp: 20_000, cost: 0, charge: 0 });
+        const inserted = await aggregator.aggregate(WINDOW_MS + 1);
+        expect(inserted).toBe(1);
+        const summaries = await db.select().from(usageSummaries);
+        const real = summaries.filter((s) => s.tenant !== "__sentinel__");
+        expect(real).toHaveLength(1);
+        expect(real[0].totalCost).toBe(0);
+        expect(real[0].totalCharge).toBe(0);
+        expect(real[0].eventCount).toBe(2);
+    });
+    it("handles a single event exactly at window boundary", async () => {
+        // Event at timestamp 0 (window start) — should be in window [0, WINDOW_MS)
+        await insertEvent({ timestamp: 0, cost: 1_000_000, charge: 2_000_000 });
+        const inserted = await aggregator.aggregate(WINDOW_MS + 1);
+        expect(inserted).toBe(1);
+        const summaries = await db.select().from(usageSummaries);
+        const real = summaries.filter((s) => s.tenant !== "__sentinel__");
+        expect(real).toHaveLength(1);
+        expect(real[0].eventCount).toBe(1);
+        expect(real[0].totalCost).toBe(1_000_000);
+    });
+    it("handles event one unit before window end", async () => {
+        // Event at WINDOW_MS - 1 should be included in first window
+        await insertEvent({ timestamp: WINDOW_MS - 1, cost: 500_000, charge: 600_000 });
+        const inserted = await aggregator.aggregate(WINDOW_MS + 1);
+        expect(inserted).toBe(1);
+        const summaries = await db.select().from(usageSummaries);
+        const real = summaries.filter((s) => s.tenant !== "__sentinel__");
+        expect(real).toHaveLength(1);
+        expect(real[0].windowStart).toBe(0);
+        expect(real[0].eventCount).toBe(1);
+        expect(real[0].totalCost).toBe(500_000);
+    });
+    it("handles event exactly at window end (goes to next window)", async () => {
+        // Event at exactly WINDOW_MS should be in window [WINDOW_MS, 2*WINDOW_MS)
+        await insertEvent({ timestamp: WINDOW_MS, cost: 700_000, charge: 800_000 });
+        await aggregator.aggregate(2 * WINDOW_MS + 1);
+        const summaries = await db.select().from(usageSummaries);
+        const real = summaries.filter((s) => s.tenant !== "__sentinel__");
+        // Should be in second window, not first
+        expect(real).toHaveLength(1);
+        expect(real[0].windowStart).toBe(WINDOW_MS);
+        expect(real[0].eventCount).toBe(1);
+        expect(real[0].totalCost).toBe(700_000);
+    });
+});

package/dist/metering/dlq.d.ts

@@ -0,0 +1,31 @@
+import type { MeterEvent } from "./types.js";
+/**
+ * Dead-Letter Queue for meter events that failed to flush after max retries.
+ *
+ * Events written here are permanently failed and require manual intervention
+ * to recover. This ensures we never silently drop billing events.
+ */
+export declare class MeterDLQ {
+    private readonly dlqPath;
+    constructor(dlqPath: string);
+    private ensureDir;
+    /**
+     * Append a failed event to the DLQ with failure metadata.
+     */
+    append(event: MeterEvent & {
+        id: string;
+    }, error: string, retries: number): void;
+    /**
+     * Read all events from the DLQ for manual recovery.
+     */
+    readAll(): Array<MeterEvent & {
+        id: string;
+        dlq_timestamp: number;
+        dlq_error: string;
+        dlq_retries: number;
+    }>;
+    /**
+     * Get the number of events in the DLQ.
+     */
+    count(): number;
+}

package/dist/metering/dlq.js

@@ -0,0 +1,82 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Dead-Letter Queue for meter events that failed to flush after max retries.
+ *
+ * Events written here are permanently failed and require manual intervention
+ * to recover. This ensures we never silently drop billing events.
+ */
+export class MeterDLQ {
+    dlqPath;
+    constructor(dlqPath) {
+        this.dlqPath = dlqPath;
+        this.ensureDir();
+    }
+    ensureDir() {
+        const dir = dirname(this.dlqPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    /**
+     * Append a failed event to the DLQ with failure metadata.
+     */
+    append(event, error, retries) {
+        const dlqEntry = {
+            ...event,
+            dlq_timestamp: Date.now(),
+            dlq_error: error,
+            dlq_retries: retries,
+        };
+        const line = `${JSON.stringify(dlqEntry)}\n`;
+        appendFileSync(this.dlqPath, line, { encoding: "utf8", flag: "a" });
+    }
+    /**
+     * Read all events from the DLQ for manual recovery.
+     */
+    readAll() {
+        if (!existsSync(this.dlqPath)) {
+            return [];
+        }
+        const content = readFileSync(this.dlqPath, "utf8");
+        if (!content.trim()) {
+            return [];
+        }
+        const entries = [];
+        for (const line of content.trim().split("\n")) {
+            try {
+                entries.push(JSON.parse(line));
+            }
+            catch {
+                // Skip malformed lines (e.g., from incomplete writes during error conditions).
+            }
+        }
+        return entries;
+    }
+    /**
+     * Get the number of events in the DLQ.
+     */
+    count() {
+        let content;
+        try {
+            content = readFileSync(this.dlqPath, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                return 0;
+            }
+            throw err;
+        }
+        if (!content) {
+            return 0;
+        }
+        let n = 0;
+        for (let i = 0; i < content.length; i++) {
+            if (content.charCodeAt(i) === 10)
+                n++;
+        }
+        if (content.length > 0 && content.charCodeAt(content.length - 1) !== 10)
+            n++;
+        return n;
+    }
+}

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

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