@wopr-network/platform-core 0.1.0

package/src/credits/credit.ts

@@ -0,0 +1,160 @@
+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 {
+  static readonly SCALE = 1_000_000_000;
+
+  private constructor(private readonly raw: number) {}
+
+  /** Zero credit (static readonly instance to avoid allocation per access). */
+  static readonly ZERO = new Credit(0);
+
+  /** Create from dollar amount. Rounds to nearest raw unit. */
+  static fromDollars(dollars: number): Credit {
+    return new Credit(Math.round(dollars * Credit.SCALE));
+  }
+
+  /** Create from cent amount. Rounds to nearest raw unit. */
+  static fromCents(cents: number): Credit {
+    return new Credit(Math.round(cents * (Credit.SCALE / 100)));
+  }
+
+  // Tiered balance thresholds (in raw units) for observability warnings.
+  private static readonly WARN_10K = 10_000 * Credit.SCALE; // $10,000
+  private static readonly WARN_100K = 100_000 * Credit.SCALE; // $100,000
+  private static readonly WARN_1M = 1_000_000 * Credit.SCALE; // $1,000,000
+
+  /** Create from raw integer units. Throws TypeError if not integer. */
+  static fromRaw(raw: number): Credit {
+    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(): Credit {
+    return Credit.ZERO;
+  }
+
+  /** Convert to dollars (floating point, for display only). */
+  toDollars(): number {
+    return this.raw / Credit.SCALE;
+  }
+
+  /** Convert to cents (floating point, for display only). */
+  toCents(): number {
+    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(): number {
+    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(): number {
+    return Math.floor(this.raw / (Credit.SCALE / 100));
+  }
+
+  /** Display as dollar amount with two decimal places. */
+  toDisplayString(): string {
+    return `$${this.toDollars().toFixed(2)}`;
+  }
+
+  /** Raw integer units (what gets stored in the database). */
+  toRaw(): number {
+    return this.raw;
+  }
+
+  /** Add another Credit, returning a new Credit. */
+  add(other: Credit): Credit {
+    return new Credit(this.raw + other.raw);
+  }
+
+  /** Subtract another Credit, returning a new Credit (may be negative). */
+  subtract(other: Credit): Credit {
+    return new Credit(this.raw - other.raw);
+  }
+
+  /** Multiply by a factor, rounding to nearest raw unit. */
+  multiply(factor: number): Credit {
+    return new Credit(Math.round(this.raw * factor));
+  }
+
+  /** True if this credit is negative. */
+  isNegative(): boolean {
+    return this.raw < 0;
+  }
+
+  /** True if this credit is exactly zero. */
+  isZero(): boolean {
+    return this.raw === 0;
+  }
+
+  /** True if this credit is greater than other. */
+  greaterThan(other: Credit): boolean {
+    return this.raw > other.raw;
+  }
+
+  /** True if this credit is less than other. */
+  lessThan(other: Credit): boolean {
+    return this.raw < other.raw;
+  }
+
+  /** True if this credit equals other. */
+  equals(other: Credit): boolean {
+    return this.raw === other.raw;
+  }
+
+  /** True if this credit is greater than or equal to other. */
+  greaterThanOrEqual(other: Credit): boolean {
+    return this.raw >= other.raw;
+  }
+
+  /** True if this credit is less than or equal to other. */
+  lessThanOrEqual(other: Credit): boolean {
+    return this.raw <= other.raw;
+  }
+
+  toString(): string {
+    return `Credit(raw=${this.raw})`;
+  }
+
+  /** Serialize to raw integer for JSON (API responses, database). */
+  toJSON(): number {
+    return this.raw;
+  }
+}

package/src/credits/dividend-cron.test.ts

@@ -0,0 +1,158 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+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 { type DividendCronConfig, runDividendCron } from "./dividend-cron.js";
+
+async function insertPurchase(db: PlatformDb, tenantId: string, amountCents: number, createdAt: string): Promise<void> {
+  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: PGlite;
+  let db: PlatformDb;
+  let ledger: CreditLedger;
+  let creditTransactionRepo: DrizzleCreditTransactionRepository;
+
+  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?: Partial<DividendCronConfig>): DividendCronConfig {
+    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/src/credits/dividend-cron.ts

@@ -0,0 +1,127 @@
+import { logger } from "../config/logger.js";
+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 async function runDividendCron(cfg: DividendCronConfig): Promise<DividendCronResult> {
+  const result: DividendCronResult = {
+    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: string, days: number): string {
+  const d = new Date(`${dateStr}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() - days);
+  return d.toISOString().slice(0, 10);
+}

package/src/credits/dividend-repository.test.ts

@@ -0,0 +1,223 @@
+import crypto from "node:crypto";
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../db/index.js";
+import { adminUsers } from "../db/schema/admin-users.js";
+import { dividendDistributions } from "../db/schema/dividend-distributions.js";
+import { createTestDb, truncateAllTables } from "../test/db.js";
+import { Credit } from "./credit.js";
+import { CreditLedger } from "./credit-ledger.js";
+import { DrizzleDividendRepository } from "./dividend-repository.js";
+
+let pool: PGlite;
+let db: PlatformDb;
+
+beforeAll(async () => {
+  ({ db, pool } = await createTestDb());
+});
+
+afterAll(async () => {
+  await pool.close();
+});
+
+/** Insert a dividend_distributions row directly (bypassing repo — it has no write method). */
+async function seedDividend(opts: {
+  tenantId: string;
+  date: string;
+  amountCents: number;
+  poolCents: number;
+  activeUsers: number;
+}): Promise<void> {
+  await db.insert(dividendDistributions).values({
+    id: crypto.randomUUID(),
+    tenantId: opts.tenantId,
+    date: opts.date,
+    amountCents: opts.amountCents,
+    poolCents: opts.poolCents,
+    activeUsers: opts.activeUsers,
+  });
+}
+
+/** Insert an admin_users row for getTenantEmail tests. */
+async function seedAdminUser(tenantId: string, email: string): Promise<void> {
+  await db.insert(adminUsers).values({
+    id: crypto.randomUUID(),
+    email,
+    tenantId,
+    status: "active",
+    role: "tenant_admin",
+    createdAt: Date.now(),
+  });
+}
+
+describe("DrizzleDividendRepository", () => {
+  let repo: DrizzleDividendRepository;
+
+  beforeEach(async () => {
+    await truncateAllTables(pool);
+    repo = new DrizzleDividendRepository(db);
+  });
+
+  // --- getHistory() ---
+
+  describe("getHistory()", () => {
+    it("returns empty array when tenant has no distributions", async () => {
+      const history = await repo.getHistory("nonexistent", 50, 0);
+      expect(history).toEqual([]);
+    });
+
+    it("returns distributions in reverse chronological order", async () => {
+      await seedDividend({ tenantId: "t1", date: "2026-01-01", amountCents: 10, poolCents: 1000, activeUsers: 5 });
+      await seedDividend({ tenantId: "t1", date: "2026-01-02", amountCents: 20, poolCents: 2000, activeUsers: 10 });
+      await seedDividend({ tenantId: "t1", date: "2026-01-03", amountCents: 30, poolCents: 3000, activeUsers: 15 });
+
+      const history = await repo.getHistory("t1", 50, 0);
+      expect(history).toHaveLength(3);
+      expect(history[0].date).toBe("2026-01-03");
+      expect(history[1].date).toBe("2026-01-02");
+      expect(history[2].date).toBe("2026-01-01");
+    });
+
+    it("converts amountCents and poolCents to Credit objects", async () => {
+      await seedDividend({ tenantId: "t1", date: "2026-01-15", amountCents: 42, poolCents: 5000, activeUsers: 8 });
+
+      const history = await repo.getHistory("t1", 50, 0);
+      expect(history).toHaveLength(1);
+      expect(history[0].amount.toCents()).toBe(42);
+      expect(history[0].pool.toCents()).toBe(5000);
+      expect(history[0].activeUsers).toBe(8);
+    });
+
+    it("respects limit and offset", async () => {
+      for (let i = 1; i <= 5; i++) {
+        await seedDividend({
+          tenantId: "t1",
+          date: `2026-01-0${i}`,
+          amountCents: i * 10,
+          poolCents: 1000,
+          activeUsers: 5,
+        });
+      }
+
+      const page1 = await repo.getHistory("t1", 2, 0);
+      expect(page1).toHaveLength(2);
+      expect(page1[0].date).toBe("2026-01-05");
+      expect(page1[1].date).toBe("2026-01-04");
+
+      const page2 = await repo.getHistory("t1", 2, 2);
+      expect(page2).toHaveLength(2);
+      expect(page2[0].date).toBe("2026-01-03");
+    });
+
+    it("is tenant-isolated", async () => {
+      await seedDividend({ tenantId: "t1", date: "2026-01-01", amountCents: 10, poolCents: 1000, activeUsers: 5 });
+      await seedDividend({ tenantId: "t2", date: "2026-01-01", amountCents: 99, poolCents: 9000, activeUsers: 50 });
+
+      const t1History = await repo.getHistory("t1", 50, 0);
+      expect(t1History).toHaveLength(1);
+      expect(t1History[0].amount.toCents()).toBe(10);
+    });
+  });
+
+  // --- getLifetimeTotal() ---
+
+  describe("getLifetimeTotal()", () => {
+    it("returns Credit.ZERO when tenant has no distributions", async () => {
+      const total = await repo.getLifetimeTotal("nonexistent");
+      expect(total.toCents()).toBe(0);
+    });
+
+    it("sums all distributions for a tenant", async () => {
+      await seedDividend({ tenantId: "t1", date: "2026-01-01", amountCents: 10, poolCents: 1000, activeUsers: 5 });
+      await seedDividend({ tenantId: "t1", date: "2026-01-02", amountCents: 25, poolCents: 2000, activeUsers: 10 });
+
+      const total = await repo.getLifetimeTotal("t1");
+      expect(total.toCents()).toBe(35);
+    });
+
+    it("is tenant-isolated", async () => {
+      await seedDividend({ tenantId: "t1", date: "2026-01-01", amountCents: 10, poolCents: 1000, activeUsers: 5 });
+      await seedDividend({ tenantId: "t2", date: "2026-01-01", amountCents: 999, poolCents: 9000, activeUsers: 50 });
+
+      const total = await repo.getLifetimeTotal("t1");
+      expect(total.toCents()).toBe(10);
+    });
+  });
+
+  // --- getDigestTenantAggregates() ---
+
+  describe("getDigestTenantAggregates()", () => {
+    it("returns empty array when no distributions in window", async () => {
+      const result = await repo.getDigestTenantAggregates("2026-02-01", "2026-02-28");
+      expect(result).toEqual([]);
+    });
+
+    it("aggregates distributions per tenant within [windowStart, windowEnd)", async () => {
+      // In window
+      await seedDividend({ tenantId: "t1", date: "2026-02-01", amountCents: 10, poolCents: 1000, activeUsers: 5 });
+      await seedDividend({ tenantId: "t1", date: "2026-02-02", amountCents: 20, poolCents: 2000, activeUsers: 10 });
+      // Out of window
+      await seedDividend({ tenantId: "t1", date: "2026-03-01", amountCents: 999, poolCents: 9000, activeUsers: 50 });
+
+      const result = await repo.getDigestTenantAggregates("2026-02-01", "2026-03-01");
+      expect(result).toHaveLength(1);
+      expect(result[0].tenantId).toBe("t1");
+      expect(result[0].total.toCents()).toBe(30); // 10 + 20
+      expect(result[0].distributionCount).toBe(2);
+    });
+
+    it("returns multiple tenants", async () => {
+      await seedDividend({ tenantId: "t1", date: "2026-02-01", amountCents: 10, poolCents: 1000, activeUsers: 5 });
+      await seedDividend({ tenantId: "t2", date: "2026-02-01", amountCents: 50, poolCents: 5000, activeUsers: 20 });
+
+      const result = await repo.getDigestTenantAggregates("2026-02-01", "2026-03-01");
+      expect(result).toHaveLength(2);
+
+      const t1 = result.find((r) => r.tenantId === "t1");
+      const t2 = result.find((r) => r.tenantId === "t2");
+      expect(t1?.total.toCents()).toBe(10);
+      expect(t2?.total.toCents()).toBe(50);
+    });
+  });
+
+  // --- getStats() ---
+
+  describe("getStats()", () => {
+    it("returns zero pool and zero activeUsers when no purchase transactions exist", async () => {
+      const stats = await repo.getStats("t1");
+      expect(stats.pool.toCents()).toBe(0);
+      expect(stats.activeUsers).toBe(0);
+      expect(stats.perUser.toCents()).toBe(0);
+      expect(stats.userEligible).toBe(false);
+      expect(stats.userLastPurchaseAt).toBeNull();
+      expect(stats.userWindowExpiresAt).toBeNull();
+      expect(stats.nextDistributionAt).toEqual(expect.any(String));
+    });
+
+    it("marks user as eligible when they have a recent purchase", async () => {
+      const ledger = new CreditLedger(db);
+      await ledger.credit("t1", Credit.fromCents(100), "purchase", "recent buy");
+
+      const stats = await repo.getStats("t1");
+      expect(stats.userEligible).toBe(true);
+      expect(stats.userLastPurchaseAt).toEqual(expect.any(String));
+      expect(stats.userWindowExpiresAt).toEqual(expect.any(String));
+    });
+  });
+
+  // --- getTenantEmail() ---
+
+  describe("getTenantEmail()", () => {
+    it("returns undefined when tenant has no admin user", async () => {
+      const email = await repo.getTenantEmail("nonexistent");
+      expect(email).toBeUndefined();
+    });
+
+    it("returns the email for the tenant's admin user", async () => {
+      await seedAdminUser("t1", "alice@example.com");
+
+      const email = await repo.getTenantEmail("t1");
+      expect(email).toBe("alice@example.com");
+    });
+  });
+});