@wopr-network/platform-core 0.1.0

package/dist/credits/credit.js

@@ -0,0 +1,139 @@
+import { logger } from "../config/logger.js";
+/**
+ * Credit value object with sub-cent precision.
+ *
+ * SCALE = 1,000,000,000 raw units per dollar (nano-dollars).
+ * All arithmetic operates on integer raw units -- no floating point
+ * in arithmetic paths. Math.round() is used only at input boundaries
+ * (fromDollars, fromCents, multiply).
+ *
+ * @example
+ * ```ts
+ * const charge = Credit.fromDollars(0.001); // 1,000,000 raw units
+ * const balance = Credit.fromCents(500);     // 5,000,000,000 raw units
+ * const remaining = balance.subtract(charge);
+ * ```
+ */
+export class Credit {
+    raw;
+    static SCALE = 1_000_000_000;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    /** Zero credit (static readonly instance to avoid allocation per access). */
+    static ZERO = new Credit(0);
+    /** Create from dollar amount. Rounds to nearest raw unit. */
+    static fromDollars(dollars) {
+        return new Credit(Math.round(dollars * Credit.SCALE));
+    }
+    /** Create from cent amount. Rounds to nearest raw unit. */
+    static fromCents(cents) {
+        return new Credit(Math.round(cents * (Credit.SCALE / 100)));
+    }
+    // Tiered balance thresholds (in raw units) for observability warnings.
+    static WARN_10K = 10_000 * Credit.SCALE; // $10,000
+    static WARN_100K = 100_000 * Credit.SCALE; // $100,000
+    static WARN_1M = 1_000_000 * Credit.SCALE; // $1,000,000
+    /** Create from raw integer units. Throws TypeError if not integer. */
+    static fromRaw(raw) {
+        if (!Number.isInteger(raw)) {
+            throw new TypeError(`Credit.fromRaw requires an integer, got ${raw}`);
+        }
+        if (raw > Number.MAX_SAFE_INTEGER) {
+            throw new RangeError(`Credit.fromRaw value ${raw} exceeds MAX_SAFE_INTEGER — bigint migration required`);
+        }
+        const dollars = raw / Credit.SCALE;
+        if (raw >= Credit.WARN_1M) {
+            logger.warn("Credit balance WTF threshold reached — consider bigint migration", { dollars: dollars.toFixed(2) });
+        }
+        else if (raw >= Credit.WARN_100K) {
+            logger.warn("Credit balance HIGH threshold reached — monitor for overflow", { dollars: dollars.toFixed(2) });
+        }
+        else if (raw >= Credit.WARN_10K) {
+            logger.info("Credit balance large threshold reached", { dollars: dollars.toFixed(2) });
+        }
+        return new Credit(raw);
+    }
+    /** Zero credit (factory method alias for Credit.ZERO). */
+    static zero() {
+        return Credit.ZERO;
+    }
+    /** Convert to dollars (floating point, for display only). */
+    toDollars() {
+        return this.raw / Credit.SCALE;
+    }
+    /** Convert to cents (floating point, for display only). */
+    toCents() {
+        return this.raw / (Credit.SCALE / 100);
+    }
+    /**
+     * Convert to cents, rounded to nearest integer (Math.round).
+     * Use for display values and API responses where exact cent is needed.
+     */
+    toCentsRounded() {
+        return Math.round(this.raw / (Credit.SCALE / 100));
+    }
+    /**
+     * Convert to cents, floored to integer (Math.floor).
+     * Use when sending amounts to Stripe/Payram — floor avoids charging
+     * more than the displayed amount.
+     */
+    toCentsFloor() {
+        return Math.floor(this.raw / (Credit.SCALE / 100));
+    }
+    /** Display as dollar amount with two decimal places. */
+    toDisplayString() {
+        return `$${this.toDollars().toFixed(2)}`;
+    }
+    /** Raw integer units (what gets stored in the database). */
+    toRaw() {
+        return this.raw;
+    }
+    /** Add another Credit, returning a new Credit. */
+    add(other) {
+        return new Credit(this.raw + other.raw);
+    }
+    /** Subtract another Credit, returning a new Credit (may be negative). */
+    subtract(other) {
+        return new Credit(this.raw - other.raw);
+    }
+    /** Multiply by a factor, rounding to nearest raw unit. */
+    multiply(factor) {
+        return new Credit(Math.round(this.raw * factor));
+    }
+    /** True if this credit is negative. */
+    isNegative() {
+        return this.raw < 0;
+    }
+    /** True if this credit is exactly zero. */
+    isZero() {
+        return this.raw === 0;
+    }
+    /** True if this credit is greater than other. */
+    greaterThan(other) {
+        return this.raw > other.raw;
+    }
+    /** True if this credit is less than other. */
+    lessThan(other) {
+        return this.raw < other.raw;
+    }
+    /** True if this credit equals other. */
+    equals(other) {
+        return this.raw === other.raw;
+    }
+    /** True if this credit is greater than or equal to other. */
+    greaterThanOrEqual(other) {
+        return this.raw >= other.raw;
+    }
+    /** True if this credit is less than or equal to other. */
+    lessThanOrEqual(other) {
+        return this.raw <= other.raw;
+    }
+    toString() {
+        return `Credit(raw=${this.raw})`;
+    }
+    /** Serialize to raw integer for JSON (API responses, database). */
+    toJSON() {
+        return this.raw;
+    }
+}

package/dist/credits/credit.test.d.ts

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

package/dist/credits/credit.test.js

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import { Credit } from "./credit.js";
+describe("Credit", () => {
+    describe("factory methods", () => {
+        it("fromDollars creates correct raw value", () => {
+            const c = Credit.fromDollars(1);
+            expect(c.toRaw()).toBe(1_000_000_000);
+        });
+        it("fromDollars handles sub-cent precision", () => {
+            const c = Credit.fromDollars(0.001); // 1 mill
+            expect(c.toRaw()).toBe(1_000_000);
+        });
+        it("fromCents creates correct raw value", () => {
+            const c = Credit.fromCents(1);
+            expect(c.toRaw()).toBe(10_000_000);
+        });
+        it("fromCents handles fractional cents", () => {
+            const c = Credit.fromCents(0.5);
+            expect(c.toRaw()).toBe(5_000_000);
+        });
+        it("fromRaw stores exact value", () => {
+            const c = Credit.fromRaw(42);
+            expect(c.toRaw()).toBe(42);
+        });
+        it("fromRaw rejects non-integer", () => {
+            expect(() => Credit.fromRaw(1.5)).toThrow(TypeError);
+        });
+        it("zero creates zero credit", () => {
+            expect(Credit.zero().toRaw()).toBe(0);
+        });
+        it("ZERO has raw value 0", () => {
+            expect(Credit.ZERO.toRaw()).toBe(0);
+        });
+    });
+    describe("conversion", () => {
+        it("toDollars converts correctly", () => {
+            const c = Credit.fromRaw(1_000_000_000);
+            expect(c.toDollars()).toBe(1);
+        });
+        it("toCents converts correctly", () => {
+            const c = Credit.fromRaw(10_000_000);
+            expect(c.toCents()).toBe(1);
+        });
+        it("sub-cent value round-trips through fromCents/toCents", () => {
+            const c = Credit.fromCents(0.123);
+            // 0.123 cents * 10_000_000 raw-per-cent = 1_230_000
+            expect(c.toRaw()).toBe(1_230_000);
+            expect(c.toCents()).toBeCloseTo(0.123, 10);
+        });
+        it("toDisplayString formats as currency", () => {
+            expect(Credit.fromDollars(1.5).toDisplayString()).toBe("$1.50");
+        });
+        it("toCentsRounded rounds to nearest integer cent", () => {
+            // 0.123 cents -> rounds to 0
+            expect(Credit.fromCents(0.123).toCentsRounded()).toBe(0);
+            // 0.5 cents -> rounds to 1 (banker's rounding irrelevant, Math.round rounds 0.5 up)
+            expect(Credit.fromCents(0.5).toCentsRounded()).toBe(1);
+            // 0.7 cents -> rounds to 1
+            expect(Credit.fromCents(0.7).toCentsRounded()).toBe(1);
+            // exact integer cents pass through unchanged
+            expect(Credit.fromCents(500).toCentsRounded()).toBe(500);
+        });
+        it("toCentsFloor truncates toward negative infinity", () => {
+            // 0.9 cents -> floors to 0
+            expect(Credit.fromCents(0.9).toCentsFloor()).toBe(0);
+            // exact integer cents pass through unchanged
+            expect(Credit.fromCents(500).toCentsFloor()).toBe(500);
+            // negative: -0.1 cents -> floors to -1
+            expect(Credit.fromCents(-0.1).toCentsFloor()).toBe(-1);
+        });
+        it("toDisplayString rounds sub-cent to two decimals", () => {
+            // 1 raw unit = $0.000000001, should display as $0.00
+            expect(Credit.fromRaw(1).toDisplayString()).toBe("$0.00");
+            // $0.999 should display as $1.00
+            expect(Credit.fromRaw(999_000_000).toDisplayString()).toBe("$1.00");
+        });
+    });
+    describe("arithmetic", () => {
+        it("add combines two credits", () => {
+            const a = Credit.fromCents(10);
+            const b = Credit.fromCents(20);
+            expect(a.add(b).toRaw()).toBe(300_000_000);
+        });
+        it("subtract removes credits", () => {
+            const a = Credit.fromCents(30);
+            const b = Credit.fromCents(10);
+            expect(a.subtract(b).toRaw()).toBe(200_000_000);
+        });
+        it("subtract can produce negative", () => {
+            const a = Credit.fromCents(5);
+            const b = Credit.fromCents(10);
+            expect(a.subtract(b).isNegative()).toBe(true);
+        });
+        it("multiply scales by factor", () => {
+            const c = Credit.fromDollars(1);
+            expect(c.multiply(2.5).toRaw()).toBe(2_500_000_000);
+        });
+        it("multiply rounds to integer raw", () => {
+            const c = Credit.fromRaw(3);
+            // 3 * 0.5 = 1.5, rounds to 2
+            expect(c.multiply(0.5).toRaw()).toBe(2);
+        });
+        it("multiply by zero gives zero", () => {
+            expect(Credit.fromDollars(5).multiply(0).isZero()).toBe(true);
+        });
+    });
+    describe("comparison", () => {
+        it("isNegative returns true for negative", () => {
+            expect(Credit.fromRaw(-1).isNegative()).toBe(true);
+        });
+        it("isNegative returns false for zero", () => {
+            expect(Credit.zero().isNegative()).toBe(false);
+        });
+        it("isZero returns true for zero", () => {
+            expect(Credit.zero().isZero()).toBe(true);
+        });
+        it("isZero returns false for non-zero", () => {
+            expect(Credit.fromRaw(1).isZero()).toBe(false);
+        });
+        it("greaterThan compares correctly", () => {
+            const a = Credit.fromRaw(10);
+            const b = Credit.fromRaw(5);
+            expect(a.greaterThan(b)).toBe(true);
+            expect(b.greaterThan(a)).toBe(false);
+        });
+        it("lessThan compares correctly", () => {
+            const a = Credit.fromRaw(5);
+            const b = Credit.fromRaw(10);
+            expect(a.lessThan(b)).toBe(true);
+            expect(b.lessThan(a)).toBe(false);
+        });
+        it("equals compares correctly", () => {
+            const a = Credit.fromRaw(42);
+            const b = Credit.fromRaw(42);
+            const c = Credit.fromRaw(43);
+            expect(a.equals(b)).toBe(true);
+            expect(a.equals(c)).toBe(false);
+        });
+        it("equals: fromDollars(1) equals fromCents(100)", () => {
+            expect(Credit.fromDollars(1).equals(Credit.fromCents(100))).toBe(true);
+        });
+        it("lessThanOrEqual compares correctly", () => {
+            expect(Credit.fromCents(5).lessThanOrEqual(Credit.fromCents(5))).toBe(true);
+            expect(Credit.fromCents(5).lessThanOrEqual(Credit.fromCents(10))).toBe(true);
+            expect(Credit.fromCents(10).lessThanOrEqual(Credit.fromCents(5))).toBe(false);
+        });
+        it("greaterThanOrEqual compares correctly", () => {
+            expect(Credit.fromCents(10).greaterThanOrEqual(Credit.fromCents(5))).toBe(true);
+            expect(Credit.fromCents(5).greaterThanOrEqual(Credit.fromCents(5))).toBe(true);
+            expect(Credit.fromCents(5).greaterThanOrEqual(Credit.fromCents(10))).toBe(false);
+        });
+    });
+    describe("toString", () => {
+        it("returns debug representation", () => {
+            const c = Credit.fromRaw(123456);
+            expect(c.toString()).toBe("Credit(raw=123456)");
+        });
+    });
+    describe("toJSON", () => {
+        it("toJSON returns raw value", () => {
+            const c = Credit.fromDollars(1);
+            expect(c.toJSON()).toBe(1_000_000_000);
+            expect(JSON.stringify({ amount: c })).toBe('{"amount":1000000000}');
+        });
+    });
+    describe("sub-cent precision proof", () => {
+        it("$0.001 charge does not round to zero", () => {
+            const charge = Credit.fromDollars(0.001);
+            expect(charge.isZero()).toBe(false);
+            expect(charge.toRaw()).toBe(1_000_000);
+        });
+        it("$0.000000001 charge (1 raw unit) does not round to zero", () => {
+            const charge = Credit.fromDollars(0.000000001);
+            expect(charge.isZero()).toBe(false);
+            expect(charge.toRaw()).toBe(1);
+        });
+        it("old integer-cents would lose $0.001 but Credit preserves it", () => {
+            // In old system: Math.round(0.001 * 100) = 0 cents (lost!)
+            const oldCents = Math.round(0.001 * 100);
+            expect(oldCents).toBe(0);
+            // In new system: preserved
+            const credit = Credit.fromDollars(0.001);
+            expect(credit.toRaw()).toBe(1_000_000);
+            expect(credit.isZero()).toBe(false);
+        });
+        it("accumulates sub-cent charges without loss", () => {
+            const tiny = Credit.fromDollars(0.0001); // 100_000 raw
+            let total = Credit.ZERO;
+            for (let i = 0; i < 10_000; i++) {
+                total = total.add(tiny);
+            }
+            expect(total.toDollars()).toBeCloseTo(1.0);
+            expect(total.toRaw()).toBe(1_000_000_000);
+        });
+    });
+});

package/dist/credits/dividend-cron.d.ts

@@ -0,0 +1,29 @@
+import { Credit } from "./credit.js";
+import type { ICreditLedger } from "./credit-ledger.js";
+import type { ICreditTransactionRepository } from "./credit-transaction-repository.js";
+export interface DividendCronConfig {
+    creditTransactionRepo: ICreditTransactionRepository;
+    ledger: ICreditLedger;
+    /** Fraction of daily purchases matched as dividend pool. Default 1.0 (100%). */
+    matchRate: number;
+    /** The date to compute dividend for, as YYYY-MM-DD string. Typically yesterday. */
+    targetDate: string;
+}
+export interface DividendCronResult {
+    pool: Credit;
+    activeCount: number;
+    perUser: Credit;
+    distributed: number;
+    skippedAlreadyRun: boolean;
+    errors: string[];
+}
+/**
+ * Compute and distribute the community dividend for a given day.
+ *
+ * 1. Check idempotency — skip if already run for this date.
+ * 2. Sum all 'purchase' transactions for the target date.
+ * 3. Find all tenants with a 'purchase' transaction in the last 7 days.
+ * 4. Compute pool = sum × matchRate, per-user share = floor(pool / activeCount).
+ * 5. Credit each active tenant with their share.
+ */
+export declare function runDividendCron(cfg: DividendCronConfig): Promise<DividendCronResult>;

package/dist/credits/dividend-cron.js

@@ -0,0 +1,88 @@
+import { logger } from "../config/logger.js";
+import { Credit } from "./credit.js";
+/**
+ * Compute and distribute the community dividend for a given day.
+ *
+ * 1. Check idempotency — skip if already run for this date.
+ * 2. Sum all 'purchase' transactions for the target date.
+ * 3. Find all tenants with a 'purchase' transaction in the last 7 days.
+ * 4. Compute pool = sum × matchRate, per-user share = floor(pool / activeCount).
+ * 5. Credit each active tenant with their share.
+ */
+export async function runDividendCron(cfg) {
+    const result = {
+        pool: Credit.ZERO,
+        activeCount: 0,
+        perUser: Credit.ZERO,
+        distributed: 0,
+        skippedAlreadyRun: false,
+        errors: [],
+    };
+    // Idempotency: check if any per-tenant dividend was already distributed for this date.
+    // We look for any referenceId matching "dividend:YYYY-MM-DD:*".
+    const sentinelPrefix = `dividend:${cfg.targetDate}:`;
+    const alreadyRan = await cfg.creditTransactionRepo.existsByReferenceIdLike(`${sentinelPrefix}%`);
+    if (alreadyRan) {
+        result.skippedAlreadyRun = true;
+        logger.info("Dividend cron already ran for this date", { targetDate: cfg.targetDate });
+        return result;
+    }
+    // Step 1: Sum all purchase amounts for the target date.
+    const dayStart = `${cfg.targetDate} 00:00:00`;
+    const dayEnd = `${cfg.targetDate} 24:00:00`;
+    const dailyPurchaseTotalCredit = await cfg.creditTransactionRepo.sumPurchasesForPeriod(dayStart, dayEnd);
+    result.pool = dailyPurchaseTotalCredit.multiply(cfg.matchRate);
+    // Step 2: Find all active tenants (purchased in last 7 days from target date).
+    // The 7-day window is: [targetDate - 6 days 00:00:00, targetDate 24:00:00)
+    // This gives a full 7-day range ending at the end of targetDate.
+    const windowStart = subtractDays(cfg.targetDate, 6);
+    const windowStartTs = `${windowStart} 00:00:00`;
+    const activeTenantIds = await cfg.creditTransactionRepo.getActiveTenantIdsInWindow(windowStartTs, dayEnd);
+    result.activeCount = activeTenantIds.length;
+    // Step 3: Compute per-user share.
+    if (result.pool.isZero() || result.activeCount <= 0) {
+        logger.info("Dividend cron: no pool or no active tenants", {
+            targetDate: cfg.targetDate,
+            pool: result.pool.toCents(),
+            activeCount: result.activeCount,
+        });
+        return result;
+    }
+    result.perUser = Credit.fromRaw(Math.floor(result.pool.toRaw() / result.activeCount));
+    if (result.perUser.isZero()) {
+        logger.info("Dividend cron: per-user share rounds to zero", {
+            targetDate: cfg.targetDate,
+            pool: result.pool.toCents(),
+            activeCount: result.activeCount,
+        });
+        return result;
+    }
+    // Step 4: Distribute to each active tenant.
+    for (const tenantId of activeTenantIds) {
+        const perUserRef = `dividend:${cfg.targetDate}:${tenantId}`;
+        try {
+            await cfg.ledger.credit(tenantId, result.perUser, "community_dividend", `Community dividend for ${cfg.targetDate}: pool ${result.pool.toCents()}c / ${result.activeCount} users`, perUserRef);
+            result.distributed++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error("Dividend distribution failed for tenant", { tenantId, error: msg });
+            result.errors.push(`${tenantId}: ${msg}`);
+        }
+    }
+    logger.info("Dividend cron complete", {
+        targetDate: cfg.targetDate,
+        pool: result.pool.toCents(),
+        activeCount: result.activeCount,
+        perUser: result.perUser.toCents(),
+        distributed: result.distributed,
+        errors: result.errors.length,
+    });
+    return result;
+}
+/** Subtract N days from a YYYY-MM-DD date string, returning YYYY-MM-DD. */
+function subtractDays(dateStr, days) {
+    const d = new Date(`${dateStr}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() - days);
+    return d.toISOString().slice(0, 10);
+}

package/dist/credits/dividend-cron.test.d.ts

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

package/dist/credits/dividend-cron.test.js

@@ -0,0 +1,128 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { creditBalances, creditTransactions } from "../db/schema/credits.js";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { CreditLedger } from "./credit-ledger.js";
+import { DrizzleCreditTransactionRepository } from "./credit-transaction-repository.js";
+import { runDividendCron } from "./dividend-cron.js";
+async function insertPurchase(db, tenantId, amountCents, createdAt) {
+    const id = `test-${tenantId}-${Date.now()}-${Math.random()}`;
+    const amount = Credit.fromCents(amountCents);
+    await db.insert(creditTransactions).values({
+        id,
+        tenantId,
+        amount,
+        balanceAfter: amount,
+        type: "purchase",
+        createdAt,
+    });
+    // Upsert credit_balances
+    const existing = await db
+        .select()
+        .from(creditBalances)
+        .where((await import("drizzle-orm")).eq(creditBalances.tenantId, tenantId));
+    if (existing.length > 0) {
+        await db
+            .update(creditBalances)
+            .set({ balance: existing[0].balance.add(amount) })
+            .where((await import("drizzle-orm")).eq(creditBalances.tenantId, tenantId));
+    }
+    else {
+        await db.insert(creditBalances).values({ tenantId, balance: amount });
+    }
+}
+describe("runDividendCron", () => {
+    let pool;
+    let db;
+    let ledger;
+    let creditTransactionRepo;
+    beforeAll(async () => {
+        ({ db, pool } = await createTestDb());
+    });
+    afterAll(async () => {
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await truncateAllTables(pool);
+        ledger = new CreditLedger(db);
+        creditTransactionRepo = new DrizzleCreditTransactionRepository(db);
+    });
+    function makeConfig(overrides) {
+        return {
+            creditTransactionRepo,
+            ledger,
+            matchRate: 1.0,
+            targetDate: "2026-02-20",
+            ...overrides,
+        };
+    }
+    it("distributes dividend to eligible tenants", async () => {
+        await insertPurchase(db, "t1", 1000, "2026-02-20 12:00:00");
+        const result = await runDividendCron(makeConfig());
+        expect(result.distributed).toBe(1);
+        expect(result.pool.toCents()).toBe(1000);
+        expect(result.perUser.toCents()).toBe(1000);
+        expect(result.activeCount).toBe(1);
+    });
+    it("is idempotent — skips if already ran for the date", async () => {
+        await insertPurchase(db, "t1", 1000, "2026-02-20 12:00:00");
+        const result1 = await runDividendCron(makeConfig());
+        expect(result1.distributed).toBe(1);
+        expect(result1.skippedAlreadyRun).toBe(false);
+        const balanceAfterFirst = await ledger.balance("t1");
+        const result2 = await runDividendCron(makeConfig());
+        expect(result2.skippedAlreadyRun).toBe(true);
+        expect(result2.distributed).toBe(0);
+        expect((await ledger.balance("t1")).equals(balanceAfterFirst)).toBe(true);
+    });
+    it("handles floor rounding — remainder is not distributed", async () => {
+        await insertPurchase(db, "t1", 50, "2026-02-20 12:00:00");
+        await insertPurchase(db, "t2", 30, "2026-02-20 12:00:00");
+        await insertPurchase(db, "t3", 20, "2026-02-20 12:00:00");
+        const result = await runDividendCron(makeConfig());
+        expect(result.pool.toCents()).toBe(100);
+        expect(result.activeCount).toBe(3);
+        // Nanodollar precision: floor(1_000_000_000 raw / 3) = 333_333_333 raw each
+        // Remainder = 1 nanodollar (not 1 cent — far less wasted with higher scale)
+        expect(result.perUser.toRaw()).toBe(333_333_333);
+        expect(result.distributed).toBe(3);
+    });
+    it("skips distribution when pool is zero", async () => {
+        // Tenant purchased within 7 days but NOT on target date -> pool = 0
+        await insertPurchase(db, "t1", 500, "2026-02-18 12:00:00");
+        const result = await runDividendCron(makeConfig());
+        expect(result.pool.toCents()).toBe(0);
+        expect(result.activeCount).toBe(1);
+        expect(result.perUser.toCents()).toBe(0);
+        expect(result.distributed).toBe(0);
+    });
+    it("distributes sub-cent amounts at nanodollar precision", async () => {
+        // 1 cent purchase, 3 active users: pool = 10_000_000 raw
+        // floor(10_000_000 / 3) = 3_333_333 raw each — non-zero, gets distributed
+        await insertPurchase(db, "t1", 1, "2026-02-20 12:00:00");
+        await insertPurchase(db, "t2", 500, "2026-02-18 12:00:00");
+        await insertPurchase(db, "t3", 500, "2026-02-17 12:00:00");
+        const result = await runDividendCron(makeConfig({ matchRate: 1.0 }));
+        expect(result.pool.toCents()).toBe(1);
+        expect(result.activeCount).toBe(3);
+        expect(result.perUser.toRaw()).toBe(3_333_333);
+        expect(result.distributed).toBe(3);
+    });
+    it("records transactions with correct type and referenceId", async () => {
+        await insertPurchase(db, "t1", 1000, "2026-02-20 12:00:00");
+        await runDividendCron(makeConfig());
+        const history = await ledger.history("t1", { type: "community_dividend" });
+        expect(history).toHaveLength(1);
+        expect(history[0].type).toBe("community_dividend");
+        expect(history[0].referenceId).toBe("dividend:2026-02-20:t1");
+        expect(history[0].amount.toCents()).toBe(1000);
+        expect(history[0].description).toContain("Community dividend");
+    });
+    it("collects errors without stopping distribution to other tenants", async () => {
+        await insertPurchase(db, "t1", 500, "2026-02-20 12:00:00");
+        await insertPurchase(db, "t2", 500, "2026-02-20 12:00:00");
+        const result = await runDividendCron(makeConfig());
+        expect(result.distributed).toBe(2);
+        expect(result.errors).toEqual([]);
+    });
+});

package/dist/credits/dividend-repository.d.ts

@@ -0,0 +1,29 @@
+import type { PlatformDb } from "../db/index.js";
+import { Credit } from "./credit.js";
+import type { DividendHistoryEntry, DividendStats } from "./repository-types.js";
+export type { DividendHistoryEntry, DividendStats };
+export interface DigestTenantRow {
+    tenantId: string;
+    total: Credit;
+    distributionCount: number;
+    avgPool: Credit;
+    avgActiveUsers: number;
+}
+export interface IDividendRepository {
+    getStats(tenantId: string): Promise<DividendStats>;
+    getHistory(tenantId: string, limit: number, offset: number): Promise<DividendHistoryEntry[]>;
+    getLifetimeTotal(tenantId: string): Promise<Credit>;
+    /** Aggregate dividend distributions per tenant for a date window [windowStart, windowEnd). */
+    getDigestTenantAggregates(windowStart: string, windowEnd: string): Promise<DigestTenantRow[]>;
+    /** Resolve email for a tenant from admin_users. Returns undefined if no row exists. */
+    getTenantEmail(tenantId: string): Promise<string | undefined>;
+}
+export declare class DrizzleDividendRepository implements IDividendRepository {
+    private readonly db;
+    constructor(db: PlatformDb);
+    getStats(tenantId: string): Promise<DividendStats>;
+    getHistory(tenantId: string, limit: number, offset: number): Promise<DividendHistoryEntry[]>;
+    getLifetimeTotal(tenantId: string): Promise<Credit>;
+    getDigestTenantAggregates(windowStart: string, windowEnd: string): Promise<DigestTenantRow[]>;
+    getTenantEmail(tenantId: string): Promise<string | undefined>;
+}