@wopr-network/platform-core 1.13.3 → 1.14.0

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

@@ -1,44 +1,40 @@
 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()}`;
+import { CREDIT_TYPE_ACCOUNT, DrizzleLedger } from "./ledger.js";
+
+/**
+ * Insert a backdated purchase entry into the double-entry ledger.
+ * Uses post() with postedAt override to simulate historical purchases.
+ */
+async function insertPurchase(
+  ledger: DrizzleLedger,
+  tenantId: string,
+  amountCents: number,
+  postedAt: string,
+): Promise<void> {
   const amount = Credit.fromCents(amountCents);
-  await db.insert(creditTransactions).values({
-    id,
+  // Purchase: DR cash (1000), CR unearned_revenue (2000:<tenantId>)
+  await ledger.post({
+    entryType: "purchase",
     tenantId,
-    amount,
-    balanceAfter: amount,
-    type: "purchase",
-    createdAt,
+    description: `Test purchase ${amountCents}¢`,
+    referenceId: `test-purchase:${tenantId}:${postedAt}:${Math.random()}`,
+    postedAt,
+    lines: [
+      { accountCode: CREDIT_TYPE_ACCOUNT.purchase, amount, side: "debit" },
+      { accountCode: `2000:${tenantId}`, amount, side: "credit" },
+    ],
   });
-  // 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;
+  let ledger: DrizzleLedger;
 
   beforeAll(async () => {
     ({ db, pool } = await createTestDb());
@@ -50,13 +46,12 @@ describe("runDividendCron", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
-    ledger = new CreditLedger(db);
-    creditTransactionRepo = new DrizzleCreditTransactionRepository(db);
+    ledger = new DrizzleLedger(db);
+    await ledger.seedSystemAccounts();
   });
 
   function makeConfig(overrides?: Partial<DividendCronConfig>): DividendCronConfig {
     return {
-      creditTransactionRepo,
       ledger,
       matchRate: 1.0,
       targetDate: "2026-02-20",
@@ -65,7 +60,7 @@ describe("runDividendCron", () => {
   }
 
   it("distributes dividend to eligible tenants", async () => {
-    await insertPurchase(db, "t1", 1000, "2026-02-20 12:00:00");
+    await insertPurchase(ledger, "t1", 1000, "2026-02-20 12:00:00");
 
     const result = await runDividendCron(makeConfig());
 
@@ -76,7 +71,7 @@ describe("runDividendCron", () => {
   });
 
   it("is idempotent — skips if already ran for the date", async () => {
-    await insertPurchase(db, "t1", 1000, "2026-02-20 12:00:00");
+    await insertPurchase(ledger, "t1", 1000, "2026-02-20 12:00:00");
 
     const result1 = await runDividendCron(makeConfig());
     expect(result1.distributed).toBe(1);
@@ -92,23 +87,22 @@ describe("runDividendCron", () => {
   });
 
   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");
+    await insertPurchase(ledger, "t1", 50, "2026-02-20 12:00:00");
+    await insertPurchase(ledger, "t2", 30, "2026-02-20 12:00:00");
+    await insertPurchase(ledger, "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");
+    await insertPurchase(ledger, "t1", 500, "2026-02-18 12:00:00");
 
     const result = await runDividendCron(makeConfig());
 
@@ -121,9 +115,9 @@ describe("runDividendCron", () => {
   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");
+    await insertPurchase(ledger, "t1", 1, "2026-02-20 12:00:00");
+    await insertPurchase(ledger, "t2", 500, "2026-02-18 12:00:00");
+    await insertPurchase(ledger, "t3", 500, "2026-02-17 12:00:00");
 
     const result = await runDividendCron(makeConfig({ matchRate: 1.0 }));
 
@@ -134,21 +128,20 @@ describe("runDividendCron", () => {
   });
 
   it("records transactions with correct type and referenceId", async () => {
-    await insertPurchase(db, "t1", 1000, "2026-02-20 12:00:00");
+    await insertPurchase(ledger, "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].entryType).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");
+    await insertPurchase(ledger, "t1", 500, "2026-02-20 12:00:00");
+    await insertPurchase(ledger, "t2", 500, "2026-02-20 12:00:00");
 
     const result = await runDividendCron(makeConfig());
 

package/src/credits/dividend-cron.ts

@@ -1,11 +1,9 @@
 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";
+import type { ILedger } from "./ledger.js";
 
 export interface DividendCronConfig {
-  creditTransactionRepo: ICreditTransactionRepository;
-  ledger: ICreditLedger;
+  ledger: ILedger;
   /** 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. */
@@ -25,8 +23,8 @@ export interface DividendCronResult {
  * 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.
+ * 2. Sum all 'purchase' entries for the target date.
+ * 3. Find all tenants with a 'purchase' entry in the last 7 days.
  * 4. Compute pool = sum × matchRate, per-user share = floor(pool / activeCount).
  * 5. Credit each active tenant with their share.
  */
@@ -40,10 +38,8 @@ export async function runDividendCron(cfg: DividendCronConfig): Promise<Dividend
     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}%`);
+  const alreadyRan = await cfg.ledger.existsByReferenceIdLike(`${sentinelPrefix}%`);
 
   if (alreadyRan) {
     result.skippedAlreadyRun = true;
@@ -51,23 +47,18 @@ export async function runDividendCron(cfg: DividendCronConfig): Promise<Dividend
     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);
+  const dailyPurchaseTotal = await cfg.ledger.sumPurchasesForPeriod(dayStart, dayEnd);
+  result.pool = dailyPurchaseTotal.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);
+  const activeTenantIds = await cfg.ledger.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,
@@ -88,17 +79,13 @@ export async function runDividendCron(cfg: DividendCronConfig): Promise<Dividend
     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,
-      );
+      await cfg.ledger.credit(tenantId, result.perUser, "community_dividend", {
+        description: `Community dividend for ${cfg.targetDate}: pool ${result.pool.toCents()}c / ${result.activeCount} users`,
+        referenceId: perUserRef,
+      });
       result.distributed++;
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -119,7 +106,6 @@ export async function runDividendCron(cfg: DividendCronConfig): Promise<Dividend
   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);

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

@@ -6,8 +6,8 @@ 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";
+import { DrizzleLedger } from "./ledger.js";
 
 let pool: PGlite;
 let db: PlatformDb;
@@ -55,6 +55,7 @@ describe("DrizzleDividendRepository", () => {
 
   beforeEach(async () => {
     await truncateAllTables(pool);
+    await new DrizzleLedger(db).seedSystemAccounts();
     repo = new DrizzleDividendRepository(db);
   });
 
@@ -195,8 +196,8 @@ describe("DrizzleDividendRepository", () => {
     });
 
     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 ledger = new DrizzleLedger(db);
+      await ledger.credit("t1", Credit.fromCents(100), "purchase", { description: "recent buy" });
 
       const stats = await repo.getStats("t1");
       expect(stats.userEligible).toBe(true);

package/src/credits/dividend-repository.ts

@@ -1,8 +1,8 @@
 import { and, desc, eq, gte, lt, sql } from "drizzle-orm";
 import type { PlatformDb } from "../db/index.js";
 import { adminUsers } from "../db/schema/admin-users.js";
-import { creditTransactions } from "../db/schema/credits.js";
 import { dividendDistributions } from "../db/schema/dividend-distributions.js";
+import { journalEntries, journalLines } from "../db/schema/ledger.js";
 import { Credit } from "./credit.js";
 import type { DividendHistoryEntry, DividendStats } from "./repository-types.js";
 
@@ -30,35 +30,36 @@ export class DrizzleDividendRepository implements IDividendRepository {
   constructor(private readonly db: PlatformDb) {}
 
   async getStats(tenantId: string): Promise<DividendStats> {
-    // 1. Pool = sum of purchase amounts from yesterday UTC
+    // 1. Pool = sum of purchase credit amounts from yesterday UTC
+    // In double-entry: purchase entries have a credit line on the tenant liability account.
+    // Sum those credit line amounts for entries posted yesterday.
     const poolRow = (
       await this.db
-        // raw SQL: Drizzle cannot express COALESCE(SUM(...), 0) aggregate
-        .select({ total: sql<number>`COALESCE(SUM(${creditTransactions.amount}), 0)` })
-        .from(creditTransactions)
+        .select({ total: sql<string>`COALESCE(SUM(${journalLines.amount}), 0)` })
+        .from(journalLines)
+        .innerJoin(journalEntries, eq(journalEntries.id, journalLines.journalEntryId))
         .where(
           and(
-            eq(creditTransactions.type, "purchase"),
+            eq(journalEntries.entryType, "purchase"),
+            eq(journalLines.side, "credit"),
             // raw SQL: Drizzle cannot express date_trunc with interval arithmetic
-            sql`${creditTransactions.createdAt}::timestamp >= date_trunc('day', timezone('UTC', now())) - INTERVAL '1 day'`,
-            sql`${creditTransactions.createdAt}::timestamp < date_trunc('day', timezone('UTC', now()))`,
+            sql`${journalEntries.postedAt}::timestamp >= date_trunc('day', timezone('UTC', now())) - INTERVAL '1 day'`,
+            sql`${journalEntries.postedAt}::timestamp < date_trunc('day', timezone('UTC', now()))`,
           ),
         )
     )[0];
-    const poolCents = poolRow?.total ?? 0;
-    const pool = Credit.fromCents(poolCents);
+    const pool = Credit.fromRaw(Number(poolRow?.total ?? 0));
 
     // 2. Active users = distinct tenants with a purchase in the last 7 days
     const activeRow = (
       await this.db
-        // raw SQL: Drizzle cannot express COUNT(DISTINCT col)
-        .select({ count: sql<number>`COUNT(DISTINCT ${creditTransactions.tenantId})` })
-        .from(creditTransactions)
+        .select({ count: sql<number>`COUNT(DISTINCT ${journalEntries.tenantId})` })
+        .from(journalEntries)
         .where(
           and(
-            eq(creditTransactions.type, "purchase"),
+            eq(journalEntries.entryType, "purchase"),
             // raw SQL: Drizzle cannot express timestamp comparison with interval arithmetic
-            sql`${creditTransactions.createdAt}::timestamp >= timezone('UTC', now()) - INTERVAL '7 days'`,
+            sql`${journalEntries.postedAt}::timestamp >= timezone('UTC', now()) - INTERVAL '7 days'`,
           ),
         )
     )[0];
@@ -75,10 +76,10 @@ export class DrizzleDividendRepository implements IDividendRepository {
     // 5. User eligibility — last purchase within 7 days
     const userPurchaseRow = (
       await this.db
-        .select({ createdAt: creditTransactions.createdAt })
-        .from(creditTransactions)
-        .where(and(eq(creditTransactions.tenantId, tenantId), eq(creditTransactions.type, "purchase")))
-        .orderBy(desc(creditTransactions.createdAt))
+        .select({ postedAt: journalEntries.postedAt })
+        .from(journalEntries)
+        .where(and(eq(journalEntries.tenantId, tenantId), eq(journalEntries.entryType, "purchase")))
+        .orderBy(desc(journalEntries.postedAt))
         .limit(1)
     )[0];
 
@@ -87,10 +88,7 @@ export class DrizzleDividendRepository implements IDividendRepository {
     let userWindowExpiresAt: string | null = null;
 
     if (userPurchaseRow) {
-      const rawTs = userPurchaseRow.createdAt;
-      // Parse the timestamp directly. PGlite may return ISO strings with or without
-      // timezone suffix. JavaScript's Date constructor handles ISO 8601 strings natively.
-      const lastPurchase = new Date(rawTs);
+      const lastPurchase = new Date(userPurchaseRow.postedAt);
       userLastPurchaseAt = lastPurchase.toISOString();
 
       const windowExpiry = new Date(lastPurchase.getTime() + 7 * 24 * 60 * 60 * 1000);

package/src/credits/index.ts

@@ -12,14 +12,33 @@ export {
 export { Credit } from "./credit.js";
 export type { CreditExpiryCronConfig, CreditExpiryCronResult } from "./credit-expiry-cron.js";
 export { runCreditExpiryCron } from "./credit-expiry-cron.js";
+// -- Double-entry ledger (new) --
 export type {
-  CreditTransaction,
+  AccountType,
+  CreditOpts,
   CreditType,
+  DebitOpts,
   DebitType,
   HistoryOptions,
-  ICreditLedger,
+  ILedger,
+  JournalEntry,
+  JournalLine,
+  MemberUsageSummary,
+  PostEntryInput,
+  Side,
+  SystemAccount,
   TransactionType,
-} from "./credit-ledger.js";
-export { CreditLedger, DrizzleCreditLedger, InsufficientBalanceError } from "./credit-ledger.js";
+  TrialBalance,
+} from "./ledger.js";
+export {
+  CREDIT_TYPE_ACCOUNT,
+  DEBIT_TYPE_ACCOUNT,
+  DrizzleLedger,
+  InsufficientBalanceError,
+  Ledger,
+  SYSTEM_ACCOUNTS,
+} from "./ledger.js";
 export { grantSignupCredits, SIGNUP_GRANT } from "./signup-grant.js";
 export type { ITenantCustomerRepository, TenantCustomerRow } from "./tenant-customer-repository.js";
+export type { TrialBalanceCronConfig, TrialBalanceCronResult } from "./trial-balance-cron.js";
+export { runTrialBalanceCron } from "./trial-balance-cron.js";